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. 즉시 액션

• 멤버십: 쿠폰 추천 + 지도 연동 + 캘린더 추가
• 배송 지연: 티켓 자동 발급 + 권장 액션 제시

프로젝트 구조

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