MCPサーバー・コードベース・アナライザー

TypeScriptコードベースを分析し、コードの健全性の問題を検出し、システムインシデントを取得し、実行可能な修復計画を生成するプロダクショングレードのMCP（Model Context Protocol）サーバーです。デュアルトランスポート（ローカル開発用のSTDIO、クラウドデプロイ用のSSE）をサポートしています。ts-morph、Express、Zodバリデーションを使用して構築されています。

🚀 機能

3つのコアツール:

1. analyze_codebase_health — TypeScriptリポジトリをスキャンして以下を検出します:

   • 大きなファイル（リファクタリング候補）

   • 明示的な関数型の欠如（弱い型付け）

   • 循環依存関係（アーキテクチャ上の問題）

   • ASTレベルの分析に ts-morph を使用

2. fetch_system_incidents — 構造化されたインシデントデータを返します:

   • モックインシデントデータ（テストやデモに最適）

   • 設定可能な遅延と障害モード

   • LLMフレンドリーなJSONレスポンス

3. generate_remediation_plan — 実行可能な修正計画を作成します:

   • スタックトレースからの根本原因分析

   • ステップバイステップの修復手順

   • コードの提案とベストプラクティス

   • リスクレベル評価

すべてのツールは、LLMでの利用を想定した構造化された成功/エラーエンベロープを返します。

アーキテクチャの概要

flowchart LR
    Client[McpClient] --> Runtime[RuntimeSelector]
    Runtime -->|stdio| Stdio[StdioTransportAdapter]
    Runtime -->|sse| Sse[SseTransportAdapter]
    Stdio --> Server[McpServer]
    Sse --> Server
    Server --> Registry[ToolRegistry]
    Registry --> ToolA[analyze_codebase_health]
    Registry --> ToolB[fetch_system_incidents]
    Registry --> ToolC[generate_remediation_plan]

ローカル実行 (STDIO)

1. 依存関係のインストール:

   • npm install

2. サーバーの起動:

   • npm run dev:stdio

3. サーバーがstdin/stdout経由で起動し、ローカルのMCPクライアントの準備が整います。

SSEでの実行 (Express)

1. 環境変数の設定:

   • TRANSPORT=sse

   • オプション: AUTH_TOKEN=your-secret-token

2. サーバーの起動:

   • npm run dev:sse

3. エンドポイント:

   • SSEストリーム用の GET /events

   • MCP JSON-RPCメッセージ用の POST /messages?sessionId=...

Cursorからの接続

ローカルで使用する場合、Nexus-Coreをstdio MCPサーバーとして登録します:

• command: node

• args: dist/index.js (ビルド後) または tsx src/index.ts (開発時)

• env: TRANSPORT=stdio

ホスト環境で使用する場合、MCPクライアントがSSEエンドポイントを使用するように設定します:

• stream URL: https://<host>/events

• message URL: https://<host>/messages?sessionId=<session-id>

• トークン認証が有効な場合は Authorization: Bearer <AUTH_TOKEN> を追加してください。

プロンプトの例

• "Analyze my repo" (リポジトリを分析して)

• "Fetch incidents" (インシデントを取得して)

• "Fix this error" (このエラーを修正して)

環境変数

サポートされているすべての設定については .env.example を参照してください。重要な制御項目:

• TRANSPORT: stdio または sse

• TOOL_TIMEOUT_MS: 各ツール呼び出しのハードタイムアウト

• TS_MORPH_MAX_FILES, TS_MORPH_MAX_DEPTH: 分析のガードレール

• INCIDENT_API_TIMEOUT_MS, INCIDENT_API_RETRIES: 外部依存関係の制御

• SSE_HEARTBEAT_MS, SSE_SESSION_TTL_MS: SSEセッションのライフサイクル

本番環境へのデプロイ

Docker

• イメージのビルド: docker build -t nexus-core .

• コンテナの実行:

  • docker run -e TRANSPORT=sse -e PORT=8080 -p 8080:8080 nexus-core

Cloud Run

deploy.sh を使用します:

PROJECT_ID=<gcp-project> REGION=<region> SERVICE=nexus-core ./deploy.sh

このスクリプトは以下の処理を行います:

1. コンテナイメージのビルド

2. GCRへのプッシュ

3. Cloud Runへのデプロイ

信頼性とエラーモデル

• すべてのツールリクエストはZodで検証されます。

• ツール実行で未処理の例外が返されることはありません。

• エラーは以下の項目を含む標準エンベロープを使用します:

  • code

  • message

  • retryable

  • suggestedAction

  • meta (requestId, toolName, タイミング)