mcp-chat

Neo4jベースのチャットボットMCPサーバー実装方法のまとめ。

MCPサーバー作成の原則

Tool設計 — APIではなくモデルの行動を設計する

• REST APIをミラーリングしない。Endpoint一つにつきtool一つではなく、モデルが実行する作業単位でまとめる。

• Toolの数は少なく、descriptionは長く。Descriptionは、いつ使うか／使ってはいけないか、引数の例、返却形式まで記載したドキュメントである。Descriptionこそがプロンプトである。

• 出力はトークン予算内で設計する。Raw JSONダンプの代わりにモデルが読みやすい形式でフォーマットし、大量の結果には limit + pagination引数を設ける。

構造の標準パターン

• Transportの分離 — ローカルはstdio、リモートはStreamable HTTP。Serverロジックとtransportを分離しておけば、両方のサポートが容易になる。

• 入力検証はschemaで — TS SDKはzod schemaでtoolの引数を宣言する。検証を手書きしない。

• エラーはthrowではなく isError: true の結果で返す。モデルがエラーメッセージを読んで再試行できるよう、メッセージに原因と解決方法を含める。

• stdioにおいてstdoutはprotocol channelである。ログは必ずstderrに出力する。console.log一つでサーバーが停止する。

• 危険な作業はプロンプトではなくコードでブロックする。例えば読み取り専用toolでのwrite構文拒否、LIMITの強制注入。

開発ワークフロー

1. MCP Inspectorで手動テスト — npx @modelcontextprotocol/inspector node dist/index.js

2. 実際のモデルでtool選択シナリオを検証 — モデルが的外れなtoolを選択した場合、コードではなくdescriptionを修正する。

3. ビジネスロジック（クエリ検証器、フォーマッター）はMCPとは無関係のユニットテストで検証する。

Related MCP server: Neo4j GraphRAG MCP Server

実装方法4種類

1. 公式Neo4j MCPサーバーをそのまま使用

Neo4jが公式に提供するMCPサーバーを設定のみで接続する方法。

• mcp-neo4j-cypher — LLMがスキーマを照会し、Cypherを直接生成して実行するtool（get_schema, read_cypher, write_cypher）を提供する。

• mcp-neo4j-memory — 会話から抽出したエンティティ/関係をナレッジグラフとして保存する長期記憶用サーバー。

2. Text2Cypher方式の自作MCPサーバー

自作のMCPサーバーを作成し、toolは「自然言語の質問 → Cypher生成 → 実行」という汎用構造にする方法。公式サーバーと似ているが、以下を直接制御できる。

• スキーマ説明の注入（プロンプトにグラフ構造を提供）

• クエリ検証（読み取り専用の強制、LIMITの強制）

• 結果のフォーマット

3. ドメイン特化tool方式

LLMにCypherを任せず、ドメインに合わせたtoolを事前に定義する方法。各tool内部ではパラメータ化されたCypherのみを実行する。

search_person(name)          → 파라미터화된 Cypher 실행
get_relationships(id, depth) → 파라미터화된 Cypher 실행
find_path(from, to)          → shortestPath 쿼리 실행

4. GraphRAG方式

Neo4jのベクトルインデックスで類似度検索を行った後、マッチしたノードからグラフを展開（隣接ノード、関連）してコンテキストを構築する retrieve(query) tool一つを公開する方法。

retrieve(query)
  1. query 임베딩 → 벡터 인덱스 유사도 검색
  2. 매칭된 노드에서 그래프 확장 (이웃 노드, 관계 수집)
  3. 수집된 서브그래프를 컨텍스트로 반환

推奨される組み合わせ

実務では 2 + 3の混合が一般的なパターンである。よく使われる質問はドメイン特化toolで処理し、残りは読み取り専用のText2Cypherをフォールバックとして使用する。

スタック参考

• TypeScript — @modelcontextprotocol/sdk

• Python — FastMCP