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:

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

• OpenAI-MCP-Leitfaden

• OpenAI-Leitfaden zur Dateisuche

• OpenAI-Leitfaden für sichere MCP-Tunnels

• FastMCP-Dokumentation