mothpost 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filippo Cavallarin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,327 @@
-# Temporary Holding Version
+# mothpost
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Secure remote MCP access without VPNs, public endpoints, or complex networking setups.**
+
+`mothpost` is an experimental bridge that lets AI agents discover and invoke tools exposed by MCP servers on other networks, without exposing those servers to the internet.
+
+It provides:
+
+- **Cross-network connectivity** — Reach MCP servers on private networks without a VPN or inbound ports.
+- **Per-agent, per-tool permissions** — Grant or revoke individual tools without changing the MCP server's configuration or its own authorization rules.
+- **End-to-end encryption** — Tool calls and responses travel encrypted between endpoints, including when routed through a third-party relay.
+- **Resilient delivery** — Calls are queued while a remote endpoint is briefly disconnected and executed when it reconnects, as long as the agent is still waiting for the result.
+
+Calls that reach the server after the agent has stopped waiting are dropped instead of executed late, so a tool never runs after the agent gave up on it, or twice when the agent retries (see [Request Expiry](#request-expiry)). Executing calls after the agent's timeout, with the result retrieved later, is planned; see [Future Work](#future-work).
+
+Under the hood, `mothpost` uses [SEPT](https://github.com/fcavallarin/sept), an open-source encrypted event protocol that handles transport, device identities, access control, and offline delivery.
+
+## Current Scope
+
+The prototype currently supports:
+
+- MCP initialization
+- Tool discovery
+- Tool calls
+- Per-tool grant/revoke
+- One or more agents connected to the same MCP server, each through its own connection (see [Multiple Agents](#multiple-agents))
+
+MCP prompts, resources, and notifications are intentionally out of scope for the first demo.
+
+## Example
+
+A newly connected client has no tools available by default. An administrator can grant access to one tool:
+
+```bash
+node src/cli.js admin grant-tool my-connection get_door_state
+```
+
+The client can then discover and invoke `get_door_state`. Revoking the permission prevents subsequent invocations, even if the agent still has the tool in a cached tool list.
+
+## Quick Start
+
+Connect an AI agent to an MCP server on another network and manage exactly which tools it can use.
+
+There are three components:
+
+- **Server** — Runs alongside an existing MCP server and makes its tools reachable remotely.
+- **Client** — Presents authorized remote tools to an AI agent through a local MCP endpoint.
+- **Admin** — Pairs the endpoints and manages tool permissions.
+
+These components can run on separate networks. No VPN or publicly exposed MCP endpoint is required.
+
+### 1. Installation
+
+On each machine running `mothpost`:
+
+```bash
+git clone https://github.com/fcavallarin/mothpost.git
+cd mothpost
+npm install
+```
+
+Each component reads `config.json` from its working directory. [`config.example.json`](config.example.json) lists every option; copy it and keep only the section for the component you run (`server`, `client`, or none for the Admin). `config.json` is git-ignored.
+
+### 2. Configure the server
+
+On the machine hosting your MCP server, create `config.json`:
+
+```json
+{
+  "server": {
+    "id": "my-server",
+    "transport": "streamable-http",
+    "url": "http://localhost:8931/mcp"
+  }
+}
+```
+
+Replace the URL with your MCP server's local endpoint and ensure that it is running.
+
+Start the bridge:
+
+```bash
+node src/cli.js server
+```
+
+On its first run, it displays Base64-encoded pairing data and prompts for a pairing PIN. Leave the terminal running; pairing will be completed in step 4.
+
+### 3. Configure the client
+
+On the machine running your AI agent, create `config.json`:
+
+```json
+{
+  "client": {
+    "id": "my-agent",
+    "listenHost": "127.0.0.1",
+    "port": 8001
+  }
+}
+```
+
+Start the local MCP bridge:
+
+```bash
+node src/cli.js client
+```
+
+On first run, it also displays pairing data and asks for a PIN. Leave this terminal running.
+
+**Note:** The server, client, and Admin each need their own working directory and `config.json`. If you run all three on the same machine, use separate copies/directories to avoid conflicting configurations.
+
+### 4. Connect the client and server
+
+In a third terminal, connect them using the pairing data displayed by each endpoint:
+
+```bash
+node src/cli.js admin connect my-connection \
+  "<CLIENT_PAIRING_DATA>" \
+  --new-server "<SERVER_PAIRING_DATA>"
+```
+
+The Admin initializes the underlying private network if necessary and generates pairing PINs for both endpoints. Enter each PIN in the corresponding terminal.
+
+Once pairing completes, the endpoints have the permissions needed to exchange MCP requests and responses. **No MCP tools are granted by default.**
+
+### 5. Grant access to a tool
+
+Inspect the connection and its available tools:
+
+```bash
+node src/cli.js admin connection my-connection
+```
+
+Grant one tool:
+
+```bash
+node src/cli.js admin grant-tool my-connection get_door_state
+```
+
+Replace `get_door_state` with a tool exposed by your MCP server. To grant all available tools:
+
+```bash
+node src/cli.js admin grant-all my-connection
+```
+
+Tool permissions are enforced by the bridge's underlying access-control layer, independently of the MCP server's own authorization mechanisms.
+
+### 6. Connect your AI agent
+
+Configure your MCP-compatible agent to use this local Streamable HTTP endpoint:
+
+```text
+http://127.0.0.1:8001/mcp
+```
+
+The agent can discover and invoke only the tools permitted for its connection. Requests are encrypted and forwarded to the remote bridge, which invokes the local MCP server and returns its response.
+
+### 7. Revoke access
+
+Revoke access to one tool:
+
+```bash
+node src/cli.js admin revoke-tool my-connection get_door_state
+```
+
+Or revoke all tools:
+
+```bash
+node src/cli.js admin revoke-all my-connection
+```
+
+Inspect the connection again:
+
+```bash
+node src/cli.js admin connection my-connection
+```
+
+Revocation blocks subsequent calls even if the agent cached the old tool list.
+
+The server bridge also follows the MCP server: when it adds or removes tools (`notifications/tools/list_changed`), the new list is reported to the Admin without restarting the bridge, and if the MCP server restarts, the bridge reconnects on the next call.
+
+Agents don't need to be restarted after a grant or revoke: the client bridge sends a `notifications/tools/list_changed` notification, and agents that listen for it refresh their tool list automatically. This requires an agent using the 2026-07-28 MCP protocol revision; agents on older revisions see the updated list the next time they reconnect or run tool discovery.
+
+## Multiple Agents
+
+Each agent gets its own connection, with its own tool permissions. There are two ways to connect a second agent to the same MCP server.
+
+**Shared server bridge.** Start a new client for the agent (with its own `id` and `port`), find the server's device ID, and connect the client to the existing bridge:
+
+```bash
+node src/cli.js admin connection my-connection    # prints "Server: <SERVER_DEVICE_ID>"
+
+node src/cli.js admin connect my-second-agent \
+  "<CLIENT_PAIRING_DATA>" \
+  --existing-server <SERVER_DEVICE_ID>
+```
+
+Permissions stay separate: granting or revoking a tool on `my-second-agent` does not affect `my-connection`. However, the bridge talks to the MCP server through **a single MCP session shared by all its connections**. If the MCP server keeps per-session state (for example a browser in a Playwright MCP server, open files, or a logged-in account), the agents share that state.
+
+**Dedicated server bridge.** For isolation, start another server bridge for the new agent (with its own `id`, pointing to the same MCP server URL) and connect it with `--new-server`, as in [step 4](#4-connect-the-client-and-server). Each bridge opens its own MCP session. This is the recommended setup when agents must not see each other's state.
+
+## Request Expiry
+
+A tool call is executed only while the agent is still waiting for its result. Each request carries the client's timeout, and the server bridge checks the request's age, based on the sender's signed timestamp, before invoking the tool. Requests that are too old are logged and dropped, without executing the tool:
+
+```text
+[my-server] Dropping mcp.tools.call.get_door_state <requestId> from <device>: expired (age 42s, window 30s)
+```
+
+This prevents a call queued while the server was offline from running long after the agent has moved on, and a retried call from running twice.
+
+The window can be tuned in `config.json`:
+
+```json
+{
+  "client": {
+    "requestTimeoutMs": 30000
+  },
+  "server": {
+    "maxRequestAgeMs": 60000,
+    "clockSkewMs": 5000
+  }
+}
+```
+
+- `client.requestTimeoutMs` — How long the client waits for a response (default: 30000). It is also sent with each request as its validity window.
+- `server.maxRequestAgeMs` — Upper bound on the window a client may request (default: 60000).
+- `server.clockSkewMs` — Tolerated clock difference between endpoints (default: 5000). It is also used as a safety margin: a call is executed only if it is younger than the window minus this value, so that the response can still reach the agent in time. Requests with a timestamp further in the future than this value are rejected as well.
+
+Keep the endpoints' clocks synchronized (for example with NTP). A clock difference larger than `clockSkewMs` causes valid requests to be dropped.
+
+## How It Works
+
+```text
+AI Agent
+   |
+   | MCP (localhost)
+   v
+Remote MCP Client Bridge
+   |
+   | Encrypted relay transport
+   | Per-agent, per-tool permissions
+   v
+Remote MCP Server Bridge
+   |
+   | MCP (local)
+   v
+MCP Server
+```
+
+The relay forwards encrypted messages without access to tool-call contents. Each endpoint has its own cryptographic identity, and an administrator controls which tools each client can invoke. No inbound ports, VPN connections, or public MCP endpoints are required between client and server.
+
+## Remote Agent Interaction
+
+The same encrypted communication infrastructure can also connect users directly to AI agents, including from mobile apps. This makes it possible to chat with an agent running on a private network while the agent accesses MCP tools hosted elsewhere.
+
+```text
+Mobile App / User
+        |
+        | Encrypted chat / commands
+        v
+     AI Agent
+        |
+        | MCP (localhost)
+        v
+  MCP Client Bridge
+        |
+        | Encrypted remote access
+        | Per-tool permissions
+        v
+  MCP Server Bridge
+        |
+        | MCP (local)
+        v
+     MCP Server
+```
+
+The underlying protocol already supports secure user-to-agent messaging. **Chat integration is not currently a feature of `mothpost` itself.**
+
+## Security Notes
+
+- Permissions are enforced per **connection** (one client bridge ↔ one server bridge), both by the server bridge, which lists and executes only granted tools, and by SEPT's access control, which rejects calls to non-granted tools before they reach the server bridge.
+- The client bridge's local MCP endpoint has no authentication of its own: any process that can reach `listenHost:port` can use the tools granted to that connection. Keep it bound to `127.0.0.1` (the default), and give agents that must not share permissions separate client bridges.
+- The relay sees only encrypted payloads and routing metadata (which devices exchange events, and when).
+
+## Relay Configuration
+
+By default, `mothpost` uses a free public relay. You can also [self-host a relay](https://github.com/fcavallarin/sept/blob/main/docs/self-hosting.md).
+
+To use a different relay, add this field to the top-level object in each component's `config.json`:
+
+```json
+{
+  "sept": {
+    "restEndpoint": "https://YOUR-SEPT-RELAY"
+  }
+}
+```
+
+Merge this `sept` field into your existing server, client, or Admin configuration; don't replace the other fields.
+
+## Future Work
+
+### Asynchronous MCP Tool Execution
+
+The transport already supports persistent offline delivery: a call can reach a disconnected endpoint when it comes back online. But standard MCP tool calls use a request/response model, so the originating agent may time out before the call is executed and would never receive its eventual result. For this reason, the server bridge currently drops calls that arrive after the agent's timeout (see [Request Expiry](#request-expiry)).
+
+A future version could use the [MCP Tasks Extension](https://tasks.extensions.modelcontextprotocol.io/) to provide native asynchronous execution and result retrieval:
+
+1. An agent invokes a remote tool.
+2. The client bridge persists a task and immediately returns a task identifier.
+3. The request is queued for delivery even if the remote endpoint is offline.
+4. On reconnection, the server bridge invokes the existing MCP server.
+5. The result is delivered back and associated with the task.
+6. The agent retrieves the result with `tasks/get` or receives an optional `notifications/tasks` update.
+
+This requires persistent task state, request/result correlation, execution deduplication, expiration policies, and cancellation handling. **Existing MCP servers would not need to implement asynchronous execution**: the bridge could manage the task lifecycle while continuing to invoke ordinary MCP tools.
+
+This is planned work, **not a feature of the current prototype**.
+
+## Status
+
+`mothpost` is an experimental prototype/demo and is not yet published on npm.
+
+## Related
+
+- [SEPT](https://github.com/fcavallarin/sept) — underlying encrypted event transport and access-control protocol

package/config.example.json

@@ -0,0 +1,19 @@
+{
+  "sept": {
+    "restEndpoint": "https://sept.filippo-572.workers.dev",
+    "logLevel": "info"
+  },
+  "client": {
+    "id": "my-agent",
+    "listenHost": "127.0.0.1",
+    "port": 8001,
+    "requestTimeoutMs": 30000
+  },
+  "server": {
+    "id": "my-server",
+    "transport": "streamable-http",
+    "url": "http://localhost:8931/mcp",
+    "maxRequestAgeMs": 60000,
+    "clockSkewMs": 5000
+  }
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "mothpost",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bridge AI agents and MCP servers across networks, with per-tool permissions, over the SEPT encrypted relay",
+  "type": "module",
+  "license": "MIT",
+  "author": "Filippo Cavallarin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fcavallarin/mothpost.git"
+  },
+  "homepage": "https://github.com/fcavallarin/mothpost#readme",
+  "bugs": {
+    "url": "https://github.com/fcavallarin/mothpost/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "e2ee",
+    "relay",
+    "sept",
+    "authorization"
+  ],
+  "bin": {
+    "mothpost": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "config.example.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start:client": "node src/cli.js client",
+    "start:server": "node src/cli.js server",
+    "test": "cd tests && npm install && node test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.1.0",
+    "@modelcontextprotocol/express": "^2.0.1",
+    "@modelcontextprotocol/node": "^2.1.0",
+    "@modelcontextprotocol/server": "^2.1.0",
+    "@sept-protocol/client": "^0.1.2",
+    "better-sqlite3": "^13.0.3",
+    "commander": "^15.0.0",
+    "express": "^5.2.1",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/admin.js

@@ -0,0 +1,208 @@
+import pc from "picocolors"
+import { Option } from "commander";
+
+import { sleep } from "./common.js"
+import { BaseCommand } from "./base-command.js";
+
+export class MothpostAdmin extends BaseCommand {
+  constructor(program) {
+    super("admin", "Manage connections and tool permissions", program)
+    this.command
+      .command("connect")
+      .description("Add a new connection")
+      .argument("name", "Connection's name")
+      .argument("device-data", "Base64 encoded device data")
+      .addOption(
+        new Option("--new-server <device-data>", "Create a new server")
+          .conflicts("existingServer")
+      )
+      .addOption(
+        new Option("--existing-server <device-id>", "Use an existing server")
+          .conflicts("newServer")
+      )
+      .action(this.action("connect"))
+
+    this.command
+      .command("grant-tool")
+      .description("Grant permission")
+      .argument("connection-name", "Connection name")
+      .argument("tool", "Tools name")
+      .action(this.action("grantTool"))
+
+    this.command
+      .command("grant-all")
+      .description("Grant permissions to all tools")
+      .argument("connection-name", "Connection name")
+      .action(this.action("grantAll"))
+
+    this.command
+      .command("revoke-all")
+      .description("Revoke permissions to all tools")
+      .argument("connection-name", "Connection name")
+      .action(this.action("revokeAll"))
+
+    this.command
+      .command("revoke-tool")
+      .description("Revoke permission")
+      .argument("connection-name", "Connection name")
+      .argument("tool", "Tools name")
+      .action(this.action("revokeTool"))
+
+    this.command
+      .command("connection")
+      .description("Get connection details")
+      .argument("connection-name", "Connection name")
+      .action(this.action("connection"))
+  }
+
+  async init() {
+    let networkId = await this.sept.getNetworkId()
+    if (!networkId) {
+      await this.sept.bootstrap()
+      networkId = await this.sept.getNetworkId()
+      console.log("Bootstrap done")
+    }
+    console.log(`NetworkID: ${networkId}`)
+    this.connectionsStorage = this.sept.appStorage("connections")
+    // The tool list belongs to the server bridge, not to a connection: several
+    // connections may share a server, and they must all see the same list.
+    this.serversStorage = this.sept.appStorage("servers")
+    // Only server bridges we connected are granted tools.list towards admins,
+    // and SEPT enforces that on receipt, so any sender here is one of ours.
+    this.sept.register("tools.list", async event => {
+      await this.serversStorage.set(event.senderDeviceId, {
+        tools: event.payload.tools ?? [],
+      })
+    })
+    await this.sept.connect()
+  }
+
+  parseDeviceData(b64Data) {
+    return JSON.parse(Buffer.from(b64Data, "base64").toString("utf8"))
+  }
+
+  async connect(name, clientDeviceData, options) {
+    const { existingServer, newServer } = options
+
+    if (!existingServer && !newServer) {
+      throw new Error("One of --new-server or --existing-server is required")
+    }
+
+    if (await this.connectionsStorage.get(name)) {
+      throw new Error(`Connection with name ${name} already exists`)
+    }
+
+    const client = this.parseDeviceData(clientDeviceData)
+
+    if (client.metadata.role !== "client") {
+      throw new Error(`Wrong client role: ${client.metadata.role}`)
+    }
+
+    const { pin: pinClient, pairing: pairingClient } = await this.sept.addDevice(client)
+    let serverDeviceId, pairingServer
+    if (newServer) {
+      const server = this.parseDeviceData(newServer)
+      if (server.metadata.role !== "server") {
+        throw new Error(`Wrong server role`)
+      }
+      const { pin: pinServer, pairing } = await this.sept.addDevice(server)
+      console.log(`PIN Server: ${pinServer}`)
+      serverDeviceId = server.deviceId
+      pairingServer = pairing
+    } else {
+      if (!(await this.sept.getDevices()).find(d => d.id === existingServer)) {
+        throw new Error(`Device ${existingServer} not found`)
+      }
+      serverDeviceId = existingServer
+    }
+
+    console.log(`PIN Client: ${pinClient}`)
+
+    if (newServer) {
+      await pairingServer
+    }
+    await pairingClient
+
+    await this.sept.grant(client.deviceId, serverDeviceId, ["mcp.tools.list"])
+    await this.sept.grant(serverDeviceId, client.deviceId, ["mcp.response"])
+    await this.connectionsStorage.set(name, {
+      name,
+      server: serverDeviceId,
+      client: client.deviceId
+    });
+    for (const admins of await this.sept.getAdmins()) {
+      await this.sept.grant(serverDeviceId, admins.deviceId, ["tools.list"])
+    }
+  }
+
+  async getConnection(connectionName) {
+    const connection = await this.connectionsStorage.get(connectionName)
+    if (!connection) {
+      throw new Error(`Connection ${connectionName} not found`)
+    }
+    return connection
+  }
+
+  async getServerTools(serverDeviceId) {
+    const server = await this.serversStorage.get(serverDeviceId)
+    return server?.tools ?? []
+  }
+
+  async grantTool(connectionName, tool) {
+    const connection = await this.getConnection(connectionName)
+    await this.sept.grant(connection.client, connection.server, [`mcp.tools.call.${tool}`])
+  }
+
+  // The server reports its tools to admins only after pairing completes, so
+  // right after `connect` the list may not have reached this admin yet.
+  // Wait for it briefly instead of silently granting/revoking nothing.
+  async getConnectionWithTools(connectionName, timeoutMs = 10000) {
+    const connection = await this.getConnection(connectionName)
+    const start = Date.now()
+    while (true) {
+      const tools = await this.getServerTools(connection.server)
+      if (tools.length > 0) {
+        return { connection, tools }
+      }
+      if (Date.now() - start > timeoutMs) {
+        throw new Error(
+          `No tool list received yet for ${connectionName}: make sure the `
+          + `server bridge is running (it reports its tools to admins on start)`
+        )
+      }
+      await sleep(250)
+    }
+  }
+
+  async grantAll(connectionName) {
+    const { connection, tools } = await this.getConnectionWithTools(connectionName)
+    const eventTypes = tools.map(t => `mcp.tools.call.${t.name}`)
+    await this.sept.grant(connection.client, connection.server, eventTypes)
+  }
+
+  async revokeAll(connectionName) {
+    const { connection, tools } = await this.getConnectionWithTools(connectionName)
+    const eventTypes = tools.map(t => `mcp.tools.call.${t.name}`)
+    await this.sept.revoke(connection.client, connection.server, eventTypes)
+  }
+
+
+  async revokeTool(connectionName, tool) {
+    const connection = await this.getConnection(connectionName)
+    await this.sept.revoke(connection.client, connection.server, [`mcp.tools.call.${tool}`])
+  }
+
+  async connection(connectionName) {
+    const c = await this.getConnection(connectionName)
+    const tools = await this.getServerTools(c.server)
+    const acl = await this.sept.getACL()
+    const enabledTools = acl.find(a => a.srcDeviceId === c.client && a.dstDeviceId === c.server)?.policy?.allowedEventTypes || []
+    console.log(`Client: ${c.client}`)
+    console.log(`Server: ${c.server}`)
+    console.log(`Tools:`)
+    for (const t of tools) {
+      const enabled = enabledTools.includes(`mcp.tools.call.${t.name}`)
+      console.log(`  ${enabled ? pc.green('✓') : pc.red('✗')} ${t.name}`)
+    }
+  }
+}