@skills-forge/mcp-server

Skills Forge MCP server — 让 Cursor / Claude Code / Codex / Windsurf 等 AI 工具按 Model Context Protocol 调用 Skills Forge skills, Bearer key 不进 AI prompt 历史.

为什么用 MCP 而不是把 curl 粘到 Rules?

| | Rules + curl (老) | MCP (新, 推荐) | |---|---|---| | Bearer key 落在 Rules 文本 | ❌ 是 | ✅ 否 | | AI 对话历史能搜到 key | ❌ 是 | ✅ 否 | | 截图 / 录屏 / git 提交泄漏 key | ❌ 高风险 | ✅ 无 | | 配置位置 | Rules + IDE Rules 编辑器 | 单一 mcp.json |

快速开始 (3 步)

1. 拿 key: 登录 skillsforge.xyz → 个人中心 (/me) → 复制 Invocation Key (sk_live_…).
2. 填配置: 按下方你用的客户端, 把 skills-forge 加进对应的 MCP 配置文件.
3. 重启 / 重连: 重启 IDE 或在 Claude Code 里跑 /mcp 重连. 之后直接说"用 skills-forge 帮我…", AI 会自动调 resolve_skill + get_skill_raw.

首次启动 npx 会拉包, 约 3–5 秒, 属正常.

各客户端配置

大多数客户端用同一份 JSON — 复制到对应路径即可:

{
  "mcpServers": {
    "skills-forge": {
      "command": "npx",
      "args": ["-y", "@skills-forge/mcp-server@latest"],
      "env": { "SKILLS_FORGE_KEY": "sk_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

| 客户端 | 配置文件路径 | |---|---| | Cursor | ~/.cursor/mcp.json (项目级 <repo>/.cursor/mcp.json) | | Claude Desktop | macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Kiro | ~/.kiro/mcp.json | | Antigravity | ~/.antigravity/mcp.json | | Trae | ~/.trae/mcp.json |

把 sk_live_… 换成你的 Invocation Key, 重启 IDE 即可.

Codex CLI (TOML 格式)

~/.codex/config.toml:

[mcp_servers.skills-forge]
command = "npx"
args = ["-y", "@skills-forge/mcp-server@latest"]

[mcp_servers.skills-forge.env]
SKILLS_FORGE_KEY = "sk_live_xxxxxxxxxxxxxxxx"

Claude Code (CLI 命令)

claude mcp add skills-forge --scope user \
  -e SKILLS_FORGE_KEY=sk_live_xxxxxxxxxxxxxxxx \
  -- npx -y @skills-forge/mcp-server@latest

跑 claude mcp list 验证, /mcp 在会话内重连.

环境变量

| 变量 | 必填 | 默认 | 说明 | |---|---|---|---| | SKILLS_FORGE_KEY | ✅ | — | Invocation Key, 格式 sk_live_…. 缺失或格式非法 → 启动 exit(1) | | SKILLS_FORGE_API_BASE | ❌ | http://localhost:3001 | backend 地址. 部署后设为 https://api.skillsforge.xyz (或你的自托管 URL) | | SKILLS_FORGE_CLIENT_NAME | ❌ | unknown | 上报来源名 (cursor / claude / codex / windsurf …), 让后台精确归因 IDE. 多数客户端会在握手时自报, 无须手填 |

更安全: 用 env 插值, 别把明文 key 写进 mcp.json

Cursor (${env:NAME}) 和 Claude Code (${NAME}) 都支持在配置里引用环境变量, 这样 key 留在你的 shell 环境, 配置文件本身零明文, 提交 git 也不泄漏:

{
  "mcpServers": {
    "skills-forge": {
      "command": "npx",
      "args": ["-y", "@skills-forge/mcp-server@latest"],
      "env": { "SKILLS_FORGE_KEY": "${env:SKILLS_FORGE_KEY}" }
    }
  }
}

然后在 shell profile (~/.zshrc / ~/.bashrc / Windows 环境变量) 里:

export SKILLS_FORGE_KEY="sk_live_xxxxxxxxxxxxxxxx"

即便直接把 key 写进 mcp.json, 也务必加 .gitignore; 用户级路径 (~/.cursor/mcp.json) 比项目级 (<repo>/.cursor/mcp.json) 更安全.

本地开发 / 自托管

包默认连 http://localhost:3001 (本地 npm run dev 的后端). 部署后 / 连其它后端时设 SKILLS_FORGE_API_BASE (如 https://api.skillsforge.xyz):

{
  "mcpServers": {
    "skills-forge": {
      "command": "npx",
      "args": ["-y", "@skills-forge/mcp-server@latest"],
      "env": {
        "SKILLS_FORGE_KEY": "sk_live_xxxxxxxxxxxxxxxx",
        "SKILLS_FORGE_API_BASE": "http://localhost:3001"
      }
    }
  }
}

从源码跑 (开发本包):

npm install
SKILLS_FORGE_KEY=sk_live_xxx SKILLS_FORGE_API_BASE=http://localhost:3001 npm run dev
npm test        # vitest, 74 测试 / 8 文件
npm run build   # tsup → dist/ ESM

暴露的工具

Skill 检索 (4)

| 工具 | 用途 | |---|---| | resolve_skill | ⭐ 服务端智能匹配: 用户原话 → Top N 最匹配的 skill (差异化护城河) | | list_skills | 列出当前账号可见的全部 skill 元数据 | | get_skill_raw | 拉取某 skill 的完整 Markdown 正文 | | list_bundles | 列出 Bundle 与其含的 skill |

Spec-driven 工作流 (4)

| 工具 | 用途 | |---|---| | spec_init | 在 .spec/<feature>/ 创建三段式骨架 (requirements.md / design.md / tasks.md); 撞名不覆盖, 返回 suggestedName | | ears_validate | 校验 EARS 6 句式 (Ubiquitous / Event / State / Unwanted / Optional + Complex), 中英双轨, 输出错误码 + 修复建议 | | task_check | 切换 tasks.md checkbox 五态 ([ ]/[~]/[x]/[-]); 命中 **Checkpoint** 自动拦停, 等用户确认 | | phase_advance | 推进 requirements → design → tasks 阶段门; req→design 强制跑 ears_validate; triggeredBy 必须 user, AI 伪造不出 |

8 个工具的 description / 入参 schema 里不含任何 key 形式 (连占位都没有).

安全设计 (Key Locality)

key 只在你本地 mcp.json (或 shell env) 落地, server 进程内 closure 持有, 用 Bearer 鉴权后调 backend, AI 全程看不到:

你 (本地 mcp.json / shell env)
    │  SKILLS_FORGE_KEY=sk_live_...
    ▼
[MCP server (本进程内部 closure, 唯一出口 getAuthHeader)]
    │  Authorization: Bearer ...
    ▼
[Skills Forge backend /api/v1/...]

• 没配 key → 启动 exit(1), 不默默运行掩盖配置错误.
• 工具返回值 / 错误体永不回写 Authorization / key.

故障排查

| 现象 | 原因 | 处理 | |---|---|---| | 启动即退出, stderr 提示 SKILLS_FORGE_KEY 未配置 | 没设 key 或格式不对 | 检查 env.SKILLS_FORGE_KEY, 须 sk_live_ 开头 | | 工具调用报 401 | key 失效 / 被撤销 | 去 /me 轮换 key | | 工具调用报 403 | 该 skill 需订阅对应 Bundle | 去 /me 订阅, 或换 resolve_skill 拿可见 skill | | 工具调用报 429 | 触发限速 | 稍后重试, 别让 AI 循环重拉 | | IDE 里看不到 8 个工具 | 没重启 / 没重连 | 重启 IDE, Claude Code 跑 /mcp | | 连不上 backend | SKILLS_FORGE_API_BASE 指向了未上线的域名 | 本地开发设 http://localhost:3001 |

远程 SSE / Streamable-HTTP 模式

规划中 (Phase 3, 暂未上线). 届时无须装 Node / npx, 填一个 URL 即可:

{
  "mcpServers": {
    "skills-forge": {
      "url": "https://api.skillsforge.xyz/mcp",
      "headers": { "Authorization": "Bearer sk_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

当前请用上方 stdio 模式.

License

MIT — 见 LICENSE.

我们主动选 MCP 协议路线 (而非本机 CLI) 做差异化 — 用户零 PATH 污染、零跨平台麻烦、零超时调优、零环境排障, 跨工具兼容更广.