DraCor MCP

DraCor MCP服务器

模型上下文协议（MCP）服务器，用于与戏剧公司项目（DraCor）API交互。此MCP服务器使您能够通过Claude或其他LLM无缝分析戏剧文本及其角色网络。

概述

该项目使用官方模型上下文协议Python SDK实现MCP服务器，该SDK提供对DraCor API v1的访问。它允许克劳德和其他LLM与戏剧文本语料库进行交互，分析角色网络，检索游戏信息，并生成关于不同语言和时期戏剧作品的见解。

该项目包括两个实现：

1. dracor_mcp_fastmcp.py -使用基于FastMCP装饰器的API和v1 API优化实现

特性

• 通过统一接口访问DraCor API v1
• 无需身份验证（DraCor API可公开访问）
• DraCor实体的结构化数据模型
• 运营支持：

- 社团与游戏信息检索 - 字符网络分析 - 游戏的度量和统计 - 字符信息和口语文本 - 比较游戏分析 - 搜索功能 - 角色关系数据 - 多种格式的网络数据（CSV、GEXF、GraphML） - 跨剧性别分析 - 纯文本和TEI XML格式的全文检索 - 完成游戏文本分析

设置

先决条件

• Python 3.10或更高版本
• UV包管理器（推荐）或pip

紫外线安装

1. 安装紫外线：

pip install uv

1. 创建虚拟环境并安装依赖项：

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

1. 在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服务器：

{
  "mcpServers": {
    "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"
      ],
      "env": {
        "DRACOR_API_BASE_URL": "https://dracor.org/api/v1"
      }
    }
  }
}

替换 /path/to/dracor-mcp/ 带有dracor mcp目录的实际路径。此配置使用 uv run 以执行具有必要依赖关系的MCP服务器，而不需要事先安装。

如果要使用其他服务器，例如临时服务器，请在环境变量中更改它 DRACOR_API_BASE_UR 在配置文件中：

"env": {
  "DRACOR_API_BASE_URL": "https://staging.dracor.org/api/v1" 
  }

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 将核心MCP SDK类与较旧的v0 API一起使用：

• Resource -用于定义API资源
• MCPToolImpl -用于实施工具
• PromptTemplate -用于创建提示模板

FastMCP实施（v1 API）

FastMCP在 dracor_mcp_fastmcp.py 在当前的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交互。以下是一些示例：

基本查询

1. 让克劳德列出可用的语料库：

Can you list all available drama corpora in DraCor?

1. 获取特定游戏的信息：

Tell me about Goethe's Faust in the German corpus

1. 分析角色网络：

Analyze the character network in Hamlet from the Shakespeare corpus

高级查询

1. 分析角色关系：

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

1. 比较游戏：

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

1. 分析角色重要性：

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

1. 分析性别代表性：

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

1. 在不同的戏剧中找到一个角色：

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

1. 分析一部戏剧的全文：

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

1. 从游戏文本中提取主题：

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

1. 分析语言模式：

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

文学分析查询

1. 分析游戏结构：

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

1. 比较作者：

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

1. 历史背景：

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} -按维基数据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 -分析戏剧全文的模板

运作原理

该项目使用官方的模型上下文协议Python SDK来构建一个MCP服务器，该服务器公开了Claude可以用来与DraCor API交互的资源和工具。

当你问克劳德一个关于戏剧文本的问题时，它可以：

1. 访问语料库、戏剧、角色和网络等资源
2. 使用工具搜索、比较和分析戏剧
3. 根据数据提供见解和可视化

DraCor API是可公开访问的，因此不需要身份验证。

速率限制

请注意DraCor的利率限制政策。服务器包括可选的速率限制设置，可以在.env文件中配置。

故障排除

如果您遇到问题：

1. 确保你使用的是Python 3.10或更高版本
2. 尝试在开发模式下运行以进行调试： mcp dev dracor_mcp_fastmcp.py
3. 在查看DraCor API状态https://dracor.org/doc/api

提示与MCP一起使用

“你的任务是分析DraCor数据库中的历史剧，以确定角色ID标记问题。具体来说：

1. 从DraCor数据库中选择一部戏剧，并对其角色关系、全文和结构进行全面分析。
2. 识别字符ID标记中所有可能的不一致，包括：

- 字符名称的拼写变化 - 字符名称混淆或混淆 - 历史拼写变体 - 角色ID和舞台方向之间的差异

1. 使用以下列以结构化表格格式创建潜在字符ID标记错误的详细报告：

- 文本ID（游戏的唯一标识符） - 数据库中使用的当前字符ID - 文本中发现有问题的变体 - 错误类型（拼写、变异、混淆等） - 问题的解释

针对此文本执行此操作：\[playname\]“

许可证

麻省理工学院

致谢

本项目使用：

• 用于构建MCP服务器的模型上下文协议Python SDK
• 用于戏剧性文本和网络数据的DraCor API v1
• Drama公司项目（DraCor），用于提供基础数据和API