MCP-RAG

✨100% von KI geschrieben

Ein dienstorientierter RAG-Service für KI-Clients, der derzeit hauptsächlich auf FastAPI HTTP-Diensten und Streamable HTTP MCP-Endpunkten basiert.

Der Code bietet derzeit eine einheitliche Backend-Shell:

• FastAPI HTTP-Dienst

• Streamable HTTP MCP

• Gemeinsame Laufzeit, Konfigurations-Hot-Reload, Authentifizierung, Ratenbegrenzung, Quoten, Beobachtbarkeit

• Abruf und Dokumentenverwaltung basierend auf einem Wissensdatenbank-Register

Aktuelle Funktionen

• Dokumentenimport: Unterstützt das direkte Hinzufügen von Text sowie das Hochladen von txt, md, pdf, docx

• Abruf: Kombination aus Vektorabruf + Schlüsselwortabruf

• Q&A: /search, /chat, MCP rag_ask

• Mehrere Wissensdatenbanken: Unterstützt einzelne Wissensdatenbanken und aggregierte Abrufe/Dialoge über mehrere kb_ids hinweg

• Wissensdatenbank-Geltungsbereich: public und agent_private

• Mandantenkontext: base_collection + user_id + agent_id

• Laufzeit-Governance: API-Key, Speicher-Ratenbegrenzung, Upload-/Index-Quoten, Request-Level Retrieval Cache

• Provider-Governance: Provider-Budget, Circuit Breaking, Fallback

• Beobachtbarkeit: /health, /ready, /metrics

• Frontend: Integriertes Single-Page-Verwaltungspanel /app

Architektur

Haupt-Link:

HTTP / MCP
  -> app_factory.py
  -> http_server.py / mcp_server.py
  -> context.py
  -> service_facade.py
  -> services/
       - runtime.py
       - indexing_service.py
       - retrieval_service.py
       - chat_service.py
  -> knowledge_bases.py
  -> core/indexing/
  -> retrieval/

Schlüsseldateien:

• src/mcp_rag/cli.py: CLI-Einstiegspunkt, bietet serve und init

• src/mcp_rag/main.py: Start-Einstiegspunkt für den HTTP-Dienst

• src/mcp_rag/http_server.py: HTTP API, SPA-Einstiegspunkt, Einbindung von Streamable HTTP MCP

• src/mcp_rag/mcp_server.py: MCP-Tool-Definition und rag_ask

• src/mcp_rag/app_factory.py: Einheitliche Assemblierung von App-Kontext, Laufzeit und Guardrails

• src/mcp_rag/knowledge_bases.py: Wissensdatenbank-Register und Standard-Wissensdatenbank-Auflösung

• src/mcp_rag/config.py: Konfigurationsmodell, JSON/SQLite-Persistenz, Hot-Reload

Systemanforderungen

• Python >= 3.13

• uv

Installation

CLI installieren:

uv tool install mcp-rag

Nach der Installation direkt ausführen:

mcp-rag serve

Entwicklung im Repository:

uv sync

Falls lokales Embedding benötigt wird:

uv sync --extra local-embeddings

Hinweise zu den Grenzen:

• Benutzer, die uv tool install mcp-rag verwenden, benötigen kein Node.js und kein pnpm

• pnpm wird nur für die Wartung des Frontend-Builds verwendet, nicht als Laufzeitabhängigkeit des Dienstes

Start und Initialisierung

Dienst starten:

uv run mcp-rag serve

Datenverzeichnis initialisieren:

uv run mcp-rag init --data-dir ./data

Der Standardport ist 8060, der Dienst lauscht standardmäßig auf 0.0.0.0:8060.

Gebräuchliche Einstiegspunkte:

• Verwaltungspanel: http://127.0.0.1:8060/app

• API-Dokumentation: http://127.0.0.1:8060/docs

• MCP-Endpunkt: http://127.0.0.1:8060/mcp

Kompatible Einstiegspunkte:

• / leitet zu /app weiter

• /doc leitet zu /docs weiter

• /documents-page leitet zu /app/documents weiter

• /config-page leitet zu /app/config weiter

Verhalten beim ersten Start:

• Wenn ./data/config.json nicht existiert, werden beim Lesen der Konfiguration Standardwerte verwendet

• Beim Start des Dienstes wird ensure_config_file() aufgerufen, um die Standardkonfiguration auf die Festplatte zu schreiben

• ./data/chroma und zugehörige SQLite-Dateien im Datenverzeichnis werden bei Bedarf erstellt

Frontend und statische Ressourcen

Das Release-Paket packt src/mcp_rag/static/ zusammen in das Wheel / sdist.

Das bedeutet:

• Benutzer, die uv tool install mcp-rag ausführen, können direkt auf /app zugreifen

• Es ist kein separates Build des Frontends erforderlich, auch kein Node.js

• Frontend-Maintainer müssen vor der Veröffentlichung die neuesten statischen Ressourcen generieren

Der Frontend-Quellcode befindet sich in frontend/, der Build wird nach src/mcp_rag/static/app ausgegeben.

Typischer Ablauf:

cd frontend
pnpm install
pnpm build

Wissensdatenbank-Modell

Das aktuelle Projekt verlässt sich nicht mehr nur auf nackte collection zur Datenorganisation, sondern primär auf ein Wissensdatenbank-Register.

Wissensdatenbank-Eigenschaften:

• Das persistente Register befindet sich in der SQLite-Datei, auf die knowledge_base_db_path verweist

• Standardmäßig wird sichergestellt, dass eine öffentliche Wissensdatenbank existiert

• Wenn user_id + agent_id übergeben werden, wird sichergestellt, dass eine entsprechende agent_private Wissensdatenbank existiert

• Nach dem Erstellen einer neuen Wissensdatenbank wird ein stabiler interner Sammlungsname zugewiesen, z. B. kb_<id>

Die Schnittstellenebene behält den collection-Parameter bei, um Kompatibilität mit alten Aufrufmethoden zu gewährleisten. Das aktuelle tatsächliche Verhalten ist:

• Es kann explizit eine kb_id übergeben werden

• Es kann weiterhin die alte collection übergeben werden

• Der Dienst löst die Anfrage in die spezifische Wissensdatenbank und den tatsächlichen Sammlungsnamen auf

HTTP-Schnittstellen

Systemschnittstellen:

• GET /health

• GET /ready

• GET /metrics

Konfigurationsschnittstellen:

• GET /config

• POST /config

• POST /config/bulk

• POST /config/reset

• POST /config/reload

Anbieterschnittstellen:

• GET /providers/{provider}/models

Wissensdatenbank-Schnittstellen:

• GET /collections

• GET /knowledge-bases

• POST /knowledge-bases

Dokumentenschnittstellen:

• POST /add-document

• POST /upload-files

• GET /list-documents

• DELETE /delete-document

• GET /list-files

• DELETE /delete-file

Abruf und Q&A:

• GET /search

• POST /chat

MCP-Debug-Schnittstellen:

• GET /debug/mcp/tools

• POST /debug/mcp/call

Einige Punkte zur Klarstellung:

• /search und /chat unterstützen kb_id

• /search und /chat unterstützen auch kb_ids für die aggregierte Suche über mehrere Wissensdatenbanken

• /upload-files verwendet multipart/form-data

• /delete-document und /delete-file übergeben Löschparameter über den Request-Body

Wenn Sicherheitsrichtlinien aktiviert sind, kann der API-Key wie folgt übergeben werden:

• HTTP Header: x-api-key

• Header: Authorization: Bearer <token>

• api_key in Abfrageparametern, JSON-Body oder Formular

MCP

Die aktuelle Hauptform ist Streamable HTTP MCP:

{
  "mcpServers": {
    "rag": {
      "url": "http://127.0.0.1:8060/mcp"
    }
  }
}

Implementierte MCP-Tools:

• rag_ask

Hauptparameter von rag_ask:

• query

• mode: raw oder summary

• collection

• kb_id

• scope

• limit

• threshold

• tenant

• user_id / agent_id

• _user_id / _agent_id

• api_key

• request_id

• trace_id

Beispiel:

{
  "name": "rag_ask",
  "arguments": {
    "query": "FastAPI 是什么",
    "kb_id": 1,
    "mode": "summary",
    "limit": 5
  }
}

Konfiguration

Standard-Konfigurationsdatei:

./data/config.json

Standard-Wissensdatenbank-Datenbank:

./data/knowledge_bases.sqlite3

Die aktuelle Konfiguration weist eine wichtige Änderung auf:

• Allgemeine Laufzeitkonfigurationen werden in config.json gespeichert

• Provider-bezogene Konfigurationen werden in SQLite persistiert, anstatt sie weiterhin vollständig in config.json zurückzuschreiben

Das bedeutet, dass diese Felder in service_provider_settings in SQLite gespeichert werden:

• embedding_provider

• embedding_fallback_provider

• provider_configs

• llm_provider

• llm_fallback_provider

• llm_model

• llm_base_url

• llm_api_key

Die übrigen Konfigurationen werden weiterhin in config.json gespeichert, zum Beispiel:

{
  "http_port": 8060,
  "chroma_persist_directory": "./data/chroma",
  "knowledge_base_db_path": "./data/knowledge_bases.sqlite3",
  "enable_llm_summary": false,
  "security": {
    "enabled": false,
    "allow_anonymous": true,
    "api_keys": [],
    "tenant_api_keys": {}
  },
  "rate_limit": {
    "requests_per_window": 120,
    "window_seconds": 60,
    "burst": 30
  },
  "quotas": {
    "max_upload_files": 20,
    "max_upload_bytes": 52428800,
    "max_upload_file_bytes": 10485760,
    "max_index_documents": 500,
    "max_index_chunks": 2000,
    "max_index_chars": 500000
  },
  "cache": {
    "enabled": false,
    "max_entries": 256,
    "ttl_seconds": 300
  },
  "provider_budget": {
    "enabled": true
  }
}

Aktuelle integrierte Provider-Funktionen:

• Standardwert für Embedding-Provider ist zhipu

• Standardwert für LLM-Provider ist doubao

• Integrierte Provider-Konfigurationen umfassen doubao, zhipu, aliyun

• qwen / dashscope werden zu aliyun normalisiert

• /providers/{provider}/models unterstützt das Abrufen von Modelllisten von OpenAI-kompatiblen Modelldiensten

• Lokales Embedding unterstützt m3e-small und e5-small

• LLM unterstützt zusätzlich ollama

Hot-Reload und Laufzeit-Aktualisierung

Verhalten bei Hot-Reload:

• Nach Änderungen über /config, /config/bulk, /config/reset, /config/reload wird die Laufzeit sofort aktualisiert

• Wenn eine Anfrage eingeht, wird über reload_if_changed() geprüft, ob sich die Festplattenkonfiguration geändert hat

• Nach Änderungen an Provider-Einstellungen oder Abrufkonfigurationen werden die zugehörigen Laufzeitabhängigkeiten neu erstellt und der Abruf-Cache geleert

Readiness und Metrics

• /health gibt eine Gesundheitszusammenfassung, einen Laufzeit-Snapshot und config_revision zurück

• /ready gibt 503 zurück, wenn das Bootstrap nicht abgeschlossen ist oder kritische Abhängigkeiten nicht bereit sind

• /metrics gibt Beobachtungsmetriken zurück, aggregiert nach Operation / Provider

Der aktuelle Readiness-Snapshot enthält:

• document_processor

• embedding_model

• vector_store

• hybrid_service

• llm_model

• retrieval_cache

• provider_budget

Tests

Alle Tests ausführen:

uv run python -m unittest discover -s tests

Kompilierungsprüfung:

uv run python -m compileall src

Aktuelle Testabdeckung:

• Konfigurations-Standardwerte, Festplatten-Reload und Provider-Konfigurationsmigration

• Verhalten der HTTP-Shell und MCP-Shell

• Request-Kontext / Mandanten-Auflösung

• Request-Level Retrieval Cache

• Provider-Budget / Fallback

• Readiness / Health / Metrics

• Paket-Metadaten und statische Ressourcen

Lizenz

MIT