Flexible Key-Value Extracting MCP Server

灵活的键值提取 MCP 服务器

版本：0.3.1

该 MCP 服务器使用 LLM（GPT-4.1-mini）和 pydantic-ai 从任意、嘈杂或非结构化文本中提取键值对。它确保类型安全并支持多种输出格式（JSON、YAML、TOML）。该服务器对任何输入都具有鲁棒性，并始终尝试尽可能地结构化数据，但无法保证完美的提取效果。

🤔💡 为什么要使用此 MCP 服务器？

虽然许多大型语言模型 (LLM) 服务都提供结构化输出功能，但此 MCP 服务器在键值提取方面具有明显优势，尤其是从具有挑战性的真实文本中提取键值：

• 🔑🔍自动密钥发现：其核心优势在于能够从非结构化文本中自主识别并提取相关的键值对， 而无需预定义密钥。典型的 LLM 结构化输出需要您指定要查找的密钥，而此服务器可以自动发现这些密钥，这使得它对于结构未知且多样化、不可预测的数据非常有效。
• 💪🧱复杂输入的卓越鲁棒性：它擅长处理任意、嘈杂或非结构化的文本，而标准 LLM 结构化输出可能会出现问题。其多步骤流程专为筛选和理解不完美数据而设计。
• 🌐🗣️高级多语言预处理：在 LLM 处理之前，它利用 spaCy 对日语、英语和中文（简体/繁体）进行命名实体识别 (NER)，通过提供上下文丰富的候选短语显著提高这些语言的提取准确性。
• 🔄✍️迭代细化和类型识别：与单遍提取不同，此服务器采用了复杂的流水线，包括基于 LLM 的类型标注、基于 LLM 的类型求值以及基于规则/LLM 回退的规范化。这确保了更准确、更符合上下文的数据类型。
• ✅🛡️保证类型安全和模式遵守：使用 Pydantic 进行最终结构化可确保输出不仅结构化，而且类型安全并根据定义的模式进行验证，从而为下游应用程序提供可靠的数据。
• 📊⚙️一致且可预测的输出：服务器设计为始终返回格式良好的响应，即使提取不完整或遇到问题，这对于构建强大的自动化系统至关重要。

发行说明

v0.3.1

• 更新：改进类型评估提示，以进行稳健校正。
• 更新：在 README.md 中添加了此 MCP 服务器的优点

v0.2.0

• 修复：zh-cn / zh-tw 的语言代码。

v0.1.0

• 初始版本

工具

• /extract_json ：从输入文本中提取 JSON 格式的类型安全键值对。
• /extract_yaml ：从输入文本中提取 YAML 格式的类型安全键值对。
• /extract_toml ：从输入文本中提取 TOML 格式的类型安全键值对。
  • 注意：由于 TOML 规范，对象数组（字典）或深度嵌套结构无法直接表示。详情请参阅下文“TOML 输出限制说明”。

笔记：

• 支持的语言：日语、英语和中文（简体：zh-cn / 繁体：zh-tw）。
• 提取依赖于 pydantic-ai 和 LLM。无法保证完美提取。
• 输入的句子较长时，处理时间会更长。请耐心等待。
• 首次启动时，服务器将下载 spaCy 模型，因此该过程最初会花费更长时间。

预计处理时间示例

实际处理时间可能因 API 响应、网络状况和模型负载而有很大差异。即使是短文本也可能需要 15 秒或更长时间。

特征

• 灵活提取：处理任何输入，包括嘈杂或损坏的数据。
• JP / EN / ZH-CN / ZH-TW 全面支持：通过自动语言检测使用 spaCy NER 进行预处理（支持日语、英语、中文 [简体：zh-cn / 繁体：zh-tw]；其他语言将被错误拒绝）。
• 类型安全输出：使用 Pydantic 进行输出验证。
• 多种格式：以 JSON、YAML 或 TOML 形式返回结果。
• 强大的错误处理：即使失败，也始终返回格式良好的响应。
• 高精度：使用 GPT-4.1-mini 进行提取/注释和类型评估，并使用 Pydantic 进行最终结构化。

测试场景

该服务器已经通过各种输入进行了测试，包括：

• 简单键值对
• 包含重要信息的嘈杂或非结构化文本
• 输出不同的数据格式（JSON、YAML、TOML）

处理流程

下面是在server.py中实现的键值提取管道的处理流程图：

使用 spaCy 进行预处理（多语言 NER）

此服务器使用带有自动语言检测功能的spaCy ，从输入文本中提取命名实体**，然后将**其传递给 LLM。支持的语言包括日语 ( ja_core_news_md )、英语 ( en_core_web_sm ) 和中文（简体/繁体， zh_core_web_sm ）。

• 使用langdetect自动检测输入文本的语言。
• 如果检测到的语言不是日语、英语或中文，服务器将返回错误： Unsupported lang detected 。
• 合适的 spaCy 模型会根据需要自动下载并加载。无需手动安装。
• 提取的短语列表包含在LLM提示中，如下所示：

  [预处理候选短语 (spaCy NER)] 以下是使用 spaCy 的检测语言模型从输入文本中自动提取的短语列表。这些短语代表检测到的实体，例如姓名、日期、组织、位置、数字等。此列表仅供参考，可能包含不相关或不正确的内容。LLM 会自行判断，并考虑整个输入文本，灵活地推断出最合适的键值对。

步骤详细信息

该项目的键值提取流水线由多个步骤组成。每个步骤的详细信息如下：

步骤 0：使用 spaCy 进行预处理（语言检测 → 命名实体识别）

• 目的：自动检测输入文本的语言，并使用适当的 spaCy 模型（例如， ja_core_news_md ， en_core_web_sm ， zh_core_web_sm ）提取命名实体。
• 输出：提取出的短语列表，作为提示包含在LLM提示中，以提高键值对提取的准确性。

步骤 1：键值提取（LLM）

• 目的：使用 GPT-4.1-mini 从输入文本和提取的短语列表中提取键值对。
• 细节：
  • 提示包括当同一个键出现多次时返回列表格式的值的指令。
  • 小样本示例旨在包含列表格式的输出。
• 输出：示例： key: person, value: ["Tanaka", "Sato"]

第 2 步：类型注释（LLM）

• 目的：使用 GPT-4.1-mini 推断步骤 1 中提取的每个键值对的数据类型（int、str、bool、list 等）。
• 细节：
  • 类型注释提示包括列表和多值支持的说明。
• 输出：示例： key: person, value: ["Tanaka", "Sato"] -> list[str]

第 3 步：类型评估（法学硕士）

• 目的：使用 GPT-4.1-mini 评估和纠正步骤 2 中的类型注释。
• 细节：
  • 对于每个键值对，GPT-4.1-mini 重新评估类型注释的有效性和上下文。
  • 如果检测到类型错误或歧义，GPT-4.1-mini 会自动更正或补充类型。
  • 示例：更正提取为数字但应为字符串的值，或确定值是列表还是单个值。
• 输出：类型评估的键值对列表。

步骤 4：类型规范化（静态规则 + LLM 回退）

• 目的：将类型评估数据转换为Python的标准类型（int，float，bool，str，list，None等）。
• 细节：
  • 应用静态规范化规则（正则表达式或类型转换函数）将值转换为 Python 的标准类型。
  • 示例：将逗号分隔的值转换为列表，将“true”/“false”转换为布尔值，或将日期表达式转换为标准格式。
  • 如果静态规则无法转换值，请使用基于 LLM 的类型转换回退。
  • 不可转换的值被安全地处理为 None 或 str。
• 输出：Python 类型规范化的键值对列表。

步骤 5：使用 Pydantic 进行最终构建

• 目的：使用 Pydantic 模型（KVOut/KVPayload）验证和构建类型规范化数据。
• 细节：
  • 将每个键值对映射到 Pydantic 模型，确保类型安全和数据完整性。
  • 根据模式验证单个值、列表、空值和复合类型。
  • 如果验证失败，则附加错误信息，同时保留尽可能多的数据。
  • 最终输出以指定的格式（JSON、YAML 或 TOML）返回。
• 输出：类型安全且经过验证的字典或指定格式（JSON/YAML/TOML）输出。

该管道旨在适应未来的列表格式支持和 Pydantic 模式扩展。

关于 TOML 输出限制的说明

• 在 TOML 中，简单数组（例如， items = ["A", "B"] ）可以本机表示，但由于 TOML 规范，对象数组（字典）或深度嵌套结构无法直接表示。
• 因此，复杂列表或嵌套结构（例如， [{"name": "A"}, {"name": "B"}] ）在 TOML 值中存储为“JSON 字符串”。
• 这是一个设计选择，旨在防止由于 TOML 的规范限制而导致信息丢失。
• YAML 和 JSON 格式可以按原样表示嵌套结构。

输入/输出示例

输入：

输出（JSON）：

输出（YAML）：

输出（TOML，简单情况）：

输出（TOML，复杂情况）：

注意：对象数组或嵌套结构在 TOML 中存储为 JSON 字符串。

工具

1. extract_json

• 描述：从任意嘈杂文本中提取键值对，并将它们作为类型安全的 JSON（Python dict）返回。
• 参数：
  • input_text （字符串）：包含噪声或非结构化数据的输入字符串。
• 返回： { "success": True, "result": ... }或{ "success": False, "error": ... }
• 例子：
  { "success": true, "result": { "foo": 1, "bar": "baz" } }

2. extract_yaml

• 描述：从任意噪声文本中提取键值对，并将它们作为类型安全的 YAML（字符串）返回。
• 参数：
  • input_text （字符串）：包含噪声或非结构化数据的输入字符串。
• 返回： { "success": True, "result": ... }或{ "success": False, "error": ... }
• 例子：
  { "success": true, "result": "foo: 1\nbar: baz" }

3. extract_toml

• 描述：从任意嘈杂文本中提取键值对，并将它们作为类型安全的 TOML（字符串）返回。
• 参数：
  • input_text （字符串）：包含噪声或非结构化数据的输入字符串。
• 返回： { "success": True, "result": ... }或{ "success": False, "error": ... }
• 例子：
  { "success": true, "result": "foo = 1\nbar = \"baz\"" }

用法

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 kv-extractor-mcp-server：

要求

• Python 3.9+
• OpenAI 模型的 API 密钥（在env下的settings.json中设置）

运行服务器

如果您想手动运行服务器。

MCP 主机配置

运行此 MCP 服务器时，您必须通过命令行参数明确指定日志输出模式和（如果启用）绝对日志文件路径。

• --log=off ：禁用所有日志记录（不写入任何日志）
• --log=on --logfile=/absolute/path/to/logfile.log ：启用日志记录并将日志写入指定的绝对文件路径
• 启用日志记录时，两个参数均为必填项。如果缺少其中一个、路径不是绝对路径或提供了无效值，服务器将返回错误并退出。

示例：禁用日志记录

示例：启用日志记录（需要绝对日志文件路径）

笔记：

• 启用日志记录后，日志仅写入指定的绝对文件路径。相对路径或省略--logfile将导致错误。
• 当禁用日志记录时，不会输出任何日志。
• 如果所需参数缺失或无效，服务器将无法启动并将打印错误消息。
• MCP 服务器进程必须能够访问和写入日志文件。
• 如果您无法运行此服务器，可能是由于缓存了旧版本的 kv-extractor-mcp-server。请尝试使用最新版本的 kv-extractor-mcp-server（将xyz设置为最新版本），并按照以下设置运行。

执照

GPL-3.0-或更高版本

作者

KunihiroS（及贡献者）