skill2mcp

skill2mcp 是一个 TypeScript CLI/库，它将 SKILL.md 文档转换为 MCP 就绪的工具定义，并能从单个文件或整个技能目录生成最小化的可部署 MCP 服务器包。

生成的服务器使用官方 MCP TypeScript SDK (@modelcontextprotocol/sdk)，并支持 stdio、http 或 both 传输方式。

为什么选择本项目

SKILL 文档通常是半结构化的 Markdown（前置元数据 + 正文 + 表格）。MCP 工具需要严格的契约（name、description、inputSchema）。

skill2mcp 通过分层流水线弥合了这一差距：

1. 将 Markdown 解析为稳定的中间表示 (IR)

2. 将 IR 转换为 MCP 工具定义

3. 生成带有处理程序存根的可部署 MCP 服务器包

Related MCP server: Skillz

当前状态

MVP 已实现并可运行：

• 确定性解析器 (strict, tolerant)

• 用于缺失元数据回退的级联语义模式 (semantic)

• 工具转换 (SchemaBuilder, ToolMapper, ToolValidator)

• 带有 MCP 风格工具 JSON 的 inspect 输出

• 带有可部署 MCP 服务器包的 build 输出

• 生成的服务器支持 stdio + http

• 用于迭代重新生成的 build --watch

安装

要求

• Node.js 20+

• npm 10+

本地安装

npm install

构建 CLI

npm run build

快速入门

1. 解析单个 SKILL

npm run parse -- ./fixtures/skills/valid-skill.md --mode strict

2. 检查生成的工具定义

npm run inspect -- ./fixtures/skills --mode tolerant

3. 生成可部署的 MCP 服务器包

npm run gen -- ./fixtures/skills --out ./generated/mcp-server --transport both --mode tolerant

4. 运行生成的服务器

cd ./generated/mcp-server
npm install
npm run build
npm run start:stdio
# or
npm run start:http

HTTP 端点：

POST /mcp

CLI 参考

parse

将 SKILL Markdown 转换为 IR JSON。

skill2mcp parse <input> [--mode strict|tolerant|semantic]

参数：

• <input>: .md 文件或目录的路径

选项：

• --mode: 解析器模式（默认为 tolerant）

• --format: 当前为 json

输出：

• results[]: 包含已解析的 SkillDocument

• diagnostics[]: 每个源文件的诊断信息

inspect

将已解析的 IR 转换为类似 MCP 的工具定义。

skill2mcp inspect <input> [--mode strict|tolerant|semantic]

输出：

• tools[]: 生成的工具定义 (name, description, inputSchema)

• results[]: 每个源文件的工具 + 诊断信息

build

从一个或多个技能生成可部署的 MCP 服务器包。

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, 处理程序)

• 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 格式（推荐）

---
name: docx-generator
version: 1.0.0
description: Generate Word docs from structured markdown
tags: [documents, office]
---

## Parameters
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| content | string | yes |  | Markdown content |
| title | string | yes |  | Document title |

## Examples
**Input:** `{ content: "# Hello", title: "Report" }`
**Output:** report.docx generated at /outputs/

## Triggers
- "generate document"
- "create report"

生成的包结构

generated/mcp-server/
  package.json
  tsconfig.json
  README.md
  tools.json
  src/
    server.ts
    generated-tools.ts
    handlers/
      index.ts
      <tool_name>.ts

开发

脚本

npm run build       # compile TypeScript
npm run test        # run test suite
npm run parse       # parse command entry
npm run inspect     # inspect command entry
npm run gen         # build command entry

测试套件

当前的自动化覆盖范围包括：

• 解析器行为 (strict, tolerant, semantic)

• 模式构建器和工具映射

• inspect 命令输出契约

• 端到端构建产物生成

工程规范

• 遵循 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

已知限制

• 参数解析目前假设 ## Parameters 中使用 Markdown 表格格式

• 语义模式优先处理缺失的元数据，并在提取可用时可能丰富缺失的参数

• 监视模式跟踪当前树；如果稍后添加了深层嵌套文件夹，请重启监视以获得完整覆盖

路线图对齐

当前的实现遵循 ROADMAP.md 中的分阶段交付。

GenAI 集成策略（启用时）优先考虑 OpenRouter 作为默认提供商策略，如路线图指令中所定义。

许可证

根据以下任一协议许可：

• MIT 许可证 (LICENSE-MIT)

• Apache 许可证 2.0 (LICENSE-APACHE)

由您选择。