AI导哈

Pathfinder 1e规则顾问服务器

一个将AI代理转变为Pathfinder第一版规则专家的服务器，提供全面的规则查询、角色管理、战斗解决和战役追踪功能。

  • by g-georgiev
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 g-georgiev/pathfinder-mcp

使用说明

探路者1e顾问——MCP服务器

一个MCP服务器，可以将任何AI代理变成具有全面规则查找、角色管理、战斗解决和战役跟踪功能的专家探路者第一版顾问。基于约13000个游戏条目的本地SQLite数据库、79个社区优化指南和一个完整的游戏状态引擎。

它的作用

规则参考（21个工具）

  • 使用全文搜索功能搜索法术、技能、职业、原型、物品、装备、种族、职业选项
  • 根据角色统计数据验证专长先决条件和原型兼容性
  • 在79个优化指南中搜索专长/法术评级和构建建议
  • 通读缓存：丢失的数据从aonprd.com/d20pfsrd.com获取并在本地缓存

游戏状态（35个工具）

  • 使用保存/加载快照进行会话管理
  • 具有自动导出统计计算的字符持久性（HP、BAB、保存、AC、攻击、技能、法术槽、CMB/CMD）
  • 实时状态跟踪：HP、状态、库存、法术槽、升级
  • NPC管理（完整统计块或仅稀疏统计块条目）
  • 战斗：主动性、攻击/保存/技能解决、转弯跟踪、条件到期
  • 活动记忆：带有FTS5搜索、任务跟踪、预示线程的事件日志

筹备代理

  • 用于角色创建的独立本地LLM代理（Gemma 4 26B A4B或任何与OpenAI兼容的端点）
  • 直接将MCP工具作为Python函数导入——无协议开销
  • 通过工具调用迭代研究和构建PF1e字符

AI DM项目的一部分

此MCP是Pathfinder AI DM合作中的三个仓库之一：

代表 角色
探路者mcp （此仓库） PF1e规则参考+有状态游戏工具+准备代理
探路者dm服务器 带LLM代理循环的WebSocket游戏服务器
地牢ai 电子瘦客户端

此MCP独立运行，不需要游戏服务器。将其添加到任何项目中 .mcp.json 用于从任何AI代理进行PF1e规则查找、角色管理和游戏状态跟踪。

设置

# Clone the repo
git clone https://github.com/g-georgiev/pathfinder-mcp
cd pathfinder-mcp

# Option A: One-command setup + add to your project
./setup.sh /path/to/your/project

# Option B: Manual setup
python3 -m venv mcp-server/.venv && mcp-server/.venv/bin/pip install mcp
claude mcp add --scope project --transport stdio pathfinder-data -- \
  $(pwd)/mcp-server/.venv/bin/python3 $(pwd)/mcp-server/server.py

SQLite数据库随repo一起提供，不需要构建步骤。游戏状态数据库(game_state.db)首次使用时自动创建。

建筑

pathfinder-mcp/
├── mcp-server/
│   ├── server.py               # MCP server entry point (56 tools)
│   ├── game_state.py           # Game state DB schema + connection management
│   ├── tools/                  # Game state tool modules
│   │   ├── session.py          #   Session lifecycle (6 tools)
│   │   ├── character.py        #   Character persistence (3 tools)
│   │   ├── character_updates.py#   HP, conditions, inventory, spells, level-up (5 tools)
│   │   ├── npc.py              #   NPC management (4 tools)
│   │   ├── combat.py           #   Combat resolution (7 tools)
│   │   ├── campaign.py         #   Campaign memory (8 tools)
│   │   └── rendering.py        #   MD export/import (2 tools)
│   ├── compute/                # PF1e derived stat engine
│   │   ├── derived.py          #   Orchestrator
│   │   ├── progression.py      #   Class data lookup from rules DB
│   │   ├── hp.py               #   Hit point computation
│   │   ├── saves.py            #   Saving throw computation
│   │   ├── combat_stats.py     #   AC, BAB, CMB/CMD, initiative, attack lines
│   │   ├── skills.py           #   Skill total computation
│   │   └── spells.py           #   Spell slot computation (+ fallback tables)
│   └── tests/                  # 104 tests (pytest)
├── prep-agent/
│   ├── agent.py                # Local LLM agent loop for character creation
│   ├── llm_client.py           # OpenAI-compatible HTTP client
│   └── prompts/                # System prompts (chargen.md, npc_gen.md)
├── db/
│   ├── pathfinder.db           # Rules database (~13MB, git-tracked)
│   ├── game_state.db           # Game state database (gitignored, auto-created)
│   └── build.py                # Rules DB builder (use with data/db-restore branch)
├── data/
│   ├── characters/
│   │   ├── FORMAT.md           # Character sheet format specification
│   │   └── samples/            # Pre-built sample characters
│   └── guides/                 # 79 community optimization guides (14MB)
│       └── INDEX.md            # Guide index by class
├── docs/                       # Runtime reference docs (served by get_reference())
├── scripts/                    # Data pipeline (PSRD + aonprd extraction)
└── config-templates/           # Starter configs for consuming projects

MCP工具（56个工具）

规则参考（13K条目，FTS5搜索）

工具 目的
search_spells 按姓名、学校、班级、最高级别搜索
search_feats 按名称、类型、先决条件搜索
search_classes 按名称、类型（核心/基础/混合/声望）搜索
search_archetypes 按名称、基类搜索
search_items 按名称、类别、位置搜索魔法物品
search_equipment 按名称、类别搜索普通设备
search_races 按名称、大小搜索
search_class_options 搜索域名、血统、神秘事物、赞助人
get_detail 按表+ID列出的任何条目的完整数据
get_skills 全部26种PF1e技能
check_feat_prerequisites 根据角色统计数据验证专长资格
check_archetype_compatibility 检查原型是否冲突
cache_entry 存储网络获取的数据以备将来查询
db_stats 每张表的行数

人物和肖像示例

工具 目的
list_sample_characters 列出可用的示例构建（正常/格式塔）
get_sample_character 阅读示例角色的表、咒语、专长、特征或背景故事
compare_with_sample 将用户的构建与示例进行比较，以获得优化见解
generate_portrait_prompt 根据字符数据生成图像生成提示

导游（79名导游，37/38个班级）

工具 目的
search_guides 浏览所有指南以获取构建建议
get_guide_index 按类别列出的完整指南

参考

工具 目的
get_reference 按需提供文档：格式、顾问、mcp、角色、活动、指南

会话管理

工具 目的
create_session 创建新的游戏会话（名称、音调、设置、DM注释）
get_session 获取会话元数据+玩家列表
list_sessions 列出所有会话
join_session 将玩家添加到会话中
save_session 快照所有会话状态以供以后还原
load_session 从最新快照还原会话

性格持久性

工具 目的
persist_character 存储角色，计算导出的统计数据（HP、BAB、保存、AC、攻击、技能、法术槽）
get_character 完整角色数据+计算统计数据+活动条件
list_characters 会话中所有角色的摘要

角色状态更新

工具 目的
update_character_hp 施加伤害/愈合，跟踪昏迷/死亡/死亡状态
update_character_conditions 添加/删除带有持续时间跟踪的条件
update_character_inventory 添加/删除项目，调整黄金
update_character_spells 跟踪法术槽的使用和恢复
apply_level_up 应用升级选项，重新计算所有导出的统计数据

NPC管理

工具 目的
persist_npc 存储NPC（稀疏统计块或完整类构建）
get_npc 完整的NPC数据
list_npcs 列出带有角色/位置/状态过滤器的NPC
update_npc 更新NPC字段（处置、HP、位置、注释）

战斗

工具 目的
start_combat 初始化与主动订购的相遇
get_combat_state 所有战斗人员的当前回合顺序、生命值和条件
resolve_attack 侧翻+AB vs AC，击中时造成伤害
resolve_save 滚动+保存奖金vs DC
resolve_skill_check 滚动+技能总数vs DC
advance_turn 下一个战斗员，减少条件持续时间
end_combat 结束遭遇战，分发经验值/战利品

活动记忆

工具 目的
log_event 记录叙述/战斗/发现/对话/决策事件
recall_events 按关键字（FTS5）、类型、参与者、重要性搜索事件
add_quest 追踪新任务
update_quest 更新任务状态/备注
list_quests 使用状态过滤器列出任务
add_foreshadow 植入具有预期回报的叙事线索
get_foreshadow_threads 列出未解决或已解决的线程
resolve_foreshadow 将线程标记为已解决

渲染

工具 目的
render_character_md 将字符导出为FORMAT.md-spec Markdown
import_character_md 将Markdown字符表导入数据库

筹备代理

准备代理使用本地LLM（Gemma 4 26B A4B或类似工具）通过在Python导入时直接调用MCP工具函数来迭代构建PF1e字符。

# Start the LLM server (requires HIP_VISIBLE_DEVICES=0 on systems with AMD iGPU)
HIP_VISIBLE_DEVICES=0 ~/workspace/models/serve-model.sh gemma-4-26b-a4b-it -c 16384

# Build a character
mcp-server/.venv/bin/python prep-agent/agent.py \
  "human fighter level 1, melee build with longsword and shield"

# Build and persist to a game session
mcp-server/.venv/bin/python prep-agent/agent.py \
  --persist --session-id abc123 \
  "dwarven stonelord paladin, level 5"

看 准备代理/README.md 完全使用。

示例字符

角色 类别 级别 类型 概念
麦基弗 巫师（法术圣人）10 10 普通 跨列表选角通才
Shwarma大师 魔法师（剑圣）//巫师（预言占卜）16 16 格式塔 动作经济强国

测试

cd mcp-server && .venv/bin/pip install pytest && .venv/bin/python -m pytest tests/ -v

104个测试，涵盖计算引擎、会话生命周期、角色持久性、战斗分辨率、战役记忆、NPC管理和MD渲染。

数据库

数据库 目的 生命周期
pathfinder.db 规则参考（约13K个条目，9个表，FTS5） 静态，跟踪git。重建与 python3 db/build.py
game_state.db 游戏会话、角色、战斗、战役记忆 动态，忽略不计。首次使用时自动创建

指南来源和归因

这 data/guides/ 该目录包含由Pathfinder社区编写的优化指南。这些指南是公开共享的资源，旨在帮助玩家塑造更好的角色。它们以重组形式作为知识库包含在这里，并完全归因于其原始作者。

如果您是下面列出的作者，并希望从该存储库中删除您的内容，请打开问题或直接联系维护人员。您的内容将被立即删除。

79个指南，349个文件，14MB-- 全文索引

作者 指南 涵盖的课程
Iluzry 13 炼金术士、奥术家、野蛮人、吟游诗人、牧师、德鲁伊（2）、圣骑士、通灵师、萨满、杀手、魔法师（2）
Allerseelen 7 检察官、调查员、动物学家、催眠师、神秘学家、先知、警戒者
N.Jolly 6 炼金术士、野蛮人、枪手、动画师、召唤师、曲兵
焦油 2 牧师、召唤师
29位作者 51 各种（见 INDEX.md)

游戏数据源

  • PSRD （探路者SRD）——来自官方SRD数据库的开放游戏许可证内容
  • 荷兰档案馆（aonprd.com） --法术、专长和原型索引

源JSON文件位于 data/db-restore 支。所有《探路者》游戏机制内容均在 开放游戏许可证v1.0a 由派佐股份有限公司提供。

许可证

源代码已获得许可 Apache许可证2.0。指南内容是各自作者的知识产权，包括非商业社区使用的属性。Pathfinder是派佐股份有限公司的注册商标。

相关 MCP