Codecompass MCP

🚀 CodeCompass MCP

エンタープライズグレードのモデルコンテキストプロトコル（MCP）サーバーで、インテリジェントなリポジトリ分析とAIによる開発支援を実現します。

開発ツールをGitHubリポジトリの包括的な分析に接続します。11の合理化されたツール、強化されたエラーハンドリング、リアルタイムモニタリング、および本番環境でのデプロイが可能です。

🚀 クイックスタート

手順に沿ったDockerセットアップ（推奨）

1. クローンと移動

git clone https://github.com/TheAlchemist6/codecompass-mcp.git
cd codecompass-mcp

期待される出力:

Cloning into 'codecompass-mcp'...
remote: Enumerating objects: 53, done.
remote: Total 53 (delta 0), reused 0 (delta 0), pack-reused 53
Receiving objects: 100% (53/53), 259.84 KiB | 1.85 MiB/s, done.

2. 環境の設定

cp .env.example .env
# 実際のAPIキーを.envに記入
nano .env  # または好みのエディタを使用

.envファイルに必要な項目:

GITHUB_TOKEN=ghp_your_actual_github_token_here
OPENROUTER_API_KEY=sk-or-v1-your_actual_openrouter_key_here

🔑 APIキーの取得場所:

• GitHubトークン: github.com/settings/tokens → 新しいトークン（クラシック）を生成 → repoスコープを選択
• OpenRouterキー: openrouter.ai/keys → 新しいAPIキーを作成

3. ビルドと実行

./scripts/docker-build.sh
./scripts/docker-run.sh --env-file .env

期待される出力:

✅ Build successful
Image information:
REPOSITORY        TAG       IMAGE ID       CREATED         SIZE
codecompass-mcp   latest    a1b2c3d4e5f6   2 seconds ago   278MB

🚀 Starting CodeCompass MCP server...
✅ Server started successfully
Health check: healthy
API limits: 5000/hour remaining

4. インストールのテスト

# ヘルスチェックでテスト
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "health_check"}}' | docker exec -i codecompass-mcp node build/index.js

サポートされるプラットフォーム

• ✅ Linux (Ubuntu 18.04以降、CentOS 7以降)
• ✅ macOS (10.14以降、IntelおよびApple Silicon)
• ✅ Windows (Docker Desktop付きの10/11)

代替インストール方法

ローカル開発

# 依存関係のインストール
npm install

# 環境変数の設定
export GITHUB_TOKEN=your_github_token
export OPENROUTER_API_KEY=your_openrouter_key

# ビルドと実行
npm run build && npm run dev

グローバルインストール

npm install -g codecompass-mcp
codecompass-mcp --help

✨ 主な機能

• 🔍 包括的なリポジトリ分析 - コード構造、依存関係、アーキテクチャに関する深い洞察
• 🤖 AIによるコードレビュー - OpenRouter統合（400以上のモデル）を用いたインテリジェントなコード分析
• 🚀 本番環境でのデプロイ可能 - セキュリティのベストプラクティスを備えたDockerコンテナ
• 📊 リアルタイムモニタリング - パフォーマンスメトリクス、ヘルスチェック、および可観測性
• 🛡️ エンタープライズセキュリティ - 入力検証、パストラバーサル防止、および安全な処理
• ⚡ 高パフォーマンス - インテリジェントなチャンク分割、並列処理、およびレスポンスの最適化
• 🔧 開発者体験 - 包括的なドキュメント、サンプル、およびデバッグツール

🔧 設定

必須の環境変数

GITHUB_TOKEN=ghp_your_github_token_here        # GitHub APIアクセス
OPENROUTER_API_KEY=sk-or-v1-your_key_here     # OpenRouter APIアクセス

オプションの設定

AI_MODEL=anthropic/claude-3.5-sonnet          # デフォルトのAIモデル
MAX_RESPONSE_TOKENS=25000                      # レスポンスサイズ制限
LOG_LEVEL=info                                 # ログレベル
NODE_ENV=production                            # 環境モード

🛠️ 利用可能なツール

コアデータツール（6つのツール）

• get_repository_info - リポジトリのメタデータ、統計情報、および重要な情報
• get_file_tree - フィルタリング機能付きの完全なディレクトリ構造とファイルリスト
• search_repository - 正規表現パターンとフィルタリングを用いた高度な検索
• get_file_content - セキュリティ検証とメタデータ付きのバッチファイル処理
• analyze_dependencies - 依存関係グラフ分析と脆弱性検出
• analyze_codebase - 包括的な構造、アーキテクチャ、およびメトリクス分析

AI強化ツール（3つのツール）

• review_code - セキュリティ、パフォーマンス、および保守性に関する洞察を持つAIによるコードレビュー
• explain_code - 自然言語によるコードの説明とドキュメント生成
• suggest_improvements - インテリジェントなリファクタリング提案と近代化戦略

変換ツール（1つのツール）

• transform_code - コードの変換、近代化、および移行支援

ユーティリティツール（1つのツール）

• health_check - システムのヘルスモニタリングとパフォーマンスメトリクス

🐳 Docker統合

本番環境でのデプロイ

# 本番用イメージのビルド
./scripts/docker-build.sh

# 環境ファイルを指定して実行
./scripts/docker-run.sh --env-file .env

# ログの表示
./scripts/docker-logs.sh -f --timestamps

Docker Compose

version: '3.8'
services:
  codecompass-mcp:
    build: .
    container_name: codecompass-mcp
    restart: unless-stopped
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "node", "-e", "console.log('Health check')"]
      interval: 30s
      timeout: 10s
      retries: 3

MCPクライアントの統合

Claude Desktopの設定

Claude Desktopの設定ファイルに追加します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codecompass": {
      "command": "docker",
      "args": [
        "exec", "-i", "codecompass-mcp", 
        "node", "build/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "OPENROUTER_API_KEY": "your_openrouter_key_here"
      }
    }
  }
}

Claude Desktopを再起動すると、UIにCodeCompassのツールが表示されます。

Claude Code CLIの統合

# MCPサーバーをClaude Codeに追加
claude mcp add codecompass-docker -s user -- \
  docker exec -i codecompass-mcp node build/index.js

その他のMCPクライアント

• Cline (VS Code): MCP設定に追加
• Continue (VS Code/JetBrains): MCPプロバイダーとして設定
• カスタムクライアント: stdioトランスポートを使用してnode build/index.jsを実行

統合のテスト

# 接続のテスト
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | docker exec -i codecompass-mcp node build/index.js

# 11のツールのリストが返されるはず

📊 モニタリングと可観測性

リアルタイムダッシュボード

# インタラクティブなモニタリングダッシュボード
./scripts/monitor.js --watch

# メトリクスのエクスポート
./scripts/monitor.js --export > metrics.json

# ヘルスチェック
curl -X POST http://localhost:3000/health

パフォーマンスメトリクス

• レスポンス時間: ヘルスチェックでは100ms未満、リポジトリ分析では2 - 10秒
• メモリ使用量: リポジトリのサイズに応じて50 - 200MB
• 並列処理: 自動スケーリング付きの設定可能な制限
• エラートラッキング: コンテキスト付きの提案を伴う包括的なエラーモニタリング

ヘルスモニタリング

{
  "name": "health_check",
  "arguments": {
     "checks": ["api-limits", "monitoring", "configuration"],
    "options": {
      "include_metrics": true,
      "include_insights": true
    }
  }
}

💻 使用例

リポジトリ分析

{
  "name": "fetch_repository_data",
  "arguments": {
    "url": "https://github.com/microsoft/typescript",
    "options": {
      "include_structure": true,
      "include_dependencies": true,
      "max_files": 100,
      "chunk_mode": true
    }
  }
}

AIによるコードレビュー

{
  "name": "ai_code_review",
  "arguments": {
    "url": "https://github.com/your-org/your-repo",
    "file_paths": ["src/main.ts", "src/utils/"],
    "review_focus": ["security", "performance", "maintainability"],
    "options": {
      "ai_model": "anthropic/claude-3.5-sonnet",
      "severity_threshold": "medium"
    }
  }
}

バッチファイル処理

{
  "name": "get_file_content",
  "arguments": {
    "url": "https://github.com/your-org/your-repo",
    "file_paths": ["src/", "docs/", "tests/"],
    "options": {
      "max_concurrent": 10,
      "include_metadata": true,
      "continue_on_error": true
    }
  }
}

🏗️ アーキテクチャ

サービス指向設計

MCP Client → MCP Server → Service Layer → External APIs
            ↓
         Monitoring & Logging

主要コンポーネント

• MCP Server: 11の合理化されたツールを備えたJSON-RPCプロトコルの処理
• Service Layer: GitHub API、OpenRouter統合、およびビジネスロジック
• Configuration: Zod検証を用いた集中型の型安全な設定
• Monitoring: リアルタイムのパフォーマンス追跡とヘルスモニタリング
• Security: 入力検証、パストラバーサル防止、および安全な処理

🔒 セキュリティ機能

入力検証

• Zodスキーマ検証: すべてのツールに対する型安全な入力検証
• パストラバーサル防止: 包括的なファイルパスのセキュリティチェック
• レート制限: 設定可能なリクエストレート制限とスロットリング
• APIキー管理: 安全な環境変数の処理

コンテナセキュリティ

• 非ルート実行: すべてのコンテナが特権のないユーザーとして実行されます
• 読み取り専用ファイルシステム: セキュリティを重視したコンテナ構成
• リソース制限: 安定性のためのメモリとCPUの制約
• ヘルスチェック: 自動化されたヘルスモニタリングと回復

🎯 パフォーマンス最適化

インテリジェントなレスポンス管理

• チャンク分割: 大きなレスポンスを管理可能なチャンクに分割
• トランケーション: データ構造を維持したスマートなトランケーション
• 並列処理: 設定可能な制限付きの並列ファイル処理
• キャッシュ: 頻繁にアクセスされるデータに対するインテリジェントなキャッシュ戦略

リソース管理

• メモリ効率: 自動クリーンアップによる最適化されたメモリ使用
• リクエスト追跡: 分散トレーシングのための相関ID
• パフォーマンス洞察: 自動化されたパフォーマンス分析と提案
• スケーラビリティ: Dockerコンテナによる水平スケーリング対応

📚 ドキュメント

完全なドキュメントセット

• セットアップガイド - インストールと設定の手順
• APIリファレンス - サンプル付きの完全なツールドキュメント
• Dockerガイド - コンテナのデプロイと管理
• モニタリングガイド - 可観測性とパフォーマンスモニタリング
• アーキテクチャガイド - 技術的なアーキテクチャとパターン

サンプルとテンプレート

• 使用例 - 実際の使用パターンとテンプレート
• 統合例 - MCPクライアントの統合例
• 設定テンプレート - 本番環境で使用可能な設定例

🤝 コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドを参照してください。

• 開発環境のセットアップとワークフロー
• コードスタイルとテスト要件
• プルリクエストのプロセスとガイドライン
• バグ報告と機能リクエスト

開発環境のセットアップ

# クローンとセットアップ
git clone https://github.com/your-org/codecompass-mcp.git
cd codecompass-mcp

# 依存関係のインストール
npm install

# テストの実行
npm test

# 開発サーバーの起動
npm run dev:watch

🔄 ロードマップ

現在のバージョン (1.0.0)

• ✅ 明確な責任を持つ11の合理化された原子ツール
• ✅ 本番環境でのDockerデプロイ可能
• ✅ リアルタイムモニタリングと可観測性
• ✅ エンタープライズセキュリティ機能
• ✅ 完全なドキュメントセット

将来の機能強化

• 🔮 会話コンテキスト管理 - セッション状態と会話履歴
• 🔮 高度なキャッシュ - Redisベースのキャッシュとインテリジェントな無効化
• 🔮 プラグインシステム - カスタムツール用の拡張可能なアーキテクチャ
• 🔮 多言語サポート - TypeScript/JavaScript以外の言語のサポート拡張
• 🔮 Kubernetes統合 - Helmチャートを用いたKubernetesネイティブデプロイ

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🙏 謝辞

• OpenRouter MCP - アーキテクチャパターンとベストプラクティスのインスピレーション
• MCP Protocol - ツールの統合と通信の基礎
• Anthropic - Claude AIの統合と開発サポート
• GitHub - リポジトリ分析とAPI統合
• Docker - コンテナ化とデプロイインフラストラクチャ

🆘 サポート

ヘルプの取得

• ドキュメント: docs/ディレクトリにある包括的なドキュメントを確認してください。
• イシュー: GitHub Issuesでバグを報告し、機能をリクエストしてください。
• ディスカッション: GitHub Discussionsでコミュニティのディスカッションに参加してください。

一般的な問題

• APIキーの設定: セットアップガイドを参照してください。
• Dockerの問題: Dockerガイドを確認してください。
• パフォーマンス: モニタリングガイドを見直してください。

🚀 開発に使用された技術

• TypeScript - 型安全なJavaScript開発
• Node.js - JavaScriptランタイム環境
• Docker - コンテナ化プラットフォーム
• Zod - TypeScriptを中心としたスキーマ検証
• MCP SDK - モデルコンテキストプロトコルの実装

Myron Labsによる愛💜で作られました

インテリジェントなリポジトリ分析とAIによるコードの洞察で、開発ワークフローを変革しましょう。