mcp

Files (1)

• SKILL.md

SKILL.md (first lines)

# MCP — Plus plugin gateway companion skill

Multi-mode skill for the ClaudeClaw-Plus MCP bridge. Connects to Plus's HTTP gateway at `http://localhost:4632/api/plugin/*` and the audit log at `~/.config/plus/plugin-audit.jsonl`.

## Mode dispatch

Read user intent from the trigger / first message:

- `/mcp` (no arg) or first-time use → **setup**
- `/mcp list` or "what plugins are registered" → **list**
- `/mcp inspect <plugin>` or "tell me about <plugin>" → **inspect**
- `/mcp diagnose` or "are my plugins healthy" → **diagnose**
- `/mcp audit` or "show recent plugin events" → **audit**
- `/mcp trace <request_id>` or "find this request" → **trace**
- `/mcp register` or "add a new plugin" → **register**
- `/mcp test <plugin> <tool>` or "test <plugin>'s <tool>" → **test**
- `/mcp report` or "this looks like an MCP bug" → **report**
- `/mcp proxy-status` or "show MCP server pool" → **proxy-status**
- `/mcp proxy-restart <server>` or "restart <server> MCP server" → **proxy-restart**

If unclear, ask.

---

## Mode: setup

Goal: prepare a new plugin install — print bootstrap token, walk through Plus config, suggest first plugin registration.

### Step 1 — Welcome

Tell the user in 3 sentences:
1. The MCP bridge lets daemon-style plugins (Python, Rust, etc.) register tools that Claude Code can call.
2. Each plugin needs a bootstrap token (one-time) and a per-plugin secret (auto-generated at register).
3. The bridge runs HTTP endpoints under `/api/plugin/*` and an MCP server at `bun run src/plugins/mcp-server.ts`.

### Step 2 — Print bootstrap token

```bash
bun run src/plugins/cli.ts print-bootstrap-token
```

If file doesn't exist (first run), Plus auto-creates it at `~/.config/plus/plugin-bootstrap.secret` (0600, 32 bytes). Display the token to the user. Tell them:

> Save this token — your plugin install scripts need it for the `register` call. You can re-print it any time with the same command.

### Step 3 — Verify Plus is running

```bash
curl -s -H "Authorization: Bearer $(bun run src/plugins/cli.ts print-bootstrap-token)" http://localhost:4632/api/plugin/list
```

A `200` (JSON plugin list) means Plus is up. A `401` also means it's UP — just a
bootstrap-token mismatch (re-print the token). Only `404` / connection refused
means the daemon isn't running with the `--web` flag. Suggest restart:
```bash
systemctl --user restart claudeclaw.service
```

If returns `{"plugins": []}` → bridge is up, no plugins yet.

### Step 4 — Suggest next steps

> Ready to register your first plugin?
>   1. Generate a Python plugin template (`/mcp register`)
>   2. Manual: see `docs/plugin-integration.md` for examples (voice-driven agents, retrieval daemons)
>   3. Skip (already have a plugin scripted)

### Step 5 — Detect mcp-proxy config

```bash
test -f ~/.config/claudeclaw/mcp-proxy.json && echo "exists" || echo "missing"
```

If exists:
> An mcp-proxy config exists. Run `/mcp proxy-status` to see pooled servers and their health.

If missing:
> No mcp-proxy config detected. Copy `mcp-proxy.json.example` to `~/.config/claudeclaw/mcp-proxy.json` and configure your MCP servers to enable warm-pool routing (~200ms direct calls vs ~3000ms inject path).

### Step 5b — Auth contract reference

For the canonical authentication contract (header names, HMAC signing scope, ISO 8601 timestamp format, replay window semantics), point the user to:

👉 [`docs/plugin-integration.md`](https://github.com/TerrysPOV/ClaudeClaw-Plus/blob/main/docs/plugin-integration.md#authentication-contract)

This is the source of truth — do not paraphrase the headers (`x-plus-ts` / `x-plus-signature`) or scope (`<ts>\n<body>`) from memory; a single character mismatch returns 401 `invalid_signature`.

End setup.

---

## Mode: list

Goal: show all registered plugins with their health status.

### Step 1 — Fetch list

```bash
curl -s -H "Authorization: Bearer $(bun run src/plugins/cli.ts print-bootstrap-token)" http://localhost:4632/api/plugin/list
```

### Step 2 — Render table

```
Registered plugins:

| Plugin       | Version | Tools                          | Health | Registered |
|--------------|---------|--------------------------------|--------|------------|
| daemon-A | 0.1.0   | pending, apply, refuse         | ✅ ok  | 2h ago     |
| voice-agent   | 1.0.0   | send_tts, transcribe_audio     | ⚠️ deg | 2d ago     |
| retrieval-daemon   | 2.1.0   | search_docs, index_doc         | ❌ down| 5d ago     |
```

For health:
- ✅ ok — last_health_check.healthy = true within last 5 min
- ⚠️ degraded — healthy but slow (>1s response) or stale check (>10 min)
- ❌ down — last_health_check.healthy = false or no manifest health_url
- ❓ unknown — no health_url declared

From TerrysPOV/ClaudeClaw-Plus, MIT.

More from TerrysPOV/ClaudeClaw-Plus