feat: add NanoClaw server-side skill and update docs
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>
This commit is contained in:
gurixs_carson
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
7fa0201a6b
commit
3fa0ec8f71
@@ -1,43 +1,158 @@
|
||||
# NanoClaw MCP Extension
|
||||
|
||||
## Overview
|
||||
This is an extension for the Pi Coding Agent (`@mariozechner/pi-coding-agent`) that integrates tools from a NanoClaw Model Context Protocol (MCP) server. It allows the Pi agent to dynamically fetch and execute tools exposed by a remote or local NanoClaw server.
|
||||
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
|
||||
When a new Pi session starts, the extension connects to the NanoClaw MCP server via a `StreamableHTTPClientTransport`. It authenticates using a Bearer token, queries the available tools (`listTools`), and automatically registers them within the Pi environment so the AI can use them.
|
||||
|
||||
## Configuration
|
||||
The extension is configured using the following environment variables:
|
||||
```
|
||||
External Agent ──SSH tunnel──▶ localhost:3002/mcp
|
||||
│
|
||||
Bearer token auth
|
||||
│
|
||||
MCP Channel (mcp:*)
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ GroupQueue │
|
||||
└──────┬──────┘
|
||||
│
|
||||
Container Agent (same image,
|
||||
workspace, tools as Telegram)
|
||||
```
|
||||
|
||||
* `NANOCLAW_MCP_TOKEN` **(Required)**: The authentication token for the MCP server. If missing, the extension will skip loading the tools.
|
||||
* `NANOCLAW_MCP_URL` **(Optional)**: The URL of the NanoClaw MCP server endpoint. Defaults to `http://localhost:3002/mcp`.
|
||||
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.
|
||||
|
||||
## Usage & Example
|
||||
## Repository Structure
|
||||
|
||||
1. Ensure the extension is placed in your Pi extensions folder (or configured in your workspace to be loaded).
|
||||
2. Set the necessary environment variables and start Pi:
|
||||
```
|
||||
├── 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"
|
||||
# Optional: export NANOCLAW_MCP_URL="http://localhost:3002/mcp"
|
||||
|
||||
pi
|
||||
```
|
||||
|
||||
3. When Pi starts, you will see a notification in the UI:
|
||||
`Connected to nanoclaw MCP server. Loaded X tools: tool_name, another_tool`
|
||||
4. You can now prompt the AI in the chat to use any of the dynamically loaded tools.
|
||||
Pi will auto-discover and register the available tools (`chat`, `list_groups`).
|
||||
|
||||
## Connecting via SSH Tunnel
|
||||
### Generic MCP Client
|
||||
|
||||
Often, the NanoClaw MCP server is running on a remote machine (e.g., a production server or a different development environment) and shouldn't be exposed directly to the public internet.
|
||||
Any MCP client can connect. Example configuration:
|
||||
|
||||
In this case, you can use an **SSH Tunnel** to securely forward the traffic.
|
||||
|
||||
**Example:**
|
||||
Forward remote port `3002` to your local port `3002`:
|
||||
```bash
|
||||
ssh -L 3002:localhost:3002 user@remote-nanoclaw-host
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"nanoclaw": {
|
||||
"type": "streamable-http",
|
||||
"url": "http://localhost:3002/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer <MCP_API_KEY>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Once the tunnel is active, you can simply run Pi locally without changing the `NANOCLAW_MCP_URL` (since it defaults to `http://localhost:3002/mcp`). The traffic will be securely routed through the SSH tunnel to the NanoClaw instance.
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
||||
Reference in New Issue
Block a user