Flexible Key-Value Extracting MCP Server

Flexibler MCP-Server zur Schlüsselwertextraktion

Version: 0.3.1

Dieser MCP-Server extrahiert Schlüssel-Wert-Paare aus beliebigem, verrauschtem oder unstrukturiertem Text mithilfe von LLMs (GPT-4.1-mini) und pydantic-ai. Er gewährleistet Typsicherheit und unterstützt mehrere Ausgabeformate (JSON, YAML, TOML). Der Server reagiert robust auf alle Eingaben und versucht stets, die Daten so weit wie möglich zu strukturieren. Eine perfekte Extraktion kann jedoch nicht garantiert werden .

🤔💡 Warum diesen MCP-Server verwenden?

Während viele Large Language Model (LLM)-Dienste strukturierte Ausgabefunktionen bieten, bietet dieser MCP-Server deutliche Vorteile bei der Schlüssel-Wert-Extraktion, insbesondere aus anspruchsvollen Texten aus der realen Welt:

• 🔑🔍 Automatische Schlüsselerkennung : Eine Kernstärke ist die Fähigkeit, relevante Schlüssel-Wert-Paare aus unstrukturiertem Text selbstständig zu identifizieren und zu extrahieren, ohne dass vordefinierte Schlüssel erforderlich sind . Während typische strukturierte LLM-Ausgaben die Angabe der gesuchten Schlüssel erfordern, erkennt dieser Server diese automatisch. Dies macht ihn besonders effektiv für vielfältige und unvorhersehbare Daten, deren Struktur im Voraus nicht bekannt ist.
• 💪🧱 Überlegene Robustheit für komplexe Eingaben : Es eignet sich hervorragend für beliebigen, verrauschten oder unstrukturierten Text, bei dem standardmäßige strukturierte LLM-Ausgaben möglicherweise versagen. Die mehrstufige Pipeline ist speziell darauf ausgelegt, unvollständige Daten zu sichten und zu interpretieren.
• 🌐🗣️ Erweiterte mehrsprachige Vorverarbeitung : Vor der LLM-Verarbeitung nutzt es spaCy für die Named Entity Recognition (NER) in Japanisch, Englisch und Chinesisch (vereinfacht/traditionell) und verbessert die Extraktionsgenauigkeit für diese Sprachen erheblich, indem es kontextreiche Kandidatenphrasen bereitstellt.
• 🔄✍️ Iterative Verfeinerung und Typisierung : Im Gegensatz zur Single-Pass-Extraktion verwendet dieser Server eine ausgeklügelte Pipeline mit LLM-basierter Typannotation, LLM-basierter Typbewertung und regelbasierter/LLM-Fallback-Normalisierung. Dies gewährleistet präzisere und kontextgerechtere Datentypen.
• ✅🛡️ Garantierte Typsicherheit und Schemaeinhaltung : Die endgültige Strukturierung mit Pydantic stellt sicher, dass die Ausgabe nicht nur strukturiert, sondern auch typsicher und anhand eines definierten Schemas validiert ist, wodurch zuverlässige Daten für nachgelagerte Anwendungen bereitgestellt werden.
• 📊⚙️ Konsistente und vorhersehbare Ausgabe : Der Server ist so konzipiert, dass er immer eine wohlgeformte Antwort zurückgibt, selbst wenn die Extraktion nur teilweise erfolgt oder auf Probleme stößt. Dies ist für den Aufbau robuster automatisierter Systeme von entscheidender Bedeutung.

Versionshinweise

Version 0.3.1

• Update: Verbessern Sie die Eingabeaufforderung zur Typauswertung für eine robuste Korrektur.
• Update: Die Stärke dieses MCP-Servers wurde in README.md hinzugefügt

Version 0.2.0

• Fix: Sprachcode für zh-cn / zh-tw.

Version 0.1.0

• Erstveröffentlichung

Werkzeuge

• /extract_json : Extrahiert typsichere Schlüssel-Wert-Paare im JSON-Format aus dem Eingabetext.
• /extract_yaml : Extrahiert typsichere Schlüssel-Wert-Paare im YAML-Format aus dem Eingabetext.
• /extract_toml : Extrahiert typsichere Schlüssel-Wert-Paare im TOML-Format aus dem Eingabetext.
  • Hinweis: Aufgrund der TOML-Spezifikationen können Objekt-Arrays (Dicts) oder tief verschachtelte Strukturen nicht direkt dargestellt werden. Weitere Informationen finden Sie weiter unten im Abschnitt „Hinweis zu TOML-Ausgabebeschränkungen“.

Notiz:

• Unterstützte Sprachen: Japanisch, Englisch und Chinesisch (vereinfacht: zh-cn / traditionell: zh-tw).
• Die Extraktion basiert auf pydantic-ai und LLMs. Eine perfekte Extraktion kann nicht garantiert werden.
• Die Verarbeitung längerer Eingabesätze dauert länger. Bitte haben Sie Geduld.
• Beim ersten Start lädt der Server spaCy-Modelle herunter, daher dauert der Vorgang anfangs länger.

Beispiel für die geschätzte Bearbeitungszeit

Die tatsächliche Verarbeitungszeit kann je nach API-Antwort, Netzwerkbedingungen und Modelllast erheblich variieren. Selbst kurze Texte können 15 Sekunden oder länger dauern.

Merkmale

• Flexible Extraktion : Verarbeitet alle Eingaben, einschließlich verrauschter oder beschädigter Daten.
• Vollständige Unterstützung für JP / EN / ZH-CN / ZH-TW : Vorverarbeitung mit spaCy NER durch automatische Spracherkennung (Japanisch, Englisch, Chinesisch [vereinfacht: zh-cn / traditionell: zh-tw] wird unterstützt; andere werden mit Fehler abgelehnt).
• Typsichere Ausgabe : Verwendet Pydantic zur Ausgabevalidierung.
• Mehrere Formate : Gibt Ergebnisse als JSON, YAML oder TOML zurück.
• Robuste Fehlerbehandlung : Gibt immer eine wohlgeformte Antwort zurück, auch bei einem Fehler.
• Hohe Genauigkeit : Verwendet GPT-4.1-mini sowohl für die Extraktion/Annotation als auch für die Typbewertung, mit Pydantic für die endgültige Strukturierung.

Getestete Szenarien

Der Server wurde mit verschiedenen Eingaben getestet, darunter:

• Einfache Schlüssel-Wert-Paare
• Unübersichtlicher oder unstrukturierter Text mit darin verborgenen wichtigen Informationen
• Verschiedene Datenformate (JSON, YAML, TOML) für die Ausgabe

Verarbeitungsablauf

Unten sehen Sie ein Flussdiagramm, das den Verarbeitungsablauf der Schlüssel-Wert-Extraktionspipeline darstellt, wie sie in server.py implementiert ist:

Vorverarbeitung mit spaCy (Mehrsprachiges NER)

Dieser Server verwendet spaCy mit automatischer Spracherkennung, um benannte Entitäten aus dem Eingabetext zu extrahieren , bevor dieser an das LLM übergeben wird. Unterstützte Sprachen sind Japanisch ( ja_core_news_md ), Englisch ( en_core_web_sm ) und Chinesisch (vereinfacht/traditionell, zh_core_web_sm ).

• Die Sprache des Eingabetextes wird automatisch mithilfe von langdetect erkannt.
• Wenn die erkannte Sprache nicht Japanisch, Englisch oder Chinesisch ist, gibt der Server einen Fehler zurück: Unsupported lang detected .
• Das passende spaCy-Modell wird bei Bedarf automatisch heruntergeladen und geladen. Eine manuelle Installation ist nicht erforderlich.
• Die extrahierte Phrasenliste wird wie folgt in die LLM-Eingabeaufforderung aufgenommen:

  [Vorverarbeitung von Kandidatenphrasen (spaCy NER)] Die folgende Liste enthält Phrasen, die mithilfe des Spracherkennungsmodells von spaCy automatisch aus dem Eingabetext extrahiert wurden. Diese Phrasen repräsentieren erkannte Entitäten wie Namen, Daten, Organisationen, Orte, Zahlen usw. Diese Liste dient nur als Referenz und kann irrelevante oder falsche Elemente enthalten. Das LLM verwendet sein eigenes Urteilsvermögen und berücksichtigt den gesamten Eingabetext, um flexibel die am besten geeigneten Schlüssel-Wert-Paare abzuleiten.

Schrittdetails

Die Schlüssel-Wert-Extraktionspipeline dieses Projekts besteht aus mehreren Schritten. Die Details der einzelnen Schritte lauten wie folgt:

Schritt 0: Vorverarbeitung mit spaCy (Spracherkennung → Named Entity Recognition)

• Zweck : Automatisches Erkennen der Sprache des Eingabetextes und Verwenden des entsprechenden spaCy-Modells (z. B. ja_core_news_md , en_core_web_sm , zh_core_web_sm ), um benannte Entitäten zu extrahieren.
• Ausgabe : Die extrahierte Phrasenliste, die in der LLM-Eingabeaufforderung als Hinweis zur Verbesserung der Genauigkeit der Schlüssel-Wert-Paar-Extraktion enthalten ist.

Schritt 1: Schlüssel-Wert-Extraktion (LLM)

• Zweck : Verwenden Sie GPT-4.1-mini, um Schlüssel-Wert-Paare aus dem Eingabetext und der extrahierten Phrasenliste zu extrahieren.
• Einzelheiten :
  • Die Eingabeaufforderung enthält Anweisungen zum Zurückgeben listenformatierter Werte, wenn derselbe Schlüssel mehrmals vorkommt.
  • Beispiele mit wenigen Beispielen sind so konzipiert, dass sie listenformatierte Ausgaben enthalten.
• Ausgabe : Beispiel: key: person, value: ["Tanaka", "Sato"]

Schritt 2: Typannotation (LLM)

• Zweck : Verwenden Sie GPT-4.1-mini, um den Datentyp (int, str, bool, list usw.) jedes in Schritt 1 extrahierten Schlüssel-Wert-Paares abzuleiten.
• Einzelheiten :
  • Die Eingabeaufforderung für Typanmerkungen enthält Anweisungen zur Unterstützung von Listen und mehreren Werten.
• Ausgabe : Beispiel: key: person, value: ["Tanaka", "Sato"] -> list[str]

Schritt 3: Typbewertung (LLM)

• Zweck : Verwenden Sie GPT-4.1-mini, um die Typanmerkungen aus Schritt 2 zu bewerten und zu korrigieren.
• Einzelheiten :
  • Für jedes Schlüssel-Wert-Paar bewertet GPT-4.1-mini die Gültigkeit und den Kontext der Typannotation neu.
  • Werden Typfehler oder Mehrdeutigkeiten erkannt, korrigiert oder ergänzt GPT-4.1-mini den Typ automatisch.
  • Beispiel: Korrigieren eines als Zahl extrahierten Werts, der aber eine Zeichenfolge sein sollte, oder Bestimmen, ob ein Wert eine Liste oder ein einzelner Wert ist.
• Ausgabe : Die nach Typ ausgewertete Liste der Schlüssel-Wert-Paare.

Schritt 4: Typnormalisierung (Statische Regeln + LLM-Fallback)

• Zweck : Konvertieren Sie die typausgewerteten Daten in die Standardtypen von Python (int, float, bool, str, list, None usw.).
• Einzelheiten :
  • Wenden Sie statische Normalisierungsregeln (reguläre Ausdrücke oder Typkonvertierungsfunktionen) an, um Werte in die Standardtypen von Python zu konvertieren.
  • Beispiel: Konvertieren von durch Kommas getrennten Werten in Listen, „true“/„false“ in boolesche Werte oder Datumsausdrücke in Standardformate.
  • Wenn statische Regeln einen Wert nicht konvertieren können, verwenden Sie die LLM-basierte Fallback-Typkonvertierung.
  • Nicht konvertierbare Werte werden sicher als None oder str behandelt.
• Ausgabe : Die Liste der Schlüssel-Wert-Paare im Python-Typ-normalisiert.

Schritt 5: Endgültige Strukturierung mit Pydantic

• Zweck : Validieren und strukturieren Sie die typnormalisierten Daten mithilfe von Pydantic-Modellen (KVOut/KVPayload).
• Einzelheiten :
  • Ordnen Sie jedes Schlüssel-Wert-Paar Pydantic-Modellen zu, um Typsicherheit und Datenintegrität zu gewährleisten.
  • Validieren Sie Einzelwerte, Listen, Null- und zusammengesetzte Typen gemäß dem Schema.
  • Wenn die Validierung fehlschlägt, fügen Sie Fehlerinformationen an, während Sie so viele Daten wie möglich beibehalten.
  • Die endgültige Ausgabe wird im angegebenen Format (JSON, YAML oder TOML) zurückgegeben.
• Ausgabe : Die typsichere und validierte Ausgabe im Dict- oder angegebenen Format (JSON/YAML/TOML).

Diese Pipeline ist für die zukünftige Unterstützung von Listenformaten und Pydantic-Schemaerweiterungen ausgelegt.

Hinweis zu TOML-Ausgabebeschränkungen

• In TOML können einfache Arrays (z. B. items = ["A", "B"] ) nativ dargestellt werden, aber Arrays von Objekten (dicts) oder tief verschachtelte Strukturen können aufgrund der TOML-Spezifikationen nicht direkt dargestellt werden.
• Daher werden komplexe Listen oder verschachtelte Strukturen (z. B. [{"name": "A"}, {"name": "B"}] ) als „JSON-Strings“ in TOML-Werten gespeichert.
• Dies ist eine Designentscheidung, um Informationsverluste aufgrund von Spezifikationsbeschränkungen von TOML zu verhindern.
• Die Formate YAML und JSON können verschachtelte Strukturen unverändert darstellen.

Beispiel-Eingabe/Ausgabe

Eingang:

Ausgabe (JSON):

Ausgabe (YAML):

Ausgabe (TOML, einfacher Fall):

Ausgabe (TOML, komplexer Fall):

Hinweis: Arrays von Objekten oder verschachtelte Strukturen werden in TOML als JSON-Strings gespeichert.

Werkzeuge

1. extract_json

• Beschreibung : Extrahiert Schlüssel-Wert-Paare aus beliebigem verrauschtem Text und gibt sie als typsicheres JSON (Python-Dict) zurück.
• Argumente :
  • input_text (Zeichenfolge): Eingabezeichenfolge mit verrauschten oder unstrukturierten Daten.
• Gibt zurück : { "success": True, "result": ... } oder { "success": False, "error": ... }
• Beispiel :
  { "success": true, "result": { "foo": 1, "bar": "baz" } }

2. extract_yaml

• Beschreibung : Extrahiert Schlüssel-Wert-Paare aus beliebigem verrauschtem Text und gibt sie als typsicheres YAML (Zeichenfolge) zurück.
• Argumente :
  • input_text (Zeichenfolge): Eingabezeichenfolge mit verrauschten oder unstrukturierten Daten.
• Gibt zurück : { "success": True, "result": ... } oder { "success": False, "error": ... }
• Beispiel :
  { "success": true, "result": "foo: 1\nbar: baz" }

3. extract_toml

• Beschreibung : Extrahiert Schlüssel-Wert-Paare aus beliebigem verrauschtem Text und gibt sie als typsicheres TOML (Zeichenfolge) zurück.
• Argumente :
  • input_text (Zeichenfolge): Eingabezeichenfolge mit verrauschten oder unstrukturierten Daten.
• Gibt zurück : { "success": True, "result": ... } oder { "success": False, "error": ... }
• Beispiel :
  { "success": true, "result": "foo = 1\nbar = \"baz\"" }

Verwendung

Installation über Smithery

So installieren Sie kv-extractor-mcp-server für Claude Desktop automatisch über Smithery :

Anforderungen

• Python 3.9+
• API-Schlüssel für OpenAI-Modelle (in settings.json unter env festgelegt)

Ausführen des Servers

Falls Sie den Server manuell ausführen möchten.

MCP-Hostkonfiguration

Wenn Sie diesen MCP-Server ausführen, müssen Sie den Protokollausgabemodus und (falls aktiviert) den absoluten Protokolldateipfad explizit über Befehlszeilenargumente angeben .

• --log=off : Deaktiviert die gesamte Protokollierung (es werden keine Protokolle geschrieben)
• --log=on --logfile=/absolute/path/to/logfile.log : Protokollierung aktivieren und Protokolle in den angegebenen absoluten Dateipfad schreiben
• Beide Argumente sind erforderlich , wenn die Protokollierung aktiviert ist. Der Server wird mit einem Fehler beendet, wenn eines der Argumente fehlt, der Pfad nicht absolut ist oder ungültige Werte angegeben werden.

Beispiel: Protokollierung deaktiviert

Beispiel: Protokollierung aktiviert (absoluter Protokolldateipfad erforderlich)

Notiz:

• Wenn die Protokollierung aktiviert ist, werden Protokolle nur in den angegebenen absoluten Dateipfad geschrieben. Relative Pfade oder das Weglassen von --logfile führen zu einem Fehler.
• Wenn die Protokollierung deaktiviert ist, werden keine Protokolle ausgegeben.
• Wenn die erforderlichen Argumente fehlen oder ungültig sind, startet der Server nicht und gibt eine Fehlermeldung aus.
• Die Protokolldatei muss für den MCP-Serverprozess zugänglich und beschreibbar sein.
• Wenn Sie Probleme beim Ausführen dieses Servers haben, liegt dies möglicherweise daran, dass eine ältere Version des kv-extractor-mcp-servers zwischengespeichert wird. Versuchen Sie, ihn mit der neuesten Version des kv-extractor-mcp-servers auszuführen (setzen Sie xyz auf die neueste Version ein), indem Sie die folgenden Einstellungen verwenden.

Lizenz

GPL-3.0 oder höher

Autor

KunihiroS (und Mitwirkende)