Godot API文档服务器

Godot API文档MCP服务器

叉子 tkmct/godot医生mcp -使用面向概念的工具扩展，用于语义API探索。看 发生了什么变化 在......下面

为Godot引擎API文档提供服务的离线模型上下文协议（MCP）服务器。自动检测您的Godot安装，提取文档，并提供 面向概念的工具 用于常见的游戏开发任务以及一般的搜索和检索——stdio共有15个工具。

• 零配置：自动检测PATH上的Godot，按版本提取和缓存文档
• 概念先行：11个工具，按你想要做的事情（物理、渲染、动画、UI等）组织
• 通用工具：4个用于开放式搜索和类/符号查找的工具
• 任何Godot版本：适用于您安装的任何Godot 3.x或4.x
• 运行时为零网络（仅限本地文档）
• BM25搜索索引，按继承、命名和描述进行概念分类

快速开始

通过克劳德代码插件（推荐）

claude plugin add look-itsaxiom/godot-doc-mcp

插件自动启动MCP服务器，添加斜线命令(/godot-search, /godot-class, /godot-concept)，并且包括自主API勘探代理。

通过npx（可选——需要npm发布）

添加到您的克劳德代码设置(~/.claude.json → mcpServers):

{
  "mcpServers": {
    "godot-docs": {
      "command": "npx",
      "args": ["-y", "godot-doc-mcp"]
    }
  }
}

多个Godot版本

指向特定的Godot二进制文件：

{
  "mcpServers": {
    "godot-docs": {
      "command": "npx",
      "args": ["-y", "godot-doc-mcp"],
      "env": {
        "GODOT_BIN": "/path/to/godot4.3"
      }
    }
  }
}

预提取文档

如果您已经提取了XML文档（或想使用捆绑的文档进行开发）：

{
  "mcpServers": {
    "godot-docs": {
      "command": "npx",
      "args": ["-y", "godot-doc-mcp"],
      "env": {
        "GODOT_DOC_DIR": "/path/to/docs"
      }
    }
  }
}

这是什么

一个MCP服务器，为LLM工具提供对权威Godot API文档的离线访问。服务器：

• 自动检测您的Godot安装并通过以下方式提取文档 --doctool （或使用预提取的XML）
• 将XML解析为类型化对象并构建BM25搜索索引
• 将类分为游戏开发概念（物理、渲染、UI等）
• 通过stdio为15个MCP工具提供搜索、查找和概念探索服务
• 缓存每个Godot版本提取的文档和索引，以实现快速重启

非目标（目前）：编写文档、实时网络获取或一般网络搜索。

仓库的规划

• server/ --MCP服务器实现（TypeScript）
  • server/src/index.ts --引导/容器
  • server/src/cli.ts --CLI（默认为stdio）
  • server/src/mcp/stdio.ts --MCP接线：工具/资源/提示
  • server/src/parser/xmlParser.ts --Godot XML→ 打印文档
  • server/src/indexer/ --索引构建+持久性（如果存在）
  • server/src/search/searchEngine.ts --内存搜索
  • server/src/resolver/ --类/符号解析助手
  • server/src/types.ts --共享TypeScript接口
• server/test/ --单元测试（解析器、索引、解析器、工具、服务器）
• doc/ --捆绑的Godot XML文档用于开发/测试（不包含在npm包中）
• .cache/ --生成的索引文件（在VCS中忽略）
• scripts/ --本地公用事业和MCP客户端演示

配置

环境变量：

• GODOT_DOC_DIR （可选，默认：自动检测）--预提取的Godot XML文档的路径（必须包含 classes/ 子目录）。覆盖自动检测。
• GODOT_BIN （可选，默认：自动检测）——特定Godot二进制文件的路径。用于通过以下方式提取文档 --doctool.
• GODOT_INDEX_PATH （默认值 ./.cache/godot-index.json)--用于热启动的磁盘索引。
• MCP_SERVER_LOG （默认值 info) — silent|error|warn|info|debug.
• MCP_STDIO （默认值 1)--使用stdio传输。

如何查找文档

服务器按以下顺序解析文档：

1. GODOT_DOC_DIR --直接使用预提取的XML文档
2. GODOT_BIN --使用以下命令运行指定的二进制文件 --doctool 提取文档
3. 自动检测 --搜索路径 godot, godot4等等。
4. 错误 --关于如何提供文档的明确说明

提取的文档缓存在 .cache/godot-{version}/ 并在后续启动时重复使用。

示例：

export GODOT_DOC_DIR=$HOME/src/godot/docs
export MCP_SERVER_LOG=debug
pnpm start

使用MCP客户端

运输：stdio（工艺管道）。启动服务器并配置MCP客户端，以便根据需要将工作目录设置为此仓库和环境变量来启动它。

资源和工具以稳定的名称和返回形状公开。以下示例显示了意图；确切的信封取决于您的客户端SDK。

搜索：

{
  "tool": "godot_search",
  "args": { "query": "Vector2.x", "limit": 5 }
}

获取一个类（可以选择包括祖先）：

{
  "tool": "godot_get_class",
  "args": { "name": "Node", "includeAncestors": true, "maxDepth": 2 }
}

按限定名获取符号：

{
  "tool": "godot_get_symbol",
  "args": { "qname": "Button.pressed" }
}

按前缀列出类：

{
  "tool": "godot_list_classes",
  "args": { "prefix": "Visu", "limit": 20 }
}

您的客户端可以作为资源打开的URI：

• godot://class/<ClassName>{?ancestors,maxDepth}
• godot://symbol/<ClassName>/<kind>/<name>
• godot://search?q=<q>&kind=<kind>

可选的助手提示显示为MCP提示：

• how_to_use_godot_docs --教模型调用 godot_search 首先，然后 godot_get_*.

上游发生了什么变化

这个叉子是基于 tkmct/godot医生mcp （承诺 fa96bfb).上游提供了一个很好的基础：XML解析、BM25搜索索引和4个通用MCP工具。我们用面向概念的工具扩展了它，因为：

问题：在制作游戏时，你会用概念思考（“我如何设置物理？”，“存在哪些动画工具？”），而不是用类名。通用工具要求你已经知道你在找什么。

解决方案：11个概念工具，返回精心策划的概述、GDScript示例和相关类-由游戏开发任务而非API结构组织。目前仍有用于深入探索的通用工具。

所做的更改

所有原始工具(godot_search, godot_get_class, godot_get_symbol, godot_list_classes)都是 未改变的.

工具参考

概念工具（新）

首先使用这些——它们为常见的游戏开发任务返回精心策划的指导：

默认情况下，概念工具返回25个最相关的类。使用 maxClasses 调整。回应包括 totalClasses 完整的计数。

通用工具（与上游保持不变）

• godot_search

  • 参数： { query: string, kind?: "class"|"method"|"property"|"signal"|"constant", limit?: number }
  • 返回： Array<{ uri: string, name: string, kind: string, score: number, snippet?: string }>

• godot_get_class

  • 参数： { name: string, includeAncestors?: boolean, maxDepth?: number }
  • 返回： GodotClassDoc | { inheritanceChain: string[], classes: GodotClassDoc[], warnings?: string[] }

• godot_get_symbol

  • 参数： { qname: string } // e.g., "Node._ready", "Vector2.x", "Button.pressed"
  • 返回： GodotSymbolDoc

• godot_list_classes

  • 参数： { prefix?: string, limit?: number }
  • 返回： string[]

类型形状（子集）：

export interface GodotMethod {
  name: string;
  returnType?: string;
  arguments: Array<{ name: string; type?: string; default?: string }>;
  description?: string;
  qualifiers?: string[]; // e.g., virtual, const, static
}

export interface GodotProperty {
  name: string;
  type?: string;
  default?: string;
  description?: string;
}

export interface GodotSignal {
  name: string;
  arguments: Array<{ name: string; type?: string }>;
  description?: string;
}

export interface GodotConstant { name: string; value?: string; description?: string }

export interface GodotClassDoc {
  name: string;
  inherits?: string;
  category?: string;
  brief?: string;
  description?: string;
  methods: GodotMethod[];
  properties: GodotProperty[];
  signals: GodotSignal[];
  constants: GodotConstant[];
  themeItems?: Record<string, string[]>; // optional, Godot 4.x
  annotations?: string[]; // optional
  since?: string; // Godot version detected
}

export type GodotSymbolDoc =
  | ({ kind: 'method'; className: string } & GodotMethod)
  | ({ kind: 'property'; className: string } & GodotProperty)
  | ({ kind: 'signal'; className: string } & GodotSignal)
  | ({ kind: 'constant'; className: string } & GodotConstant);

运作原理

解析：

• 使用宽容的XML解析器来处理实体和CDATA
• 保留内联代码跨度并规范空白
• 将缺失的部分视为空数组

搜索索引：

• 标记名称(Camera3D → camera, 3d, camera3d)
• 将文本字段标记化；低阶；删除停用词；保留2个以上char令牌
• 通过类似BM25的启发式方法得分；增强精确的类和符号匹配
• 将帖子存储在内存中；坚持 .cache/godot-index.json

绩效目标：

• 对于典型的Godot 4文档，在现代笔记本电脑上冷启动（解析+索引）≤3s
• 搜索p95≤20ms（简单）/≤60ms（多项）
• 内存索引的内存开销≤150MB

发展

安装并运行：

pnpm install
pnpm dev

对于本地开发，请使用捆绑文档：

GODOT_DOC_DIR=./doc pnpm dev

类型检查和格式化：

pnpm run check:biome
pnpm run format:check
pnpm run format --write

测验：

pnpm test

代码样式：

• TypeScript严格模式；ESM模块
• 喜欢构图；小型、可测试的模块
• 日志记录在一个最小的包装器后面，可通过以下方式控制 MCP_SERVER_LOG

添加或更改MCP工具：

• 发布后保持工具名称和返回模式的稳定
• 更新此自述文件 AGENTS.md 如果你引入新工具或改变形状

故障排除

• 未找到文档

  • 症状：启动失败，并显示明确信息
  • 修复：确保Godot在您的PATH上，或设置 GODOT_BIN 或 GODOT_DOC_DIR.如果使用 GODOT_DOC_DIR，确保路径存在并包含 classes/ XML文件。

• 缺少类或符号

  • 症状： NOT_FOUND 工具错误及建议
  • 修复：检查拼写/大小写；使用 godot_search 首先确认可用性

• XML分析错误

  • 症状：错误包括文件名和行/列（如果可用）
  • 修复：验证XML；从Godot仓库重新同步文档

• 冷启动缓慢

  • 原因：文档集太大或磁盘受限
  • 缓解措施：保持 .cache/godot-index.json 用于暖启动

安全与隐私

• 仅在解析的文档目录中读取 .cache/
• 可以使用以下命令执行Godot二进制文件 --doctool 和 --version 用于文档提取（不运行游戏代码）
• 正常运行期间不进行网络呼叫
• 将文档视为纯文本；从不执行嵌入式代码

常见问题解答

• 文件从哪里来？

  • 服务器会自动检测您的Godot安装，并通过以下方式提取文档 --doctool。你也可以指出 GODOT_DOC_DIR 复制到预先提取的副本或集合 GODOT_BIN 转换为特定的二进制文件。

• 这支持Godot 3.x文档吗？

  • 是的，可以优雅地处理旧模式差异（某些部分可能缺失）。

• 哪些客户可以使用此功能？

  • 任何可以启动stdio服务器进程和调用工具的MCP兼容客户端。

• 文档更改时，我可以重建索引吗？

  • 对。更新XML文件后重新启动服务器。将来可能会添加文件监视器。

积分

• 上游: tkmct/godot医生mcp --带有XML解析、BM25搜索索引和通用工具的原始MCP服务器
• 概念工具：由添加 Axiom工作室 使用为开发的相同模式 freecad mcp
• Godot引擎和文档是其各自所有者的商标。此项目与Godot项目无关，也不受其认可。