Flexible Key-Value Extracting MCP Server

Гибкий сервер MCP для извлечения пар «ключ-значение»

Версия: 0.3.1

Этот сервер MCP извлекает пары ключ-значение из произвольного, зашумленного или неструктурированного текста с помощью LLM (GPT-4.1-mini) и pydantic-ai. Он обеспечивает безопасность типов и поддерживает несколько форматов вывода (JSON, YAML, TOML). Сервер устойчив к любым входным данным и всегда пытается максимально структурировать данные, однако идеальное извлечение не гарантируется .

🤔💡 Зачем использовать этот MCP-сервер?

В то время как многие службы Large Language Model (LLM) предлагают возможности структурированного вывода, этот сервер MCP обеспечивает явные преимущества для извлечения ключевого значения, особенно из сложного реального текста:

• 🔑🔍 Автоматическое обнаружение ключей : основная сила заключается в его способности автономно идентифицировать и извлекать соответствующие пары ключ-значение из неструктурированного текста без необходимости предопределенных ключей . В то время как типичные структурированные выходные данные LLM требуют указания искомых ключей, этот сервер обнаруживает их, что делает его высокоэффективным для разнообразных и непредсказуемых данных, где структура заранее неизвестна.
• 💪🧱 Превосходная надежность для сложных входных данных : он отлично справляется с произвольным, шумным или неструктурированным текстом, где стандартные структурированные выходные данные LLM могут давать сбои. Многоступенчатый конвейер специально разработан для просеивания и осмысления несовершенных данных.
• 🌐🗣️ Расширенная многоязычная предварительная обработка : перед обработкой LLM используется spaCy для распознавания именованных сущностей (NER) на японском, английском и китайском (упрощенном/традиционном) языках, что значительно повышает точность извлечения для этих языков за счет предоставления фраз-кандидатов с богатым контекстом.
• 🔄✍️ Итеративное уточнение и типизация : в отличие от однопроходного извлечения, этот сервер использует сложный конвейер, включающий аннотацию типа на основе LLM, оценку типа на основе LLM и нормализацию на основе правил/LLM-fallback. Это обеспечивает более точные и контекстно соответствующие типы данных.
• ✅🛡️ Гарантированная безопасность типов и соответствие схеме : окончательное структурирование с помощью Pydantic гарантирует, что выходные данные не только структурированы, но и безопасны с точки зрения типов, а также проверены на соответствие определенной схеме, предоставляя надежные данные для последующих приложений.
• 📊⚙️ Последовательный и предсказуемый вывод : сервер всегда возвращает правильно сформированный ответ, даже если извлечение выполнено частично или возникают проблемы, что имеет решающее значение для создания надежных автоматизированных систем.

Заметки о выпуске

v0.3.1

• Обновление: улучшена подсказка по оценке типа для надежного исправления.
• Обновление: Добавлена сильная сторона этого сервера MCP в README.md

v0.2.0

• Исправление: языковой код для zh-cn / zh-tw.

v0.1.0

• Первоначальный выпуск

Инструменты

• /extract_json : Извлекает типобезопасные пары ключ-значение в формате JSON из входного текста.
• /extract_yaml : Извлекает типобезопасные пары ключ-значение в формате YAML из входного текста.
• /extract_toml : Извлекает типобезопасные пары ключ-значение в формате TOML из входного текста.
  • Примечание: Из-за спецификаций TOML массивы объектов (dicts) или глубоко вложенные структуры не могут быть представлены напрямую. Подробности см. в разделе «Примечание об ограничениях вывода 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 для определения типа данных (int, str, bool, list и т. д.) каждой пары ключ-значение, извлеченной на шаге 1.
• Подробности :
  • Подсказка аннотации типа включает инструкции по поддержке списков и множественных значений.
• Вывод : Пример: key: person, value: ["Tanaka", "Sato"] -> list[str]

Шаг 3: Оценка типа (LLM)

• Цель : использовать GPT-4.1-mini для оценки и исправления аннотаций типов из шага 2.
• Подробности :
  • Для каждой пары «ключ-значение» GPT-4.1-mini повторно оценивает допустимость и контекст аннотации типа.
  • При обнаружении ошибок или неоднозначностей типа GPT-4.1-mini автоматически исправляет или дополняет тип.
  • Пример: Исправление значения, извлеченного как число, но должно быть строкой, или определение того, является ли значение списком или отдельным значением.
• Вывод : список пар ключ-значение с оценкой типа.

Шаг 4: Нормализация типов (статические правила + резервный вариант LLM)

• Назначение : Преобразовать данные с оцененным типом в стандартные типы Python (int, float, bool, str, list, None и т. д.).
• Подробности :
  • Применяйте правила статической нормализации (регулярные выражения или функции преобразования типов) для преобразования значений в стандартные типы Python.
  • Пример: преобразование значений, разделенных запятыми, в списки, «истина»/«ложь» в логические значения или выражений дат в стандартные форматы.
  • Если статические правила не могут преобразовать значение, используйте резервное преобразование типов на основе LLM.
  • Неконвертируемые значения безопасно обрабатываются как None или str.
• Вывод : список пар ключ-значение, нормализованный по типу Python.

Шаг 5: Окончательное структурирование с помощью Pydantic

• Цель : Проверка и структурирование нормализованных по типу данных с использованием моделей Pydantic (KVOut/KVPayload).
• Подробности :
  • Сопоставьте каждую пару «ключ-значение» с моделями Pydantic, гарантируя безопасность типов и целостность данных.
  • Проверяйте отдельные значения, списки, значения null и составные типы в соответствии со схемой.
  • Если проверка не пройдена, прикрепите информацию об ошибке, сохранив как можно больше данных.
  • Окончательный вывод возвращается в указанном формате (JSON, YAML или TOML).
• Вывод : типобезопасный и проверенный словарь или указанный формат вывода (JSON/YAML/TOML).

Этот конвейер разработан с учетом поддержки будущих форматов списков и расширений схемы Pydantic.

Примечание об ограничениях вывода TOML

• В TOML простые массивы (например, items = ["A", "B"] ) могут быть представлены изначально, но массивы объектов (dicts) или глубоко вложенные структуры не могут быть представлены напрямую из-за спецификаций TOML.
• Поэтому сложные списки или вложенные структуры (например, [{"name": "A"}, {"name": "B"}] ) хранятся как "строки JSON" в значениях TOML.
• Это решение было принято для предотвращения потери информации из-за ограничений спецификации TOML.
• Форматы YAML и JSON могут представлять вложенные структуры «как есть».

Пример ввода/вывода

Вход:

Вывод (JSON):

Вывод (YAML):

Вывод (TOML, простой случай):

Вывод (TOML, сложный случай):

Примечание: Массивы объектов или вложенные структуры хранятся в виде строк JSON в TOML.

Инструменты

1. extract_json

• Описание : Извлекает пары «ключ-значение» из произвольного зашумленного текста и возвращает их в виде типобезопасного JSON (словарь Python).
• Аргументы :
  • input_text (string): Входная строка, содержащая зашумленные или неструктурированные данные.
• Возвращает : { "success": True, "result": ... } или { "success": False, "error": ... }
• Пример :
  { "success": true, "result": { "foo": 1, "bar": "baz" } }

2. extract_yaml

• Описание : Извлекает пары «ключ-значение» из произвольного зашумленного текста и возвращает их в виде типобезопасного YAML (строки).
• Аргументы :
  • input_text (string): Входная строка, содержащая зашумленные или неструктурированные данные.
• Возвращает : { "success": True, "result": ... } или { "success": False, "error": ... }
• Пример :
  { "success": true, "result": "foo: 1\nbar: baz" }

3. extract_toml

• Описание : Извлекает пары «ключ-значение» из произвольного зашумленного текста и возвращает их в виде типобезопасного TOML (строки).
• Аргументы :
  • input_text (string): Входная строка, содержащая зашумленные или неструктурированные данные.
• Возвращает : { "success": True, "result": ... } или { "success": False, "error": ... }
• Пример :
  { "success": true, "result": "foo = 1\nbar = \"baz\"" }

Использование

Установка через Smithery

Чтобы автоматически установить kv-extractor-mcp-server для Claude Desktop через Smithery :

Требования

• Питон 3.9+
• Ключ API для моделей OpenAI (устанавливается в settings.json в env )

Запуск сервера

На случай, если вы хотите запустить сервер вручную.

Конфигурация хоста MCP

При запуске этого сервера MCP необходимо явно указать режим вывода журнала и (если включено) абсолютный путь к файлу журнала с помощью аргументов командной строки .

• --log=off : Отключить все журналы (журналы не пишутся)
• --log=on --logfile=/absolute/path/to/logfile.log : Включить ведение журнала и записывать журналы в указанный абсолютный путь к файлу
• Оба аргумента требуются , если включено ведение журнала. Сервер выйдет с ошибкой, если один из них отсутствует, путь не абсолютный или если указаны недопустимые значения.

Пример: ведение журнала отключено

Пример: Ведение журнала включено (требуется абсолютный путь к файлу журнала)

Примечание:

• Если включено ведение журнала, журналы записываются только по указанному абсолютному пути к файлу. Относительные пути или пропуск --logfile приведут к ошибке.
• Если ведение журнала отключено, журналы не выводятся.
• Если требуемые аргументы отсутствуют или недействительны, сервер не запустится и выведет сообщение об ошибке.
• Файл журнала должен быть доступен и доступен для записи процессу сервера MCP.
• Если у вас возникли проблемы с запуском этого сервера, это может быть связано с кэшированием старой версии kv-extractor-mcp-server. Попробуйте запустить его с последней версией (установите xyz на последнюю версию) kv-extractor-mcp-server с помощью следующих настроек.

Лицензия

GPL-3.0 или более поздняя версия

Автор

KunihiroS (и участники)