Initial commit: Add NanoClaw MCP extension with README and secure tests

2026-04-24 22:11:23 +02:00
commit 7fa0201a6b
7 changed files with 5051 additions and 0 deletions
@@ -0,0 +1,43 @@
+# 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.
+
+## 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:
+
+* `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`.
+
+## Usage & Example
+
+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:
+
+```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.
+
+## Connecting via SSH Tunnel
+
+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. 
+
+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
+```
+
+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.