lowcode-mcp

lowcode-mcp 是面向 lowcode 使用者与维护者的 MCP server：它把指定 repo 和 branch 的组件文档固化为本地 git 快照，让 Agent 按职责查询结构化组件配置、Schema 示例和专题文档，并在交付 Schema 前执行校验。

list_components
  ├─ get_component_props / events / actions
  └─ list_component_demos ──> get_component_demo

list_guides ──> list_guide_sections ──> get_guide_section

Schema ──> validate_schema

组件配置来自固定机器事实区；支撑文档只在服务端内部展开 inherits / aliasOf，不会被当作 renderer 暴露。Agent 不猜组件名、示例 ID、guide 或 section。

快速开始

需要 Node.js ≥ 18 与本机 git。LOWCODE_REPO 必填；消费项目应通过 LOWCODE_BRANCH 固定自己的 lowcode 分支。

以 Claude Code 为例，其他 MCP client 使用同构配置：

{
  "mcpServers": {
    "lowcode-docs": {
      "command": "npx",
      "args": ["-y", "@fa-software/lowcode-mcp"],
      "env": {
        "LOWCODE_REPO": "[email protected]:semi2/lowcode.git",
        "LOWCODE_BRANCH": "6.12.0"
      }
    }
  }
}

server 启动时同步文档快照，然后固定暴露 10 个只读 tool：

1. 调用 list_components 锁定精确 renderer name。
2. 按需要调用 get_component_props、get_component_events、get_component_actions；结果已展开显式继承。
3. 示例先调用 list_component_demos，再将精确 id 传给 get_component_demo。
4. 跨组件概念依次调用 list_guides、list_guide_sections、get_guide_section。
5. 编写或修改 Schema 后调用 validate_schema，处理全部 issue 后重新校验。

返回结果

成功结果直接位于 structuredContent，text content 镜像同一份 JSON，不再使用 {status, data} 信封。每个成功结果都带统一来源：

{
  "source": {
    "branch": "6.12.0",
    "commit": "0123456789abcdef",
    "stale": false
  }
}

staleReason 仅在网络失败并回退本地缓存时出现。

无法完成调用时返回 isError: true，结构为：

{
  "error": {
    "code": "not_found",
    "message": "...",
    "candidates": []
  }
}

错误码包括 invalid_arguments、not_found、ambiguous、not_available、invalid_document、runtime_error。可恢复错误继续提供候选组件、示例 ID、guide、section 或可用配置类型。

10 个 tool 均声明 readOnlyHint: true、destructiveHint: false、idempotentHint: true 和 openWorldHint: true。

Tool reference

组件

| Tool | 参数 | 返回 | |---|---|---| | list_components | 无 | renderer 组件目录；排除 supportDoc | | get_component_props | name | 根属性与 子配置：X 分组，包含继承属性和 definedBy | | get_component_events | name | 结构化事件、触发条件、详情和定义来源 | | get_component_actions | name | 结构化动作、参数、约束、详情和定义来源 |

属性合并优先级为：本组件 → aliasOf → inherits 声明顺序；同名项先出现者生效。

Schema 示例

| Tool | 参数 | 返回 | |---|---|---| | list_component_demos | name | id、场景标题和 scope 的瘦目录 | | get_component_demo | name、id | 已解析的 JSON schema |

id 必须来自 list_component_demos。完整示例不返回 Markdown fence、raw 或代码字符串。

专题

| Tool | 参数 | 返回 | |---|---|---| | list_guides | 无 | 表达式、数据域、API、事件动作等专题目录 | | list_guide_sections | guide | guide 元信息、introduction 和精确 section 目录 | | get_guide_section | guide、section | 指定专题章节的 Markdown |

validate_schema

输入可为 object、数组或 JSON 字符串；strictTypes: true 会将 unknown_type 升级为 error。

校验覆盖：

• JSON 与模板表达式语法；
• 未注册或无文档的 renderer type，以及 docs 与类型注册表冲突；
• 未知属性、frontmatter aliases 记录的更名属性、字面量枚举值；
• onEvent 事件名与 actionType 动作名；
• 同一数据域内重复的表单项 name；
• 全局重复的 id。

公开的 issues[] 只包含 path、severity、code、message 和可选 candidates；不包含文档路由或内部判据来源。valid 仅在零 issue 时为 true，warning 也会令其为 false。

快照、缓存与认证

启动时按 (repo, branch) 建立独立缓存桶。每桶一个浅 clone：

--depth 1 --filter=blob:none --sparse

稀疏工作树包含 docs/zh-CN，以及 validate_schema 构建同 revision 判据所需的 packages/amis-core/src/schema.ts 和 packages/amis/src/SchemaFull.ts。分支出现新 commit 时原地更新；多分支 server 实例互不覆盖。

瞬时网络失败会回退已有缓存并标记 stale。认证失败、仓库不存在或分支不存在会拒绝启动，缓存不会冒充当前文档。仓库同时存在同名 branch 和 tag 时始终锁定 branch。

| 环境变量 | 必填 | 说明 | |---|---|---| | LOWCODE_REPO | 是 | lowcode 仓库 git 地址，支持 ssh 或 https | | LOWCODE_BRANCH | 否 | 固定文档分支；缺省时探测远程默认分支；接受 refs/heads/x | | LOWCODE_GIT_TOKEN | 否 | https token；通过 GIT_ASKPASS 环境传递，不进入参数或 .git/config | | LOWCODE_GIT_USERNAME | 否 | https token 用户名，默认 oauth2 | | LOWCODE_CACHE_DIR | 否 | 缓存根目录，默认 ~/.amis/lowcode-docs |

开发与文档治理

npm run build            # tsc → dist/
npm test                 # 单测、git 同步、协议层、stdio E2E、schema 快照、真实 docs 校验
npm run test:conformance # MCP 官方通用协议场景
npm run docs:drift       # 扫描全部组件文档示例并生成漂移报告
npm run docs:lint        # 执行文档结构与 schema 示例门禁
npm pack                 # prepack 自动构建

docs:drift 把全部组件文档中的 Schema 示例交给同一套内部校验判据，默认输出仓库根目录的 reports/docs-drift.md。它用于盘点漂移，不把发现本身作为失败门禁。

docs:lint 检查组件文档身份、机器事实区顺序与表头、显式继承和别名、Schema fence 归属及全部 Schema 示例。任一结构违规或校验 issue 都会令进程以非零状态退出，不接受旧格式兼容或数量基线。

有意修改 tool schema、description 或 server instructions 后，使用 MCP_UPDATE_SNAPSHOTS=1 npm test 更新快照；意外漂移会令测试失败。测试在临时目录中使用 fixture docs 与本地 git remote，不访问网络；test/docs.test.ts 会解析 monorepo 当前 commit 的真实文档。

内部数据流、判据构建和模块职责见 docs/architecture.md。

License

Apache License 2.0