skill2mcp

# skill2mcp [](./LICENSE-MIT) [](./LICENSE-APACHE) [](https://github.com/agenttic-ai-dev/skill2mcp)  `skill2mcp` 是一个 TypeScript 命令行工具/库，用于将 `SKILL.md` 文档转换为 MCP-ready 工具定义，并可以从单个文件或整个技能目录生成最小的可部署的 MCP 服务器包。 生成的服务器使用官方的 MCP TypeScript SDK (`@modelcontextprotocol/sdk`)，并支持 `stdio`、`http` 或 `both` 传输方式。 ## 为什么有这个项目 SKILL 文档通常是半结构化的 markdown（前言 + 正文 + 表格）。MCP 工具需要严格的契约（`name`、`description`、`inputSchema`）。 `skill2mcp` 通过分层管道弥合了这一差距： 1. 将 markdown 解析为稳定的中间表示（IR） 2. 将 IR 转换为 MCP 工具定义 3. 使用处理程序存根生成可部署的 MCP 服务器包 ## 当前状态 MVP 已实现并正常运行： - 确定性解析器（`strict`、`tolerant`） - cascading semantic 模式（`semantic`）用于缺失元数据的回退 - 工具转换（`SchemaBuilder`、`ToolMapper`、`ToolValidator`） - `inspect` 输出，带有 MCP 样式的工具 JSON - `build` 输出，带有可部署的 MCP 服务器包 - 生成的服务器支持 `stdio` + `http` - `build --watch` 用于迭代再生 ## 安装 ### 要求 - Node.js 20+ - npm 10+ ### 本地安装 ```bash npm install ``` ### 构建 CLI ```bash npm run build ``` ## 快速开始 ### 1. 解析单个 SKILL ```bash npm run parse -- ./fixtures/skills/valid-skill.md --mode strict ``` ### 2. 检查生成的工具定义 ```bash npm run inspect -- ./fixtures/skills --mode tolerant ``` ### 3. 生成可部署的 MCP 服务器包 ```bash npm run gen -- ./fixtures/skills --out ./generated/mcp-server --transport both --mode tolerant ``` ### 4. 运行生成的服务器 ```bash cd ./generated/mcp-server npm install npm run build npm run start:stdio # 或 npm run start:http ``` HTTP 端点： ```text POST /mcp ``` ## CLI 参考 ### `parse` 将 SKILL markdown 转换为 IR JSON。 ```bash skill2mcp parse <input> [--mode strict|tolerant|semantic] ``` 参数： - `<input>`：`.md` 文件或目录的路径 选项： - `--mode`：解析模式（默认为 `tolerant`） - `--format`：目前为 `json` 输出： - `results[]`，包含解析的 `SkillDocument` - `diagnostics[]`，每个源文件一个 ### `inspect` 将解析的 IR 转换为类似 MCP 的工具定义。 ```bash skill2mcp inspect <input> [--mode strict|tolerant|semantic] ``` 输出： - `tools[]`：生成的工具定义（`name`、`description`、`inputSchema`） - `results[]`：工具 + 每个源的诊断信息 ### `build` 从一个或多个技能生成可部署的 MCP 服务器包。 ```bash skill2mcp build <input> --out <dir> [--transport stdio|http|both] [--mode strict|tolerant|semantic] [--watch] ``` 参数： - `<input>`：`.md` 文件或目录的路径 必需选项： - `--out`：生成的包的输出目录 可选选项： - `--transport`：默认生成的服务器传输方式（默认为 `both`） - `--mode`：解析模式（默认为 `tolerant`） - `--watch`：在源代码更改时重新生成包 输出： - 生成的包文件（`package.json`、`tools.json`、`src/server.ts`、`handlers`） - JSON 格式的诊断信息汇总 ## 解析模式 ### `strict` - 在必需的元数据/模式缺失时失败 - 适用于 CI 质量门控 ### `tolerant` - 继续处理，并对缺失字段发出警告 - 适用于批量处理混合质量的技能 ### `semantic` - 从宽容解析开始 - 通过 OpenRouter（配置后）尝试语义提取 - 对未解析字段应用确定性回退推理 - 保留诊断跟踪（`SEMANTIC_*` 代码） ### `semantic` 的 OpenRouter 配置 环境变量： - `OPENROUTER_API_KEY`：启用远程语义提取 - `OPENROUTER_MODEL`（可选）：默认为 `anthropic/claude-3.5-sonnet` - `SKILL2MCP_CACHE_DIR`（可选）：覆盖缓存目录 - `OPENROUTER_HTTP_REFERER`（可选）：转发为 OpenRouter 头部 - `OPENROUTER_X_TITLE`（可选）：转发为 OpenRouter 头部 缓存行为： - 语义响应按内容哈希缓存在 `.skill2mcp-cache/semantic-openrouter-cache.json` 中 - 如果存在缓存，语义模式将重用缓存并避免额外的远程调用 ## 规范的 `SKILL.md` 格式（推荐） ```md --- name: docx-generator version: 1.0.0 description: 从结构化 markdown 生成 Word 文档 tags: [documents, office] --- ## 参数 | 名称 | 类型 | 必需 | 默认值 | 描述 | |------|------|----------|---------|-------------| | content | string | 是 | | Markdown 内容 | | title | string | 是 | | 文档标题 | ## 示例 **输入：** `{ content: "# Hello", title: "Report" }` **输出：** 在 `/outputs/` 处生成 report.docx ## 触发器 - "生成文档" - "创建报告" ``` ## 生成的包结构 ```text generated/mcp-server/ package.json tsconfig.json README.md tools.json src/ server.ts generated-tools.ts handlers/ index.ts <tool_name>.ts ``` ## 开发 ### 脚本 ```bash npm run build # 编译 TypeScript npm run test # 运行测试套件 npm run parse # 解析命令入口 npm run inspect # 检查命令入口 npm run gen # 构建命令入口 ``` ### 测试套件 当前自动覆盖范围包括： - 解析器行为（`strict`、`tolerant`、`semantic`） - 模式构建器和工具映射 - 检查命令输出契约 - 端到端构建工件生成 ## 工程约定 - 遵循 `AGENTS.md` 中的仓库协作规则 - 产品/业务指令由 `ROADMAP.md` 管理 - 提交消息必须在 AI 生成时使用 `[AI]` 前缀 ## 发布工件 此仓库包含： - 双重许可分发：`MIT OR Apache-2.0` - `CHANGELOG.md` - `CONTRIBUTING.md` - `RELEASE_CHECKLIST.md` ## 协作模型 - 治理和决策规则：`GOVERNANCE.md` - 代码行为：`CODE_OF_CONDUCT.md` - 安全报告：`SECURITY.md` - 支持渠道：`SUPPORT.md` ## 已知限制 - 参数解析目前假设 `## 参数` 中的 markdown 表格格式 - 语义模式优先考虑缺失的元数据，并在提取可用时可能会丰富缺失的参数 - 监视模式跟踪当前树；如果稍后添加深度嵌套的文件夹，请重新启动监视以实现完整覆盖 ## 路线图对齐 活跃的实现遵循 `ROADMAP.md` 中的分阶段交付。 GenAI 集成策略（启用时）优先使用 OpenRouter 作为默认提供商策略，如路线图指令中所述。 ## 许可证 根据以下任一许可证授权： - MIT 许可证 (`LICENSE-MIT`) - Apache 许可证 2.0 (`LICENSE-APACHE`) 由您选择。