mcp-skill-bridge

English

mcp-skill-bridge 是一个 HTTP MCP Server，用来把本地 skills 目录转换成 MCP 可读取的上下文，适合那些只能接入 MCP Server、但不支持原生 skills 机制的智能体产品。

它不要求客户端理解自定义 skill 系统，而是把技能发现暴露为 MCP resources，把技能详情查询和 shell 执行暴露为 MCP tools。这样一来，智能体可以先发现可用 skill，读取对应的 SKILL.md，再按文档要求执行本地命令。

快速开始

1. 启动已发布的 npm 包

Windows PowerShell：

$env:SKILLS_DIR = "C:\path\to\skills"; npx -y mcp-skill-bridge

macOS/Linux Bash：

SKILLS_DIR="/path/to/skills" npx -y mcp-skill-bridge

SKILLS_DIR 必须指向一个已经存在的目录。

默认监听地址：

• Host: 127.0.0.1
• Port: 5151

默认端点：

• MCP endpoint: http://127.0.0.1:5151/mcp
• 健康检查: http://127.0.0.1:5151/healthz

服务允许任意 Origin 的跨域请求，便于浏览器扩展访问本机端点。

2. 可选环境变量

• HOST

  • 可选。
  • 默认值：127.0.0.1

• PORT

  • 可选。
  • 默认值：5151

• LOG_LEVEL

  • 可选。
  • 默认值：info

示例：

$env:SKILLS_DIR = "C:\Users\me\skills"; $env:HOST = "127.0.0.1"; $env:PORT = "5151"; $env:LOG_LEVEL = "debug"; npx -y mcp-skill-bridge

SKILLS_DIR="/Users/me/skills" HOST="127.0.0.1" PORT="5151" LOG_LEVEL="debug" npx -y mcp-skill-bridge

为什么需要它

很多智能体产品支持添加 MCP Server，但并不支持原生的 “skills” 机制。

这个项目就是为了补上这层能力：

• 本地 SKILLS_DIR 会变成 MCP 可读取的发现数据。
• 每个 skill 仍然只是磁盘上的普通目录。
• 智能体可以通过 MCP 发现 skill 并读取技能文档，而不需要直接访问文件系统。
• 如果 skill 需要执行脚本或终端操作，智能体还可以通过 shell tool 调用本地命令。

当一个 skill 目录中包含以下内容时，这种方式尤其有用：

• SKILL.md
• scripts/ 下的辅助脚本
• 与技能文档放在一起的参考文件、模板或示例

读取技能文档时，服务端会在末尾追加一条说明，明确告诉模型当前 skill 对应的本地目录路径，从而让文档里提到的同级脚本和文件都有明确落点。

功能

Resources

• skills://root

  • 返回当前配置的 SKILLS_DIR 绝对路径。

• skills://index

  • 返回 SKILLS_DIR 下扫描到的所有有效 skill。
  • 递归扫描子目录中的 SKILL.md 文件，大小写不敏感。
  • 读取 YAML frontmatter，并提取：
    • name
    • description
    • 可选的 metadata

Tools

• get_skill_detail

  • 根据目录名返回某个 skill 的完整 SKILL.md 内容。
  • 响应末尾会追加一条英文说明，例如：
    • Note: The current skill directory is ...

• shell

  • 在子进程中执行 shell 命令。
  • 继承当前进程的环境变量。
  • 支持超时控制。
  • 返回：
    • return_code
    • stdout
    • stderr
    • timeout

Skill 发现规则

只有同时满足以下条件的目录才会被视为有效 skill：

• 目录中存在名为 SKILL.md 的文件，大小写不敏感。
• 文件以 YAML frontmatter 开头。
• frontmatter 中包含非空字符串字段：
  • name
  • description

无效的 skill 目录会被跳过，不会导致整个索引过程失败。

Skill 目录示例

skills/
  my-skill/
    SKILL.md
    scripts/
      setup.ps1
    references/
      example.txt

SKILL.md frontmatter 示例：

---
name: My Skill
description: Explains how to run a local workflow
metadata:
  category: automation
---

Use `scripts/setup.ps1` to prepare the environment.

当智能体为 my-skill 调用 get_skill_detail 时，返回内容末尾会附带一条说明，指明该 skill 目录路径类似于：

.../skills/my-skill/

客户端的典型使用流程

1. 连接 MCP endpoint。
2. 列出 resources。
3. 读取 skills://index 发现可用 skill。
4. 调用 get_skill_detail 获取目标 skill 的详细内容。
5. 如果 skill 要求执行终端命令或脚本，再调用 shell。

开发

安装依赖：

npm install

构建：

npm run build

运行测试：

npm test

只做类型检查：

npx tsc --noEmit

从本地编译产物启动：

npm start

项目技术栈

• Node.js
• TypeScript
• Hono
• 官方 MCP TypeScript SDK

服务使用的是基于 /mcp 的 Streamable HTTP MCP transport。

说明

• 面向使用者的推荐启动方式是 npx -y mcp-skill-bridge。
• npm start 主要用于本地开发，它运行的是 dist/ 下的编译产物。
• 修改源码后，需要重新构建再启动。
• shell 被单独设计成 tool，而不是 resource，因为它执行的是命令而不是读取数据。