MCP Knowledge Assistant

読み取り専用のModel Context Protocol（MCP）サーバーで、AIクライアントがナレッジベースを検索し、完全なソースドキュメントを取得できるようにします。このプロジェクトは小さなローカルプロトタイプから始まり、同じツール契約をOpenAIベクターストアからのセマンティック検索に適用します。

このプロジェクトが示すもの

• 狭いsearchとfetchの責務を持つMCPツールの設計

• FastMCPとPydanticを使用した構造化された入力と出力

• OpenAIベクターストアにアップロードされたドキュメントに対するセマンティック検索

• ベクター検索が複数の一致チャンクを返す場合のドキュメントレベルの重複排除

• Streamable HTTPおよびstdio MCPトランスポート

• OpenAI Responses APIとセキュアなMCPトンネルを通じたエンドツーエンドのツール利用

• ソースコードに認証情報を含めず、環境変数による設定

• 有料API呼び出しを行わないユニットテストおよびプロトコルレベルのテスト

Related MCP server: File AI

アーキテクチャ

OpenAI Responses API
        |
        | MCP tool calls through an outbound secure tunnel
        v
Local FastMCP server (Streamable HTTP)
        |
        | vector-store search and file retrieval
        v
OpenAI vector store -> uploaded documents

このリポジトリには、完全にローカルで動作する学習パスも含まれています：

Local demo client -> FastMCP server (stdio) -> data/documents.json

両方のサーバーは同じ公開ツール契約を公開します：

発見と取得を分離することで、必要になる前に完全なドキュメントを送信することを避け、モデルが後続の呼び出しで使用する安定したドキュメントIDを提供します。

プロジェクト構造

.
├── data/documents.json                   # Sample local knowledge base
├── sample_data/cats.pdf                  # Public-domain vector-store sample
├── src/mcp_knowledge_assistant/
│   ├── knowledge_base.py                 # Local keyword retrieval
│   ├── models.py                         # Shared response schemas
│   ├── server.py                         # Local stdio MCP server
│   └── vector_store_server.py            # OpenAI vector-store MCP server
├── tests/                                # Offline unit and MCP tests
├── demo_client.py                        # Local stdio demonstration
├── vector_store_demo_client.py           # Direct HTTP MCP demonstration
└── api_client.py                         # Responses API + secure tunnel demonstration

要件

• Python 3.11以降

• ベクターストアパス用に課金が有効なOpenAI APIプロジェクト

• OpenAIベクターストアにアップロードされた同梱のサンプルPDF、または独自のドキュメント

• セキュアトンネルのデモンストレーションにのみ必要なOpenAIトンネルクライアント

ローカルJSONサーバーと完全なテストスイートはAPIキーを必要としません。

サンプルドキュメントの帰属

ベクターストアのデモンストレーションでは、W. Gordon Stables著、Project Gutenberg電子書籍#43429のCats: Their Points and Characteristicsを使用しています。サンプルPDFはOpenAIがホストしており、Project Gutenberg版から作成されました。Project Gutenbergのライセンスと適用される再利用条件についてはPDFを参照してください。

セットアップ

リポジトリをクローンし、仮想環境を作成して、プロジェクトをインストールします：

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

OpenAIを利用する例では、環境テンプレートをコピーします：

cp .env.example .env.local

次に、.env.localに独自の値を追加します：

OPENAI_API_KEY=your_project_api_key
VECTOR_STORE_ID=vs_your_vector_store_id

.env.local、PyCharm設定、仮想環境、ローカルトンネルプロファイルはGitから除外されています。

1. ローカルプロトタイプを実行する

最初のサーバーはstdioを使用するため、MCPクライアントが子プロセスとして起動し、標準入力と標準出力を介して通信します：

python demo_client.py

デモは両方のツールを発見し、サンプルJSONナレッジベースを検索して、選択したドキュメントを取得します。

インストールされたコマンドでサーバーを起動することもできます：

mcp-knowledge-assistant

接続されたクライアントのないstdioサーバーでは、静かに待機するプロセスが正常です。

2. ベクターストアサーバーを実行する

sample_data/cats.pdfをOpenAIベクターストアにアップロードし、.env.localにOPENAI_API_KEYとVECTOR_STORE_IDを設定します。必要に応じて独自のドキュメントとクエリに置き換えても構いません。Streamable HTTPサーバーを起動します：

mcp-vector-store-assistant

デフォルトでは、MCPエンドポイントは次のとおりです：

http://127.0.0.1:8000/mcp

別のターミナルで、エンドポイントを直接テストします：

python vector_store_demo_client.py

ベクター検索はチャンク単位で動作するため、長いドキュメントでは同じファイルIDを持つ複数の一致が発生する可能性があります。MCPのsearchツールは、これらの一致を意図的に1つのドキュメント結果にまとめます。その後、fetchツールがそのドキュメントの解析済みコンテンツを取得して結合し、モデルに提供します。

3. Responses APIを通じて呼び出す

OpenAIのセキュアMCPトンネルガイドに従ってトンネルを作成し、無視されるローカルプロファイルがhttp://127.0.0.1:8000/mcpをターゲットにするように設定し、トンネルクライアントを起動します。結果のIDを.env.localに追加します：

MCP_TUNNEL_ID=tunnel_your_tunnel_id

トンネルクライアントは、CONTROL_PLANE_API_KEYから独自のランタイム認証情報を読み取ります。この値もローカルに保持してください。ベクターサーバーとトンネルクライアントの両方が実行されている状態で、以下を実行します：

python api_client.py

Responses APIリクエストは、読み取り専用のsearchおよびfetch MCPツールのみを宣言します。モデルは検索し、選択したソースを取得し、取得したコンテンツから回答を構成できます。

テスト

すべてのテストを実行するには：

pytest

テストは、ローカルのランキングと取得、MCPツールの発見、ベクター結果の重複排除、コンテンツの組み立て、入力検証をカバーしています。OpenAI呼び出しはモックされているため、スイートは再現可能で、APIクレジットを消費しません。

設計上の決定と範囲

• 読み取り専用を優先： どちらのMCPツールもファイルや外部状態を変更しません。

• 安定した互換性契約： search(query)はドキュメント参照を返し、fetch(id)は完全なコンテンツとメタデータを返します。

• チャンク結果ではなくドキュメント結果： チャンクはベクターストア内の検索エビデンスであり、MCPクライアントは安定したファイルIDを受け取ります。

• MCPは抽象化レイヤー： 単一のOpenAIホスト型ベクターストアの場合、Responses APIの組み込みFile Searchツールの方がシンプルです。MCPは、同じ検索インターフェースを複数のクライアントに提供する必要がある場合、バックエンドの詳細を隠す必要がある場合、または後で認可とドメインロジックを追加する場合に有用になります。

• 検証済みの統合境界： ローカルサーバー、直接のMCPクライアント、セキュアトンネルを通じたResponses APIパスは、開発中に実行されました。このリポジトリは、デプロイされた公開サーバーや公開されたChatGPTアプリを主張するものではありません。

セキュリティに関する注意事項

• .env.local、APIキー、トンネルランタイムキー、組織IDをコミットしないでください。

• プロジェクトスコープの認証情報を使用し、必要な権限のみを付与してください。

• インバウンドのファイアウォールポートを開くのではなく、ローカルMCPサーバーをセキュアなアウトバウンドトンネルの背後にバインドしたままにしてください。

• 書き込みや結果を伴うアクションを追加する前に、ツールの権限を確認してください。

参考資料

• OpenAI MCPガイド

• OpenAI File Searchガイド

• OpenAIセキュアMCPトンネルガイド

• FastMCPドキュメント