AI导哈

规则裁判服务

Gamemaster是一个基于MCP服务器的桌面游戏规则裁判服务，通过自然语言处理从PDF规则书中提取证据，支持检索和问答功能。

  • by jonathan-hsiao
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jonathan-hsiao/gamemaster-mcp

使用说明

游戏大师MCP

概述

Gamemaster是一个 棋盘游戏规则裁判：MCP服务器加上可选的瘦聊天客户端（CLI），该客户端使用以下命令回答自然语言问题 佩奇引用证据 从摄入的规则手册PDF中提取。检索很轻（仅限CPU且完全本地）：SQLite FTS5、FAISS和一个小型交叉编码器重链器。任何MCP客户端（Cursor、Claude Desktop等）都可以使用服务器；所包含的CLI是一个工作示例客户端。

演示

特性

  • 证据第一答案：答案以检索到的块为基础 (source_name, pp. start–end) 引用。
  • 混合上下文检索：稀疏（FTS5）+密集（FAISS）与RRF和交叉编码器重新排序器合并，用于证据检索。
  • 无缝MCP集成：通过MCP暴露的工具和资源（stdio）；从任何MCP客户端使用服务器。
  • 内置摄入：摄取工具是服务器的一部分；代理人可以为你添加规则手册。

工具

MCP服务器公开：

  • list_games -在规则商店中列出游戏
  • list_sources -在规则存储中列出游戏的源文件（PDF）
  • search_rules -从规则存储中检索带有引用的证据块
  • get_chunks -获取整段文本作为证据
  • ask_user_clarification -用于请求澄清消息的包装器，因此代理和客户端可以共享严格的 “询问用户并将回复作为工具结果传递回”的协议
  • submit_answer -发出最终答案的信号，以便客户可以收听
  • ingest_pdf -将一个规则手册PDF导入规则存储
  • ingest_pdfs -批量摄取多个PDF

安装

  1. 克隆仓库并安装Poetry：

    poetry install

  2. 复制 .env.example 到 .env 并且至少设置：

    • 规则手册_目录 --规则手册PDF的目录（例如。 rulebooks).
    • OPENAI_API密钥 --要求包含 ask-gamemaster MCP客户端CLI。

配置

所有设置都是通过环境变量（或 .env 项目根目录中的文件）。看 .env.example 查看完整列表。

变量 默认值 描述
规则手册_目录 rulebooks PDF路径的根；摄入使用 <RULEBOOKS_DIR>/<game_id>/<pdf_name>.
RULES_STORE_DIR rules_store SQLite数据库和FAISS索引的目录。
OPENAI_API_KEY - 对于是必需的 ask-gamemaster.
OPENAI_MODEL gpt-5-mini 使用的模型 ask-gamemaster CLI。
嵌入模型 intfloat/e5-small-v2 句子嵌入模型。
重新登录模型 cross-encoder/ms-marco-MiniLM-L-6-v2 重新排序搜索。
TEXT_DENSITY_MIN_CHARS_PER_PAGE 100 接受PDF的最小字符数/页（拒绝扫描/图像PDF）。
AGENT_DEBUG_LOG_DIR logs 在哪里 --debug 写入代理日志。
GAMEMASTER_CONTEXT_MAX_回合 50 在上下文中保持对话的次数（滑动窗口）。
游戏主_玩家_回合 20 在“我无法完成”之前，每个用户问题的最大LLM+工具轮次。
GAMEMASTER _ QUIT_TRIGGER /quit 用户键入什么以退出聊天CLI。

可选： GET_CHUNKS_MAX_CHUNKS, GET_CHUNKS_MAX_CHARS, SEARCH_K_SPARSE, SEARCH_K_DENSE, HF_HOME, TRANSFORMERS_CACHE, HF_HUB_CACHE.

用法

手动摄取规则手册

可选-代理也可以从聊天CLI为您完成此操作（只需说“我需要摄取文件”）。

地方 基于文本 PDF在 RULEBOOKS_DIR/<game_id>/<filename>.pdf。扫描/图像PDF被拒绝。

单个文件：

poetry run ingest-rulebook "game_id=wingspan,pdf_name=wingspan_rulebook.pdf"

多个文件：

poetry run ingest-rulebook "game_id=wingspan,pdf_name=wingspan_rulebook.pdf" "game_id=everdell,pdf_name=everdell_rules.pdf"

通过MCP客户端CLI聊天

poetry run ask-gamemaster

CLI将MCP服务器作为子进程启动，并运行 长期会话：一段完整的历史对话。类型 /quit 退出。模型加载时，第一次运行可能需要1-2分钟；等待“Gamemaster就绪”。

  • 可选： --game-id <id> 和 --source-pdf-names all （或逗号分隔的列表）跳过代理的澄清问题。
  • 调试： --debug 将提示和工具调用写入 AGENT_DEBUG_LOG_DIR 对于CLI会话。

仅运行MCP服务器

poetry run run-mcp

服务器通过MCP进行通话 标准.将任何MCP客户端指向此命令以使用工具；包含的 ask-gamemaster CLI是一个示例客户端。

项目布局

gamemaster-mcp/
├── src/gamemaster_mcp/
│   ├── mcp_server/    # FastMCP server, tools, resources, instructions
│   ├── ingest/        # PDF extraction, chunking, path validation, run_ingest
│   ├── index/         # Sparse (FTS), dense (FAISS), rerank
│   ├── storage/       # SQLite schema and store
│   ├── search/        # Retrieval pipeline (search_rules, get_chunks_for_agent)
│   ├── agent/         # LLM client, MCP session, runner (ask-gamemaster)
│   ├── cli/           # ingest-rulebook and ask-gamemaster CLIs
│   └── config.py      # Env and settings
├── rules_store/       # SQLite DB + FAISS index (created on first ingest)
├── rulebooks/         # PDFs go here (or set RULEBOOKS_DIR)
├── .env               # Copy from .env.example
└── pyproject.toml

相关 MCP