适合谁
- 已采用 GEML 的文档管理。
- 需要与 AI 代理或脚本安全地共同编写文档。
- 依赖文档或代码骨架的软件开发流程。
G
68FMRS · C
GEML MCP 服务器提供了一种在文档中以原子方式编辑块的安全方式，强调验证和细粒度的修订控制。它服务于采用 GEML 格式的用户。整体上，其功能已明确说明，并通过 --root 边界和预写验证来回应安全问题。
该服务器通过标准输入输出协议运行，允许 AI 代理通过逐块操作而不是重写整个文档来编辑 GEML 文件（基于 Markdown 的纯文本文档）。它将每次写入前进行解析，拒绝可能导致文档无效的更改，并维护基于块的修订历史（.gemlhistory），以便回滚。它要求使用 --root 指定工作目录，并且永远不会超出该目录。它适用于任何 MCP 兼容的客户端，如 Claude Desktop 或 Claude Code。它可以额外提供只读的代码图谱工具，以回答诸如“谁调用这个？”等问题，在适用情况下。
工具能力
geml_get
读取一个单独的块（例如，通过 #id）。
geml_set
替换一个块，可选内容来自另一个模板或文件。
geml_add
在另一块之后插入一个片段，保持其自身的 ID。
geml_delete
删除指定块。
geml_rename
重命名一个块 ID。
geml_history
查看特定块的修订历史。
geml_revert
回滚一个单独的块到先前的修订，保持文件的其他部分不变。
geml_check
验证文档，并报告诊断信息和非零退出码以标记错误。
geml_codemap_called_by
查找哪些方法调用了给定方法。
geml_codemap_calls
查找给定方法调用的方法。
geml_codemap_view
查看代码图的节点或其路径。
geml_codemap_find
搜索代码图中的方法或路径。
安装接入
- 在目标机器上安装 Node.js 22 或更高版本。2. 对于 Claude Code，运行：claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs。3. 对于 Claude Desktop，向 claude_desktop_config.json 添加类似配置，如上方所提供。4. 可选：如果仓库包含代码图谱，则额外提供图谱工具。
claude_desktop_config.json
{
"mcpServers": {
"geml": {
"command": "npx",
"args": [
"-y",
"@geml/geml@latest",
"mcp",
"--root",
"/absolute/path/to/your/docs"
]
}
}
}
选型与风险
不适合谁
- 不适合在未使用 GEML 的文档仓库上使用。
- 不适合作为通用文件系统方法。
- 不适合需要远程托管的 MCP 服务器。
所需权限
- 读写对 --root 指定的目录中文件的访问，以及仅在该目录内的访问。
- 使用 npm/npx 按需获取包。
- 在 root 内创建和写入 .gemlhistory 边车文件。
风险与副作用
- 配置错误的 --root 可能导致意外的变动，但超出目录的写入会被明确拒绝。
- 文档的非法修改会被拒绝，但需要网络访问才能安装包。
- 历史记录可能随着时间的推移而增大；需要在 root 目录外跟踪配额。
- 易受工具或客户端错误配置的影响；请确保 --root 路径正确。
常见排障
- 确认 Node 22+ 已安装 (`node --version`)。
- 确保 --root 是一个绝对路径且存在。
- 测试来自命令行的基本操作：geml check yourfile.geml。
- 检查客户端以标准输入输出模式启动服务器，并且权限允许。
- 检查 .gemlhistory 的写入权限。
- 如果图谱工具缺失，检查图形索引是否存在 (.geml-code-graph/index.geml)。
使用场景
使用 AI 代理在大型 GEML 文档中编辑单个块，同时保持文档的其余部分不变。
验证文档的引用完整性，通过块 ID 或内容哈希引入结构化上下文。
通过逐块机制查找错误，并回滚有问题的更改。
对于包含代码图谱的仓库，回答基于代码库级别的调用图查询。
支持客户端
Claude Desktop完整支持
Claude Code完整支持
Generic MCP client完整支持