doc-lib-mcp

doc-lib-mcp MCP-Server

Ein Model Context Protocol (MCP)-Server für die Dokumentenaufnahme, das Chunking, die semantische Suche und die Notizverwaltung.

Komponenten

Ressourcen

• Implementiert ein einfaches Notizspeichersystem mit:
  • Benutzerdefiniertes note:// URI-Schema für den Zugriff auf einzelne Notizen
  • Jede Notizressource hat einen Namen, eine Beschreibung und text/plain MIME-Typ

Eingabeaufforderungen

• Bietet eine Eingabeaufforderung:
  • summarize-notes : Erstellt Zusammenfassungen aller gespeicherten Notizen
    • Optionales „Stil“-Argument zur Steuerung des Detaillierungsgrads (kurz/detailliert)
    • Generiert eine Eingabeaufforderung, die alle aktuellen Notizen mit der Stilpräferenz kombiniert

Werkzeuge

Der Server implementiert eine breite Palette von Tools:

• add-note : Fügt dem Notizspeicher im Arbeitsspeicher eine neue Notiz hinzu
  • Argumente: name (Zeichenfolge), content (Zeichenfolge)
• ingest-string : Nehmen Sie eine Markdown- oder Nur-Text-Zeichenfolge auf und teilen Sie sie in Blöcke auf, die über eine Nachricht bereitgestellt wird.
  • Argumente: content (Zeichenfolge, erforderlich), source (Zeichenfolge, optional), tags (Liste von Zeichenfolgen, optional)
• ingest-markdown : Eine Markdown-Datei (.md) aufnehmen und in Blöcke aufteilen
  • Argumente: path (Zeichenfolge)
• ingest-python : Eine Python-Datei (.py) aufnehmen und in Blöcke aufteilen
  • Argumente: path (Zeichenfolge)
• ingest-openapi : Eine OpenAPI-JSON-Datei aufnehmen und in Blöcke aufteilen
  • Argumente: path (Zeichenfolge)
• ingest-html : Eine HTML-Datei aufnehmen und in Blöcke aufteilen
  • Argumente: path (Zeichenfolge)
• ingest-html-url : HTML-Inhalte von einer URL aufnehmen und in Blöcke aufteilen (optional mit Playwright für dynamische Inhalte)
  • Argumente: url (Zeichenfolge), dynamic (Boolesch, optional)
• smart_ingestion : Extrahiert mit Gemini alle technisch relevanten Inhalte aus einer Datei und unterteilt sie dann mithilfe einer robusten Markdown-Logik in Blöcke.
  • Argumente:
    • path (Zeichenfolge, erforderlich): Zu erfassender Dateipfad.
    • prompt (Zeichenfolge, optional): Benutzerdefinierte Eingabeaufforderung zur Verwendung für Gemini.
    • tags (Liste von Zeichenfolgen, optional): Optionale Liste von Tags zur Klassifizierung.
  • Verwendet Gemini 2.0 Flash 001, um nur Code, Konfiguration, Markdown-Struktur und technische Definitionen zu extrahieren (keine Zusammenfassungen oder Kommentare).
  • Übergibt den extrahierten Inhalt an einen auf Mistune 3.x basierenden Chunker, der sowohl Codeblöcke als auch Markdown-/Narrativinhalte als separate Chunks beibehält.
  • Jeder Block wird eingebettet und für die semantische Suche und Abfrage gespeichert.
• Suchblöcke : Semantische Suche über aufgenommene Inhalte
  • Argumente:
    • query (Zeichenfolge): Die semantische Suchabfrage.
    • top_k (Ganzzahl, optional, Standard 3): Anzahl der zurückzugebenden Top-Ergebnisse.
    • type (Zeichenfolge, optional): Filtern Sie die Ergebnisse nach Blocktyp (z. B. code , html , markdown ).
    • tag (Zeichenfolge, optional): Filtern Sie die Ergebnisse nach Tag in den Chunk-Metadaten.
  • Gibt die relevantesten Blöcke für eine bestimmte Abfrage zurück, optional gefiltert nach Typ und/oder Tag.
• delete-source : Löscht alle Chunks aus einer bestimmten Quelle
  • Argumente: source (Zeichenfolge)
• delete-chunk-by-id : Löscht einen oder mehrere Chunks nach ID
  • Argumente: id (Ganzzahl, optional), ids (Liste von Ganzzahlen, optional)
  • Sie können einen einzelnen Block löschen, indem Sie id angeben, oder mehrere Blöcke gleichzeitig löschen, indem Sie ids angeben.
• update-chunk-type : Aktualisieren Sie das Typattribut für einen Block nach ID
  • Argumente: id (Ganzzahl, erforderlich), type (Zeichenfolge, erforderlich)
• ingest-batch : Mehrere Dokumentationsdateien (Markdown, OpenAPI JSON, Python) im Batch aufnehmen und in Blöcke aufteilen
  • Argumente: paths (Liste von Zeichenfolgen)
• list-sources : Listet alle eindeutigen Quellen (Dateipfade) auf, die aufgenommen und im Speicher abgelegt wurden, mit optionaler Filterung nach Tag oder semantischer Suche.
  • Argumente:
    • tag (Zeichenfolge, optional): Filtern Sie Quellen nach Tag in Chunk-Metadaten.
    • query (Zeichenfolge, optional): Semantische Suchanfrage zum Auffinden relevanter Quellen.
    • top_k (Ganzzahl, optional, Standard 10): Anzahl der Top-Quellen, die bei Verwendung der Abfrage zurückgegeben werden sollen.
• get-context : Rufen Sie relevante Inhaltsblöcke (nur Inhalt) zur Verwendung als KI-Kontext ab, mit Filterung nach Tag, Typ und semantischer Ähnlichkeit.
  • Argumente:
    • query (Zeichenfolge, optional): Die semantische Suchabfrage.
    • tag (Zeichenfolge, optional): Filtern Sie die Ergebnisse nach einem bestimmten Tag in den Chunk-Metadaten.
    • type (Zeichenfolge, optional): Filtern Sie die Ergebnisse nach Blocktyp (z. B. „Code“, „Markdown“).
    • top_k (Ganzzahl, optional, Standard 5): Die Anzahl der abzurufenden relevantesten Blöcke.
• update-chunk-metadata : Aktualisieren Sie das Metadatenfeld für einen Block nach ID
  • Argumente: id (Ganzzahl), metadata (Objekt)
• tag-chunks-by-source : Fügt den Metadaten aller Chunks, die einer bestimmten Quelle (URL oder Dateipfad) zugeordnet sind, angegebene Tags hinzu. Fügt vorhandene Tags hinzu.
  • Argumente: source (Zeichenfolge), tags (Liste von Zeichenfolgen)
• list-notes : Listet alle aktuell gespeicherten Notizen und deren Inhalt auf.

Chunking und Code-Extraktion

• Markdown-, Python-, OpenAPI- und HTML-Dateien werden zum effizienten Abrufen und Suchen in logische Blöcke aufgeteilt.
• Der Markdown-Chunker verwendet die AST-API und Regex von Mistune 3.x, um Inhalte robust nach Codeblöcken und Text aufzuteilen und dabei die gesamte ursprüngliche Formatierung beizubehalten.
• Sowohl Codeblöcke als auch Markdown-/Narrativinhalte bleiben als separate Blöcke erhalten.
• Der HTML-Chunker verwendet die Bibliothek readability-lxml , um zunächst den Hauptinhalt zu extrahieren. Anschließend werden Blockcode-Ausschnitte aus <pre> -Tags als dedizierte „Code“-Chunks extrahiert. Inline- <code> -Inhalte bleiben Teil der narrativen Chunks.

Semantische Suche

• Das search-chunks Tool führt eine vektorbasierte semantische Suche über alle aufgenommenen Inhalte durch und gibt die relevantesten Blöcke für eine bestimmte Abfrage zurück.
• Unterstützt optionale type und tag -Argumente, um Ergebnisse nach Chunk-Typ (z. B. code , html , markdown ) und/oder nach Tag in Chunk-Metadaten zu filtern, bevor eine semantische Rangfolge erstellt wird.
• Dies ermöglicht eine sehr gezielte Abfrage, beispielsweise nach „alle mit ‚langfuse‘ markierten Codeblöcke, die für ‚Kosten und Nutzung‘ relevant sind“.

Metadatenverwaltung

• Chunks enthalten ein metadata zur Kategorisierung und Markierung.
• Mit dem Tool update-chunk-metadata können Metadaten für jeden Chunk anhand seiner ID aktualisiert werden.
• Mit dem Tool „ tag-chunks-by-source können Sie alle Chunks einer bestimmten Quelle in einem Vorgang mit Tags versehen. Beim Taggen werden neue Tags mit vorhandenen zusammengeführt, wobei die vorherigen Tags erhalten bleiben.

Konfiguration

Der Server benötigt die folgenden Umgebungsvariablen (können in einer .env-Datei festgelegt werden):

Ollama-Konfiguration

• OLLAMA_HOST: Hostname für die Ollama-API (Standard: localhost)
• OLLAMA_PORT: Port für Ollama-API (Standard: 11434)
• RAG_AGENT: Für RAG-Antworten zu verwendendes Ollama-Modell (Standard: llama3)
• OLLAMA_MODEL: Für Einbettungen zu verwendendes Ollama-Modell (Standard: nomic-embed-text-v2-moe)

Datenbankkonfiguration

• HOST: PostgreSQL-Datenbankhost (Standard: localhost)
• DB_PORT: PostgreSQL-Datenbankport (Standard: 5432)
• DB_NAME: Name der PostgreSQL-Datenbank (Standard: doclibdb)
• DB_USER: PostgreSQL-Datenbankbenutzer (Standard: doclibdb_user)
• DB_PASSWORD: PostgreSQL-Datenbankpasswort (Standard: doclibdb_password)

Reranker-Konfiguration

• RERANKER_MODEL_PATH: Pfad zum Reranker-Modell (Standard: /srv/samba/fileshare2/AI/models/bge-reranker-v2-m3)
• RERANKER_USE_FP16: Ob FP16 für Reranker verwendet werden soll (Standard: True)

Schnellstart

Installieren

Claude Desktop

Unter MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json Unter Windows: %APPDATA%/Claude/claude_desktop_config.json

Entwicklung

Erstellen und Veröffentlichen

So bereiten Sie das Paket für die Verteilung vor:

1. Abhängigkeiten synchronisieren und Sperrdatei aktualisieren:

2. Erstellen Sie Paketverteilungen:

Dadurch werden Quell- und Wheel-Distributionen im Verzeichnis dist/ erstellt.

3. Auf PyPI veröffentlichen:

Hinweis: Sie müssen PyPI-Anmeldeinformationen über Umgebungsvariablen oder Befehlsflags festlegen:

• Token: --token oder UV_PUBLISH_TOKEN
• Oder Benutzername/Passwort: --username / UV_PUBLISH_USERNAME und --password / UV_PUBLISH_PASSWORD

Debuggen

Da MCP-Server über stdio laufen, kann das Debuggen eine Herausforderung darstellen. Für ein optimales Debugging empfehlen wir dringend die Verwendung des MCP Inspector .

Sie können den MCP Inspector über npm mit diesem Befehl starten:

Beim Start zeigt der Inspector eine URL an, auf die Sie in Ihrem Browser zugreifen können, um mit dem Debuggen zu beginnen.