Skip to main content
Glama
deenesjakoruzh
channico

MCP Knowledge Assistant

by channico
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

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

ツール

入力

目的

search

query: string

コンパクトで関連性の高いドキュメント参照を返します。

fetch

id: string

検索で選択された完全なドキュメントを1件取得します。

発見と取得を分離することで、必要になる前に完全なドキュメントを送信することを避け、モデルが後続の呼び出しで使用する安定したドキュメント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サーバーをセキュアなアウトバウンドトンネルの背後にバインドしたままにしてください。

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

参考資料

Available Tools

2 tools
fetchA

Retrieve one complete document using an ID returned by search.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
urlYes
textYes
titleYes
metadataNo

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals that this returns a complete document (not a summary) and that it depends on search-generated IDs, but doesn't mention error handling, permissions, or potential side effects. For a simple read operation this is adequate but has gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, no redundant details, and the key information (retrieve by ID) is front-loaded. Perfect conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema is present and there is only one parameter, the description sufficiently covers the essential context and its relationship to the sibling search tool. It could be improved by mentioning error cases or what happens if the ID is invalid, but for this simplicity it is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'id' has no schema description, so the description's phrase 'returned by search' provides crucial semantic context, explaining where the ID comes from and how it should be used to retrieve the document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Retrieve' with the resource 'one complete document' and the qualifier 'using an ID returned by search', which clearly defines the tool's scope and distinguishes it from the sibling tool 'search'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states that the ID must come from search, establishing a clear workflow (search first, then fetch). It doesn't explicitly mention alternatives, but the context is clear enough for an agent to know when to use this tool versus search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedfetch
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

search and fetch have clearly distinct purposes: one finds documents by query, the other retrieves a specific document by ID. There is no overlap or ambiguity.

Naming Consistency5/5

Both tools use simple, consistent single-verb names ('search' and 'fetch') that clearly indicate their actions. The pattern is uniform.

Tool Count3/5

With only 2 tools, the server is minimal but functionally complete for a simple search-and-retrieve pattern. It feels thin but is reasonable for a narrow purpose.

Completeness4/5

The two tools cover the core workflow of searching and retrieving documents. Minor gaps could include listing all documents or getting metadata, but the essential lifecycle is covered.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • RAG Docs MCP Server

    gorizond
    A
    license
    Not graded
    quality
    A
    maintenance
    An MCP server that provides tools for retrieving and processing documentation through vector search, enabling AI assistants to augment their responses with relevant documentation context.
    24 npm
    MIT

  • File AI

    flyfish-dev
    A
    license
    B
    quality
    D
    maintenance
    A read-only MCP server that provides document awareness for agents by parsing local files into structured profiles, blocks, chunks, and search results, enabling agents to understand and cite document content without dealing with raw file formats.
    5
    43 npm
    3
    Apache 2.0

  • CasioPlus MCP

    hadiranweb
    F
    license
    Not graded
    quality
    B
    maintenance
    An MCP server that connects the Casio Plus knowledge base (playbooks, architecture, learning resources) to AI clients, offering read-only search and validation tools along with controlled feedback intake and review workflows.
    -