tomevault-io MCP to mcporter Skill Generator
将任意 MCP 服务器转换为基于 mcporter 的 Claude Code skill。输入 MCP 包名或 command，自动生成完整的 SKILL.md。
When To Use
- 用户想把某个 MCP 服务器包装成 skill
- 用户说"把这个 MCP 转成 skill"
- 用户想减少 MCP 工具占用的 context token
- 用户有多个 MCP 想要统一管理
Requirements
- Node.js >= 18
- mcporter 已安装（
npx mcporter --version可用）
Workflow
Step 1: 获取 MCP 信息
用户提供 MCP 服务器信息，支持以下格式：
npm 包名：
codecov-mcp
@anthropic/mcp-server-github
自定义 command：
bun run ./server.ts
python mcp_server.py --port 8080
已配置的服务器名：
github (从 mcporter 配置中读取)
Step 2: 获取工具列表
使用 mcporter 列出服务器的所有工具：
# 对于 npm 包
npx mcporter list --stdio "npx -y <package>" --schema
# 对于自定义 command
npx mcporter list --stdio "<command>" --schema
# 对于已配置的服务器
npx mcporter list <server-name> --schema
如果命令需要环境变量，使用 --env 传递：
npx mcporter list --stdio "npx -y codecov-mcp" --env CODECOV_TOKEN=test --schema
Step 2.1: 处理包兼容性问题
如果 npx -y <package> 失败（如包没有 bin 字段），尝试以下方案：
方案 A：搜索替代包
npm search <keyword> --json | jq '.[] | select(.name | test("mcp")) | .name'
很多 MCP 服务器有多个发布者，尝试其他包名。
方案 B：下载并直接运行
# 下载包
mkdir -p /tmp/mcp-server && cd /tmp/mcp-server
npm pack <package> && tar -xzf *.tgz
# 安装依赖
cd package && npm install --production
# 检查入口文件
cat package.json | jq '.main // .module // "index.js"'
# 使用 node 直接运行
npx mcporter list --stdio "node /tmp/mcp-server/package/build/index.js" --schema
方案 C：检查包是否有 CLI 入口
# 查看 package.json 的 bin 字段
npm info <package> bin
在生成的 SKILL.md 中，记录发现的兼容性问题和解决方案。
Step 2.5: 验证工具可用性
重要：不要信任文档中的工具名，必须实际验证。
很多 MCP 服务器的文档（README）与实际实现不一致。在 Step 2 获取工具列表后，必须：
- 用实际工具名（从
mcporter list --schema输出中提取）替换文档中的工具名 - 对每个工具进行一次实际调用测试，确认可用
- 记录工具的实际参数格式（可能与文档描述不同）
# 测试工具是否可用
npx mcporter call --stdio "npx -y <package>" --env TOKEN=test <tool_name> <required_params>
如果调用失败，检查：
- 工具名是否正确（大小写、下划线）
- 必需参数是否齐全
- 环境变量是否正确传递
Step 3: 分析工具
从获取的 schema 中提取：
- 工具列表 — 所有可用工具的名称和描述
- 参数定义 — 每个工具的输入参数、类型、是否必需
- 分类 — 按功能分组（查询类、操作类、复合工具等）
- 环境变量 — 从以下来源推断必需的环境变量：
- mcporter list 输出中的 env 相关错误
- 包的 README 或文档（使用
npm info <package>查看） - 工具参数中的 token/key 相关字段
- 常见模式：
<SERVICE>_TOKEN、<SERVICE>_API_KEY、<SERVICE>_ACCESS_TOKEN
环境变量推断规则：
- 如果工具需要认证，检查文档中的环境变量名
- 常见 MCP 服务器的环境变量：
- GitHub:
GITHUB_TOKEN - Linear:
LINEAR_ACCESS_TOKEN或LINEAR_API_KEY - Codecov:
CODECOV_TOKEN - Slack:
SLACK_BOT_TOKEN
- GitHub:
- 如果无法确定，在 SKILL.md 中标记为
<SERVICE>_TOKEN并提示用户查阅文档
Step 4: 生成 SKILL.md
根据分析结果生成 SKILL.md，结构如下：
---
name: <skill-name>
description: "<触发描述，包含关键词和场景>"
---
# <Skill 标题>
<一句话说明这个 skill 的用途>
## When To Use
<基于工具功能推导的使用场景列表>
## Requirements
<运行依赖，包括 Node.js、环境变量等>
## Hard Boundaries
<安全边界，如不暴露 token、只读操作等>
## First-Time Setup
<环境变量设置说明>
## Command Syntax
<mcporter call --stdio 的调用格式>
## Common Workflows
<基于工具分类推导的常用工作流，每个包含具体命令示例>
## Tool Reference
<工具分类表格，包含工具名、用途、关键参数>
## Environment Variables
<环境变量表格>
## Troubleshooting
<常见错误和解决方案>
Step 5: 生成规则
Frontmatter：
name：从包名推导，移除mcp-server-或-mcp后缀description：包含触发关键词（wrap、convert、skill 等）和核心功能描述
触发描述模板：
"<功能描述> Use when: <场景1>, <场景2>, <场景3>. Triggers on: <关键词1>, <关键词2>."
命令格式：
npx mcporter call --stdio "<command>" <tool_name> <param>:<value>
工作流生成规则：
- 优先使用复合工具（一次调用完成多步骤）
- 每个工作流包含：场景说明、命令示例、参数说明
- 常见工作流：快速概览、详情查看、搜索/过滤、创建/修改
工具表格格式：
| Tool | 用途 | 关键参数 |
|---|---|---|
tool_name |
一句话描述 | param1, param2 |
Step 6: 保存输出
将生成的 SKILL.md 保存到用户指定位置，默认为：
skills/<skill-name>/SKILL.md
Step 7: 脚本封装（推荐）
对于工具数量 >= 3 个的 MCP 服务器，建议创建 scripts/ 目录封装 bash 脚本，简化 agent 调用。
目录结构：
skills/<skill-name>/
SKILL.md
scripts/
_common.sh # 公共函数
<tool1>.sh # 每个工具一个脚本
<tool2>.sh
_common.sh 模板：
#!/usr/bin/env bash
# 公共辅助函数
die() { echo "错误: $*" >&2; exit 1; }
require_cmd() { command -v "$1" >/dev/null 2>&1 || die "缺少依赖: $1"; }
check_token() { [[ -n "${SERVICE_TOKEN:-}" ]] || die "SERVICE_TOKEN 未设置"; }
# 从 git remote 检测 owner/repo
parse_owner_repo() {
# ... 解析 --owner/--repo 参数，fallback 到 git remote
}
# 调用 MCP 工具，自动处理错误
call_mcp() {
local tool="$1"; shift
local result
result=$(npx mcporter call --stdio "<command>" --env TOKEN="$TOKEN" "$tool" "$@" 2>&1)
[[ "$result" == Error:* ]] && die "${result#Error: }"
echo "$result"
}
脚本封装要点：
- 每个脚本使用
set -euo pipefail严格模式 - 支持
--help显示用法 - 支持
--json输出原始 JSON - 自动从 git remote 检测 owner/repo
- 用 jq 格式化输出为人类可读格式
大 JSON 处理：
某些 MCP 工具返回超大 JSON（>1MB），直接管道传递可能被截断。解决方案：
# 先写入临时文件，再用 jq 提取需要的字段
tmpfile=$(mktemp)
trap "rm -f '$tmpfile'" EXIT
npx mcporter call ... > "$tmpfile" 2>&1
jq '{field1, field2}' "$tmpfile"
SKILL.md 更新：
在生成的 SKILL.md 的 Command Syntax 部分，同时提供脚本调用和原始 mcporter 调用两种方式，优先推荐脚本。
Output Format
生成的 SKILL.md 必须包含：
- Frontmatter — name、description
- When To Use — 至少 5 个使用场景
- Requirements — 所有依赖项
- Hard Boundaries — 安全约束
- Command Syntax — 调用格式说明
- Common Workflows — 至少 3 个工作流
- Tool Reference — 所有工具的分类表格
- Environment Variables — 环境变量表格（如有）
- Troubleshooting — 常见错误（至少 3 条）
Example
输入：
将 codecov-mcp 转换成 skill
处理：
npx mcporter list --stdio "npx -y codecov-mcp" --schema
输出：
生成 skills/codecov-mcp/SKILL.md，包含 37 个工具的说明和 9 个工作流。
Error Handling
| 错误 | 解决方案 |
|---|---|
| mcporter 未安装 | 提示 npm install -g mcporter |
| MCP 服务器无法启动 | 检查 command 是否正确，依赖是否安装 |
| 工具列表为空 | 检查服务器是否正常运行，是否有认证要求 |
| schema 获取失败 | 使用 --env 传递必要的环境变量 |
Limitations
- 无法自动推断所有环境变量，可能需要用户补充
- 生成的工作流是基于工具描述的推导，可能需要人工调整
- 不支持需要 OAuth 认证的 MCP 服务器（需先完成认证）
Source: zhangzqs/myskills — distributed by TomeVault.