nanoclaw-mcp-ext/README.md

# NanoClaw MCP Extension

External agent access for [NanoClaw](https://github.com/qwibitai/nanoclaw) via the [Model Context Protocol](https://modelcontextprotocol.io/). Contains both the **server-side skill** (for NanoClaw) and a **client extension** (for pi.dev).

## How it works

```
External Agent ──SSH tunnel──▶ localhost:3002/mcp
                                     │
                               Bearer token auth
                                     │
                              MCP Channel (mcp:*)
                                     │
                              ┌──────┴──────┐
                              │  GroupQueue  │
                              └──────┬──────┘
                                     │
                         Container Agent (same image,
                         workspace, tools as Telegram)
```

An MCP server registers as a NanoClaw channel. External agents connect via Streamable HTTP, send messages through the `chat` tool, and receive the assistant's response. Messages use an isolated `mcp:*` JID namespace — other channels (Telegram, WhatsApp) see nothing.

## Repository Structure

```
├── nanoclaw-skill/          # Server-side: NanoClaw skill
│   ├── SKILL.md             # Installation instructions
│   ├── src/mcp-server.ts    # MCP server + channel implementation
│   └── modify/              # Intent files for existing file modifications
├── index.ts                 # Client-side: pi.dev extension
├── mcp_test.mjs             # Test scripts
└── README.md
```

---

## Server Setup (NanoClaw)

### Option A: Using the NanoClaw skill

If you have Claude Code available:

```
/add-mcp
```

Or manually follow the instructions in [`nanoclaw-skill/SKILL.md`](nanoclaw-skill/SKILL.md).

### Option B: Manual installation

1. Install dependencies:
   ```bash
   npm install @modelcontextprotocol/sdk zod
   ```

2. Copy `nanoclaw-skill/src/mcp-server.ts` to `src/mcp-server.ts`

3. Add `import '../mcp-server.js';` to `src/channels/index.ts`

4. Add `MCP_API_KEY` and `MCP_PORT` to `src/config.ts` (see SKILL.md for details)

5. Add MCP server startup to `src/index.ts` (see SKILL.md for details)

6. Configure `.env`:
   ```
   MCP_API_KEY=<generate with: openssl rand -base64 32>
   MCP_PORT=3002
   ```

7. Build and restart:
   ```bash
   npm run build
   sudo systemctl restart nanoclaw
   ```

### Security

The MCP server binds to `127.0.0.1` only. Clients connect via SSH tunnel:

```bash
ssh -L 3002:localhost:3002 user@your-server -N
```

---

## Client Setup (pi.dev)

### Configuration

Set environment variables:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NANOCLAW_MCP_TOKEN` | yes | — | Bearer token (= `MCP_API_KEY` from server) |
| `NANOCLAW_MCP_URL` | no | `http://localhost:3002/mcp` | MCP server URL |

### Usage

1. Place the extension in your Pi extensions folder
2. Start the SSH tunnel (if server is remote)
3. Start Pi:

```bash
export NANOCLAW_MCP_TOKEN="your-secret-token"
pi
```

Pi will auto-discover and register the available tools (`chat`, `list_groups`).

### Generic MCP Client

Any MCP client can connect. Example configuration:

```json
{
  "mcpServers": {
    "nanoclaw": {
      "type": "streamable-http",
      "url": "http://localhost:3002/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_API_KEY>"
      }
    }
  }
}
```

---

## Available MCP Tools

### `chat`

Send a message to the assistant and receive a response.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message` | string | yes | The message to send |
| `group` | string | no | Target group (default: main) |

**Response time:** ~2-3 min cold start, ~5-10s warm (container reuse within idle timeout).

### `list_groups`

Lists available groups. No parameters.

---

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Connection refused | SSH tunnel not running | Start tunnel: `ssh -L 3002:localhost:3002 ...` |
| 401 Unauthorized | Token mismatch | Check `MCP_API_KEY` in `.env` matches client token |
| Slow first response | Cold start | Expected (~2-3 min). Subsequent calls are fast. |
| `(no response)` | Container timeout | Check `docker logs <container>` for errors |
| MCP server not starting | Missing config | Verify `MCP_API_KEY` in `.env`, rebuild, restart |