Flexible Key-Value Extracting MCP Server

Servidor MCP de extracción flexible de clave-valor

Versión: 0.3.1

Este servidor MCP extrae pares clave-valor de texto arbitrario, con ruido o sin estructura mediante LLM (GPT-4.1-mini) y Pydantic-AI. Garantiza la seguridad de tipos y admite múltiples formatos de salida (JSON, YAML, TOML). El servidor es robusto ante cualquier entrada y siempre intenta estructurar los datos al máximo; sin embargo, no se garantiza una extracción perfecta.

🤔💡 ¿Por qué utilizar este servidor MCP?

Si bien muchos servicios de modelos de lenguaje grandes (LLM) ofrecen capacidades de salida estructurada, este servidor MCP proporciona ventajas distintivas para la extracción de valores clave, especialmente a partir de textos complejos del mundo real:

• 🔑🔍 Descubrimiento automático de claves : Una de sus principales ventajas es su capacidad para identificar y extraer de forma autónoma pares clave-valor relevantes de texto no estructurado , sin necesidad de claves predefinidas . Mientras que las salidas estructuradas típicas de LLM requieren que se especifiquen las claves buscadas, este servidor las descubre, lo que lo hace muy eficaz para datos diversos e impredecibles cuya estructura se desconoce de antemano.
• Robustez superior para entradas complejas : Funciona de maravilla con texto arbitrario, ruidoso o no estructurado, donde las salidas estructuradas LLM estándar podrían fallar. El pipeline de múltiples pasos está diseñado específicamente para filtrar y comprender datos imperfectos.
• 🌐🗣️ Preprocesamiento multilingüe avanzado : antes del procesamiento LLM, aprovecha spaCy para el reconocimiento de entidades nombradas (NER) en japonés, inglés y chino (simplificado/tradicional), lo que mejora significativamente la precisión de extracción para estos idiomas al proporcionar frases candidatas ricas en contexto.
• 🔄✍️ Refinamiento y tipificación iterativos : A diferencia de la extracción de un solo paso, este servidor emplea una sofisticada canalización que incluye anotación y evaluación de tipos basadas en LLM, y normalización basada en reglas/fallback de LLM. Esto garantiza tipos de datos más precisos y contextualmente apropiados.
• ✅🛡️ Seguridad de tipos y adhesión al esquema garantizadas : la estructuración final con Pydantic garantiza que la salida no solo esté estructurada, sino que también sea segura en cuanto a tipos y validada frente a un esquema definido, lo que proporciona datos confiables para aplicaciones posteriores.
• 📊⚙️ Salida consistente y predecible : el servidor está diseñado para devolver siempre una respuesta bien formada, incluso si la extracción es parcial o encuentra problemas, lo cual es fundamental para construir sistemas automatizados robustos.

Notas de la versión

versión 0.3.1

• Actualización: Mejorar la solicitud de evaluación de tipo para una corrección robusta.
• Actualización: Se agregó el punto fuerte de este servidor MCP en README.md

versión 0.2.0

• Corrección: Código de idioma para zh-cn / zh-tw.

versión 0.1.0

• Lanzamiento inicial

Herramientas

• /extract_json : extrae pares clave-valor de tipos seguros en formato JSON del texto de entrada.
• /extract_yaml : extrae pares clave-valor de tipos seguros en formato YAML del texto de entrada.
• /extract_toml : extrae pares clave-valor de tipos seguros en formato TOML del texto de entrada.
  • Nota: Debido a las especificaciones de TOML, las matrices de objetos (dictados) o estructuras profundamente anidadas no se pueden representar directamente. Consulte la "Nota sobre las limitaciones de salida de TOML" a continuación para obtener más información.

Nota:

• Idiomas admitidos: japonés, inglés y chino (simplificado: zh-cn / tradicional: zh-tw).
• La extracción se basa en pydantic-ai y LLM. No se garantiza una extracción perfecta.
• Las oraciones más largas tardarán más en procesarse. Por favor, tenga paciencia.
• En el primer lanzamiento, el servidor descargará modelos de spaCy, por lo que el proceso tardará más tiempo inicialmente.

Muestra de tiempo de procesamiento estimado

El tiempo real de procesamiento puede variar significativamente según la respuesta de la API, las condiciones de la red y la carga del modelo. Incluso los textos cortos pueden tardar 15 segundos o más.

Características

• Extracción flexible : maneja cualquier entrada, incluidos datos ruidosos o dañados.
• Compatibilidad total con JP/EN/ZH-CN/ZH-TW : preprocesamiento con spaCy NER mediante detección automática de idioma (se admiten japonés, inglés, chino [simplificado: zh-cn/tradicional: zh-tw]; los demás se rechazan con error).
• Salida segura de tipos : utiliza Pydantic para la validación de salida.
• Múltiples formatos : devuelve resultados como JSON, YAML o TOML.
• Manejo robusto de errores : siempre devuelve una respuesta bien formada, incluso en caso de error.
• Alta precisión : utiliza GPT-4.1-mini tanto para la extracción/anotación como para la evaluación de tipos, con Pydantic para la estructuración final.

Escenarios probados

El servidor ha sido probado con varias entradas, incluidas:

• Pares clave-valor simples
• Texto ruidoso o desestructurado con información importante oculta en su interior
• Diferentes formatos de datos (JSON, YAML, TOML) para salida

Flujo de procesamiento

A continuación se muestra un diagrama de flujo que representa el flujo de procesamiento de la canalización de extracción de clave-valor tal como se implementa en server.py :

Preprocesamiento con spaCy (NER multilingüe)

Este servidor utiliza spaCy con detección automática de idioma para extraer entidades con nombre del texto de entrada antes de pasarlo al LLM. Los idiomas admitidos son japonés ( ja_core_news_md ), inglés ( en_core_web_sm ) y chino (simplificado/tradicional, zh_core_web_sm ).

• El idioma del texto de entrada se detecta automáticamente utilizando langdetect .
• Si el idioma detectado no es japonés, inglés o chino, el servidor devuelve un error: Unsupported lang detected .
• El modelo de spaCy adecuado se descarga y carga automáticamente según sea necesario. No requiere instalación manual.
• La lista de frases extraídas se incluye en la solicitud de LLM de la siguiente manera:

  [Preprocesamiento de Frases Candidatas (NER de spaCy)] A continuación, se presenta una lista de frases extraídas automáticamente del texto de entrada mediante el modelo de lenguaje detectado de spaCy. Estas frases representan entidades detectadas, como nombres, fechas, organizaciones, ubicaciones, números, etc. Esta lista es solo de referencia y puede contener elementos irrelevantes o incorrectos. El LLM utiliza su propio criterio y considera todo el texto de entrada para inferir con flexibilidad los pares clave-valor más adecuados.

Detalles del paso

El proceso de extracción de clave-valor de este proyecto consta de varios pasos. Los detalles de cada paso son los siguientes:

Paso 0: Preprocesamiento con spaCy (Detección de lenguaje → Reconocimiento de entidades con nombre)

• Propósito : Detectar automáticamente el idioma del texto de entrada y utilizar el modelo spaCy apropiado (por ejemplo, ja_core_news_md , en_core_web_sm , zh_core_web_sm ) para extraer entidades nombradas.
• Salida : La lista de frases extraídas, que se incluye en el mensaje LLM como una sugerencia para mejorar la precisión de la extracción de pares clave-valor.

Paso 1: Extracción de clave-valor (LLM)

• Propósito : utilizar GPT-4.1-mini para extraer pares clave-valor del texto de entrada y la lista de frases extraída.
• Detalles :
  • El mensaje incluye instrucciones para devolver valores con formato de lista cuando la misma clave aparece varias veces.
  • Los ejemplos de pocas tomas están diseñados para incluir salidas con formato de lista.
• Salida : Ejemplo: key: person, value: ["Tanaka", "Sato"]

Paso 2: Anotación de tipo (LLM)

• Propósito : utilizar GPT-4.1-mini para inferir el tipo de datos (int, str, bool, lista, etc.) de cada par clave-valor extraído en el Paso 1.
• Detalles :
  • La solicitud de anotación de tipo incluye instrucciones para la compatibilidad con listas y valores múltiples.
• Salida : Ejemplo: key: person, value: ["Tanaka", "Sato"] -> list[str]

Paso 3: Evaluación de tipo (LLM)

• Propósito : utilizar GPT-4.1-mini para evaluar y corregir las anotaciones de tipo del Paso 2.
• Detalles :
  • Para cada par clave-valor, GPT-4.1-mini reevalúa la validez y el contexto de la anotación de tipo.
  • Si se detectan errores de tipo o ambigüedades, GPT-4.1-mini corrige o complementa el tipo automáticamente.
  • Ejemplo: corregir un valor extraído como número pero que debería ser una cadena, o determinar si un valor es una lista o un valor único.
• Salida : La lista de pares clave-valor evaluados por tipo.

Paso 4: Normalización de tipos (reglas estáticas + respaldo LLM)

• Propósito : Convertir los datos evaluados por tipo en los tipos estándar de Python (int, float, bool, str, list, None, etc.).
• Detalles :
  • Aplicar reglas de normalización estática (expresiones regulares o funciones de conversión de tipos) para convertir valores en los tipos estándar de Python.
  • Ejemplo: Convertir valores separados por comas en listas, "verdadero"/"falso" en booleanos o expresiones de fecha en formatos estándar.
  • Si las reglas estáticas no pueden convertir un valor, utilice la conversión de tipo alternativa basada en LLM.
  • Los valores no convertibles se manejan de forma segura como Ninguno o str.
• Salida : La lista de pares clave-valor normalizados por tipo de Python.

Paso 5: Estructuración final con Pydantic

• Propósito : Validar y estructurar los datos normalizados de tipo utilizando modelos Pydantic (KVOut/KVPayload).
• Detalles :
  • Asigne cada par clave-valor a los modelos de Pydantic, lo que garantiza la seguridad de tipos y la integridad de los datos.
  • Validar valores individuales, listas, tipos nulos y compuestos según el esquema.
  • Si la validación falla, adjunte información de error conservando la mayor cantidad de datos posible.
  • La salida final se devuelve en el formato especificado (JSON, YAML o TOML).
• Salida : El diccionario validado y de tipo seguro o la salida en formato especificado (JSON/YAML/TOML).

Esta canalización está diseñada para admitir futuros formatos de listas y extensiones de esquema de Pydantic.

Nota sobre las limitaciones de salida de TOML

• En TOML, las matrices simples (por ejemplo, items = ["A", "B"] ) se pueden representar de forma nativa, pero las matrices de objetos (diccionarios) o estructuras profundamente anidadas no se pueden representar directamente debido a las especificaciones de TOML.
• Por lo tanto, las listas complejas o estructuras anidadas (por ejemplo, [{"name": "A"}, {"name": "B"}] ) se almacenan como "cadenas JSON" en valores TOML.
• Esta es una elección de diseño para evitar la pérdida de información debido a las limitaciones de especificación de TOML.
• Los formatos YAML y JSON pueden representar estructuras anidadas tal como están.

Ejemplo de entrada/salida

Aporte:

Salida (JSON):

Salida (YAML):

Salida (TOML, caso simple):

Salida (TOML, caso complejo):

Nota: Las matrices de objetos o estructuras anidadas se almacenan como cadenas JSON en TOML.

Herramientas

1. extract_json

• Descripción : Extrae pares clave-valor de texto ruidoso arbitrario y los devuelve como JSON de tipo seguro (dictado de Python).
• Argumentos :
  • input_text (cadena): cadena de entrada que contiene datos ruidosos o no estructurados.
• Devuelve : { "success": True, "result": ... } o { "success": False, "error": ... }
• Ejemplo :
  { "success": true, "result": { "foo": 1, "bar": "baz" } }

2. extract_yaml

• Descripción : Extrae pares clave-valor de texto ruidoso arbitrario y los devuelve como YAML (cadena) de tipo seguro.
• Argumentos :
  • input_text (cadena): cadena de entrada que contiene datos ruidosos o no estructurados.
• Devuelve : { "success": True, "result": ... } o { "success": False, "error": ... }
• Ejemplo :
  { "success": true, "result": "foo: 1\nbar: baz" }

3. extract_toml

• Descripción : Extrae pares clave-valor de texto ruidoso arbitrario y los devuelve como TOML (cadena) de tipo seguro.
• Argumentos :
  • input_text (cadena): cadena de entrada que contiene datos ruidosos o no estructurados.
• Devuelve : { "success": True, "result": ... } o { "success": False, "error": ... }
• Ejemplo :
  { "success": true, "result": "foo = 1\nbar = \"baz\"" }

Uso

Instalación mediante herrería

Para instalar kv-extractor-mcp-server para Claude Desktop automáticamente a través de Smithery :

Requisitos

• Python 3.9+
• Clave API para modelos OpenAI (establecida en settings.json en env )

Ejecución del servidor

En caso de que desee ejecutar el servidor manualmente.

Configuración del host MCP

Al ejecutar este servidor MCP, debe especificar explícitamente el modo de salida del registro y (si está habilitado) la ruta absoluta del archivo de registro mediante argumentos de la línea de comandos .

• --log=off : Deshabilita todos los registros (no se escriben registros)
• --log=on --logfile=/absolute/path/to/logfile.log : Habilita el registro y escribe registros en la ruta de archivo absoluta especificada
• Ambos argumentos son necesarios cuando el registro está habilitado. El servidor cerrará con un error si falta alguno, si la ruta no es absoluta o si se proporcionan valores no válidos.

Ejemplo: Registro deshabilitado

Ejemplo: Registro habilitado (se requiere ruta absoluta del archivo de registro)

Nota:

• Cuando el registro está habilitado, los registros se escriben solo en la ruta de archivo absoluta especificada. Las rutas relativas o la omisión de --logfile provocarán un error.
• Cuando el registro está deshabilitado, no se generan registros.
• Si faltan los argumentos requeridos o no son válidos, el servidor no se iniciará e imprimirá un mensaje de error.
• El archivo de registro debe ser accesible y escribible por el proceso del servidor MCP.
• Si tiene problemas para ejecutar este servidor, es posible que se deba a que almacena en caché una versión anterior de kv-extractor-mcp-server. Intente ejecutarlo con la versión más reciente (configure xyz a la última versión) de kv-extractor-mcp-server con la siguiente configuración.

Licencia

GPL-3.0 o posterior

Autor

KunihiroS (y colaboradores)