Corpus

Corpus は、組織内のすべてのリポジトリにわたるドキュメントを集約し、Spotify Backstage カタログエンティティを使用してライブなシステムマップを構築し、それらすべてを強力な Model Context Protocol (MCP) サーバーの背後に配置します。

AI エージェント（Claude、Copilot など）に、アーキテクチャ、サービス所有権、ドキュメント、コードを理解するために必要な全体像を提供します。すべてをひとつの場所で！

✨ 特徴

• 🗺️ 自動生成エンティティグラフ: Backstage の catalog-info.yaml エンティティ（Components、APIs、Systems、Users）を完全に解析し、よく知られたリレーション（例: ownerOf/ownedBy、providesApi/apiProvidedBy）を使用して双方向の関係グラフを生成します。

• 📖 集中型ドキュメント検索: 組織全体の README.md、docs/**/*.md、adr/**/*.md、AI スキルにわたる高速な語彙検索を提供します。

• 🔍 グローバルコード検索: GitHub Code Search API を介して、組織内のすべてのリポジトリを横断したキーワード検索を実行します。

• 💬 Issue と PR のコンテキスト: GitHub の検索 API にプロキシして、組織全体のディスカッション、PR、Issue を検索します（search_issues_and_prs）。

• 📄 ファイル読み取り: 任意のリポジトリのブランチやコミットから、正確なファイル内容に直接アクセスできます。

• ⚙️ API スキーマ集約: openapi および swagger ファイルを自動的にインデックス化し、エージェントがエンドポイント契約を即座に取得できるようにします（list_api_schemas）。

• 🚀 ゼロ設定スタート: 起動時に不足しているビルドを自動実行します。認証情報があれば、npm start を実行するだけでサーバーがすべてを取得してインデックス化します。

• 🐞 ギャップレポート: ドキュメントがエージェントの質問に回答できない場合に、GitHub Issue を自動作成するオプション機能です。

Related MCP server: repovine

🛠️ クイックスタート

1. 前提条件

• Node.js v22 以降

• GitHub PAT（Personal Access Token）:

  • クラシックトークン: repo（プライベートリポジトリの読み取り用）と read:org（組織をクエリする場合）が必要です。

  • ファイングレインドトークン: すべてのリポジトリに対して Contents: Read-only と Metadata: Read-only が必要です。ENABLE_GAP_REPORTING を有効にする場合は、対象リポジトリに対して Issues: Read & Write も必要です。

2. 環境設定

ルートディレクトリに .env ファイルを作成します:

GIT_ORG=your-github-org-or-username
GIT_PAT=your-github-personal-access-token

# Optional
ENABLE_GAP_REPORTING=false
GITHUB_PROJECT=your-github-org/doc-gaps-repo

3. ビルドと実行

ローカル実行:

npm install
npm run build
npm start

注: npm start は、コーパスとシステムマップの生成スクリプトがまだ実行されていない場合、自動的に起動します。

Docker 実行:

docker build -t corpus-mcp .
docker run -i -e GIT_ORG=your-github-org -e GIT_PAT=your-github-pat corpus-mcp

🤖 AI クライアントへの登録

Antigravity

Antigravity は MCP をネイティブにサポートしています。~/.gemini/config/mcp_config.json に追加して、サーバーをグローバルに設定します:

{
  "mcpServers": {
    "corpus": {
      "command": "node",
      "args": ["/absolute/path/to/code-context-mcp/dist/src/index.js"],
      "env": {
        "GIT_ORG": "your-github-org",
        "DOTENV_CONFIG_PATH": "/absolute/path/to/code-context-mcp/.env",
        "CORPUS_DIR": "/absolute/path/to/code-context-mcp/corpus"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json に以下を追加します:

{
  "mcpServers": {
    "corpus": {
      "command": "node",
      "args": ["/absolute/path/to/code-context-mcp/dist/src/index.js"],
      "env": {
        "GIT_ORG": "your-github-org",
        "GIT_PAT": "your-github-pat",
        "CORPUS_DIR": "/absolute/path/to/code-context-mcp/corpus"
      }
    }
  }
}

Claude Code

プロジェクトのルートで以下を実行します:

claude mcp add corpus "node $(pwd)/dist/src/index.js"

🏗️ アーキテクチャとコマンド

• npm run build:corpus: GitHub 組織をクロールし、ドキュメントとカタログデータを corpus/manifest.json にダウンロードします。

• npm run build:map: マニフェストをアクティブな依存関係グラフに変換し、corpus/system-map.yaml に保存します。

• npm run build: 完全なパイプラインを実行し、TypeScript をコンパイルします。

• npm run test: ネイティブの Node.js テストランナーを使用してユニットテストを実行します。

🧩 システムマップと catalog-info.yaml

Corpus は、組織のサービスのグローバルな依存関係グラフを自動的に生成します。システムマップに参加するには、各リポジトリのルートに Backstage Descriptor Format に準拠した catalog-info.yaml ファイルが含まれている必要があります。

Corpus は Backstage カタログプロセッサのように動作するため、任意のエンティティタイプ（Component、API、System、Group）を抽出し、双方向の関係を自動的に配線します。Component が owner: group:auth-team と providesApis: [api:auth-api] を定義している場合、Corpus は自動的に ownedBy/ownerOf と providesApi/apiProvidedBy のエッジを生成し、AI エージェントが組織全体のサービスグラフをネイティブにトラバースできるようにします。

catalog-info.yaml の例:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-auth-service
  description: Handles user authentication and token generation
spec:
  type: service
  lifecycle: production
  owner: group:auth-team
  providesApis:
    - api:auth-api
  dependsOn:
    - component:user-database
    - component:email-service

💡 ベストプラクティスと哲学

Corpus と AI エージェントを最大限に活用するために、以下のエコシステムプラクティスを推奨します:

1. ドキュメントをコードの近くに置く: ドキュメントはコードの隣のリポジトリに置くべきです。システムの仕組みを文書化する最適な場所は、そのシステム自体のすぐ隣です。Corpus は、すべてのリポジトリの docs/**/*.md と adr/**/*.md を自動的に取得します。

2. 中央 Wiki リポジトリ: 複数のシステムにまたがる全社的なアーキテクチャ決定、RFC、コード品質基準がある場合は、それらをマークダウンファイルとして中央の「Wiki」リポジトリに保管してください。Corpus はそれらを完璧に集約します。

3. Spotify Backstage との相乗効果: Backstage を使用している場合、Corpus は完璧なコンパニオンです。

   • Backstage は 人間 向けに構築された Internal Developer Portal（IDP）であり、リッチな Web UI を提供します。

   • Corpus は AI エージェント 向けに構築された IDP であり、MCP を介してまったく同じコンテキストを公開します。 Corpus は標準の catalog-info.yaml ファイルをネイティブに解析するため、重複する作業はゼロです。チームがすでに Backstage 用に dependsOn、lifecycle、owner タグを定義している場合、Corpus は自動的にそれらを収集し、AI エージェントがトラバースできるアクティブなグラフに変換します。

4. 頻繁な自動更新: コーパスは組織の生きたスナップショットであることを意図しています。ビルドスクリプト（npm run build）を実行すると、コーパスがローカルで再取得され再構築されます。これは単純な API スクレイピングスクリプトであるため、ビルドに LLM トークンを消費しません。理想的には、Corpus は社内に中央展開し、cron ジョブ（GitHub Action など）を使用して毎晩 manifest.json を再構築し、開発者に配布するべきです。

🤝 コントリビューション

コントリビューションを歓迎します！開始方法、開発環境のセットアップ、Pull Request の提出方法の詳細については、コントリビューションガイドライン をご覧ください。

このプロジェクトは Conventional Commits を採用しています。pre-commit フックがコードを Prettier で自動フォーマットし、ESLint でチェックします。

詳細については、セットアップスキルガイド をご覧ください。

📄 ライセンス

Corpus は無料で使用できます。すべての知的財産は Sayam Hussain が所有しています。

このプロジェクトは MIT ライセンス の下でライセンスされています。