mcp-skill-bridge

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.

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

Tool

• get_skill_detail

  • Returns the full SKILL.md for a single skill.
  • Input: skill 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.

Project Stack

• Node.js
• TypeScript
• Hono
• Official MCP TypeScript SDK

The server uses Streamable HTTP MCP transport over /mcp.

Getting Started

1. Install dependencies

npm install

2. Set SKILLS_DIR

$env:SKILLS_DIR = "C:\path\to\skills"

SKILLS_DIR must point to an existing directory.

3. Build

npm run build

4. Start

npm start

Or run the published package directly:

npx -y mcp-skill-bridge

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

Environment Variables

• SKILLS_DIR

  • Required.
  • Root directory containing skills.

• HOST

  • Optional.
  • Default: 127.0.0.1

• PORT

  • Optional.
  • Default: 5151

• LOG_LEVEL

  • Optional.
  • Default: info

Example:

$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

Example Skill Layout

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

Example 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.

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:

.../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

Build:

npm run build

Run tests:

npm test

Type-check only:

npx tsc --noEmit

Notes

• npm start runs compiled output from dist/, not source files directly.
• Published builds can be started with npx -y mcp-skill-bridge.
• After changing source code, rebuild before starting again.
• shell is intentionally separate from resources because it performs execution, not data retrieval.