gurixs_carsonandClaude Opus 4.6
3fa0ec8f71
Adds the complete server-side MCP implementation as a NanoClaw feature skill (nanoclaw-skill/). Includes source code, modification intents, and step-by-step SKILL.md for installation. README updated to cover both server (NanoClaw) and client (pi.dev) setup. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
159 lines
4.4 KiB
Markdown
159 lines
4.4 KiB
Markdown
# 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 |
|