# SkillsWebMcp — WebMCP & MCP Bridge for Developer Skills

> Production WebMCP (W3C Draft) & Model Context Protocol server for GitHub-scraped SKILL.md instruction files. Skills are markdown files (like unlazy SKILL.md) — you load them and follow their instructions yourself. No server execution.

## For LLMs: How to Use This Site (No Browser Needed)

You do NOT need to launch a browser, take screenshots, or do DOM scraping. Use plain HTTP POST to discover and load SKILL.md files.

### Professional Decomposition (Required — Read First)

Act as a professional: before searching, decompose your task into required skill domains and search each domain separately. Do NOT search the literal task phrase if it is too specific — it will return 0 results.

- Example: "beautiful waterfall animation" → domains: animation, 3d, canvas, shader, gsap, motion design, ui. Search: "animation", "3d", "canvas-design", "shader", "gsap" (2-3 domains is enough), then combine results and pick 1-2 best skills.
- Available domains: animation, ui, 3d, three.js, webgl, shader, gsap, canvas, particle, motion, design, frontend, tailwind, lottie, scroll
- If a search returns 0, broaden to domain terms and combine. GET fallback needs no JSON: GET `https://swmcp.vercel.app/api/skills?search=<domain>&limit=5`

### Option A: WebMCP HTTP (Simplest — Recommended for ChatGPT, Gemini, Claude Web)

**Discovery:** GET `https://swmcp.vercel.app/api/webmcp/intro` — returns full spec with all endpoints.
**Tools list:** GET `https://swmcp.vercel.app/api/webmcp/tools` — returns available WebMCP tools (search_skills, get_skill_manual).
**Search:** POST `https://swmcp.vercel.app/api/webmcp/invoke` `{"name":"search_skills","args":{"keyword":"<domain>"}}` — search a domain, repeat for 2-3 domains
**Load SKILL.md:** POST `https://swmcp.vercel.app/api/webmcp/invoke` `{"name":"get_skill_manual","args":{"skillIdOrName":"<skill-id>"}}` — returns the full SKILL.md markdown. Read it and follow its instructions yourself.

**Workflow:**
0. Decompose: break task into domains (e.g., waterfall → animation + 3d + canvas + shader)
1. Search: `POST https://swmcp.vercel.app/api/webmcp/invoke` `{"name":"search_skills","args":{"keyword":"animation"}}` (repeat for 2-3 domains)
2. Load SKILL.md: `POST https://swmcp.vercel.app/api/webmcp/invoke` `{"name":"get_skill_manual","args":{"skillIdOrName":"<id-from-search>"}}` — returns SKILL.md markdown
3. Follow the SKILL.md instructions yourself (e.g., write GATES.md, run checks, etc.) — do NOT try to execute it as a server tool.

**Curl examples (use curl.exe on Windows):**
```bash
curl.exe -X POST https://swmcp.vercel.app/api/webmcp/invoke -H "Content-Type: application/json" -d '{"name":"search_skills","args":{"keyword":"animation"}}'
curl.exe -X POST https://swmcp.vercel.app/api/webmcp/invoke -H "Content-Type: application/json" -d '{"name":"get_skill_manual","args":{"skillIdOrName":"<skill-id>"}}'
```
**PowerShell:**
```powershell
Invoke-RestMethod -Uri "https://swmcp.vercel.app/api/webmcp/invoke" -Method Post -ContentType "application/json" -Body '{"name":"search_skills","args":{"keyword":"animation","limit":5}}'
Invoke-RestMethod -Uri "https://swmcp.vercel.app/api/webmcp/invoke" -Method Post -ContentType "application/json" -Body '{"name":"get_skill_manual","args":{"skillIdOrName":"<id>"}}'
# GET fallback (no JSON needed):
Invoke-RestMethod -Uri "https://swmcp.vercel.app/api/skills?search=animation&limit=5"
```

### Option B: MCP JSON-RPC 2.0 (For Claude Desktop, Cursor, Windsurf, VS Code Copilot)

**Endpoint:** POST `https://swmcp.vercel.app/api/mcp` with `Content-Type: application/json`
**SSE:** GET `https://swmcp.vercel.app/api/mcp/sse` then POST to `https://swmcp.vercel.app/api/mcp`
**Resources (native SKILL.md loading):** `resources/list` and `resources/read` return SKILL.md files as text/markdown.

```bash
# List tools (3 meta tools: search_agent_skills, get_skill_manual, list_active_skills)
curl.exe -X POST https://swmcp.vercel.app/api/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# Search via MCP
curl.exe -X POST https://swmcp.vercel.app/api/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_agent_skills","arguments":{"query":"unlazy"}}}'
# Load SKILL.md via MCP
curl.exe -X POST https://swmcp.vercel.app/api/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_skill_manual","arguments":{"skillIdOrName":"<skill-id>"}}}'
# Or via resources (native MCP)
curl.exe -X POST https://swmcp.vercel.app/api/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":4,"method":"resources/list"}'
curl.exe -X POST https://swmcp.vercel.app/api/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":"skill://<repoId>/<skillId>"}}'
```

**MCP Config for Claude Desktop / Cursor:** GET `https://swmcp.vercel.app/api/mcp/configs` — copy-paste JSON for your client.

### Option C: In-Browser WebMCP (Only if you ARE running in a browser)

Embed `<script src="https://swmcp.vercel.app/api/webmcp/script"></script>` then use the WebMCP API: `const tools = await document.modelContext.getTools();` and `await document.modelContext.executeTool(tools.find(t => t.name === "search_skills"), {keyword: "unlazy"})` then `executeTool(tools.find(t => t.name === "get_skill_manual"), {skillIdOrName: "<id>"})`. (`navigator.modelContext` and `callTool(name, args)` are kept as aliases.)

## Endpoints Summary

- Intro & Spec: `https://swmcp.vercel.app/api/webmcp/intro` (also `https://swmcp.vercel.app/webmcp.json`, `https://swmcp.vercel.app/.well-known/mcp`)
- WebMCP Tools: `https://swmcp.vercel.app/api/webmcp/tools`
- WebMCP Invoke: `https://swmcp.vercel.app/api/webmcp/invoke` (POST) — search_skills, get_skill_manual
- MCP JSON-RPC: `https://swmcp.vercel.app/api/mcp` (POST), SSE `https://swmcp.vercel.app/api/mcp/sse`
- MCP Resources: `resources/list` and `resources/read` for SKILL.md files
- MCP Configs: `https://swmcp.vercel.app/api/mcp/configs`
- Skills: `https://swmcp.vercel.app/api/skills?search=unlazy&category=all&page=1&limit=24`
- Repositories: `https://swmcp.vercel.app/api/skills/repositories`

## Available Skills

GitHub-scraped SKILL.md files from connected repositories. Search via search_skills to discover them. Each skill is a markdown instruction file — load it with get_skill_manual and follow its instructions yourself.

## Notes for LLMs

- Always use `curl.exe` on Windows (not `curl` alias) and wrap JSON in single quotes: `-d '{"name":"search_skills","args":{"keyword":"unlazy"}}'`
- All POST endpoints return JSON (never HTML). If you get HTML, you hit the wrong URL — use the endpoints above.
- Skills are SKILL.md instruction files, not executable server tools. After loading a SKILL.md, follow its instructions yourself.
- For unknown tools, you get `{"success":false,"error":"Tool not found"}` — then search again with search_skills.