synapse

# synapse-rmcp

Host, Docker, Compose, SSH, logs, ZFS, and file operations over MCP and CLI.

Synapse is a full-parity Rust port of
[synapse-mcp](https://github.com/dinglebear-ai/synapse-mcp), built with the
[rmcp](https://github.com/modelcontextprotocol/rust-sdk) framework.

The server exposes two MCP tools (`flux` and `scout`) plus equivalent CLI
commands, covering all 59 production actions from the original TypeScript server.

## Contents

- [Naming](#naming)
- [Capabilities And Boundaries](#capabilities-and-boundaries)
- [Install](#install)
- [Quickstart](#quickstart)
- [Client Configuration](#client-configuration)
- [Plugin Packages](#plugin-packages)
- [Runtime Surfaces](#runtime-surfaces)
- [MCP Tool Reference](#mcp-tool-reference)
- [CLI Reference](#cli-reference)
- [Authentication](#authentication)
- [Safety And Trust Model](#safety-and-trust-model)
- [Distribution Contract](#distribution-contract)
- [Verification](#verification)
- [Deployment](#deployment)
- [Troubleshooting](#troubleshooting)
- [Tools and Actions](#tools-and-actions)
- [Known Parity Gaps](#known-parity-gaps)
- [Configuration](#configuration)
- [Run](#run)
- [Architecture](#architecture)
- [Development](#development)
- [Documentation](#documentation)
- [Related Servers](#related-servers)
- [License](#license)

## Naming

The repository is `synapse-rmcp`, the Rust crate is `synapse`, the MCP server
identity is `synapse`, and the installed binary is `synapse`. The npm launcher
package is `synapse-rmcp`.

Across most of the RMCP family, naming follows
`repo=<service>-rmcp`, `npm=<service>-rmcp`, and `CLI=r<service>`. Synapse is an
exception because it is a Rust port of the older TypeScript `synapse-mcp`
project and keeps the operator-facing `synapse` binary.

## Capabilities And Boundaries

Synapse provides local Docker, Compose, host, SSH, log, ZFS, and file-operation
workflows through two MCP tools and the equivalent CLI:

- `flux` manages Docker infrastructure, containers, Compose projects, and host
  inspection.
- `scout` handles SSH/local host inspection, safe file reads, allowlisted
  command execution, bounded descriptor-confined file transfer, ZFS introspection,
  and log retrieval.
- REST exists only as a compatibility shim for a subset of actions.
- The web surface is a lightweight static admin shell, not a full dashboard.

**Not for:** arbitrary shell access, unaudited remote mutation, or bypassing
host SSH trust. Destructive Docker/Compose/exec/file-transfer actions require
explicit host targets and confirmation policy.

MCP callers never provide credentials, tokens, keys, or secrets as action
arguments. Tokens, OAuth settings, host topology, SSH trust, and allowlists live
in server-side configuration or the local SSH environment.

## Install

Use the npm launcher for stdio MCP or CLI access without a manual binary
install:

```bash
npx -y @dinglebear/synapse --help
npx -y @dinglebear/synapse mcp
```

For a permanent command:

```bash
npm i -g @dinglebear/synapse
synapse --version
```

The npm package downloads the `synapse` binary from GitHub Releases during
`postinstall`, keeping the release tag aligned with
`packages/synapse-rmcp/package.json`.

From source:

```bash
cargo build --release
```

The production image includes Python 3 plus the official Docker CLI/Compose
plugin because Scout's remote descriptor wrappers and Flux Compose operations
invoke those runtime tools. The image does not contain a Docker daemon; Flux
uses the mounted socket or SSH-forwarded remote socket. Persistent appdata lives
at `~/.synapse` on the host and `/data` in the container.

## Quickstart

The first-screen 30-second path is:

```bash
npx -y @dinglebear/synapse mcp
```

Then configure an MCP client with stdio:

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-rmcp", "mcp"]
    }
  }
}
```

Start with a read-only call:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scout",
    "arguments": {
      "action": "nodes"
    }
  }
}
```

## Client Configuration

stdio is preferred for local MCP clients:

```json
{
  "mcpServers": {
    "synapse": {
      "command": "synapse",
      "args": ["mcp"]
    }
  }
}
```

Streamable HTTP uses `/mcp` on the configured host and port:

```json
{
  "mcpServers": {
    "synapse": {
      "url": "http://127.0.0.1:40080/mcp",
      "headers": {
        "Authorization": "Bearer ${SYNAPSE_MCP_TOKEN}"
      }
    }
  }
}
```

## Plugin Packages

`plugins/synapse/` ships Claude Code, Codex, and Gemini CLI manifests that all
point at the same HTTP MCP endpoint and the same shared skill.

These packages contain **no lifecycle hooks**. Connecting to a server that is
already running needs no setup — the manifests substitute your `server_url` and
`api_token` directly. If this machine also *runs* the server, bootstrap it once
by hand:

```bash
synapse setup install                  # put/refresh the binary on PATH
synapse setup plugin-hook              # check, then repair on blocking failures
synapse setup plugin-hook --no-repair  # audit only; never mutates appdata
```

Export the relevant `SYNAPSE_*` variables (or write them to `~/.synapse/.env`)
first; `plugins/README.md` maps each plugin option to its variable. Re-run
`synapse setup install` after a plugin update.

## Runtime Surfaces

| Surface | Status | Purpose |
|---|---:|---|
| MCP | Required | Agent-facing `flux` and `scout` tools |
| CLI | Required | Scriptable parity surface for operators |
| REST | Compatibility | Thin local action endpoint for 14 of 59 actions |
| Web | Present | Lightweight static admin shell |

## MCP Tool Reference

Synapse exposes two MCP tools:

- `flux`: Docker daemon, container, host, and Compose operations.
- `scout`: SSH/local host inspection, filesystem reads, allowlisted exec,
  multi-host emit, file beam, ZFS, and logs.

Both tools use an action-dispatched JSON shape:

```json
{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"scout","arguments":{"action":"nodes"}}
```

The detailed action tables below are curated README reference material. The
generated runtime MCP schema and the Rust action definitions are the source of
truth for the live tool contract.

## CLI Reference

Common commands:

```bash
synapse flux docker info
synapse flux container list
synapse flux compose list --host myhost
synapse scout nodes
synapse scout exec --host myhost --command hostname
synapse scout zfs pools --host myhost
synapse scout logs journal --host myhost --unit docker
```

## Authentication

Mounted HTTP supports bearer and Google OAuth modes. Loopback stdio/local dev
can run without mounted HTTP auth. Important variables:

```bash
SYNAPSE_MCP_HOST=127.0.0.1
SYNAPSE_MCP_PORT=40080
SYNAPSE_MCP_TOKEN=change-me
SYNAPSE_MCP_AUTH_MODE=bearer
```

See [Configuration](#configuration) and `docs/CONFIG.md` for the full auth
matrix.

## Safety And Trust Model

Synapse separates read and write scopes (`synapse:read`, `synapse:write`) and
uses confirmation gates for destructive operations. `SYNAPSE_MCP_ALLOW_DESTRUCTIVE`
can skip prompts only in loopback-safe contexts. Host `protocol` is authoritative
and defaults to SSH when omitted; local execution requires the explicit built-in
`local` host or `protocol: "local"`. SSH host trust is delegated to OpenSSH
known-hosts behavior, and command execution uses execvp/argv semantics without
shell interpolation. `scout beam` enforces both endpoints' configured read roots,
blocks sensitive and symlinked paths, and caps each transfer at 64 MiB.

`scout exec` and `scout emit` accept only these 18 typed commands
(`ALLOWED_READ_COMMANDS` in `src/synapse/command_policy.rs`):

`cat`, `head`, `tail`, `grep`, `rg`, `ls`, `tree`, `wc`, `uniq`, `diff`, `stat`,
`file`, `du`, `df`, `pwd`, `hostname`, `uptime`, `whoami`

`git` is deliberately excluded, as are shells, interpreters, network clients, and
mutating tools (`EXEC_DENYLIST`). There is no `find` or `sort` in the allowlist —
use the dedicated `scout find` action for filesystem search. Per-host custom
commands may be enabled via `execAllowlist`, but receive a zero-argument policy
until a typed argument policy is registered.

## Distribution Contract

The source of truth for release identity is the version shared by `Cargo.toml`,
`.release-please-manifest.json`, `packages/synapse-rmcp/package.json`, release
artifacts, and `server.json`.

Distribution/version invariants:

- The npm package downloads the matching GitHub Release binary.
- The installed binary remains `synapse`.
- `server.json` must point at `ghcr.io/dinglebear-ai/synapse:<version>`.
- Plugin manifests stay versionless where marketplaces derive identity from git
  state.
- Generated docs and schemas must come from source-controlled generation
  inputs; curated README/docs should point at source-of-truth files for details.

## Verification

```bash
just validate-plugin          # plugin manifests, MCP config, monitors, skills
npm --prefix packages/synapse-rmcp run check
cargo fmt --check
cargo check
cargo test
git diff --check
```

## Deployment

For a persistent mounted HTTP server:

```bash
SYNAPSE_MCP_HOST=0.0.0.0 \
SYNAPSE_MCP_PORT=40080 \
SYNAPSE_MCP_TOKEN=change-me \
synapse serve
```

Use bearer or OAuth before exposing the endpoint beyond loopback. Production
Docker/Compose notes live in `docs/DEPLOYMENT.md` and `docs/DOCKER.md` when
present; local operator usage can stay on stdio.

## Troubleshooting

- `401` or `403` from `/mcp`: check bearer/OAuth settings and gateway headers.
- no hosts appear: check `SYNAPSE_HOSTS_CONFIG`, `SYNAPSE_CONFIG_FILE`, and
  `~/.ssh/config`.
- destructive actions are refused: confirm the host target and confirmation
  policy.
- SSH errors: verify OpenSSH known_hosts, mux/socket availability, and host
  reachability outside Synapse first.

## Tools and Actions

### `flux` — Docker infrastructure management

#### `flux docker` — Docker daemon operations