Servidor DraCor MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con la API del Proyecto de Corpora Dramática (DraCor). Este servidor MCP permite analizar textos dramáticos y sus redes de personajes sin problemas mediante Claude u otros LLM.

Descripción general

Este proyecto implementa un servidor MCP utilizando el SDK oficial de Python del Protocolo de Contexto de Modelo, que proporciona acceso a la API DraCor v1. Esto permite a Claude y a otros LLM interactuar con corpus de textos dramáticos, analizar redes de personajes, recuperar información de obras y generar información sobre obras dramáticas en diferentes idiomas y períodos.

El proyecto incluye dos implementaciones:

dracor_mcp_fastmcp.py : implementación optimizada mediante la API basada en decorador FastMCP con API v1

Características

Acceso a DraCor API v1 a través de una interfaz unificada
No se requiere autenticación (la API de DraCor es de acceso público)
Modelos de datos estructurados para entidades DraCor
Apoyo a las operaciones:
- Recuperación de información de corpus y juegos
- Análisis de red de caracteres
- Métricas y estadísticas de las jugadas
- Información del personaje y texto hablado
- Análisis comparativo del juego
- Funcionalidad de búsqueda
- Datos de relación entre personajes
- Datos de red en múltiples formatos (CSV, GEXF, GraphML)
- Análisis de género en las obras
- Recuperación de texto completo en formatos de texto plano y XML TEI
- Análisis completo del texto de la obra

Configuración

Prerrequisitos

Python 3.10 o superior
Gestor de paquetes UV (recomendado) o pip

Instalación con UV

Instalar UV:

pip install uv

Cree un entorno virtual e instale dependencias:

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

Instalar el servidor MCP en Claude Desktop:

Para la implementación estándar (API v0):

mcp install dracor_mcp_server.py

O para la implementación de FastMCP con API v1 (recomendado):

mcp install dracor_mcp_fastmcp.py

Modo de desarrollo

Para pruebas y desarrollo:

mcp dev dracor_mcp_server.py

O para la implementación de FastMCP con API v1 (recomendado):

mcp dev dracor_mcp_fastmcp.py

Esto iniciará el Inspector MCP donde podrá probar sus herramientas y recursos de forma interactiva.

Configuración de Claude

También puede configurar directamente Claude para usar el servidor DraCor MCP agregando lo siguiente a su archivo de configuración de Claude:

{
  "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"
      ]
    }
  }
}

Reemplace /path/to/dracor-mcp/ con la ruta real a su directorio dracor-mcp. Esta configuración utiliza uv run para ejecutar el servidor MCP con las dependencias necesarias sin necesidad de una instalación previa.

Docker (opcional)

Si prefieres usar Docker:

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

Para utilizar la implementación de FastMCP con la API v1 en su lugar:

docker run -e IMPLEMENTATION=fastmcp dracor-mcp

Detalles de implementación

Implementación estándar de MCP (API v0)

La implementación estándar en dracor_mcp_server.py utiliza las clases principales del SDK de MCP con la API v0 anterior:

Resource : para definir recursos de API
MCPToolImpl - Para implementar herramientas
PromptTemplate : para crear plantillas de indicaciones

Implementación de FastMCP (API v1)

La implementación de FastMCP en dracor_mcp_fastmcp.py utiliza un enfoque basado en decoradores más conciso con la API v1 actual:

@mcp.resource() - Para definir recursos de API
@mcp.tool() - Para implementar herramientas
@mcp.prompt() - Para crear plantillas de indicaciones

Este enfoque da como resultado un código más limpio y fácil de mantener, al tiempo que proporciona la misma funcionalidad pero con acceso a características de API más completas.

Características de la API v1

La implementación de la API v1 proporciona acceso a muchos puntos finales y capacidades adicionales:

Información de la API : información de la versión de la API de DraCor
Metadatos del corpus : metadatos detallados de todas las obras de un corpus
Métricas de juego : métricas de red y datos de análisis
Datos de red de caracteres : formatos CSV, GEXF y GraphML
Relaciones entre personajes : Relaciones explícitas entre personajes
Filtros de texto hablado : filtre por género, tipo de relación o rol del personaje
Acotaciones : recupera acotaciones con o sin oradores
Búsqueda de personajes : encuentra obras que contengan personajes específicos (por ID de Wikidata)

Uso

Una vez instalado en Claude Desktop, podrá interactuar con la API de DraCor a través de Claude. Aquí tiene algunos ejemplos:

Consultas básicas

Pídale a Claude que enumere los corpus disponibles:

Can you list all available drama corpora in DraCor?

Obtenga información sobre una obra específica:

Tell me about Goethe's Faust in the German corpus

Analizar redes de personajes:

Analyze the character network in Hamlet from the Shakespeare corpus

Consultas avanzadas

Analizar las relaciones entre los personajes:

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

Comparar obras:

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

Analizar la importancia del personaje:

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

Analizar la representación de género:

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

Encuentra un personaje en diferentes obras:

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

Analizar el texto completo de una obra de teatro:

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

Extraer temas del texto de la obra:

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

Analizar patrones del lenguaje:

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

Consultas de análisis literario

Analizar la estructura del juego:

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

Comparar autores:

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

Contexto histórico:

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

Recursos (API v1)

El servidor FastMCP expone los siguientes recursos:

info:// - Información de la API y detalles de la versión
corpora:// - Lista de todos los corpus disponibles
corpus://{corpus_name} - Información sobre un corpus específico
corpus_metadata://{corpus_name} - Metadatos para todas las obras de un corpus
plays://{corpus_name} - Lista de obras de un corpus específico
play://{corpus_name}/{play_name} - Información sobre una obra específica
play_metrics://{corpus_name}/{play_name} - Métricas de red para una jugada específica
characters://{corpus_name}/{play_name} - Lista de personajes de una obra específica
spoken_text://{corpus_name}/{play_name} - Texto hablado en una obra (con filtros opcionales)
spoken_text_by_character://{corpus_name}/{play_name} - Texto hablado por cada personaje
stage_directions://{corpus_name}/{play_name} - Indicaciones escénicas en una obra
network_data://{corpus_name}/{play_name} - Datos de red en formato CSV
relations://{corpus_name}/{play_name} - Datos de relación de personajes en formato CSV
character_by_wikidata://{wikidata_id} - Lista de reproducciones que contienen un personaje por ID de Wikidata
full_text://{corpus_name}/{play_name} - Texto completo de una obra en formato de texto sin formato
tei_text://{corpus_name}/{play_name} - Texto XML TEI completo de una obra

Herramientas (API v1)

El servidor FastMCP proporciona las siguientes herramientas:

search_plays - Busca reproducciones basadas en una consulta
compare_plays - Compara dos jugadas en términos de métricas y estructura
analyze_character_relations - Analiza las relaciones entre los personajes de una obra.
analyze_play_structure - Analizar la estructura de una obra
find_character_across_plays - Encuentra un personaje en varias obras
analyze_full_text - Analizar el texto completo de una obra, incluidos los diálogos y las acotaciones.

Plantillas de indicaciones (API v1)

El servidor FastMCP incluye estas plantillas de aviso:

analyze_play - Plantilla para analizar una jugada específica
character_analysis - Plantilla para analizar un personaje específico
network_analysis - Plantilla para analizar una red de personajes
comparative_analysis - Plantilla para comparar dos obras
gender_analysis - Plantilla para analizar la representación de género en una obra de teatro
historical_context - Plantilla para analizar el contexto histórico de una obra
full_text_analysis - Plantilla para analizar el texto completo de una obra de teatro

Cómo funciona

Este proyecto utiliza el SDK oficial del Protocolo de Contexto de Modelo de Python para construir un servidor MCP que expone recursos y herramientas que Claude puede usar para interactuar con la API de DraCor.

Cuando le preguntas a Claude una pregunta sobre textos dramáticos, puede:

Acceda a recursos como corpus, obras de teatro, personajes y redes.
Utilice herramientas para buscar, comparar y analizar jugadas
Proporcionar información y visualizaciones basadas en los datos.

La API de DraCor es de acceso público, por lo que no se requiere autenticación.

Limitación de velocidad

Tenga en cuenta las políticas de limitación de velocidad de DraCor. El servidor incluye opciones de limitación de velocidad que se pueden configurar en el archivo .env.

Solución de problemas

Si encuentra problemas:

Asegúrese de estar utilizando Python 3.10 o superior
Intente ejecutar en modo de desarrollo para depurar: mcp dev dracor_mcp_fastmcp.py
Verifique el estado de la API de DraCor en https://dracor.org/doc/api

Aviso para usar con MCP

Su tarea consiste en analizar las jugadas históricas de la base de datos DraCor para identificar problemas de etiquetado de identificación de personajes. En concreto:

Seleccione una obra de la base de datos de DraCor y realice un análisis exhaustivo de sus relaciones entre personajes, texto completo y estructura.
Identifique todas las posibles inconsistencias en el etiquetado de identificación de caracteres, incluyendo:
- Variaciones ortográficas de los nombres de los personajes
- Confusión o combinación de nombres de personajes
- Variantes ortográficas históricas
- Discrepancias entre la identificación de los personajes y las indicaciones escénicas
Cree un informe detallado de posibles errores de etiquetado de identificación de caracteres en un formato de tabla estructurada con las siguientes columnas:
- ID de texto (identificador único de la obra)
- ID de personaje actual utilizado en la base de datos
- Variante(s) problemática(s) encontrada(s) en el texto
- Tipo de error (ortográfico, variación, confusión, etc.)
- Explicación del problema

Hazlo por este texto: [nombre del juego]"

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Expresiones de gratitud

Este proyecto utiliza:

SDK de Python del protocolo de contexto de modelo para crear el servidor MCP
DraCor API v1 para texto dramático y datos de red
Proyecto Drama Corpora (DraCor) para proporcionar los datos subyacentes y la API

DraCor MCP Server

Integrations