Skills-Finder-MCP: Self-Hosted Reusable AI Workflows

A production-ready MCP server for discovering and executing reusable Claude Skills, with zero vendor lock-in.

What Is This?

Skills-Finder-MCP is a self-hosted MCP (Model Context Protocol) server that lets you:

✅ Define reusable workflows as skills (simple folder + SKILL.md metadata file) ✅ Deploy to any LLM client (Claude Desktop, Windsurf, Jan, or any MCP-aware tool) ✅ Run locally, on Raspberry Pi, or in the cloud (with one-click HTTPS setup) ✅ Integrate multiple LLMs (Claude, Grok, GPT, local Llama) without rewrites ✅ Skip boilerplate: Just write SKILL.md; server handles discovery, selection, execution

Quick Facts

| Property | Value | |----------|-------| | Startup Time | < 100ms (lazy-loads skills on demand) | | Skills Ready | 3 production-ready (changelog → newsletter, demo notes → email, browser automation) | | Supported Clients | Windsurf, Jan, Claude Desktop, ChatGPT, any MCP-aware LLM | | Transport Modes | Stdio (local) or HTTP (remote) | | Deployment | Local, Docker, Fly.io, Raspberry Pi, Cloudflare tunnel, any cloud | | Language | Python 3.11+ (FastAPI + MCP SDK) | | Skill Format | YAML frontmatter + Markdown (SKILL.md) | | Discovery Mode | Search-first (skills_search) with selective skill injection |

🚀 Quick Start (5 minutes)

1. Clone & Setup

git clone <your-repo-url>
cd Custom-Skills-Server
cp .env.example .env
# Edit .env and change API_KEY to a secure value (for REST API, optional for MCP)
nano .env

2. Start Server

Option A: Local Stdio Server (for Claude Desktop, Windsurf, Jan)

python -m venv .venv
source .venv/bin/activate  # or: .venv\Scripts\activate (Windows)
pip install -r requirements.txt
python mcp_server.py

Option B: HTTP Server (for remote access, ChatGPT, Fly.io)

python -m venv .venv
source .venv/bin/activate  # or: .venv\Scripts\activate (Windows)
pip install -r requirements.txt
python mcp_server_http.py
# Server starts on http://localhost:8000
# Dashboard available at http://localhost:8000/dashboard

Option C: Docker (HTTP Server)

docker-compose up -d

3. Connect with MCP Client

Windsurf:

1. Open Settings → Extensions → MCP Servers
2. Copy configuration from MCP-SETUP-GUIDE.md
3. Restart Windsurf
4. Should see 3 tools: ✓ changelog-newsletter, ✓ demo-followup, ✓ playwright-automation

Jan (same process, see MCP-SETUP-GUIDE.md)

📦 What's Included?

3 Production Skills

| Skill | Purpose | When to Use | |-------|---------|-------------| | changelog-newsletter | Transform changelogs → marketing emails | Release announcements, newsletters | | demo-followup | Sales call notes → personalized emails | Post-demo follow-ups, CRM integration | | playwright-automation ⭐ | Browser automation for forms, PDFs, data extraction | Form filling, PDF → web pipeline, Salesforce automation |

Core Server

• mcp_server_optimized.py - Main MCP server (STDIO protocol, lazy-loading)
• skill_loader.py - Parses SKILL.md files + loads metadata
• skill_selector.py - Auto-selects skills based on descriptions
• llm_executor.py - Executes skills (mock executor; ready for real LLM)

Deployment Ready

• Dockerfile + docker-compose.yml - Local containerized development (now includes agent-lightning integration)
• deploy.sh - Automated Raspberry Pi deployment
• setup-cloudflare.sh - One-click HTTPS tunnel setup
• Makefile - Convenient commands (make up, make logs, make test)
• manage-services.sh - Script to easily manage both skills-server and agent-lightning services

📚 Full Documentation

| For | Read This | Time | |-----|-----------|------| | Setup (step-by-step) | QUICKSTART.md | 10 min | | Agent workflows (system brain) | AGENTS.md | 20 min | | Claude integration | CLAUDE.md | 10 min | | MCP client config (Windsurf/Jan) | MCP-SETUP-GUIDE.md | 15 min | | Troubleshooting | DIAGNOSIS-SUMMARY.md | 10 min | | Performance tuning | TIMEOUT_FIX.md | 10 min | | Agent-Lightning integration | AGENT_LIGHTNING.md | 10 min | | Roadmap & strategy | PLAN.md | 15 min | | Task execution list | TODO.md | 5 min | | All docs (index) | docs/INDEX.md | 5 min |

🏗️ Architecture

┌─────────────────────────────┐
│  MCP Client (Windsurf, Jan) │
└──────────────┬──────────────┘
               │ JSON-RPC 2.0 (STDIO)
               ↓
┌──────────────────────────────────┐
│  MCP Server (mcp_server_optimized.py)
│  ├─ Initialize: < 100ms
│  ├─ Tools/List: Lazy-loads skills
│  └─ Tools/Call: Executes skill
└──────────────┬──────────────────┘
               │
               ↓
┌──────────────────────────────────┐
│  Skills Directory (auto-discovered)
│  ├─ changelog-newsletter/
│  ├─ demo-followup/
│  └─ playwright-automation/
└──────────────────────────────────┘
               │
               ↓
┌──────────────────────────────────┐
│  Agent-Lightning Service
│  ├─ Training AI agents with RL/APO
│  ├─ Running in Docker container
│  └─ Accessible via ports 6006, 7860, 8001, 8080
└──────────────────────────────────┘

Key Feature: Skills only load on first request (lazy-loading = fast startup ⚡). Agent-Lightning service runs alongside the MCP server for training AI agents.

📋 Use Cases

1. Marketing Automation

Engineer writes changelog → You ask Claude "Make a newsletter"
→ Claude calls changelog-newsletter skill → Newsletter generated in 5 seconds

2. Sales Follow-ups

Sales rep takes demo notes → You ask Claude "Turn into follow-up email"
→ Claude calls demo-followup skill → Personalized email ready

3. Browser Automation

You upload a PDF application form → Claude asks "Fill out the web form"
→ Claude calls playwright-automation skill → Form auto-filled from PDF data

4. Your Custom Workflows

Just create a new skills/your-skill/SKILL.md and restart—Claude auto-discovers it!

🛠️ Create Your Own Skill (5 minutes)

1. Create folder:

   mkdir -p skills/my-awesome-skill/templates

2. Create SKILL.md (metadata + instructions):

   ---
   name: my-awesome-skill
   description: Transform input X into output Y. Use for [your use case].
   allowed-tools: Read, Write  # Optional: restrict Claude's tool access
   ---
   
   # My Awesome Skill
   
   ## When to Use This
   - When you need to [task]
   - For [use case]
   
   ## Instructions
   1. Step one
   2. Step two
   3. Return result
   
    ## Examples
    Input: "..."
    Output: "..."

🔎 Skill Houser Pattern (Index + Search + Selective Injection)

• Default discovery is search-first via skills_search (metadata only).
• Full catalog listing is still available via skills_list, but is now explicit.
• skill and orchestration flows load full skill bodies/resources only for selected matches.

3. Add templates (optional):

   echo "Output template here" > skills/my-awesome-skill/templates/output.txt

4. Add scripts (optional, if you need Python helpers):

   echo "import sys; print('Hello')" > skills/my-awesome-skill/scripts/helper.py

5. Restart server (skills auto-discovered):

   docker-compose restart  # or: Ctrl+C + python mcp_server_optimized.py

6. Done! Claude now sees your skill and auto-activates it when relevant.

🚢 Deployment Options

Local Development

make dev
# Open: http://localhost:8000/docs (interactive API)

Docker (Recommended)

docker-compose up -d
docker-compose logs -f  # View logs

Docker with Agent-Lightning

# Start both services (skills-server and agent-lightning)
docker-compose up -d

# View logs for both services
docker-compose logs -f

# Enter the agent-lightning container shell
docker exec -it agent-lightning-cpu /bin/bash

# Stop all services
docker-compose down

You can also use the provided scripts for easier management:

1. manage-services.sh - For day-to-day management of services
2. test-services.sh - To verify that both services work together

# Make the scripts executable (on Linux/WSL)
chmod +x manage-services.sh test-services.sh

# Start both services
./manage-services.sh start

# Enter the agent-lightning container
./manage-services.sh enter

# View status
./manage-services.sh status

# Test both services
./test-services.sh

Raspberry Pi (One Command)

chmod +x deploy.sh
sudo ./deploy.sh
# Automated: setup, dependencies, Docker, systemd service

Public HTTPS (Cloudflare Tunnel)

chmod +x setup-cloudflare.sh
sudo ./setup-cloudflare.sh
# Provides: https://your-domain.com/skills (auto-renewed, no port forwarding)

🔗 API Endpoints (REST Mode)

If using REST API instead of MCP (optional):

| Endpoint | Method | Purpose | |----------|--------|---------| | /health | GET | Health check | | /skills | GET | List all skills | | /skill/{name} | GET | Get skill details | | /run_skill | POST | Run a skill (auto-select or explicit) | | /suggest | GET | Get skill suggestions for query | | /docs | GET | Interactive Swagger UI |

Example:

curl -H "x-api-key: YOUR_KEY" http://localhost:8000/health

🔐 Security

✅ API Key Authentication - All endpoints (REST mode) require x-api-key header ✅ HTTPS Support - Cloudflare tunnel or your own HTTPS proxy ✅ Tool Restrictions - Skills can declare allowed-tools to limit access ✅ Local Execution - Everything runs on your server; no data sent to cloud ✅ Environment Variables - Sensitive data in .env (never committed to git)

Recommended: Change API_KEY in .env to a long random string.

🐛 Troubleshooting

Skills Not Showing in Windsurf?

1. Verify MCP config: Check MCP-SETUP-GUIDE.md for Windsurf setup
2. Test server: Run python diagnose.py → should show "ALL CHECKS PASSED"
3. Restart Windsurf: Close completely, restart

See: DIAGNOSIS-SUMMARY.md

"Request Timed Out" Error?

1. Use optimized server: mcp_server_optimized.py (not mcp_server.py)
2. Check logs: docker-compose logs skills-server
3. Details: TIMEOUT_FIX.md

Server Won't Start?

# Check Python version
python --version  # Should be 3.11+

# Check dependencies
pip install -r requirements.txt

# Test server directly
python mcp_server_optimized.py
# Should start and wait for input (Ctrl+C to stop)

🎯 Key Features

✨ Auto-Discovery: Add a skill → Claude automatically finds it ⚡ Fast Startup: < 100ms (lazy-loads skills on demand) 🔄 Multi-LLM: Works with Claude, Grok, GPT, local Llama (no rewrites) 🏠 Self-Hosted: Run anywhere: laptop, Raspberry Pi, cloud 📦 Zero Boilerplate: Just SKILL.md; no API scaffolding needed 🔐 Secure: API keys, HTTPS, optional tool restrictions 📖 Well-Documented: Setup, architecture, troubleshooting guides

🚀 Next Steps

New Users

1. Read QUICKSTART.md (setup guide)
2. Run docker-compose up -d to start server
3. Configure your MCP client (see MCP-SETUP-GUIDE.md)
4. Ask Claude to use a skill!

Developers

1. Read AGENTS.md (system architecture)
2. Check PLAN.md (roadmap + next steps)
3. See TODO.md (task list)

Integrators

1. See CLAUDE.md for Claude integration best practices
2. Check docs/INDEX.md for full documentation map

🤝 Contributing

Found a bug? Have a skill idea?

1. Check DIAGNOSIS-SUMMARY.md for troubleshooting
2. Review AGENTS.md for system details
3. Create a GitHub issue with:
   • What you expected vs. what happened
   • Steps to reproduce
   • Logs (from docker-compose logs or stderr)

📄 License

MIT License. See LICENSE file.

📞 Support & Resources

• Setup: QUICKSTART.md
• Architecture: AGENTS.md
• Troubleshooting: DIAGNOSIS-SUMMARY.md
• Roadmap: PLAN.md
• Full Docs: docs/INDEX.md

Built with FastAPI, Docker, MCP, and ❤️ for the AI era.

Questions? See the docs above or check out the test scripts: test_api.py, diagnose.py, test_mcp_stdio.py.