# SkillsWebMcp

**A production WebMCP & Model Context Protocol bridge for developer agent skills.**

SkillsWebMcp indexes thousands of open-source `SKILL.md` instruction files from curated GitHub repositories and exposes them to AI agents through two standards at once:

- **WebMCP** — the in-browser tool-calling API (`document.modelContext`) for browser agents and extensions.
- **Model Context Protocol (MCP)** — a JSON-RPC 2.0 server for desktop clients and IDEs (Claude Desktop, Cursor, Windsurf, VS Code Copilot, Gemini CLI).

Skills are markdown instruction files. An agent discovers them via search, loads the full `SKILL.md`, and follows the instructions itself — the server never executes skill code.

---

## Highlights

- **~5,000 curated skills** from 22 license-verified repositories (Anthropic, VoltAgent, Composio, Mindrally, omer-metin, RobLe3, and more), covering 3D/graphics, security, cloud, databases, Git, and full-stack specializations.
- **Spec-compliant WebMCP** — `document.modelContext.registerTool / getTools / executeTool`, `toolchange` events, abort-to-unregister, and declarative `<form toolname>` tools.
- **Security pipeline** — every ingested `SKILL.md` passes an 8-category prompt-injection audit; flagged files are quarantined and never served. Repos must pass an open-source license allowlist.
- **Incremental sync + permanent store** — raw `SKILL.md` files are persisted on disk keyed by GitHub blob SHA; syncs re-download only changed files.
- **Instant serverless cold starts** — a gzip catalog snapshot hydrates ~5,000 skills in milliseconds on Vercel instead of re-scraping GitHub.
- **Progressive disclosure** — agents load a lightweight meta-tool and mount skills on demand, saving context tokens.

---

## Architecture

```text
┌──────────────────────────────────────────────────────────────────┐
│                        AI Clients & Agents                        │
│  Claude Desktop · Cursor · Windsurf · VS Code Copilot · Browser   │
└───────────────┬──────────────────────────────────┬───────────────┘
                │ MCP (JSON-RPC 2.0 / SSE)         │ WebMCP (document.modelContext)
                ▼                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│                      SkillsWebMcp Bridge Server                   │
│                                                                   │
│   MCP Server Engine          WebMCP Engine                        │
│   (JSON-RPC 2.0 / SSE)       (spec polyfill + HTTP invoke)        │
│                                                                   │
│   Security Auditor ──► Skills Registry ──► Search Index           │
│   (prompt-injection)     (upsert/prune)    (typo-tolerant)        │
│                                                                   │
│   Background Sync Engine ──► GitHub Scraper ──► Content Store     │
│   (24h schedule)             (SHA-incremental)  (.skill-store/)   │
└──────────────────────────────────────────────────────────────────┘
```

---

## Quick Start

### Prerequisites

- Node.js `>= 18`
- npm `>= 9`

### Install & run

```bash
git clone https://github.com/AbinashBalaraman/skills-webmcp.git
cd skills-webmcp
npm install

cp .env.example .env   # optional but recommended

npm run dev            # Express + Vite with hot reload
```

Open <http://localhost:3000>.

### Environment variables

| Variable | Description | Default |
| :--- | :--- | :--- |
| `PORT` | Server port | `3000` |
| `NODE_ENV` | `development` or `production` | `development` |
| `APP_URL` | Optional public URL override for generated links | auto-detected |
| `GITHUB_TOKEN` | Optional GitHub token — avoids API rate limits while scraping | none |

> On first run the server scrapes all configured repositories and builds the on-disk content store. Subsequent starts hydrate instantly from the cache.

---

## Using it as an MCP server

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "skills-webmcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote-client", "http://localhost:3000/api/mcp/sse"]
    }
  }
}
```

### Cursor / Windsurf

In **Settings → MCP Servers → Add**:

- **Name:** `skills-webmcp`
- **Type:** `sse`
- **URL:** `http://localhost:3000/api/mcp/sse`

Pre-generated snippets for every supported client are available at `GET /api/mcp/configs`.

### Core MCP tools

| Tool | Purpose |
| :--- | :--- |
| `search_agent_skills` | Search the catalog by keyword, category, or topic |
| `get_skill_manual` | Load the full `SKILL.md` for a skill to follow its instructions |
| `list_active_skills` | List connected repositories and pinned tools |

---

## Using it via WebMCP (in-browser)

Embed the polyfill, then use the standard API:

```html
<script src="http://localhost:3000/api/webmcp/script"></script>
```

```javascript
// Discover tools
const tools = await document.modelContext.getTools();

// Run one
const search = tools.find(t => t.name === 'search_skills');
const result = await document.modelContext.executeTool(search, { keyword: 'three.js' });
```

`navigator.modelContext` and `callTool(name, args)` are kept as back-compat aliases. The self-discovery spec for LLMs lives at `GET /api/webmcp/intro`.

---

## Security

Every `SKILL.md` that enters the catalog is screened before it can be served to a model:

1. **License allowlist** — repositories must use an approved open-source license (MIT, Apache-2.0, BSD, MPL-2.0, ISC, Unlicense).
2. **Prompt-injection audit** — 8 pattern categories (instruction override, system-prompt leak, data exfiltration, dangerous commands, hidden content, social engineering, credential harvest, network beacon).
3. **Quarantine** — flagged files are stored with a quarantine marker and excluded from search and `get_skill_manual`.

The auditor is implemented in `server/skill-security-auditor.ts` (with a standalone PowerShell twin at `scripts/audit-skills.ps1`).

---

## Deployment

### Render

The `render` branch ships a `render.yaml` blueprint. The public catalog is curated there — the "Connect GitHub Repo" button and the ingestion endpoint are disabled so visitors cannot add arbitrary repositories.

- **Build:** `npm install && npm run build`
- **Start:** `npm run start`

### Vercel

The `vercel` branch packages the server as a serverless function:

- `server.ts` exports `createApp()` and only listens when not on Vercel.
- `api/index.js` re-exports the bundled Express app.
- `vercel.json` rewrites `/api/*`, `/llms.txt`, `/robots.txt`, `/webmcp.json`, and `/.well-known/*` to the handler.
- A gzip **catalog snapshot** (`data/skills-snapshot.json.gz`) hydrates the registry on cold starts, so the demo responds instantly without scraping GitHub.

Regenerate the snapshot after the catalog changes:

```bash
npm run snapshot
```

---

## API Reference

| Method | Endpoint | Description |
| :--- | :--- | :--- |
| `GET` | `/api/health` | Health check |
| `GET` | `/api/mcp` | MCP server discovery info |
| `POST` | `/api/mcp` | MCP JSON-RPC 2.0 handler |
| `GET` | `/api/mcp/sse` | MCP Server-Sent Events stream |
| `GET` | `/api/mcp/tools` | List MCP tools |
| `GET` | `/api/mcp/configs` | Client config snippets |
| `GET` | `/api/skills` | List/search skills (paginated) |
| `GET` | `/api/skills/repositories` | Connected repositories |
| `GET` | `/api/skills/categories` | Category breakdown |
| `POST` | `/api/skills/toggle-pin` | Pin/unpin a skill as a direct tool |
| `POST` | `/api/skills/execute` | Execute a pinned tool action |
| `POST` | `/api/skills/fetch-repo` | Connect a repository (disabled on public deploys) |
| `GET` | `/api/sync-engine/status` | Background sync health & logs |
| `GET` | `/api/webmcp/intro` | WebMCP self-discovery spec for LLMs |
| `GET` | `/api/webmcp/tools` | WebMCP tool list |
| `GET` | `/api/webmcp/script` | WebMCP client polyfill |
| `POST` | `/api/webmcp/invoke` | WebMCP tool execution |
| `GET` | `/llms.txt` | LLM-friendly usage guide |

---

## Project Structure

```text
server.ts                     Express app + all HTTP routes (createApp export)
server/
  skills-registry.ts          Skill catalog, search, MCP tool dispatch
  github-scraper.ts           License audit + SHA-incremental scraping
  background-sync-engine.ts   24h sync scheduler + cache/snapshot hydration
  skill-content-store.ts      Permanent on-disk SKILL.md store (.skill-store/)
  skill-security-auditor.ts   Prompt-injection screening
  webmcp-engine.ts            WebMCP polyfill + intro spec
  mcp-server.ts               MCP JSON-RPC engine
src/                          React 19 dashboard (Vite + Tailwind)
scripts/
  generate-snapshot.mjs       Build the serverless catalog snapshot
  audit-skills.ps1            Standalone security auditor
data/
  skills-snapshot.json.gz     Bundled catalog snapshot for cold starts
```

---

## License

[MIT](LICENSE) © Abinash Balaraman