内容
# mcp-skill-bridge
[中文说明](./README.zh-CN.md)
`mcp-skill-bridge` 是一个 HTTP MCP 服务器，它将本地技能目录转换为 MCP 可读的上下文，供只能附加 MCP 服务器的代理使用。
与其要求客户端理解自定义技能系统，不如让该服务器将技能发现暴露为 MCP 资源，并将技能详细信息查找和 shell 执行保留为 MCP 工具。这样，代理可以发现可用的技能，获取技能的 `SKILL.md`，然后在技能指示时执行本地命令。
## 快速入门
### 1. 启动已发布的软件包
Windows PowerShell:
```powershell
$env:SKILLS_DIR = "C:\path\to\skills"; npx -y mcp-skill-bridge
```
macOS/Linux Bash:
```bash
SKILLS_DIR="/path/to/skills" npx -y mcp-skill-bridge
```
`SKILLS_DIR` 必须指向一个存在的目录。
默认情况下，服务器监听：
- 主机：`127.0.0.1`
- 端口：`5151`
端点：
- MCP 端点：`http://127.0.0.1:5151/mcp`
- 健康检查：`http://127.0.0.1:5151/healthz`
### 2. 可选环境变量
- `HOST`
- 可选。
- 默认值：`127.0.0.1`
- `PORT`
- 可选。
- 默认值：`5151`
- `LOG_LEVEL`
- 可选。
- 默认值：`info`
示例：
```powershell
$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
```
```bash
SKILLS_DIR="/Users/me/skills" HOST="127.0.0.1" PORT="5151" LOG_LEVEL="debug" npx -y mcp-skill-bridge
```
## 为什么存在
许多代理产品支持添加 MCP 服务器，但不支持原生的“技能”机制。
该服务器弥合了这一差距：
- 本地 `SKILLS_DIR` 成为 MCP 可读的发现数据。
- 每个技能仍然是磁盘上的普通文件夹。
- 代理可以通过 MCP 发现技能和获取技能文档，而无需直接的文件系统集成。
- 代理仍然可以通过 `shell` 工具在技能需要脚本或终端步骤时运行本地命令。
这在技能文件夹包含以下内容时尤其有用：
- `SKILL.md`
- `scripts/` 下的辅助脚本
- 技能文档旁边的引用文件、模板或示例
当读取技能文档时，服务器会追加一个最终注释，告诉模型该技能位于哪个本地目录，因此对兄弟脚本和文件的提及被限定为实际路径。
## 功能
### 资源
- `skills://root`
- 返回配置的 `SKILLS_DIR` 绝对路径。
- `skills://index`
- 返回在 `SKILLS_DIR` 下发现的所有有效技能。
- 递归扫描子目录以查找 `SKILL.md` 文件（不区分大小写）。
- 读取 YAML 前置信息并提取：
- `name`
- `description`
- 可选的 `metadata`
### 工具
- `get_skill_detail`
- 返回由目录名称标识的单个技能的完整 `SKILL.md`。
- 响应追加了一条额外的注释，例如：
- `注意：当前技能目录是 ...`
- `shell`
- 在子进程中运行 shell 命令。
- 继承当前进程的环境变量。
- 支持超时控制。
- 返回：
- `return_code`
- `stdout`
- `stderr`
- `timeout`
## 技能发现规则
服务器仅当以下所有条件均为真时，才将文件夹视为有效技能：
- 文件夹包含一个名为 `SKILL.md` 的文件（不区分大小写）。
- 文件以 YAML 前置信息开头。
- 前置信息包含非空字符串字段：
- `name`
- `description`
无效的技能文件夹将被跳过，不会破坏整个索引。
## 示例技能布局
```text
skills/
my-skill/
SKILL.md
scripts/
setup.ps1
references/
example.txt
```
示例 `SKILL.md` 前置信息：
```md
---
name: 我的技能
description: 解释如何运行本地工作流
metadata:
category: automation
---
使用 `scripts/setup.ps1` 准备环境。
```
当代理为 `my-skill` 调用 `get_skill_detail` 时，服务器返回文档以及一个最终注释，指示技能目录为：
```text
.../skills/my-skill/
```
## 客户端典型用法
1. 连接到 MCP 端点。
2. 列出资源。
3. 读取 `skills://index` 以发现可用的技能。
4. 为要应用的技能调用 `get_skill_detail`。
5. 如果技能要求终端命令或本地脚本，则调用 `shell`。
## 开发
安装依赖项：
```powershell
npm install
```
构建：
```powershell
npm run build
```
运行测试：
```powershell
npm test
```
仅类型检查：
```powershell
npx tsc --noEmit
```
从编译输出运行本地：
```powershell
npm start
```
## 项目栈
- Node.js
- TypeScript
- Hono
- 官方 MCP TypeScript SDK
服务器使用可流式 HTTP MCP 传输，路径为 `/mcp`。
## 注释
- 已发布的构建旨在使用 `npx -y mcp-skill-bridge` 启动。
- `npm start` 主要用于本地开发，并从 `dist/` 运行编译后的输出。
- 修改源代码后，请在重新启动前重新构建。
- `shell` 与资源故意分开，因为它执行的是执行操作，而不是数据检索。
