Game MCP Server

游戏MCP服务器

MCP（模型上下文协议）服务器，支持 genai游戏引擎 该项目将研究、架构、叙事、QA和游戏测试知识存储在Qdrant中。服务器在端口上公开可流式HTTP MCP传输 3000 默认情况下，Claude或任何兼容MCP的客户端都可以通过HTTP或curl进行连接。

此仓库中的项目

项目命名空间

所有持久性现在都存在于项目范围的Qdrant集合中。规范项目列表存储在 mcp/config/projects.json:

• 每个项目ID都是小写/烤肉串大小写（例如。 default, prototype-alpha).

• MCP HTTP端点可在 `/

/mcp 和 / /sse （遗产 /mcp 和 /sse` 路径解析为默认项目）。

• 使用以下命令创建新项目及其Qdrant集合 POST /project 在MCP服务器上：

  curl -X POST http://localhost:5356/project \
    -H 'Content-Type: application/json' \
    -d '{"id":"glass"}'

  curl -v -X POST http://localhost:5356/reset \
    -H 'Content-Type: application/json' \
    -d '{"id":"glass","snapshot":false}'

卷曲-X POST”http://localhost:6333/collections/glass\_\_backlog_items/points/delete?wait=true" \ -H“内容类型：应用程序/json” \ -d'{“筛选器”：{“必须”：\[\]}' 卷曲”http://localhost:6333/collections/glass\_\_backlog_items

响应列出了完全限定的集合名称（例如。 prototype-alpha__research_findings).

• backlog编辑器通过以下方式转发当前项目 project 查询参数或 X-Project-Id 标题（UI包括项目切换器）。如果省略，它将回退到共享配置文件中定义的默认项目。
• 图形生成器接受可选 project 场上 POST /build 填充相应的 code_graph 命名空间。省略时，将使用默认项目。
• list_qdrant_collections 返回特定于项目的集合名称，同时 get_server_metadata 发布支持项目的HTTP模板。
• 使用 POST /reset 与身体 `{ "id": "

" } 对项目的Qdrant集合和Neo4j实体进行快照 /app/snapshots/ //`，然后清除它们，以便项目重新开始。

功能管理

• 每个项目都可以暂停功能引入。呼叫 set_feature_lock { "locked": true } 拒绝新 create_feature 请求（MCP服务器响应“此时没有新功能”）并解锁 { "locked": false } 当计划恢复时。
• 待办事项支持可选 feature_id 在...期间 create_backlog_item 和 update_backlog_item.使用 assign_backlog_to_feature 将现有PBI与 list_feature_backlog_items 以检索该功能的工作队列。

先决条件

• Node.js 18+
• Qdrant实例（默认为 http://qdrant:6333)
• Neo4j实例（默认为 bolt://localhost:7687)
• 嵌入服务公开 POST /embed （默认为 http://embedding-service:80，请参阅 嵌入服务)
• OpenAI API密钥，可访问 gpt-4o-mini （可通过以下方式配置 OPENAI_MODEL)

脚本

npm run dev    # Start with ts-node + Streamable HTTP transport (default port 3000)
npm run build  # Type-check and compile TypeScript to dist/
npm start      # Build then run the compiled server from dist/

集 PORT 和 MCP_PATH 覆盖HTTP绑定（默认值为 3000 和 /mcp).

卷曲烟雾测试

该传输实现了MCP的流式HTTP流。每节课都以 initialize 请求。响应返回一个 Mcp-Session-Id 必须包含在后续请求和SSE流中的标头。

ℹ️ POST端点需要 Accept: application/json, text/event-stream 因此，传输可以协商JSON回复或服务器发送的事件。在每个JSON-RPC POST请求中包含此标头。

1. 初始化会话

   curl -i -X POST http://localhost:3000/default/mcp \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json, text/event-stream' \
     -d '{
       "jsonrpc": "2.0",
       "id": "init-1",
       "method": "initialize",
       "params": {
         "protocolVersion": "2024-11-05",
         "clientInfo": { "name": "curl", "version": "0.1" },
         "capabilities": {}
       }
     }'

Note the `Mcp-Session-Id` header in the response (e.g. `bf6fda5a-a8d5-4ad6-b8e1-...`). Use it for all follow-up requests.

2. **List available tools**

curl -i -X POST http://localhost:3000/default/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'Mcp-Session-Id: d3baee33-df43-442d-a164-5675450c6860' \ -H 'Mcp-Protocol-Version: 2024-11-05' \ -d '{ "jsonrpc": "2.0", "id": "list-1", "method": "tools/list", "params": {} }'

3. **调用工具（例如：获取服务器元数据）**

curl -i -X POST http://localhost:3000/default/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'Mcp-Session-Id: ' \ -H 'Mcp-Protocol-Version: 2024-11-05' \ -d '{ "jsonrpc": "2.0", "id": "call-1", "method": "tools/call", "params": { "name": "get_server_metadata", "arguments": {} } }'

1. **订阅SSE流（可选）**

curl -N http://localhost:3000/default/sse \ -H 'Accept: text/event-stream' \ -H 'Mcp-Session-Id: ' \ -H 'Mcp-Protocol-Version: 2024-11-05'

   保持此curl运行以接收流式响应（例如记录事件）。使用 `Ctrl+C` 退出。

1. **终止会话（可选清理）**

curl -i -X DELETE http://localhost:3000/default/mcp \ -H 'Mcp-Session-Id: ' \ -H 'Mcp-Protocol-Version: 2024-11-05'

## 收藏和工具

- `config/collections.json` 记录每个Qdrant集合、其基数以及Claude代理依赖它的对象。
- `docs/mcp/usage.md` 涵盖了Claude集成和服务器公开的完整MCP工具目录。
- Bug修复内存存在 `bug_fix_patterns` 收藏，可通过 `record_bug_fix`, `match_bug_fix`，以及 `get_bug_fix` 工具。错误消息可以与修复一起存储，这样代理就可以在回退到语义匹配之前执行精确的日志行查找。
- 知识图嵌入存在于名为的项目范围集合中 `
__code_graph`.使用 `explore_graph_entity` 拉取Neo4j节点及其周围的关系，以及 `search_graph_semantic` 用于对图形生成器输出进行矢量搜索。
- 功能定义存在 `
__features`；用 `create_feature`, `update_feature`, `list_features`，以及 `get_feature`，并通过以下方式链接PBI `assign_backlog_to_feature` 或 `list_feature_backlog_items`.
- `GET /stats` 返回每个启动工具的使用计数器(`writes`/`reads`)对于MCP端点。

使用 `list_qdrant_collections` 和 `get_mcp_documentation` 以编程方式从客户端发现服务器功能。

## 知识图谱

设置以下环境变量，以便服务器可以访问图形生成器数据库：

|变量|默认值|用途|
| --- | --- | --- |
| `NEO4J_URL` | `bolt://localhost:7687` |由图构建器填充的Neo4j实例的螺栓端点|
| `NEO4J_USER` | `neo4j` |Neo4j身份验证的用户名|
| `NEO4J_PASSWORD` | `password` |Neo4j身份验证密码|
| `GRAPH_COLLECTION` | `code_graph` |图嵌入的基本集合名称(`
__code_graph` 按项目创建）|
| `DEFAULT_PROJECT` | `memory` |客户端省略时使用的初始命名空间 `project` |
| `SNAPSHOT_DIR` | `./snapshots` |目录在哪里 `POST /reset` 写入存档（在Docker compose中挂载到主机）|
| `GRAPH_BUILDER_PORT` | `4100` |图形生成器服务的HTTP端口|
| `OPENAI_API_KEY` | _（必填）_ |图形生成器用于丰富实体|
| `OPENAI_MODEL` | `gpt-5` |覆盖OpenAI模型以丰富语义|
| `REPO_URL` | `https://github.com/chris-arsenault/genai-game-engine.git` |构建器克隆的默认存储库|
| `REPO_BRANCH` | `main` |每次生成前同步默认分支|

图形生成器克隆 `chris-arsenault/genai-game-engine` 进入 `/mnt/apps/apps/mcp-server/game-mcp/server/source/genai-game-engine` 默认情况下，将数据同步到Neo4j+Qdrant中。构建器运行后，MCP客户端可以：

1. 呼叫 `search_graph_semantic` 使用自然语言或代码片段来获取最相关的图形实体。
1. 传递实体ID（例如。， `file:src/tools/graph.tool.ts`)to `explore_graph_entity` 直接从Neo4j检查入站/出站关系。

生成器在上公开REST API `http://:${GRAPH_BUILDER_PORT}`:

- `POST /build` 与身体 `{"mode":"full|incremental","stage":"all|parse|enrich|populate","baseCommit":"...","repoUrl":"...","branch":"...","project":""}` 开始一份工作。 `project` 是可选的，默认为配置的默认项目。 `repoUrl` 和 `branch` 默认为服务配置（请参阅上面的env-vars）。
- `GET /status` 轮询当前或上次运行摘要。
- `POST /reset` 以清除分期伪影和增量标记。

`POST /build` 排队工作后立即返回（HTTP 202）；使用 `GET /status` 观察进展并获得最终总结。

示例：使用curl从localhost触发完全重建（所有阶段，默认repo/branch）：

curl -s -X POST http://localhost:5346/build \ -H 'Content-Type: application/json' \ -d '{ "mode": "full", "stage": "all", "branch": "main", "project": "default" }'

然后投票：

curl -s http://localhost:4100/status | jq '.'

## 嵌入服务

提供的 `docker-compse.yml` 现在在CPU上启动拥抱人脸文本嵌入推理 `nomic-ai/nomic-embed-text-v1.5` 模型。它支持8192个令牌上下文窗口和768个维度嵌入，为长工具有效载荷提供了充足的空间，同时在双Xeon E5/128上仍然实用 GB RAM TrueNAS盒子。由于矢量大小相对于原始设置发生了变化，请运行 `./init-collections.sh` （或手动重新创建Qdrant集合），然后再摄取新数据。

容器安装 `/mnt/apps/apps/mcp-server/embedding-cache` 和设置 `MODEL_CACHE=/data`，因此模型权重在重新启动时保持不变。要在脱机计算机上预种子缓存，请执行以下操作：

huggingface-cli download nomic-ai/nomic-embed-text-v1.5 --local-dir /mnt/apps/apps/mcp-server/embedding-cache

嵌入客户端 `src/services/embedding.service.ts` 现在直接在日志中显示HTTP错误体（例如令牌限制警告），以使诊断配置错误更容易。