← 返回目录

GEML MCP Server

社区

一个用于 GEML 文档的 MCP 服务器，支持逐块编辑与验证。

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 开发工具第 20 / 438
Stars: ★ 30 热门
传输方式: stdio（本地进程）
运行环境: Node.js 22+
凭据: 无需凭据
许可证: MIT
最近提交: 8 天前
工具数: 12

68FMRS · C

GEML MCP 服务器提供了一种在文档中以原子方式编辑块的安全方式，强调验证和细粒度的修订控制。它服务于采用 GEML 格式的用户。整体上，其功能已明确说明，并通过 --root 边界和预写验证来回应安全问题。

最强项 · 文档质量 16/20 最弱项 · 可靠性 12/20

可靠性

12/20

安全与权限

14/20

维护活跃度

13/20

文档质量

16/20

安装易用性

13/20

查看各项评分依据

可靠性 12/20: README 声称 600+ 单元测试、≥95% 覆盖率 CI 门禁、写入前解析校验、.gemlhistory 撤销机制，且有 CI 徽章，但这些均为项目自述，未提供服务器关键路径（init、工具列表、geml_set 拒绝坏写入）的直接可验证执行证据，静态审查不得高于 12 分。错误处理声明详细但未经独立核实。
安全与权限 14/20: 无红线风险：本地 stdio、强制 --root 路径沙箱（含 ../、绝对路径、符号链接拒绝说明）、写入前校验、副作用可撤销。扣分点：manifest 与 README 未说明 .gemlhistory 写入量、codemap build 会下载 scip 索引器（外部获取行为）的供应链披露不足，权限模型未经代码核实。
维护活跃度 13/20: 活跃：v1.10.1、npm 包、CI 工作流、开放讨论和贡献治理文档（GOVERNANCE/CONTRIBUTING）、双许可（MIT + CC-BY）。但 GitHub 元数据显示 License NOASSERTION（双许可导致识别混乱）、0 open issues 且星数低，安全响应渠道未明确披露，单人/单一观点维护风险存在。
文档质量 16/20: 文档分层充分：README、mcp-guide.md、双语规范、示例、已知限制（有损投影、IANA 未注册）均有披露，工具与 CLI 动词一一对应说明清晰。扣分：MCP 服务器各工具的参数、错误码、成本细节散落在链接中，未在审查材料内直接呈现。
安装易用性 13/20: 安装路径清晰：npm 包 + npx 一条命令或 Claude Desktop JSON 配置，Node 22+ 要求明确，--root 需绝对路径有说明。扣分：未提供故障排查步骤，--graph 可选项细节依赖外部文档，静态审查下未能确认安装即用。

静态评测 · 未实际运行收录于 2026-09-08

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件

适合谁

已采用 GEML 的文档管理。
需要与 AI 代理或脚本安全地共同编写文档。
依赖文档或代码骨架的软件开发流程。

不适合谁

不适合在未使用 GEML 的文档仓库上使用。
不适合作为通用文件系统方法。
不适合需要远程托管的 MCP 服务器。

所需权限

读写对 --root 指定的目录中文件的访问，以及仅在该目录内的访问。
使用 npm/npx 按需获取包。
在 root 内创建和写入 .gemlhistory 边车文件。

风险与副作用

配置错误的 --root 可能导致意外的变动，但超出目录的写入会被明确拒绝。
文档的非法修改会被拒绝，但需要网络访问才能安装包。
历史记录可能随着时间的推移而增大；需要在 root 目录外跟踪配额。
易受工具或客户端错误配置的影响；请确保 --root 路径正确。

安装接入

准备工作

运行环境：Node.js 22+

在目标机器上安装 Node.js 22 或更高版本。
对于 Claude Code，运行：claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs。
对于 Claude Desktop，向 claude_desktop_config.json 添加类似配置，如上方所提供。
可选：如果仓库包含代码图谱，则额外提供图谱工具。

claude_desktop_config.json

{
  "mcpServers": {
    "geml": {
      "command": "npx",
      "args": [
        "-y",
        "@geml/geml@latest",
        "mcp",
        "--root",
        "/absolute/path/to/your/docs"
      ]
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "geml": {
      "command": "npx",
      "args": [
        "-y",
        "@geml/geml@latest",
        "mcp",
        "--root",
        "/absolute/path/to/your/docs"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在客户端工具列表中确认出现 geml_get、geml_set 等工具；然后让 agent 读取文档中的某个区块（如 "显示 #hello 区块"），能返回该区块内容即说明连接正常。注意：--root 必须是绝对路径，路径之外的读写会被拒绝。

常见排障

确认 Node 22+ 已安装 (`node --version`)。
确保 --root 是一个绝对路径且存在。
测试来自命令行的基本操作：geml check yourfile.geml。
检查客户端以标准输入输出模式启动服务器，并且权限允许。
检查 .gemlhistory 的写入权限。
如果图谱工具缺失，检查图形索引是否存在 (.geml-code-graph/index.geml)。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

读取 doc.geml 中 #budget 那一个区块的内容
把 FY26 表格里的 Q3 那一行改成 12
在 #intro 后面插入 snippet.geml 里的片段
查看 #plan 区块的修改历史，并把它的上一个版本还原回来

工具能力 12

geml_get 只读

读取一个单独的块（例如，通过 #id）。

geml_set 写入

替换一个块，可选内容来自另一个模板或文件。

geml_add 写入

在另一块之后插入一个片段，保持其自身的 ID。

geml_delete 破坏性

删除指定块。

geml_rename 写入

重命名一个块 ID。

geml_history 只读

查看特定块的修订历史。

geml_revert 破坏性

回滚一个单独的块到先前的修订，保持文件的其他部分不变。

geml_check 只读

验证文档，并报告诊断信息和非零退出码以标记错误。

展开其余 4 个工具

geml_codemap_called_by 只读

查找哪些方法调用了给定方法。

geml_codemap_calls 只读

查找给定方法调用的方法。

geml_codemap_view 只读

查看代码图的节点或其路径。

geml_codemap_find 只读

搜索代码图中的方法或路径。

使用场景

使用 AI 代理在大型 GEML 文档中编辑单个块，同时保持文档的其余部分不变。

验证文档的引用完整性，通过块 ID 或内容哈希引入结构化上下文。

通过逐块机制查找错误，并回滚有问题的更改。

对于包含代码图谱的仓库，回答基于代码库级别的调用图查询。

支持客户端

Claude Desktop

Claude Code

Generic MCP client

依据项目文档列出，未经本站实测。

详细介绍

该服务器通过标准输入输出协议运行，允许 AI 代理通过逐块操作而不是重写整个文档来编辑 GEML 文件（基于 Markdown 的纯文本文档）。它将每次写入前进行解析，拒绝可能导致文档无效的更改，并维护基于块的修订历史（.gemlhistory），以便回滚。它要求使用 --root 指定工作目录，并且永远不会超出该目录。它适用于任何 MCP 兼容的客户端，如 Claude Desktop 或 Claude Code。它可以额外提供只读的代码图谱工具，以回答诸如“谁调用这个？”等问题，在适用情况下。