TOTM Converx MCP服务器
连接到Converx应用程序的MCP（模型上下文协议）服务器 totm-convex 管理遭遇战、玩家角色和怪物模板。
特性
服务器提供以下工具：
- list_encounters -列出所有遭遇及其详细信息，包括相关玩家角色和怪物
- add_encounter -在系统中添加新遭遇
- add_player_character -添加新玩家角色
- add_monster_template -添加新的怪物模板
- add_player_character_to_feat -在遭遇战中添加玩家角色
- remove_player_character_from_encounter -从遭遇战中删除玩家角色
- add_monster_to_encounter -使用怪物模板将怪物添加到遭遇战中
- remove_monster_from_encounter -从遭遇战中移除怪物
设置
1.安装依赖项
npm install2.配置环境变量
创建一个 .env 项目根目录中的文件：
cp .env.example .env然后编辑 .env 并设置凸形URL：
CONVEX_URL=https://your-deployment-name.convex.cloud身份验证（电子邮件+密码）
如果凭据存在于中，则此MCP使用Converx Auth（密码提供程序）登录 .env:
CONVEX_AUTH_EMAIL=your-email@example.com
CONVEX_AUTH_PASSWORD=your-password启动时，服务器调用 auth:signIn 并且在调用HTTP API时将使用返回的令牌（授权：承载）或会话cookie。如果省略这些变量，则请求将无法通过身份验证，并且可能会失败，具体取决于您的Converx函数可见性。
3.构建服务器
npm run build4.配置克劳德桌面（自动）
此仓库包含一个同步的辅助脚本 claude_desktop_config.json 在您的Claude应用程序配置中。
- 在中设置Claude配置的绝对路径
.env:
- macOS（默认路径）：
echo "CLAUDE_DESKTOP_CONFIG_PATH=$HOME/Library/Application Support/Claude/claude_desktop_config.json" >> .env- Windows（PowerShell示例）：
Add-Content .env "CLAUDE_DESKTOP_CONFIG_PATH=$env:APPDATA\Claude\claude_desktop_config.json"- 编辑
claude_desktop_config.json在此仓库中设置（需要绝对路径）：
- command：您的节点二进制路径（例如。， /usr/local/bin/node) - args：包括 --env-file，通往你的道路 .env，以及通往 build/index.js例如：
"args": [
"--env-file",
"/absolute/path/to/project/.env",
"/absolute/path/to/project/build/index.js"
]- cwd：设置为项目根绝对路径
- 构建和同步：
- 一步（推荐）：
npm run build-and-sync- 或者单独：
npm run build
npm run sync:claude-config该脚本将把您现有的Claude配置备份到 claude_desktop_config.json.bak 然后应用这些更改。
5.重新启动克劳德桌面
配置后，完全退出并重新启动Claude Desktop（而不仅仅是关闭窗口）：
- macOS：使用Cmd+Q或从菜单栏中选择“Quit Claude”
- 视窗：右键单击系统托盘中的Claude图标，然后选择“退出”
用法
配置后，您可以使用Claude Desktop中的MCP工具。例如：
- “列出所有遭遇”
- “添加一个名为‘妖精洞’的新遭遇”
- “添加一个名为‘Aragorn’的玩家角色”
- “将地精模板添加到地精洞穴遭遇战中”
故障排除
服务器未显示在Claude Desktop中
- 检查你的
claude_desktop_config.json文件语法 - 确保所有路径都是绝对的（而不是相对的）
- 完全退出并重新启动Claude Desktop（而不仅仅是关闭窗口）
工具调用失败
- 检查克劳德的登录：
- macOS: ~/Library/Logs/Claude/mcp*.log - 视窗：检查Claude日志目录
- 验证您的
CONVEX_URL是正确的 - 确保您的Converx部署正在运行且可访问
- 如果功能需要身份验证，请确保
CONVEX_AUTH_TOKEN设置正确
凸API误差
如果您看到凸API错误，请验证：
- 您的Converx部署URL正确
- 函数名称与Converx应用程序中的名称匹配(
myFunctions:listEncounters等等） - 您的凸函数已正确导出并可访问
发展
建筑
为了清晰和未来增长，源代码被模块化：
src/index.ts–入口点；启动服务器src/server.ts–MCP服务器引导和请求处理程序连接src/tools/–域拆分工具定义和处理程序
- src/tools/types.ts –共享工具类型 - src/tools/encounters.ts –遇到相关工具和处理程序 - src/tools/characters.ts –与角色相关的工具和处理程序 - src/tools/monsters.ts -怪物相关的工具和处理程序 - src/tools/index.ts –组合工具阵列，导出 toolsList, ToolName, dispatchTool
src/convexClient.ts–callConvexFunction凸HTTP API的包装器src/auth.ts–身份验证/会话管理和标头构建src/config.ts–环境变量访问和验证
典型工作流程
- 对相关模块进行更改（见上文架构）
- 构建：
npm run build - 重新启动Claude Desktop以加载新版本
添加新工具
对于现有域（遭遇/角色/怪物）：
- 将工具定义添加到相关文件中（例如。，
src/tools/encounters.ts) - 实施相应
case在该文件的处理程序中 - 如果它调用Converx，请使用
callConvexFunction从src/convexClient.ts - 构建并重新启动Claude Desktop
对于新域：
- 创建新的
src/tools/.ts出口aTools阵列和handleTool - 更新
src/tools/index.ts导入和传播新的工具阵列，并传入dispatchTool - 构建并重新启动Claude Desktop
调试记录
集 MCP_DEBUG=1 在您的环境中查看其他身份验证日志。
许可证
麻省理工学院