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에 대한 Lang 코드.

v0.1.0

• 최초 출시

도구

• /extract_json : 입력 텍스트에서 JSON 형식의 유형이 안전한 키-값 쌍을 추출합니다.
• /extract_yaml : 입력 텍스트에서 YAML 형식의 유형이 안전한 키-값 쌍을 추출합니다.
• /extract_toml : 입력 텍스트에서 TOML 형식의 유형 안전 키-값 쌍을 추출합니다.
  • 참고: TOML 사양으로 인해 객체 배열(dict)이나 깊이 중첩된 구조체는 직접 표현할 수 없습니다. 자세한 내용은 아래 "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 에 구현된 키-값 추출 파이프라인의 처리 흐름을 나타내는 흐름도입니다.

지엑스피1

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단계: 유형 평가(LLM)

• 목적 : 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"를 bool로 변환, 날짜 표현식을 표준 형식으로 변환합니다.
  • 정적 규칙으로 값을 변환할 수 없는 경우 LLM 기반 유형 변환 대체 방법을 사용합니다.
  • 변환할 수 없는 값은 None 또는 str로 안전하게 처리됩니다.
• 출력 : Python 유형으로 정규화된 키-값 쌍 목록입니다.

5단계: Pydantic을 사용한 최종 구조화

• 목적 : Pydantic 모델(KVOut/KVPayload)을 사용하여 유형이 정규화된 데이터를 검증하고 구조화합니다.
• 세부 정보 :
  • 각 키-값 쌍을 Pydantic 모델에 매핑하여 유형 안전성과 데이터 무결성을 보장합니다.
  • 스키마에 따라 단일 값, 목록, null 및 복합 유형을 검증합니다.
  • 유효성 검사에 실패하면 가능한 한 많은 데이터를 보존하면서 오류 정보를 첨부합니다.
  • 최종 출력은 지정된 형식(JSON, YAML 또는 TOML)으로 반환됩니다.
• 출력 : 유형이 안전하고 검증된 dict 또는 지정된 형식(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를 자동으로 설치하려면:

요구 사항

• 파이썬 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(및 기여자)