DraCor MCP 서버

Drama Corpora Project(DraCor) API와 상호 작용하기 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 MCP 서버를 사용하면 Claude 또는 다른 LLM을 통해 극적 텍스트와 그 등장인물 네트워크를 원활하게 분석할 수 있습니다.

개요

이 프로젝트는 DraCor API v1에 대한 액세스를 제공하는 공식 모델 컨텍스트 프로토콜(Model Context Protocol) Python SDK를 사용하여 MCP 서버를 구현합니다. 이를 통해 Claude를 비롯한 LLM들은 극적 텍스트 코퍼스와 상호작용하고, 등장인물 네트워크를 분석하고, 연극 정보를 검색하고, 다양한 언어와 시대의 극작에 대한 통찰력을 얻을 수 있습니다.

이 프로젝트에는 두 가지 구현이 포함됩니다.

dracor_mcp_fastmcp.py - v1 API를 사용한 FastMCP 데코레이터 기반 API를 사용한 간소화된 구현

특징

통합 인터페이스를 통해 DraCor API v1에 액세스
인증이 필요하지 않습니다(DraCor API는 공개적으로 접근 가능합니다)
DraCor 엔터티에 대한 구조화된 데이터 모델
운영 지원:
- 코퍼스 및 연극 정보 검색
- 캐릭터 네트워크 분석
- 연극에 대한 지표 및 통계
- 캐릭터 정보 및 음성 텍스트
- 비교 플레이 분석
- 검색 기능
- 캐릭터 관계 데이터
- 다양한 형식(CSV, GEXF, GraphML)의 네트워크 데이터
- 연극 전반의 성별 분석
- 일반 텍스트 및 TEI XML 형식의 전체 텍스트 검색
- 완전한 연극 텍스트 분석

설정

필수 조건

Python 3.10 이상
UV 패키지 관리자(권장) 또는 pip

UV를 이용한 설치

UV 설치:

지엑스피1

가상 환경을 만들고 종속성을 설치합니다.

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Claude Desktop에 MCP 서버를 설치하세요:

표준 구현(v0 API):

mcp install dracor_mcp_server.py

또는 v1 API를 사용한 FastMCP 구현의 경우(권장):

mcp install dracor_mcp_fastmcp.py

개발 모드

테스트 및 개발을 위해:

mcp dev dracor_mcp_server.py

또는 v1 API를 사용한 FastMCP 구현의 경우(권장):

mcp dev dracor_mcp_fastmcp.py

이렇게 하면 MCP 검사기가 실행되어 도구와 리소스를 대화형으로 테스트할 수 있습니다.

클로드 구성

Claude 구성 파일에 다음을 추가하여 Claude가 DraCor MCP 서버를 사용하도록 직접 구성할 수도 있습니다.

{
  "tools": {
    "DraCor API v1": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "requests",
        "--with",
        "pydantic",
        "--with",
        "python-multipart",
        "mcp",
        "run",
        "/path/to/dracor-mcp/dracor_mcp_fastmcp.py"
      ]
    }
  }
}

/path/to/dracor-mcp/ dracor-mcp 디렉터리의 실제 경로로 바꾸세요. 이 구성에서는 uv run 사용하여 사전 설치 없이 필요한 종속성을 갖춘 MCP 서버를 실행합니다.

Docker(선택 사항)

Docker를 사용하는 것을 선호하는 경우:

docker build -t dracor-mcp .
docker run dracor-mcp

대신 v1 API와 함께 FastMCP 구현을 사용하려면:

docker run -e IMPLEMENTATION=fastmcp dracor-mcp

구현 세부 사항

표준 MCP 구현(v0 API)

dracor_mcp_server.py 의 표준 구현은 이전 v0 API와 함께 핵심 MCP SDK 클래스를 사용합니다.

Resource - API 리소스 정의용
MCPToolImpl - 도구 구현용
PromptTemplate - 프롬프트 템플릿을 만드는 데 사용

FastMCP 구현(v1 API)

dracor_mcp_fastmcp.py 의 FastMCP 구현은 현재 v1 API를 사용하여 보다 간결한 데코레이터 기반 접근 방식을 사용합니다.

@mcp.resource() - API 리소스를 정의하기 위해
@mcp.tool() - 도구 구현용
@mcp.prompt() - 프롬프트 템플릿을 만드는 데 사용

이 접근 방식을 사용하면 동일한 기능을 제공하면서도 더욱 포괄적인 API 기능에 액세스할 수 있고, 더 깔끔하고 유지 관리하기 쉬운 코드를 얻을 수 있습니다.

v1 API 기능

v1 API 구현은 많은 추가 엔드포인트와 기능에 대한 액세스를 제공합니다.

API 정보 - DraCor API 버전 정보
코퍼스 메타데이터 - 코퍼스의 모든 연극에 대한 자세한 메타데이터
플레이 메트릭 - 네트워크 메트릭 및 분석 데이터
문자 네트워크 데이터 - CSV, GEXF 및 GraphML 형식
캐릭터 관계 - 캐릭터 간의 명시적 관계
음성 텍스트 필터 - 성별, 관계 유형 또는 캐릭터 역할별로 필터링
무대 지시 - 스피커가 있거나 없는 무대 지시를 검색합니다.
캐릭터 검색 - 특정 캐릭터가 포함된 연극 찾기(위키데이터 ID 기준)

용법

Claude Desktop에 설치하면 Claude를 통해 DraCor API와 상호 작용할 수 있습니다. 몇 가지 예를 들면 다음과 같습니다.

기본 쿼리

Claude에게 사용 가능한 코퍼스를 나열해 달라고 요청하세요.

Can you list all available drama corpora in DraCor?

특정 연극에 대한 정보를 얻으세요:

Tell me about Goethe's Faust in the German corpus

캐릭터 네트워크 분석:

Analyze the character network in Hamlet from the Shakespeare corpus

고급 쿼리

캐릭터 관계 분석:

What are the strongest character relationships in Pushkin's Boris Godunov?

연극을 비교해보세요:

Compare Goethe's Faust and Schiller's Die Räuber in terms of network density and character count

캐릭터의 중요도 분석:

Who are the most central characters in Shakespeare's Hamlet based on speaking time and relationships?

성별 대표성 분석:

Analyze the gender distribution and representation in Molière's Le Misanthrope

다양한 연극에서 캐릭터 찾기:

Find all plays that feature a character named "Hamlet" or similar

희곡의 전체 텍스트를 분석하세요:

Provide a comprehensive analysis of the full text of Goethe's Faust

연극 텍스트에서 테마 추출:

What are the main themes and motifs in the full text of Shakespeare's Hamlet?

언어 패턴 분석:

Analyze the language patterns and style in Chekhov's The Cherry Orchard

문학 분석 쿼리

플레이 구조 분석:

Analyze the structure of Molière's Le Misanthrope in terms of acts, scenes, and dialogue distribution

저자 비교:

Compare the network structures in plays by Shakespeare and Molière

역사적 맥락:

Put Pushkin's Boris Godunov in its historical context and analyze how this is reflected in the character network

리소스(v1 API)

FastMCP 서버는 다음과 같은 리소스를 제공합니다.

info:// - API 정보 및 버전 세부 정보
corpora:// - 사용 가능한 모든 코퍼스 목록
corpus://{corpus_name} - 특정 코퍼스에 대한 정보
corpus_metadata://{corpus_name} - 코퍼스의 모든 연극에 대한 메타데이터
plays://{corpus_name} - 특정 코퍼스의 연극 목록
play://{corpus_name}/{play_name} - 특정 연극에 대한 정보
play_metrics://{corpus_name}/{play_name} - 특정 플레이에 대한 네트워크 메트릭
characters://{corpus_name}/{play_name} - 특정 연극의 캐릭터 목록
spoken_text://{corpus_name}/{play_name} - 연극의 음성 텍스트(선택적 필터 포함)
spoken_text_by_character://{corpus_name}/{play_name} - 각 캐릭터가 말하는 텍스트
stage_directions://{corpus_name}/{play_name} - 연극의 무대 지시
network_data://{corpus_name}/{play_name} - CSV 형식의 네트워크 데이터
relations://{corpus_name}/{play_name} - CSV 형식의 캐릭터 관계 데이터
character_by_wikidata://{wikidata_id} - Wikidata ID별로 캐릭터가 포함된 연극 목록을 표시합니다.
full_text://{corpus_name}/{play_name} - 일반 텍스트 형식의 연극 전체 텍스트
tei_text://{corpus_name}/{play_name} - 연극의 전체 TEI XML 텍스트

도구(v1 API)

FastMCP 서버는 다음과 같은 도구를 제공합니다.

search_plays - 쿼리를 기반으로 연극 검색
compare_plays - 두 연극을 측정 기준과 구조 측면에서 비교합니다.
analyze_character_relations - 연극 속 캐릭터 관계 분석
analyze_play_structure - 연극의 구조를 분석합니다
find_character_across_plays - 여러 플레이에서 캐릭터 찾기
analyze_full_text - 대화와 무대 지시를 포함한 연극의 전체 텍스트를 분석합니다.

프롬프트 템플릿(v1 API)

FastMCP 서버에는 다음과 같은 프롬프트 템플릿이 포함되어 있습니다.

analyze_play - 특정 플레이를 분석하기 위한 템플릿
character_analysis - 특정 캐릭터를 분석하기 위한 템플릿
network_analysis - 캐릭터 네트워크 분석을 위한 템플릿
comparative_analysis - 두 연극을 비교하기 위한 템플릿
gender_analysis - 연극의 성별 표현을 분석하기 위한 템플릿
historical_context - 연극의 역사적 맥락을 분석하기 위한 템플릿
full_text_analysis - 연극의 전체 텍스트를 분석하기 위한 템플릿

작동 원리

이 프로젝트에서는 공식 Model Context Protocol Python SDK를 사용하여 Claude가 DraCor API와 상호 작용하는 데 사용할 수 있는 리소스와 도구를 제공하는 MCP 서버를 구축합니다.

클로드에게 극적 텍스트에 대한 질문을 하면 다음과 같은 결과가 나올 수 있습니다.

코퍼스, 연극, 캐릭터, 네트워크와 같은 리소스에 액세스하세요
도구를 사용하여 연극을 검색, 비교 및 분석하세요
데이터를 기반으로 통찰력과 시각화를 제공합니다.

DraCor API는 공개적으로 접근 가능하므로 인증이 필요하지 않습니다.

속도 제한

DraCor의 속도 제한 정책을 주의하세요. 서버에는 .env 파일에서 구성할 수 있는 선택적 속도 제한 설정이 포함되어 있습니다.

문제 해결

문제가 발생하는 경우:

Python 3.10 이상을 사용하고 있는지 확인하세요.
디버깅을 위해 개발 모드에서 실행해보세요: mcp dev dracor_mcp_fastmcp.py
https://dracor.org/doc/api 에서 DraCor API 상태를 확인하세요.

MCP와 함께 사용하도록 프롬프트됨

"당신의 임무는 DraCor 데이터베이스에서 역사적 사건을 분석하여 캐릭터 ID 태그 문제를 파악하는 것입니다. 구체적으로는 다음과 같습니다.

DraCor 데이터베이스에서 연극을 선택하고 캐릭터 관계, 전체 텍스트, 구조에 대한 포괄적인 분석을 수행합니다.
다음을 포함하여 문자 ID 태그의 모든 불일치 사항을 식별합니다.
- 캐릭터 이름의 철자 변형
- 캐릭터 이름 혼동 또는 합치기
- 역사적 철자 변형
- 캐릭터 ID와 스테이지 지시 간의 불일치
다음 열을 포함하는 구조화된 표 형식으로 잠재적인 문자 ID 태그 오류에 대한 자세한 보고서를 작성합니다.
- 텍스트 ID(연극의 고유 식별자)
- 현재 데이터베이스에서 사용되는 문자 ID
- 텍스트에서 문제가 있는 변형이 발견되었습니다.
- 오류 유형(철자, 변형, 혼동 등)
- 문제에 대한 설명

이 텍스트에 대해 이렇게 하세요: [플레이네임]"

특허

MIT

감사의 말

이 프로젝트에서는 다음을 사용합니다.

MCP 서버 구축을 위한 Model Context Protocol Python SDK
극적인 텍스트 및 네트워크 데이터를 위한 DraCor API v1
기반 데이터와 API를 제공하는 Drama Corpora Project(DraCor)

DraCor MCP Server

Integrations