Uniquity Mcp Server

Uniquity MCP Server

概要

Uniquity MCP Server は、UniquityReporter の機能を MCP（Model Context Protocol）経由で外部ツールや AI エージェントから利用できるようにするサーバーです。

UniquityReporter: UniquityReporter

• UniquityReporter の分析機能を MCP Host や AI エージェントから呼び出せます。
• コアロジックとインターフェースを分離し、保守性と拡張性を向上させます。
• 標準化されたプロトコルを通じて、さまざまなクライアントから利用できます。

リリースノート

• 0.1.0
  • 初期バージョン

MCP Host の設定

必須および任意の環境変数

• 必須（MCP Host から渡す必要があります）
  • GITHUB_TOKEN：GitHub API のトークン
  • OPENAI_API_KEY：OpenAI API キー
  • TAVILY_API_KEY：Tavily API キー
• 任意（指定しない場合は config/config.js のデフォルト値が使用されます）
  • openaiModel：使用する OpenAI モデル名（例：o3-mini、gpt-4.1-nano など）
  • logEnabled：ログ出力の有効／無効（on／off）

MCP Host 設定の例

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

• env 設定でシークレットを指定する必要があります。
• この MCP はレポートやログファイルの保存に対応していません。
• ファイルへの保存が必要な場合は、Host 側で標準出力をファイルに保存してください。

提供するツールの一覧（MCP Server）

1. analyze_repository

• 説明：指定された GitHub リポジトリの類似性分析レポートを生成します。レポートは常に Markdown 形式で標準出力に返されます。
• 戻り値：Markdown 形式のレポート本文（標準出力）

引数	型	必須	説明
repositoryUrl	string	はい	分析対象の GitHub リポジトリ URL
openaiModel	string	いいえ	使用する OpenAI モデル名（例：o3-mini、gpt-4.1-nano など）
logEnabled	string	いいえ	ログ出力の有効／無効（on／off、デフォルト：off）

2. list_tools

• 説明：MCP Server が提供するツールと、その仕様（引数と戻り値）の一覧を返します。
• 戻り値：MCP Server で利用可能なツールの配列（各ツールの名前、説明、parameterSchema、returnSchema を含む）

引数	型	必須	説明
なし

---

これにより、MCP Host とクライアントは「どのようなツールが利用可能か」「どのように呼び出すか」を明確に把握できます。

注意事項

• MCP Server は標準出力のみをサポートします。
• openaiModel と logEnabled は、ツールの引数として動的に指定できます。
• 任意の値は省略できます。省略した場合は、UniquityReporter のデフォルト値が使用されます。

依存パッケージ（uniquity-reporter）のバージョン管理

• package.json の uniquity-reporter の依存関係は ^1.4.4 と指定されています。

  • これにより、マイナーアップデートとパッチアップデートは自動的に適用されますが、メジャーバージョンの更新（2.x など）は自動的には適用されません。
  • 「常に最新」を保証したい場合は、Uniquity MCP Server 自体をバージョンアップしてリリースし、ユーザーには npx uniquity-mcp@latest の使用を推奨してください。

• npx のキャッシュ動作に関する注意

  • npx は取得したパッケージと依存関係をキャッシュします。
  • パッケージと依存関係を常に最新に保つには、MCP Host 設定の例のように "uniquity-mcp@latest" を明示的に指定し、安全のためユーザーにキャッシュのクリア（npx clear-npx-cache など）を案内してください。

• 依存パッケージの仕様変更や大幅な更新があった場合は、速やかに MCP Server のバージョンを上げ、リリースノートまたは README で告知してください。

アーキテクチャの概要

• このリポジトリでは、MCP サーバーの実装のみを管理しており、コアロジックには uniquity-reporter npm パッケージを使用しています。
• MCP ホストからリクエストを受け取り、UniquityReporter CLI を呼び出して結果を返します。
• 標準入力／標準出力（stdin/stdout）を使用したプロセス間通信を行います。
• レポートは常に標準出力に出力され、ファイルには保存されません。

アーキテクチャ図

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

技術スタック

• ランタイム：Node.js 18+
• 主なパッケージ：
  • @modelcontextprotocol/sdk：MCP プロトコルの実装
  • uniquity-reporter：コア分析エンジン
  • winston：ロギング
  • dotenv：環境変数の管理
• 開発ツール：
  • TypeScript
  • ESLint
  • Prettier
  • Jest（テスト）

プロジェクト構成

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

開発ガイド

インストール

Smithery 経由でのインストール

Smithery を利用して、Claude Desktop 用の uniquity-mcp を自動的にインストールするには：

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

依存関係のインストール

# Install dependency packages
pnpm install

# Install including development dependencies
pnpm install --dev

ビルド

pnpm run build

開発モードでの起動

pnpm run dev

使用方法

MCP サーバーの起動

# After building
node dist/index.js

# Or run directly
pnpm start

開発サーバーの起動

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

# Build and then run
pnpm run build
pnpm start

ライセンス

MIT ライセンス

作者

KunihiroS