Content
# mcp-skill-bridge
[中文说明](./README.zh-CN.md)
`mcp-skill-bridge` is an HTTP MCP server that turns a local skills directory into MCP-readable context for agents that can only attach MCP servers.
Instead of requiring a client to understand a custom skill system, this server exposes skill discovery as MCP resources and keeps skill detail lookup plus shell execution as MCP tools. That lets an agent discover available skills, fetch a skill's `SKILL.md`, and then execute local commands when the skill instructs it to do so.
## Getting Started
### 1. Start the published package
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` must point to an existing directory.
By default, the server listens on:
- Host: `127.0.0.1`
- Port: `5151`
Endpoints:
- MCP endpoint: `http://127.0.0.1:5151/mcp`
- Health check: `http://127.0.0.1:5151/healthz`
### 2. Optional environment variables
- `HOST`
- Optional.
- Default: `127.0.0.1`
- `PORT`
- Optional.
- Default: `5151`
- `LOG_LEVEL`
- Optional.
- Default: `info`
Example:
```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
```
## Why This Exists
Many agent products support adding MCP servers, but do not support a native "skills" mechanism.
This server bridges that gap:
- A local `SKILLS_DIR` becomes MCP-readable discovery data.
- Each skill remains a normal folder on disk.
- The agent can discover skills and fetch skill docs over MCP without needing direct filesystem integration.
- The agent can still run local commands through the `shell` tool when the skill requires scripts or terminal steps.
This is especially useful when a skill folder contains:
- `SKILL.md`
- helper scripts under `scripts/`
- reference files, templates, or examples next to the skill document
When a skill document is read, the server appends a final note telling the model which local directory that skill lives in, so mentions of sibling scripts and files are grounded to an actual path.
## Capabilities
### Resources
- `skills://root`
- Returns the configured `SKILLS_DIR` absolute path.
- `skills://index`
- Returns all valid skills discovered under `SKILLS_DIR`.
- Scans subdirectories recursively for `SKILL.md` files, case-insensitive.
- Reads YAML frontmatter and extracts:
- `name`
- `description`
- optional `metadata`
### Tools
- `get_skill_detail`
- Returns the full `SKILL.md` for a single skill identified by directory name.
- The response appends an extra English note like:
- `Note: The current skill directory is ...`
- `shell`
- Runs a shell command in a child process.
- Inherits the current process environment variables.
- Supports timeout control.
- Returns:
- `return_code`
- `stdout`
- `stderr`
- `timeout`
## Skill Discovery Rules
The server treats a folder as a valid skill only when all of the following are true:
- The folder contains a file named `SKILL.md`, case-insensitive.
- The file starts with YAML frontmatter.
- Frontmatter contains non-empty string fields:
- `name`
- `description`
Invalid skill folders are skipped and do not break the whole index.
## Example Skill Layout
```text
skills/
my-skill/
SKILL.md
scripts/
setup.ps1
references/
example.txt
```
Example `SKILL.md` frontmatter:
```md
---
name: My Skill
description: Explains how to run a local workflow
metadata:
category: automation
---
Use `scripts/setup.ps1` to prepare the environment.
```
When the agent calls `get_skill_detail` for `my-skill`, the server returns the document plus a final note indicating that the skill directory is:
```text
.../skills/my-skill/
```
## How A Client Typically Uses It
1. Connect to the MCP endpoint.
2. List resources.
3. Read `skills://index` to discover available skills.
4. Call `get_skill_detail` for the skill you want to apply.
5. Call `shell` if the skill asks for terminal commands or local scripts.
## Development
Install dependencies:
```powershell
npm install
```
Build:
```powershell
npm run build
```
Run tests:
```powershell
npm test
```
Type-check only:
```powershell
npx tsc --noEmit
```
Run locally from compiled output:
```powershell
npm start
```
## Project Stack
- Node.js
- TypeScript
- Hono
- Official MCP TypeScript SDK
The server uses Streamable HTTP MCP transport over `/mcp`.
## Notes
- Published builds are intended to be started with `npx -y mcp-skill-bridge`.
- `npm start` is mainly for local development and runs compiled output from `dist/`.
- After changing source code, rebuild before starting again.
- `shell` is intentionally separate from resources because it performs execution, not data retrieval.
