soil-ui-mcp

面向 @sobot/soil-ui 的 Model Context Protocol（MCP） 服务：在本地检索、阅读组件 Markdown 文档，并可选接入 soil-ui 源码，在文档不足以回答问题时直接查阅源码实现。

设计说明

| 项目 | 说明 | |------|------| | 服务名 | soil-ui-mcp | | 传输 | stdio（由 Cursor / Claude Desktop 等 MCP 客户端拉起子进程） | | 运行时 | Node.js ≥ 16（18+ 使用原生 fetch，16/17 自动 polyfill） | | 文档根目录 | 相对路径 docs/（即 mcp-docs/docs，启动时全量预加载至内存） | | 源码目录 | 可选，通过环境变量 SOIL_UI_SRC 配置 |

工具一览

文档工具（始终可用）

| 工具 | 作用 | |------|------| | list_docs | 列出所有 .md 文件名，可选按文件名子串过滤 | | search_docs | 在全部文档中做子串搜索，返回按文件分组的行号与片段 | | read_doc | 按文件名读取单个文档完整内容 |

源码工具（配置 SOIL_UI_SRC 后可用）

| 工具 | 作用 | |------|------| | list_src | 递归列出源码目录下的文件，支持路径子串和扩展名过滤 | | search_src | 在源码文件中做子串搜索，返回按文件分组的行号与片段 | | read_src | 按相对路径读取单个源码文件完整内容 |

Agent 工作策略：优先通过文档工具回答问题；当文档信息不足时，自动使用源码工具查阅实现细节。

安装

cd mcp-docs
npm install   # 或 yarn install

本地验证

npm start

进程从 stdin 读取 MCP JSON-RPC；无交互时看似「挂起」属正常，由 MCP 客户端连接使用。

在 Cursor 中注册 MCP

仅使用文档工具

{
  "mcpServers": {
    "soil-ui-mcp": {
      "command": "node",
      "args": ["/Users/you/sobot-ui/mcp-docs/src/server.mjs"]
    }
  }
}

同时启用源码工具

在配置中加入 env.SOIL_UI_SRC，指向 soil-ui 源码目录（绝对路径）：

{
  "mcpServers": {
    "soil-ui-mcp": {
      "command": "node",
      "args": ["/Users/you/sobot-ui/mcp-docs/src/server.mjs"],
      "env": {
        "SOIL_UI_SRC": "/Users/you/sobot-ui/src"
      }
    }
  }
}

SOIL_UI_SRC 为可选项。若路径不存在或未配置，服务器正常启动，仅文档工具可用，stderr 会打印一条警告。

更完整示例见 cursor-mcp-config.example.json。

发布到 npm

npm login                 # 首次需要登录
npm run release:patch     # 补丁版本 1.0.0 → 1.0.1
npm run release:minor     # 次版本   1.0.0 → 1.1.0
npm run release:major     # 主版本   1.0.0 → 2.0.0

发布后用户可通过 npx 直接运行：

npx soil-ui-mcp

目录结构

mcp-docs/
  package.json          # 包名 soil-ui-mcp，engines: node >=16
  .yarnrc               # ignore-engines true（兼容 Yarn Classic + Node 16）
  src/
    server.mjs          # MCP 入口（stdio）
  docs/                 # 被检索的 Markdown 组件文档
  README.md
  cursor-mcp-config.example.json

安全说明

• 文档工具：read_doc 仅允许 docs/ 目录下的 *.md 文件，通过 path.resolve 校验，防止路径穿越。
• 源码工具：read_src / search_src 仅允许 SOIL_UI_SRC 目录内的文件，扩展名限制为 .js .jsx .ts .tsx .vue .css .less .scss .json .md；自动跳过 node_modules、dist、build 等目录。