Skip to main content
Glama
biancaroh-design

entity-extraction-mcp

by biancaroh-design
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Entity 추출 MCP + Next.js Web UI

대화에서 AI(Claude)가 Entity를 추출하고 즉시 액션(쿠폰 추천, 티켓 발급)으로 연결하는 시스템입니다.

주요 특징

1. AI 기반 Entity 추출

  • Anthropic Claude API를 사용하여 대화 분석

  • 자동 대화 유형 감지 (멤버십 vs 배송 지연)

  • 정확한 정보 추출 (장소, 시간, 활동, 주문정보 등)

2. 2가지 사용 방법

  • 웹 UI: Next.js 기반 미니멀 인터페이스

  • Claude Desktop: MCP 서버 통합 사용

3. 즉시 액션

  • 멤버십: 쿠폰 추천 + 지도 연동 + 캘린더 추가

  • 배송 지연: 티켓 자동 발급 + 권장 액션 제시

Related MCP server: Logistics AI MCP

프로젝트 구조

testEntityMCP/
├── server.py                 # Python MCP 서버 (Claude Desktop용)
├── requirements.txt          # Python 의존성
├── pyproject.toml           # Python 프로젝트 설정
├── web/                     # Next.js 웹 UI
│   ├── app/
│   │   ├── page.tsx         # 메인 페이지
│   │   ├── layout.tsx       # 레이아웃
│   │   ├── globals.css      # 글로벌 스타일
│   │   └── api/             # API 라우트
│   │       ├── extract/     # Entity 추출 (Claude API)
│   │       ├── recommend/   # 쿠폰 추천
│   │       └── ticket/      # 티켓 발급
│   ├── components/          # React 컴포넌트
│   │   ├── ConversationPanel.tsx
│   │   └── ResultPanel.tsx
│   ├── public/data/         # JSON 데이터
│   └── package.json
├── conversation.json        # 멤버십 대화 1
├── conversation2.json       # 멤버십 대화 2
├── delivery_delay_inquiry_conversation.json
├── membership_personas_and_partners_kr.json
└── claude_desktop_config.json  # Claude Desktop 설정 예시

설치 및 실행

필수 요구사항

  • Python 3.10+

  • Node.js 18+

  • Anthropic API Key (웹 UI 사용 시)

1. Python MCP 서버 설정 (Claude Desktop용)

# Python 의존성 설치
pip install -r requirements.txt

# 또는 uv 사용
uv pip install -e .

2. Next.js 웹 UI 설정

# 웹 디렉토리로 이동
cd web

# 의존성 설치
npm install

# 환경 변수 설정
cp .env.local.example .env.local
# .env.local 파일을 열어서 ANTHROPIC_API_KEY 설정

.env.local 파일:

ANTHROPIC_API_KEY=your-api-key

3. 웹 UI 실행

# 개발 모드
cd web
npm run dev

# 브라우저에서 열기
open http://localhost:3000

4. Claude Desktop MCP 설정

설정 파일 위치:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

설정 파일에 추가:

{
  "mcpServers": {
    "entity-extraction": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/Desktop/testEntityMCP",
        "run",
        "entity-extraction-mcp"
      ]
    }
  }
}

중요:

  • YOUR_USERNAME을 본인의 사용자명으로 변경하세요

  • uv 경로 확인: which uv 명령어로 확인 가능

  • 프로젝트 디렉토리 경로를 본인의 실제 경로로 변경하세요

적용:

Claude Desktop을 완전히 종료하고 다시 실행하면 MCP 서버가 활성화됩니다.

사용 방법

웹 UI 사용

  1. http://localhost:3000 접속

  2. 왼쪽에서 대화 선택

  3. "Entity 추출" 버튼 클릭

  4. 오른쪽에서 결과 확인

  5. 쿠폰 "지도 보기" 또는 "캘린더 추가" 클릭

Claude Desktop 사용

멤버십 대화 쿠폰 추천:

  1. Claude Desktop 실행

  2. 다음과 같이 요청:

    멤버십 대화 1을 읽고 장소를 추출한 다음, 쿠폰을 추천해줘

Claude가 자동으로:

  • conversation://1 리소스를 읽어서 대화 분석

  • 장소, 시간, 활동 추출

  • recommend_coupons 도구를 호출하여 쿠폰 추천

  • 결과를 JSON 형태로 반환

배송 지연 티켓 발급:

배송 지연 문의 대화를 읽고, 티켓을 발급해줘

Claude가 자동으로:

  • conversation://delivery 리소스를 읽어서 대화 분석

  • 주문번호, 고객명, 상품, 상황 추출

  • issue_ticket 도구를 호출하여 티켓 생성

  • 티켓 ID와 우선순위 반환

UI 특징 (미니멀 디자인)

  • 2가지 색상: 파랑 (#2563eb) + 검정 (#1f2937)

  • 3단 레이아웃:

    1. 대화 선택 & 표시

    2. Entity 추출 버튼

    3. 결과 & 액션

  • Tailwind CSS 사용

  • 반응형 디자인

MCP 서버 기능

리소스 (Resources)

MCP 서버가 제공하는 대화 데이터:

  • conversation://1 - 멤버십 대화 1 (영화 & 아이스크림)

  • conversation://2 - 멤버십 대화 2 (러닝 & 브런치)

  • conversation://delivery - 배송 지연 문의

  • data://membership - 멤버십 파트너 정보

도구 (Tools)

1. recommend_coupons

멤버십 쿠폰 추천

입력:

{
  "places": ["강남역", "CCW 영화관"],
  "times": ["토요일 4시"],
  "activities": ["영화", "아이스크림"]
}

출력:

{
  "success": true,
  "recommendedCoupons": [
    {
      "partnerName": "CCW 영화관",
      "description": "연간 무료 3회, 1+1 9회",
      "location": "신논현역 6번 출구 근처",
      "mapUrl": "https://naver.me/..."
    }
  ]
}

2. issue_ticket

배송 지연 티켓 발급

입력:

{
  "orderNumber": "SP20251024-1123",
  "customerName": "김은지",
  "product": "러닝화",
  "issueSummary": "배송 예정일 경과, 미도착",
  "deliveryStatus": "물류센터 대기 중",
  "customerDecision": "취소 고려 중"
}

출력:

{
  "success": true,
  "ticket": {
    "ticketId": "TKT-1234567890-ABC",
    "priority": "high",
    "actions": [
      {
        "type": "offer_cancellation",
        "description": "취소 절차 안내 및 환불 처리"
      }
    ]
  }
}

시연 시나리오

시나리오 1: 웹 UI - 멤버십 대화

  1. 대화 선택: "멤버십 대화 1" 선택

  2. Entity 추출: Claude AI가 자동 분석

    • 장소: 강남역, CCW 영화관, 베스킨 랄라스

    • 시간: 토요일 4시

    • 활동: 영화, 아이스크림

  3. 쿠폰 추천: 2개 자동 추천

    • CCW 영화관 (무료 티켓)

    • 베스킨 랄라스 (50% 할인)

  4. 액션: 지도 보기 → 네이버 지도 열림

시나리오 2: Claude Desktop - 배송 지연

Claude에게 요청:

conversation://delivery 리소스를 읽고,
고객의 주문번호, 이름, 상품명, 배송 상태를 추출해줘.
그리고 issue_ticket 도구로 티켓을 발급해줘.

Claude가:

  1. 대화 분석

  2. Entity 추출

  3. issue_ticket 도구 자동 호출

  4. 티켓 발급 결과 반환

기술 스택

프론트엔드

  • Next.js 15 (App Router)

  • TypeScript

  • Tailwind CSS

  • React 18

백엔드

  • Python 3.10+

  • MCP SDK (Model Context Protocol)

  • Anthropic Claude API (Sonnet 3.5)

트러블슈팅

웹 UI가 안 보여요

cd web
npm run dev
# http://localhost:3000 접속

Anthropic API 오류

.env.local 파일에 올바른 API 키가 설정되어 있는지 확인하세요.

Claude Desktop에서 MCP 서버가 안 보여요

  1. claude_desktop_config.json 파일 경로 확인

  2. server.py의 절대 경로를 사용했는지 확인

  3. Claude Desktop 재시작

Python 의존성 오류

pip install --upgrade mcp

라이선스

MIT

문의

프로젝트 관련 문의사항이 있으시면 이슈를 생성해주세요.

entity-extraction-mcp

Available Tools

2 tools
issue_ticketA

배송 지연 건에 대한 티켓을 발급합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
productYes상품명
orderNumberYes주문번호
customerNameYes고객명
issueSummaryNo이슈 요약
deliveryStatusNo배송 상태
customerDecisionNo고객 의사결정 (취소 고려 중 / 수령 대기)

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It only states the action (issuing a ticket) without mentioning side effects, permissions, idempotency, or response behavior. It does not go beyond the obvious creation aspect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence in Korean that immediately states the tool's purpose. It is front-loaded and contains no filler, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is minimal and lacks information about expected return values or post-issuance behavior, especially given there is no output schema. It also does not integrate with the sibling tool context. The schema covers parameters, but the overall description does not provide enough operational context for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema includes descriptions for all six parameters, so schema description coverage is 100%. The tool description adds no additional parameter meaning, leaving the schema to fully explain each field. This meets the baseline for schema-covered parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool issues tickets specifically for delivery delay cases (배송 지연 건에 대한 티켓을 발급합니다), using a specific verb '발급' and resource '티켓'. This distinguishes it from the sibling tool recommend_coupons, which handles coupon recommendations, so the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear context (orders with delivery delays) but does not explicitly state when not to use it or mention alternatives like recommend_coupons. It implies usage for delay scenarios but lacks explicit exclusion or comparison.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recommend_couponsA

추출된 Entity를 기반으로 멤버십 쿠폰을 추천합니다. places 배열이 필요합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
timesNo대화에서 추출된 시간 목록 (선택사항)
placesYes대화에서 추출된 장소 목록 (예: ['강남역', 'CCW 영화관'])
activitiesNo대화에서 추출된 활동 목록 (선택사항)

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states the action and a required parameter, but does not mention whether the operation is read-only, has side effects, requires auth, or what happens if required data is missing. This lack of context for a tool with no annotations is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that state the purpose and the key requirement with no filler. It is front-loaded and every word earns its place, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 simple string-array parameters, no output schema), the description is minimally adequate. It explains what the tool does and the required parameter. However, since there is no output schema, the description does not explain what the tool returns (e.g., a list of recommended coupons), leaving a gap for the agent to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters (times, places, activities). The description adds no semantic value beyond noting that the 'places' array is required, which is already present in the schema. This meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: recommending membership coupons based on extracted entities. It uses a specific verb ('recommends') and resource ('membership coupons'), making the purpose clear. However, it does not explicitly differentiate from the sibling tool 'issue_ticket', so it doesn't fully earn a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when you have extracted entities and need coupon recommendations, with the explicit prerequisite that the 'places' array is required. It does not mention alternatives or exclusions, but the context is sufficiently clear for basic usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedissue_ticket
    • First observedrecommend_coupons
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools, recommend_coupons and issue_ticket, have completely distinct purposes: one handles coupon recommendations based on extracted entities, while the other issues tickets for delivery delays. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow the consistent verb_noun pattern: recommend_coupons and issue_ticket. This makes the naming predictable and easy to understand.

Tool Count3/5

With only 2 tools, the server is on the low end of the scale. While the tools themselves are focused, the server's name suggests a broader entity-extraction purpose, making the count feel somewhat thin.

Completeness1/5

The server is named entity-extraction-mcp, but there are no tools for extracting entities at all. The available tools are downstream actions that rely on extracted data, creating a severe gap between the server's stated purpose and its actual capabilities.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers