Uniquity-mcp

Uniquity MCP Server

Overview

Uniquity MCP Server is a server that makes the functions of UniquityReporter available to external tools and AI agents via MCP (Model Context Protocol).

UniquityReporter: UniquityReporter

• Enables the analysis functions of UniquityReporter to be called from MCP Host or AI agents.
• Separates core logic and interface to improve maintainability and extensibility.
• Makes it available from various clients through a standardized protocol.

Release Note

• 0.1.0
  • Initial version

MCP Host Settings

Required and Optional Environment Variables

• Required (Must be passed from MCP Host)
  • GITHUB_TOKEN: Token for GitHub API
  • OPENAI_API_KEY: OpenAI API key
  • TAVILY_API_KEY: Tavily API key
• Optional (If not specified, the default values in config/config.js will be used)
  • openaiModel: Name of the OpenAI model to use (e.g., o3-mini, gpt-4.1-nano, etc.)
  • logEnabled: Enable/disable log output (on/off)

Example MCP Host Configuration

{
  "uniquity-mcp": {
    "command": "npx",
    "args": [
      "-y",
      "uniquity-mcp@latest"
    ],
    "env": {
      "GITHUB_TOKEN": "{apikey}",
      "OPENAI_API_KEY": "{apikey}",
      "TAVILY_API_KEY": "{apikey}"
    }
  }
}

• Secrets in env settings are required.
• This MCP does not support report and log file saving.
• If file saving is required, save the standard output to a file on the Host side.

List of Provided Tools (MCP Server)

1. analyze_repository

• Description: Generates a similarity analysis report for the specified GitHub repository. The report is always returned in Markdown format to standard output.
• Return Value: Report body in Markdown format (standard output)

2. list_tools

• Description: Returns a list of tools provided by the MCP Server and their specifications (arguments and return values).
• Return Value: Array of tools available in the MCP Server (including name, description, parameterSchema, returnSchema for each tool)

---

This makes it clear to MCP Hosts and clients "what tools are available" and "how to call them."

Notes

• MCP Server supports standard output only.
• openaiModel and logEnabled can be dynamically specified as tool arguments.
• Optional values can be omitted, and if omitted, the default values of UniquityReporter will be used.

Version Management of Dependency Package (uniquity-reporter)

• The dependency of uniquity-reporter in package.json is specified as ^1.4.4.

  • This allows minor and patch updates to be automatically followed, but major version updates (such as 2.x) will not be automatically followed.
  • If you want to guarantee "always the latest," perform version updates and releases of the MCP Server itself, and recommend users to use npx uniquity-mcp@latest.

• Note on npx Cache Behavior

  • npx caches the retrieved packages and dependencies.
  • If you want to always use the latest version of the package and dependencies, explicitly specify "uniquity-mcp@latest" as in the MCP Host configuration example, and guide users to clear the cache (npx clear-npx-cache, etc.) for safety.

• If there are specification changes or significant updates to the dependency package, promptly version up the MCP Server and announce it in the release notes or README.

Architecture Overview

• This repository manages only the implementation of the MCP Server and depends on the uniquity-reporter npm package for core logic.
• Receives requests from MCP Host, calls UniquityReporter CLI, and returns the results.
• Uses standard input/output (stdin/stdout) based inter-process communication.
• Reports are always output to standard output and are not saved to files.

Architecture Diagram

graph LR
    subgraph MCP Host
        Client[Client Application]
    end

    subgraph MCP Server
        Server[Uniquity MCP Server]
        Server -->|Command Execution| UniquityReporter[UniquityReporter CLI]
    end

    subgraph External Services
        GitHub[GitHub API]
        OpenAI[OpenAI API]
        Tavily[Tavily API]
    end

    Client -- MCP Protocol --> Server
    Server -- JSON Response --> Client
    UniquityReporter -- Repository Analysis --> GitHub
    UniquityReporter -- Code Analysis --> OpenAI
    UniquityReporter -- Web Search --> Tavily

Technology Stack

• Runtime: Node.js 18+
• Main Packages:
  • @modelcontextprotocol/sdk: MCP protocol implementation
  • uniquity-reporter: Core analysis engine
  • winston: Logging
  • dotenv: Environment variable management
• Development Tools:
  • TypeScript
  • ESLint
  • Prettier
  • Jest (Testing)

Project Structure

uniquity-mcp/
├── uniquity-mcp/           # Main Project
│   ├── src/
│   │   └── index.js       # Entry Point
│   └── package.json
├── .github/              # GitHub Actions Configuration
└── README.md             # This File

Development Guide

Installation

Installing via Smithery

To install uniquity-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @KunihiroS/uniquity-mcp --client claude

Installing Dependencies

# Install dependency packages
pnpm install

# Install including development dependencies
pnpm install --dev

Build

pnpm run build

Start in Development Mode

pnpm run dev

Usage

Starting the MCP Server

# After building
node dist/index.js

# Or run directly
pnpm start

Starting the Development Server

# Start in development mode (with hot reload)
pnpm run dev

# Build and then run
pnpm run build
pnpm start

License

MIT License

Author

KunihiroS