Skip to main content
Glama
deenesjakoruzh
channico

MCP Knowledge Assistant

by channico
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MCP Knowledge Assistant

Ein schreibgeschützter Server für das Model Context Protocol (MCP), der einem KI-Client die Suche in einer Wissensbasis und das Abrufen vollständiger Quelldokumente ermöglicht. Das Projekt beginnt mit einem kleinen lokalen Prototypen und überträgt denselben Tool-Vertrag auf das semantische Retrieval aus einem OpenAI-Vector-Store.

Was hier demonstriert wird

  • MCP-Tool-Design mit eng begrenzten Zuständigkeiten für search und fetch

  • Strukturierte Ein- und Ausgaben mit FastMCP und Pydantic

  • Semantisches Retrieval über hochgeladene Dokumente in einem OpenAI-Vector-Store

  • Deduplizierung auf Dokumentebene, wenn die Vektorsuche mehrere passende Chunks zurückgibt

  • Streamable-HTTP- und stdio-MCP-Transporte

  • End-to-End-Tool-Nutzung über die OpenAI Responses API und einen sicheren MCP-Tunnel

  • Konfiguration über Umgebungsvariablen, ohne Credentials im Quellcode

  • Unit- und Protokollebenen-Tests, die keine kostenpflichtigen API-Aufrufe ausführen

Related MCP server: File AI

Architektur

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

Das Repository enthält außerdem einen vollständig lokalen Lernpfad:

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

Beide Server bieten denselben öffentlichen Tool-Vertrag an:

Tool

Eingabe

Zweck

search

query: string

Kompakte, relevante Dokumentverweise zurückgeben.

fetch

id: string

Ein vollständiges, über die Suche ausgewähltes Dokument abrufen.

Die Trennung von Suche und Abruf verhindert, dass vollständige Dokumente übertragen werden, bevor sie benötigt werden, und gibt dem Modell stabile Dokument-IDs für spätere Aufrufe.

Projektstruktur

.
├── 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

Anforderungen

  • Python 3.11 oder neuer

  • Ein OpenAI-API-Projekt mit aktivierter Abrechnung für den Vector-Store-Pfad

  • Das enthaltene Beispiel-PDF oder ein eigenes Dokument, hochgeladen in einen OpenAI-Vector-Store

  • Der OpenAI-Tunnel-Client nur für die Demonstration des sicheren Tunnels

Der lokale JSON-Server und die vollständige Testsuite benötigen keinen API-Schlüssel.

Quellenangabe zum Beispieldokument

Die Vector-Store-Demonstration verwendet Cats: Their Points and Characteristics von W. Gordon Stables, Project Gutenberg eBook #43429. Das Beispiel-PDF wird von OpenAI gehostet und wurde aus der Project-Gutenberg-Ausgabe erstellt. Die Project-Gutenberg-Lizenz und die anwendbaren Wiederverwendungsbedingungen entnehmen Sie bitte dem PDF.

Einrichtung

Das Repository klonieren, eine virtuelle Umgebung anlegen und das Projekt installieren:

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

Kopieren Sie für die OpenAI-gestützten Beispiele die Umgebungsvorlage:

cp .env.example .env.local

Tragen Sie anschließend Ihre eigenen Werte in .env.local ein:

OPENAI_API_KEY=your_project_api_key
VECTOR_STORE_ID=vs_your_vector_store_id

.env.local, PyCharm-Einstellungen, virtuelle Umgebungen und lokale Tunnel-Profile sind von Git ausgeschlossen.

1. Den lokalen Prototypen ausführen

Der erste Server verwendet stdio; der MCP-Client startet ihn deshalb als untergeordneten Prozess und kommuniziert über Standardeingabe und -ausgabe:

python demo_client.py

Die Demo entdeckt beide Tools, durchsucht die lokale JSON-Wissensbasis und ruft das ausgewählte Dokument ab.

Sie können den Server auch über seinen installierten Befehl starten:

mcp-knowledge-assistant

Ein stiller, wartender Prozess ist für einen stdio-Server normal, bei dem kein Client verbunden ist.

2. Den Vector-Store-Server ausführen

Laden Sie sample_data/cats.pdf in einen OpenAI-Vector-Store hoch und setzen Sie dann OPENAI_API_KEY und VECTOR_STORE_ID in .env.local. Wenn Sie möchten, können Sie ein eigenes Dokument und eine eigene Abfrage verwenden. Starten Sie den Streamable-HTTP-Server:

mcp-vector-store-assistant

Sein MCP-Endpunkt lautet standardmäßig:

http://127.0.0.1:8000/mcp

Testen Sie den Endpunkt in einem zweiten Terminal direkt:

python vector_store_demo_client.py

Die Vektorsuche arbeitet auf Chunk-Ebene, sodass ein langes Dokument mehrere Treffer mit derselben Datei-ID erzeugen kann. Das MCP-Tool search führt diese Treffer bewusst zu einem einzigen Dokumentergebnis zusammen. Das Tool fetch ruft dann den geparsten Inhalt dieses Dokuments ab und kombiniert ihn für das Modell.

3. Aufruf über die Responses API

Folgen Sie dem Leitfaden für sichere MCP-Tunnels von OpenAI, um einen Tunnel einzurichten. Konfigurieren Sie das zugehörige ignorierte lokale Profil so, dass es auf http://127.0.0.1:8000/mcp zeigt, und starten Sie den Tunnel-Client. Fügen Sie die resultierende ID in .env.local hinzu:

MCP_TUNNEL_ID=tunnel_your_tunnel_id

Der Tunnel-Client liest seine eigenen Laufzeit-Zugangsdaten aus CONTROL_PLANE_API_KEY. Bewahren Sie auch diesen Wert ausschließlich lokal auf. Mit laufendem Vector-Server und laufendem Tunnel-Client führen Sie Folgedes aus:

python api_client.py

Die Requests-API-Anfrage deklariert nur die schreibgeschützten MCP-Tools search und fetch. Das Modell kann suchen, eine ausgewählte Quelle abrufen und eine Antwort aus den abgerufenen Inhalten erstellen.

Tests

Führen Sie alle Tests aus mit:

pytest

Die Tests decken lokales Ranking und Abrufen, die MCP-Tool-Erkennung, die Deduplizierung von Vektortreffern, die Inhaltszusammenstellungen und die Eingabevalidierung ab. OpenAI-Aufrufe werden gedumt, sodass die Suite wiederholbar ist und keine API-Guthaben verbraucht.

Designentscheidungen und Umfang

  • Read-only zuerst: Keines der MCP-Tools verändert Dateien oder den externen Zustand.

  • Stabiler Kompatibilitätsvertrag: search(query) liefert Dokumentverweise; fetch(id) liefert den vollständigen Inhalt und die Metadaten.

  • Dokumentergebnisse statt Chunk-Ergebnisse: Chunks dienen im Vector-Store als Nachweis bei der Abfrage, während der MCP-Client stabile Datei-IDs erhält.

  • MCP is eine Abstraktionsschicht: Für einen einzelnen OpenAI-gehosteter Vector Store ist das in die Responses API integrierte File-Search-Tool auch sorgfältig not waiting. MCP wird dann nützlich, wenn dieselbe Abrufnnung mehrere Clients bedienen soll, Backend-Details verbergen soll oder später um Autorisierung und Fachlogik erweitert robotic.

  • Verifizierte Integrationsgrenze: Die lokalen Server, die direkten MCP-Clients sowie der Pfad über die Responses API durch den sicheren Tunnel wurden während der Entwicklung erprobt. Dieses Repository erhebt nicht, dass ich sie eingesetzde deployed public Server or a published ChatGPT app.

Sicherheitshinweise

  • Committen Sie niemals .env.local, API-Schlüssel, Tunnel-Laufzeitschlüssel oder Organisations-IDs.

  • Verwenden Sie projektspezifische Zugangsdaten und erteilen Sie nur die tatsächlich erforderlichen Berechtigungen.

  • Halten sich den lokalen MCP-Server hinter dem sicheren ausgehenden Tunnel an, anstatt einen eigehenden Firewall-Port zu öffnen.

  • Prüfen Sie die Tool-Berechtigungen, bevor Sie eine Schreib- oder eine Aktion mit Folgen hinzufügen.

Referenzen

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.
    -