Totm Convex MCP

TOTM Converx MCP服务器

连接到Converx应用程序的MCP（模型上下文协议）服务器 totm-convex 管理遭遇战、玩家角色和怪物模板。

特性

服务器提供以下工具：

1. list_encounters -列出所有遭遇及其详细信息，包括相关玩家角色和怪物
2. add_encounter -在系统中添加新遭遇
3. add_player_character -添加新玩家角色
4. add_monster_template -添加新的怪物模板
5. add_player_character_to_feat -在遭遇战中添加玩家角色
6. remove_player_character_from_encounter -从遭遇战中删除玩家角色
7. add_monster_to_encounter -使用怪物模板将怪物添加到遭遇战中
8. remove_monster_from_encounter -从遭遇战中移除怪物

设置

1.安装依赖项

npm install

2.配置环境变量

创建一个 .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 build

4.配置克劳德桌面（自动）

此仓库包含一个同步的辅助脚本 claude_desktop_config.json 在您的Claude应用程序配置中。

1. 在中设置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"

1. 编辑 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：设置为项目根绝对路径

1. 构建和同步：

- 一步（推荐）：

     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中

1. 检查你的 claude_desktop_config.json 文件语法
2. 确保所有路径都是绝对的（而不是相对的）
3. 完全退出并重新启动Claude Desktop（而不仅仅是关闭窗口）

工具调用失败

1. 检查克劳德的登录：

- macOS: ~/Library/Logs/Claude/mcp*.log - 视窗：检查Claude日志目录

1. 验证您的 CONVEX_URL 是正确的
2. 确保您的Converx部署正在运行且可访问
3. 如果功能需要身份验证，请确保 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 –环境变量访问和验证

典型工作流程

1. 对相关模块进行更改（见上文架构）
2. 构建： npm run build
3. 重新启动Claude Desktop以加载新版本

添加新工具

对于现有域（遭遇/角色/怪物）：

1. 将工具定义添加到相关文件中（例如。， src/tools/encounters.ts)
2. 实施相应 case 在该文件的处理程序中
3. 如果它调用Converx，请使用 callConvexFunction 从 src/convexClient.ts
4. 构建并重新启动Claude Desktop

对于新域：

1. 创建新的 src/tools/.ts 出口a Tools 阵列和 handleTool
2. 更新 src/tools/index.ts 导入和传播新的工具阵列，并传入 dispatchTool
3. 构建并重新启动Claude Desktop

调试记录

集 MCP_DEBUG=1 在您的环境中查看其他身份验证日志。

许可证

麻省理工学院