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 파일: ``env 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 사용

http://localhost:3000 접속
왼쪽에서 대화 선택
"Entity 추출" 버튼 클릭
오른쪽에서 결과 확인
쿠폰 "지도 보기" 또는 "캘린더 추가" 클릭

Claude Desktop 사용

멤버십 대화 쿠폰 추천:

Claude Desktop 실행
다음과 같이 요청:

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

Claude가 자동으로:

conversation://1 리소스를 읽어서 대화 분석
장소, 시간, 활동 추출
recommend_coupons 도구를 호출하여 쿠폰 추천
결과를 JSON 형태로 반환

배송 지연 티켓 발급:

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

Claude가 자동으로:

conversation://delivery 리소스를 읽어서 대화 분석
주문번호, 고객명, 상품, 상황 추출
issue_ticket 도구를 호출하여 티켓 생성
티켓 ID와 우선순위 반환

UI 특징 (미니멀 디자인)

2가지 색상: 파랑 (#2563eb) + 검정 (#1f2937)
3단 레이아웃:

대화 선택 & 표시
Entity 추출 버튼
결과 & 액션

Tailwind CSS 사용
반응형 디자인

MCP 서버 기능

리소스 (Resources)

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

conversation://1 - 멤버십 대화 1 (영화 & 아이스크림)
conversation://2 - 멤버십 대화 2 (러닝 & 브런치)
conversation://delivery - 배송 지연 문의
data://membership - 멤버십 파트너 정보

도구 (Tools)

1. `recommend_coupons`

멤버십 쿠폰 추천

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

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

2. `issue_ticket`

배송 지연 티켓 발급

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

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

시연 시나리오

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

대화 선택: "멤버십 대화 1" 선택
Entity 추출: Claude AI가 자동 분석

장소: 강남역, CCW 영화관, 베스킨 랄라스
시간: 토요일 4시
활동: 영화, 아이스크림

쿠폰 추천: 2개 자동 추천

CCW 영화관 (무료 티켓)
베스킨 랄라스 (50% 할인)

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

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

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

Claude가:

대화 분석
Entity 추출
issue_ticket 도구 자동 호출
티켓 발급 결과 반환

기술 스택

프론트엔드

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 서버가 안 보여요

claude_desktop_config.json 파일 경로 확인
server.py의 절대 경로를 사용했는지 확인
Claude Desktop 재시작

Python 의존성 오류

pip install --upgrade mcp

entity-extraction-mcp