CIViC MCP Server

CIViC MCP サーバー

これは、CIViC（Clinical Interpretation of Variants in Cancer）API をクエリするツールを提供する、Cloudflare Workers ベースの Model Context Protocol（MCP）サーバーです。このサーバーは、Durable Objects を使用して効率的にデータを処理し、GraphQL のレスポンスをクエリ可能な SQLite テーブルに変換します。

CIViC データベースは、がんのバリアントに関する臨床的解釈を集約した、クラウドソーシング型のリポジトリです。この MCP サーバーを使用すると、AI アシスタントとの自然言語でのやり取りを通じて、がんゲノミクス情報を構造化クエリで検索し、分析できます。

MCP 仕様への準拠

このサーバーは、fleet のステートレス SDK v2 アダプターを通じて MCP 2026-07-28 を実装しています。

• server/discover が初期化に代わり、すべてのリクエストにプロトコルと機能のエンベロープが含まれます。
• Worker はステートレスな Streamable HTTP を使用し、MCP セッション Durable Object や Mcp-Session-Id は使用しません。
• SDK は Mcp-Method／Mcp-Name を検証し、resultType と serverInfo を付与して、キャッシュヒントを提供します。
• ツールリストの登録順は決定的です。
• ツールは成功時とエラー時の両方で content と structuredContent を返し、エラー時には isError: true を設定します。
• 大規模な構造化結果では、fleet のステージングと 100KB の転送保護が維持されます。

ツールアノテーションのリファレンス

このサーバーは、MCP クライアント向けに包括的なツールアノテーションを定義しています。

// GraphQL Query Tool
annotations: {
  readOnlyHint: false,      // Creates/modifies data in SQLite
  destructiveHint: false,   // Non-destructive data staging
  idempotentHint: false,    // Different queries produce different results
  openWorldHint: true       // Interacts with external CIViC API
}

// SQL Query Tool  
annotations: {
  readOnlyHint: true,       // Only reads data
  destructiveHint: false,   // Cannot modify data (read-only SQL)
  idempotentHint: true,     // Same query produces same results
  openWorldHint: false      // Operates on closed SQLite database
}

トランスポート

// MCP 2026-07-28 stateless Streamable HTTP
CivicMCP.serve("/mcp").fetch(request, env, ctx)

保持される Durable Objects は、ステージングに使用されるアプリケーション／データオブジェクトのみです。MCP トランスポートセッションではありません。

機能

• GraphQL から SQL への変換：CIViC API のレスポンスを、構造化された SQLite テーブルに自動変換します
• 効率的なデータストレージ：Cloudflare Durable Objects と SQLite を使用して、データのステージングとクエリを行います
• スマートなレスポンス処理：小規模なレスポンス、エラー、スキーマイントロスペクションクエリではステージングを省略し、パフォーマンスを最適化します
• ツールパイプライン：
  1. civic_graphql_query：GraphQL クエリを実行し、大規模なデータセットをステージングします
  2. civic_query_sql：ステージングされたデータを SQL で分析できます
  3. civic_execute：コードモード — gql.query() とスキーマヘルパーを使用して、V8 アイソレート内で JavaScript を実行し、GraphQL にフルアクセスできます

インストールと設定

前提条件

• Cloudflare アカウント
• Wrangler CLI がインストールされていること
• Claude Desktop アプリ

Cloudflare Workers へのデプロイ

1. このリポジトリをクローンします。

   git clone <repository-url>
   cd civic-mcp-server
   

2. 依存関係をインストールします。

   npm install
   

3. Cloudflare Workers にデプロイします。

   npm run deploy
   

4. デプロイ後、次のような URL が発行されます：https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev

Claude Desktop の設定

claude_desktop_config.json ファイルに次の設定を追加します。

{
  "mcpServers": {
    "civic-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://civic-mcp-server.quentincody.workers.dev/mcp"
      ]
    }
  }
}

quentincody を、お使いの Cloudflare Workers のサブドメインに置き換えてください。

使用方法

設定が完了したら、Claude Desktop を再起動します。このサーバーでは、次の 3 つの主要なツールを使用できます。

1. civic_graphql_query：CIViC API に対して GraphQL クエリを実行します
2. civic_query_sql：SQL を使用してステージングされたデータをクエリします
3. civic_execute：コードモード — V8 アイソレート内で CIViC GraphQL API を操作する JavaScript を記述します

プロンプト

このサーバーは、正しい GraphQL 構文と堅牢な検索戦略を用いて civic_graphql_query ツールを使用するようモデルを導く、3 つの MCP プロンプトを公開しています。

個別のデータ型プロンプト

• get-variant-evidence — Evidence Items のみを対象とする GraphQL を生成します（variantName フィルターは CIViC スキーマでサポートされていないため使用しません）
• get-variant-assertions — Assertion のみを対象とする GraphQL を生成し、体系的なフォールバック戦略を使用します

統合データプロンプト

• get-variant-data — Evidence Items と Assertions の両方のクエリを実行し、包括的なバリアント分析を行います

使用例（VS Code Copilot Chat／スラッシュコマンド）：

• /get-variant-evidence molecularProfileName:"TP53 Mutation" diseaseName:"Lung Adenocarcinoma" evidenceType:"PROGNOSTIC" first:"200"
• /get-variant-assertions molecularProfileName:"TPM3-NTRK1 Fusion" therapyName:"Larotrectinib" status:"ALL"
• /get-variant-data molecularProfileName:"BRAF V600E" diseaseName:"Melanoma" therapyName:"Trametinib" status:"ALL"

主なプロンプト機能

• 確実な GraphQL 生成：失敗しない、完全かつ検証済みのクエリ
• インテリジェントな検索戦略：関連データを見つけるための代替アプローチを自動的に使用します
• 包括的な結果：Evidence Items には臨床的な説明が含まれ、Assertions には概要が示されます
• 最適なフィルタリング：過剰なフィルタリングを避けるため、ステータスのデフォルト値は "ALL" です。null パラメーターは自動的に除外されます
• 適切な URL の生成：検証用の正規リンク（evidence：/evidence/{id}、assertions：/assertions/{id}）

これらのプロンプトは、CIViC v2 スキーマに適合した完全な GraphQL クエリと体系的な検索手法を提供します。ユーザーが不完全なパラメーターを指定した場合でも、データを確実に見つけられます。

クエリの例

Claude には、次のような質問をできます。

• 「BRAF 変異に関する最新の Evidence Items は何ですか？」
• 「肺がんのバリアントに関する治療的解釈をすべて表示してください」
• 「CIViC データベースで最も多くの Evidence Items がある遺伝子を見つけてください」

Claude はサーバー（およびその civic_graphql_query ツール）を使用して、CIViC データベースから関連データを取得し、提示します。このサーバーは CIViC API のバージョン 2 にクエリを実行するよう設計されているため、最新の情報を取得できます。

問題が発生した場合や、Claude が CIViC のデータを使用していないように見える場合は、上記の設定手順を再確認してください。

レスポンスの処理

このサーバーは、大きな結果を一時的な SQLite データベースに保存することで、コンテキストの使用をインテリジェントに最適化します。GraphQL のレスポンスが特定の条件を満たす場合、データベースを作成せず、未加工のレスポンスを直接返します。

• 小さなレスポンス（1500 文字未満）：不要なオーバーヘッドを避けるため、直接返します
• エラーレスポンス：トラブルシューティングを容易にするため、そのまま渡します
• 空／null のレスポンス：空のデータベースの作成を避けるため、処理を省略します
• スキーマイントロスペクションクエリ：__schema、__type、またはその他のイントロスペクションパターンを含むクエリは、SQL 変換に適したデータではなくメタデータを含むため、直接返します

この最適化により、サーバーの効率とエラーの可視性が向上するとともに、大規模なデータセットに対する強力な SQL ベースの分析も引き続き利用できます。

ライセンス

MIT ライセンス（学術引用の要件あり）— LICENSE.md を参照してください