Open MCP Tools

打开MCP工具

A. 通用MCP服务器 具有可扩展的工具模块。目前包括带有LLM驱动的PDF摄取的桌面规则手册工具。

特性

🎲 桌面规则手册工具 （第一工具模块）

• 列出资源：浏览可用的规则手册，按复杂性、玩家数量、游戏时间、标签进行过滤
• 生成快速入门：获取包含组件、设置步骤和第一轮演练的快速入门指南
• 查找规则：使用引用和页面参考搜索特定规则
• 玩家角色备忘单：生成具有能力、提醒和提示的角色特定备忘单

📚 LLM驱动的PDF摄取

• 智能提取：使用Anthropic Claude或OpenAI从PDF规则手册中提取结构化数据
• 高质量YAML：生成干净、结构化的YAML文件，随时可用
• PDF回退：当YAML内容不足时，工具可以回退到原始PDF
• 自动检测：从API密钥中自动检测可用的LLM提供程序

🚀 生产基础结构

• DCAP性能跟踪：通过DCAP v2协议进行实时性能监控
• x402支付基础设施：内置支付支持（默认禁用）
• HTTP+SSE传输：支持服务器发送事件的流媒体
• 类型安全工具：使用Pydantic模型的全类型参数和结果
• 热重新加载：开发过程中自动重新加载

安装

先决条件

• Python 3.10或更高版本
• uv（推荐）或pip

使用紫外线（推荐）

# Clone and install
git clone https://github.com/boorich/open-mcp-tools.git
cd open-mcp-tools
uv sync

# Install ingestion dependencies (for PDF processing)
uv sync --group ingestion

# Run the server
uv run open-mcp-tools serve

使用pip

# Install from source
pip install -e .

# Install ingestion dependencies
pip install pdfplumber anthropic openai

# Run the server
open-mcp-tools serve

环境设置

复制示例环境文件并配置：

cp .env.example .env
# Edit .env with your configuration

PDF摄取所需：

# Set one of these (auto-detected)
ANTHROPIC_API_KEY=your-key-here
# OR
OPENAI_API_KEY=your-key-here

快速开始

1.摄取PDF规则手册

处理PDF规则手册以生成结构化的YAML：

# Process a single PDF
python scripts/ingest_rulebooks.py resources/game.pdf

# Process multiple PDFs
python scripts/ingest_rulebooks.py resources/*.pdf

# Use Anthropic (default if ANTHROPIC_API_KEY is set)
python scripts/ingest_rulebooks.py resources/game.pdf --llm-provider anthropic

# Use OpenAI
python scripts/ingest_rulebooks.py resources/game.pdf --llm-provider openai

看 scripts/INGESTION.md 获取详细的摄入记录。

2.启动服务器

# Using uv
uv run open-mcp-tools serve

# Using pip
open-mcp-tools serve

# Or directly
python -m open_mcp_tools.cli serve

服务器运行在 http://localhost:7284 默认情况下。

3.使用MCP检验员进行测试

npx @modelcontextprotocol/inspector http://localhost:7284/mcp

与Claude Desktop一起使用

对于Claude Desktop，服务器在stdio模式下运行。添加到您的Claude Desktop配置中：

地点： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "open-mcp-tools": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/open-mcp-tools",
        "open-mcp-tools",
        "stdio"
      ]
    }
  }
}

替换 /path/to/open-mcp-tools 带有项目目录的实际路径。

与光标一起使用

快速安装（推荐）

单击下面的按钮自动将服务器添加到游标：


先决条件：

1. 确保服务器正在运行(uv run open-mcp-tools serve)
2. 服务器必须可在以下位置访问 http://localhost:7284/mcp

手动安装

或者，手动添加到您的Cursor MCP配置中：

地点： ~/.cursor/mcp.json

{
  "mcpServers": {
    "open-mcp-tools": {
      "type": "sse",
      "url": "http://localhost:7284/mcp"
    }
  }
}

注： 服务器必须运行，Cursor才能连接到它。

可用工具

桌面工具

tabletop_list_resources

列出可用的桌面规则手册资源，并可选择过滤。

参数：

• play_style （可选）：按游戏风格过滤（例如，“合作”、“竞争”、“独奏”）
• complexity （可选）：按复杂性筛选（“轻”、“中”、“重”、“非常重”）
• min_players （可选）：最低玩家数量
• max_players （可选）：最大玩家数
• max_playtime （可选）：最大播放时间（分钟）
• tags （可选）：按标签筛选（任何匹配项）

例子：

{
  "play_style": "cooperative",
  "complexity": "medium",
  "min_players": 2,
  "max_players": 4
}

tabletop_generate_quickstart

为桌面游戏生成快速入门指南。

参数：

• game_id （必填）：游戏标识符（例如，“法师骑士”、“无效降落”）
• player_count （可选）：快速入门的玩家数量
• experience_level （可选）：“初学者”或“经验丰富”

例子：

{
  "game_id": "mage-knight",
  "player_count": 1,
  "experience_level": "beginner"
}

tabletop_lookup_rule

在游戏规则手册中搜索特定规则。

参数：

• game_id （必填）：游戏标识符
• query （必填）：要搜索的规则或主题（例如，“运动”、“战斗”）
• section （可选）：用于缩小搜索范围的可选部分

特征：

• 首先搜索YAML内容（快速）
• 当YAML不足时，回退到PDF提取
• 返回页面引用和引文

例子：

{
  "game_id": "voidfall",
  "query": "combat resolution",
  "section": "Combat"
}

tabletop_player_role_cheatsheet

为特定玩家角色或派系生成备忘单。

参数：

• game_id （必填）：游戏标识符
• role （必填）：角色或派系名称（例如，“骑士”、“虚空帝国”）
• player_name （可选）：用于个性化的可选玩家名称

例子：

{
  "game_id": "voidfall",
  "role": "Voidfall Imperium",
  "player_name": "Alice"
}

配置

服务器使用环境变量进行配置。创建一个 .env 文件：

# MCP Server Configuration
MCP_SERVER_URL=http://localhost:7284

# LLM API Keys (for PDF ingestion)
ANTHROPIC_API_KEY=your-key-here
# OR
OPENAI_API_KEY=your-key-here

# DCAP (Performance Tracking) - ENABLED by default
DCAP_ENABLED=true
DCAP_MULTICAST_IP=159.89.110.236
DCAP_PORT=10191

# x402 Payment Configuration - DISABLED by default
X402_ENABLED=false

看 .env.example 所有可用选项。

项目结构

open-mcp-tools/
├── src/open_mcp_tools/
│   ├── tools/
│   │   └── tabletop/          # Tabletop rulebook tools (first tool module)
│   │       ├── list_resources.py
│   │       ├── generate_quickstart.py
│   │       ├── lookup_rule.py
│   │       └── player_role_cheatsheet.py
│   ├── core/                   # Core MCP infrastructure
│   ├── handlers/                # MCP protocol handlers
│   └── server.py               # FastAPI server
├── resources/
│   └── rulebooks/              # Generated YAML rulebook resources
├── scripts/
│   ├── ingest_rulebooks.py     # LLM-powered PDF ingestion
│   └── INGESTION.md            # Ingestion documentation
└── schemas/
    └── resource.schema.json    # Generic resource schema

添加新工具模块

服务器被设计为可扩展的。要添加新的工具模块，请执行以下操作：

1. 在中创建新目录 src/open_mcp_tools/tools/ （例如。， tools/my_module/)
2. 按照中的模式创建工具文件 tools/tabletop/
3. 导入工具 tools/my_module/__init__.py
4. 添加导入 tools/__init__.py

有关工具模式的示例，请参阅现有的桌面工具。

发展

# Install development dependencies
uv sync --dev

# Run server in development mode (with hot-reload)
OPEN_MCP_TOOLS_HOT_RELOAD=true uv run open-mcp-tools serve

# Run tests
pytest

# Format code
ruff format .

# Lint code
ruff check .

测试MCP工具

使用MCP检查器

npx @modelcontextprotocol/inspector http://localhost:7284/mcp

使用curl

# List all tools
curl -X POST http://localhost:7284/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# Call a tool
curl -X POST http://localhost:7284/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "tabletop_list_resources",
      "arguments": {
        "complexity": "medium"
      }
    }
  }'

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

相关项目

• 模型上下文协议 -MCP规范
• x402 -人工智能服务的支付协议
• DCAP -性能跟踪协议