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搜索索引,按继承、命名和描述进行概念分类
快速开始
通过克劳德代码插件(推荐)```bash
claude plugin add look-itsaxiom/godot-doc-mcp
插件自动启动MCP服务器,添加斜线命令(`/godot-search`, `/godot-class`, `/godot-concept`),并且包括自主API勘探代理。
### 通过npx(可选——需要npm发布)
添加到您的克劳德代码设置(`~/.claude.json` → `mcpServers`):```json
{
"mcpServers": {
"godot-docs": {
"command": "npx",
"args": ["-y", "godot-doc-mcp"]
}
}
}
多个Godot版本
指向特定的Godot二进制文件:```json
{
"mcpServers": {
"godot-docs": {
"command": "npx",
"args": ["-y", "godot-doc-mcp"],
"env": {
"GODOT_BIN": "/path/to/godot4.3"
}
}
}
}
### 预提取文档
如果您已经提取了XML文档(或想使用捆绑的文档进行开发):```json
{
"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传输。
如何查找文档
服务器按以下顺序解析文档:
GODOT_DOC_DIR--直接使用预提取的XML文档GODOT_BIN--使用以下命令运行指定的二进制文件--doctool提取文档- 自动检测 --搜索路径
godot,godot4等等。 - 错误 --关于如何提供文档的明确说明
提取的文档缓存在 .cache/godot-{version}/ 并在后续启动时重复使用。
示例:```bash
export GODOT_DOC_DIR=$HOME/src/godot/docs
export MCP_SERVER_LOG=debug
pnpm start
______________________________________________________________________
## 使用MCP客户端
运输:stdio(工艺管道)。启动服务器并配置MCP客户端,以便根据需要将工作目录设置为此仓库和环境变量来启动它。
资源和工具以稳定的名称和返回形状公开。以下示例显示了意图;确切的信封取决于您的客户端SDK。
搜索:```json
{
"tool": "godot_search",
"args": { "query": "Vector2.x", "limit": 5 }
}
获取一个类(可以选择包括祖先):```json
{
"tool": "godot_get_class",
"args": { "name": "Node", "includeAncestors": true, "maxDepth": 2 }
}
按限定名获取符号:```json
{
"tool": "godot_get_symbol",
"args": { "qname": "Button.pressed" }
}
按前缀列出类:```json
{
"tool": "godot_list_classes",
"args": { "prefix": "Visu", "limit": 20 }
}
您的客户端可以作为资源打开的URI:
- `godot://class/{?ancestors,maxDepth}`
- `godot://symbol///`
- `godot://search?q=&kind=`
可选的助手提示显示为MCP提示:
- `how_to_use_godot_docs` --教模型调用 `godot_search` 首先,然后 `godot_get_*`.
______________________________________________________________________
## 上游发生了什么变化
这个叉子是基于 tkmct/godot医生mcp (承诺 `fa96bfb`).上游提供了一个很好的基础:XML解析、BM25搜索索引和4个通用MCP工具。我们用面向概念的工具扩展了它,因为:
**问题**:在制作游戏时,你会用概念思考(“我如何设置物理?”,“存在哪些动画工具?”),而不是用类名。通用工具要求你已经知道你在找什么。
**解决方案**:11个概念工具,返回精心策划的概述、GDScript示例和相关类-由游戏开发任务而非API结构组织。目前仍有用于深入探索的通用工具。
### 所做的更改
|区域|什么|为什么|
|------|------|-----|
| `server/src/concepts/classifier.ts` | **新** --混合类分类器(继承+名称模式+描述关键字)|用以下概念标记892个类中的每一个 `physics`, `rendering`, `ui`等等。 |
| `server/src/concepts/registry.ts` | **新** --精心策划的概述+每个概念的GDScript示例|概念工具需要散文指导,而不仅仅是类列表|
| `server/src/adapters/godotTools.ts` | **扩展的** --添加 `getConcept()` 和 `listConcepts()` |将概念数据连接到工具界面|
| `server/src/mcp/stdio.ts` | **扩展的** --11个新的工具注册|将概念工具与现有的通用工具一起公开|
| `server/src/index.ts` | **扩展的** --启动时运行分类器,传递给工具|启动时根据解析的XML构建一次概念图|
所有原始工具(`godot_search`, `godot_get_class`, `godot_get_symbol`, `godot_list_classes`)都是 **未改变的**.
______________________________________________________________________
## 工具参考
### 概念工具(新)
首先使用这些——它们为常见的游戏开发任务返回精心策划的指导:
工具 · 描述 · 参数
`godot_scene_tree` · 节点、育儿、团体、生命周期 · `maxClasses?: number`
`godot_physics` · 物体、碰撞、关节、光线投射 · `dimension?: "2d"\ · "3d"`, `maxClasses?: number`
`godot_rendering` · 材质、着色器、网格、灯光、摄影机 · `dimension?: "2d"\ · "3d"`, `maxClasses?: number`
`godot_audio` · 玩家、流媒体、效果、巴士 · `maxClasses?: number`
`godot_animation` · AnimationPlayer、青少年、骷髅 · `maxClasses?: number`
`godot_ui` · 控件、按钮、容器、主题 · `maxClasses?: number`
`godot_input` · 事件、动作、键盘、鼠标、游戏手柄 · `maxClasses?: number`
`godot_networking` · 多人游戏、RPC、WebSocket、HTTP · `maxClasses?: number`
`godot_resources` · 加载、保存、自定义资源 · `maxClasses?: number`
`godot_math` · 向量、变换、四元数、几何 · `maxClasses?: number`
`godot_list_concepts` · 列出所有具有类计数的概念
默认情况下,概念工具返回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[]`
类型形状(子集):```ts
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; // 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
发展
安装并运行:```bash
pnpm install
pnpm dev
对于本地开发,请使用捆绑文档:```bash
GODOT_DOC_DIR=./doc pnpm dev
类型检查和格式化:```bash
pnpm run check:biome
pnpm run format:check
pnpm run format --write
测验:```bash
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项目无关,也不受其认可。
