mcp2skill 0.1.10

Generate Claude Code skills from mcp2rest servers

mcp2skill: Generate Claude Code Skills from MCP Servers

Turn MCP servers into Claude Code skills in 3 steps.

# 1. Check available servers
mcp2skill servers

# 2. Generate skill
mcp2skill generate chrome-devtools

# 3. Done! Claude Code auto-discovers it

Skills include minimal SKILL.md documentation and Python scripts that wrap REST API calls to your mcp2rest service.

---

What is mcp2skill?

mcp2skill is a skill generator that transforms MCP servers running in mcp2rest into Claude Code skills.

• 🎯 Queries mcp2rest REST API to get tool schemas
• 📝 Generates SKILL.md with concise documentation
• 🐍 Creates Python scripts for each tool (clean argparse wrappers)
• 🤖 Claude Code ready - auto-discovered from ~/.claude/skills/
• 🔄 Stateful - mcp2rest maintains server state between calls

Not a runtime library - it's a code generator that creates skills from MCP servers.

---

Prerequisites

1. Install and Configure mcp2rest

mcp2rest is a Node.js service that manages MCP servers and exposes them via REST API.

# Install globally
npm install -g mcp2rest

# Add MCP servers
mcp2rest add chrome-devtools chrome-devtools-mcp@latest
mcp2rest add figma-desktop --url http://127.0.0.1:3845/mcp

# Start service (runs on localhost:28888)
mcp2rest start

# Or run as system service
mcp2rest service install
mcp2rest service start

2. Install mcp2skill

pip install mcp2skill

---

Quick Start

List Available Servers

mcp2skill servers

Output:

Available servers in mcp2rest (http://localhost:28888):

  ✓ chrome-devtools
    Status: connected
    Tools: 26
    Transport: stdio
    Package: chrome-devtools-mcp@latest

  ✓ figma-desktop
    Status: connected
    Tools: 7
    Transport: http
    URL: http://127.0.0.1:3845/mcp

Generate Skills

# Generate one skill
mcp2skill generate chrome-devtools

# Generate all at once
mcp2skill generate --all

# Custom output location
mcp2skill generate chrome-devtools --output /path/to/skills

Generated Structure

~/.claude/skills/
└── mcp-chrome-devtools/
    ├── SKILL.md              # Concise documentation (~130 lines)
    └── scripts/
        ├── mcp_client.py     # Shared REST client
        ├── new_page.py       # Tool: Open new browser page
        ├── click.py          # Tool: Click element
        ├── take_snapshot.py  # Tool: Get page structure
        └── ... (26 tools total)

Use with Claude Code

Claude Code automatically discovers skills in ~/.claude/skills/. Just ask:

User: "Open example.com and click the login button"

Claude: [Discovers mcp-chrome-devtools skill]
        [Runs: python scripts/new_page.py --url https://example.com]
        [Runs: python scripts/take_snapshot.py]
        [Finds button UID in snapshot]
        [Runs: python scripts/click.py --uid login_btn_123]

        ✓ Opened example.com and clicked the login button

Use Scripts Directly

cd ~/.claude/skills/mcp-chrome-devtools/scripts

# Get help for any tool
python new_page.py --help

# Execute tools
python new_page.py --url https://example.com
python take_snapshot.py
python click.py --uid button_abc123

---

Complete Example: Web Form Automation

Scenario: Fill out a contact form on example.com

Step 1: Navigate to the Form

python scripts/new_page.py --url https://example.com/contact

Step 2: Get Page Structure

python scripts/take_snapshot.py

Output shows element UIDs:

# contact_form response
## Accessibility Tree

Window - Contact Us

[uid="email_input"] textbox "Email"
[uid="message_textarea"] textbox "Message"
[uid="submit_btn"] button "Submit"

Step 3: Fill Form Fields

python scripts/fill.py --uid email_input --value "[e-mail]"
python scripts/fill.py --uid message_textarea --value "Hello, I need help!"

Step 4: Submit

python scripts/click.py --uid submit_btn

Step 5: Verify

python scripts/take_screenshot.py --format png

All state persists - the browser session stays open between script calls because mcp2rest maintains the server state.

---

How It Works

Architecture Flow

┌─────────────────────────────────────────┐
│ 1. mcp2skill queries mcp2rest           │
│    GET /servers/chrome-devtools/tools   │
└───────────────┬─────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│ 2. Generates SKILL.md + Python scripts  │
│    Saves to ~/.claude/skills/           │
└───────────────┬─────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│ 3. Claude Code discovers skill OR       │
│    User runs scripts manually           │
└───────────────┬─────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│ 4. Script calls mcp2rest REST API       │
│    POST /call                           │
│    {server, tool, arguments}            │
└───────────────┬─────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│ 5. mcp2rest forwards to MCP server      │
│    Server maintains state               │
│    Returns result                       │
└─────────────────────────────────────────┘

Key Concepts

State Persistence

• mcp2rest runs MCP servers as persistent processes
• Browser pages, sessions, data persist between script calls
• Scripts are stateless - they just make REST calls
• State lives in mcp2rest/MCP server

Minimal Context

• SKILL.md files are concise (~100-150 lines)
• Just tool names, args, and basic examples
• No verbose curl commands cluttering context
• Python scripts handle REST complexity

Type Safety

• Scripts auto-generated from JSON Schema
• Proper argparse with types, required/optional args
• Help text from tool descriptions
• --help on any script shows usage

---

Advanced Usage

Inspect Server Tools

mcp2skill tools chrome-devtools

Shows all 26 tools with descriptions and parameters.

Custom mcp2rest Endpoint

# Via command line
mcp2skill servers --endpoint http://192.168.1.100:28888

# Via environment variable
export MCP_REST_URL="http://192.168.1.100:28888"
mcp2skill generate chrome-devtools

Scripts respect MCP_REST_URL environment variable.

Generate to Custom Location

# Project-specific skills
mcp2skill generate chrome-devtools --output ./project-skills

# Then use them
cd project-skills/mcp-chrome-devtools/scripts
python new_page.py --url https://myapp.local

Distribution via Git

# Generate skills
mcp2skill generate --all --output ./my-mcp-skills

# Publish
cd my-mcp-skills
git init
git add .
git commit -m "MCP skills for our team"
git push origin main

# Team members install
git clone https://github.com/team/my-mcp-skills.git ~/.claude/skills/

---

CLI Reference

Commands

mcp2skill servers [--endpoint URL]

• List available MCP servers from mcp2rest
• Shows status, tool count, transport type

mcp2skill generate <server_name> [--output DIR] [--endpoint URL]

• Generate skill for specific server
• Default output: ~/.claude/skills/

mcp2skill generate --all [--output DIR] [--endpoint URL]

• Generate skills for all connected servers

mcp2skill tools <server_name> [--endpoint URL]

• Show detailed tool information for a server

Options

• --output, -o: Output directory (default: ~/.claude/skills/)
• --endpoint: mcp2rest URL (default: http://localhost:28888)
• --help: Show help message
• --version: Show version

---

Generated Skill Structure

SKILL.md

Concise documentation with:

• Prerequisites (mcp2rest running)
• Tool listing by category
• Common workflow examples
• State persistence notes
• Troubleshooting tips

scripts/

mcp_client.py - Shared REST client

• Handles POST requests to mcp2rest /call endpoint
• Formats responses (text, images, errors)
• Error handling with clear messages

Tool scripts (e.g., click.py)

• Auto-generated from tool's JSON Schema
• Argparse with proper types
• Required vs optional parameters
• --help documentation
• Calls mcp_client.call_tool()

---

Real-World Examples

Browser Automation (chrome-devtools)

# Full workflow: search and extract data
python new_page.py --url https://news.ycombinator.com
python take_snapshot.py > structure.txt
# Review structure.txt to find article UIDs
python click.py --uid article_5
python evaluate_script.py --function "() => document.title"

Design Tool Integration (figma-desktop)

# Extract design tokens from Figma
python get_design_context.py --nodeId "1:2"
python get_variable_defs.py --nodeId "1:2"
python get_screenshot.py --nodeId "1:2" --format png

Combining with Other Tools

# Take screenshot, process with vision model
python new_page.py --url https://myapp.com/dashboard
python take_screenshot.py --format png > dashboard.png
# Use vision API to analyze dashboard.png

---

Troubleshooting

"Cannot connect to mcp2rest"

# Check mcp2rest is running
curl http://localhost:28888/health

# If not running, start it
mcp2rest start

# Check what servers are loaded
curl http://localhost:28888/servers

"Server not found"

# List available servers
mcp2skill servers

# Add server to mcp2rest
mcp2rest add chrome-devtools chrome-devtools-mcp@latest

# Restart mcp2rest
mcp2rest service restart

Script Errors

# Check tool arguments
python scripts/click.py --help

# Test mcp2rest API directly
curl -X POST http://localhost:28888/call \
  -H "Content-Type: application/json" \
  -d '{"server":"chrome-devtools","tool":"list_pages","arguments":{}}'

---

Why mcp2skill?

Clean Agent Context

• SKILL.md is concise (~100 lines) not bloated with curl commands
• Python scripts handle REST complexity
• Agent just needs to know: tool name, arguments

State Management

• mcp2rest maintains server state
• Browser sessions persist
• Database connections stay open
• Sequential operations work naturally

Developer Friendly

• Type-safe scripts from JSON Schema
• --help on every script
• Standard argparse interface
• Easy to test and debug

Distribution

• Share skills via git repos
• Team installs: git clone url ~/.claude/skills/
• Version control for skills
• Custom skills per project

---

Related Projects

• mcp2rest - REST API gateway for MCP servers (required)
• MCP - Model Context Protocol specification
• Claude Code - AI coding assistant with skill support

---

License

MIT License - see LICENSE file

Contributing

Issues and pull requests welcome!

• GitHub: https://github.com/ulasbilgen/mcp2skill
• Issues: https://github.com/ulasbilgen/mcp2skill/issues

---

Changelog

v0.1.10 (Current)

• Change default port from 3000 to 28888 to match mcp2rest v0.6.0+

v0.1.9

• Documentation update (removed slash command references)

v0.1.8

• Initial PyPI release
• Core skill generation from mcp2rest servers
• CLI commands: servers, generate, tools
• Python scripts with argparse wrappers
• Auto-discovery in ~/.claude/skills/
• Comprehensive test suite with 94% coverage