convez.ai
MCP Server
jmagar

synapse2

jmagar/synapse2

Ver no GitHub
InicialPluginScore · de 0 a 100

Rust MCP server for Synapse-style homelab scout and flux workflows

Instalação

$npx convez-ai jmagar/synapse2

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v1.0.0
Issues abertas
8
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

synapse2

Rust MCP and CLI server for local Synapse workflows — a full-parity port of synapse-mcp implemented in Rust with the rmcp framework.

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

Surfaces

SurfaceStatusPurpose
MCPRequiredAgent-facing flux and scout tools
CLIRequiredScriptable parity surface
RESTPresentThin local action endpoint
WebPresentLightweight static admin shell

Tools and Actions

flux — Docker infrastructure management

flux docker — Docker daemon operations (9 actions)

SubactionScopeDescription
infosynapse:readDocker daemon information
dfsynapse:readDocker disk usage
imagessynapse:readList Docker images; dangling_only to filter untagged
networkssynapse:readList Docker networks
volumessynapse:readList Docker volumes
pullsynapse:writePull a Docker image; requires host, image
buildsynapse:writeBuild a Docker image; requires host, context, tag; optional dockerfile, no_cache
rmisynapse:writeRemove a Docker image; requires host, image, force=true
prunesynapse:writeRemove unused resources; requires host, prune_target, force=true

flux container — Container lifecycle + inspection (14 actions)

SubactionScopeDescription
listsynapse:readList containers; optional state, name_filter, image_filter, label_filter
inspectsynapse:readDetailed container info; requires container_id; optional summary
logssynapse:readContainer logs; requires container_id; optional lines, since, until, grep, stream
statssynapse:readResource usage stats; optional container_id
topsynapse:readShow running processes; requires container_id
searchsynapse:readFull-text search by name/image/labels; requires query
startsynapse:writeStart a stopped container; requires container_id
stopsynapse:writeStop a running container (destructive); requires container_id
restartsynapse:writeRestart a container; requires container_id
pausesynapse:writePause a running container; requires container_id
resumesynapse:writeResume a paused container; requires container_id
pullsynapse:writePull latest image for a container; requires container_id
recreatesynapse:writeRecreate container with image pull (destructive); requires container_id; optional pull (default true)
execsynapse:writeExecute command inside container (destructive, execvp); requires container_id, command array

flux host — Host inspection (9 actions)

SubactionScopeDescription
statussynapse:readCheck Docker connectivity on a host
infosynapse:readOS, kernel, architecture
uptimesynapse:readSystem uptime
resourcessynapse:readCPU, memory, disk usage
servicessynapse:readSystemd service status; requires host; optional state, service
networksynapse:readNetwork interfaces
mountssynapse:readMounted filesystems; requires host
portssynapse:readPort mappings; requires host; optional protocol, limit, offset
doctorsynapse:readDiagnostic checks; requires host; optional checks (comma-separated)

flux compose — Docker Compose project management (10 actions)

SubactionScopeDescription
listsynapse:readList all Docker Compose projects; requires host
statussynapse:readGet project service status; requires host, project; optional service
upsynapse:writeStart a compose project; requires host, project
downsynapse:writeStop a compose project (destructive); requires host, project; optional remove_volumes, force
restartsynapse:writeRestart a compose project (destructive); requires host, project
recreatesynapse:writeRecreate compose containers (destructive); requires host, project
logssynapse:readGet project logs; requires host, project; optional service, lines, since
buildsynapse:writeBuild compose project images; requires host, project; optional service
pullsynapse:writePull compose project images; requires host, project; optional service
refreshsynapse:readRefresh compose project cache; requires host

flux help — Auto-generated flux docs

ActionScopeDescription
helppublicReturn flux action reference; optional topic (e.g. "container:list"), format (markdown|json)

scout — SSH/local host inspection

Scout simple actions (9 actions)

ActionScopeDescription
nodessynapse:readList all configured SSH hosts
peeksynapse:readRead a file or directory listing; requires host, path; optional tree, depth
findsynapse:readFind files by glob; requires host, path, pattern; optional depth, limit
pssynapse:readList processes; requires host; optional sort (cpu|mem|pid|time), grep, user, limit
dfsynapse:readDisk usage; requires host; optional path
deltasynapse:readCompare files or content; requires source_host, source_path; then either target_host+target_path or content
execsynapse:writeExecute allowlisted command (destructive, execvp); requires host, command; optional path, args, timeout_secs
emitsynapse:writeMulti-host execution (destructive); requires targets array, command; optional args, timeout_secs
beamsynapse:writeFile transfer between hosts (destructive); requires source_host, source_path, dest_host, dest_path

scout zfs — ZFS introspection (3 subactions)

SubactionScopeDescription
poolssynapse:readList ZFS pools; requires host; optional pool name filter
datasetssynapse:readList ZFS datasets; requires host; optional pool, dataset_type, recursive
snapshotssynapse:readList ZFS snapshots; requires host; optional pool, dataset, limit

scout logs — Log retrieval (4 subactions)

SubactionScopeDescription
syslogsynapse:readRead /var/log/syslog (falls back to /var/log/messages); requires host; optional lines, grep
journalsynapse:readRead systemd journal; requires host; optional lines, unit, priority, since, until, grep
dmesgsynapse:readRead kernel ring buffer; requires host; optional lines, grep
authsynapse:readRead /var/log/auth.log (falls back to /var/log/secure); requires host; optional lines, grep

scout help — Auto-generated scout docs

ActionScopeDescription
helppublicReturn scout action reference; optional topic (e.g. "zfs:pools"), format (markdown|json)

Known Parity Gaps

synapse2 achieves action-level parity with synapse-mcp — all 59 production actions from synapse-mcp/docs/INVENTORY.md are implemented. However, the following features from the original TypeScript server are not yet ported:

Not ported

FeatureDescription
claude/channel notificationsOriginal forwards Docker events and log tails as notifications/claude/channel MCP notifications. No equivalent exists in Rust.
Templated MCP resourcesOriginal exposes synapse://hosts/{host}, synapse://hosts/{host}/stacks, synapse://stacks, synapse://stacks/{host}/{stack}, synapse://stacks/{host}/{stack}/env, synapse://containers/{host}, synapse://containers/{host}/{id}. Rust exposes schema resources, synapse://hosts, synapse://compose/projects, and help resources.
Root SSH login gateOriginal gates sshUser=root through elicitation unless SYNAPSE_ALLOW_ROOT_LOGIN=true. Rust has destructive-operation elicitation but no root-login gate.
TOFU fingerprint storeOriginal persists fingerprints to ~/.config/synapse/known_hosts.json and rejects changed fingerprints. Rust uses strict OpenSSH known_hosts with wildcard warnings — different operator behavior.
SYNAPSE_EXCLUDE_HOSTSOriginal env var to exclude hosts from fleet discovery is absent in Rust.
SYNAPSE_MCP_ALLOW_YOLOOriginal "skip all confirmation gates" mode. Rust has SYNAPSE_MCP_ALLOW_DESTRUCTIVE (per-restart override, loopback-only), which is not identical.
SYNAPSE_DEBUG_ERRORSOriginal opt-in mode that returns full internal error detail. Rust always sanitizes internal tool errors.
git in exec allowlistOriginal includes git in ALLOWED_READ_COMMANDS with flag guards. Rust deliberately excludes git.

Configuration

SYNAPSE_MCP_HOST=127.0.0.1
SYNAPSE_MCP_PORT=40080
SYNAPSE_MCP_TOKEN=change-me

Key environment variables:

VariableDefaultDescription
SYNAPSE_MCP_HOST127.0.0.1Bind host for HTTP transport.
SYNAPSE_MCP_PORT40080Bind port for HTTP transport.
SYNAPSE_MCP_TOKENunsetStatic bearer token for auth.
SYNAPSE_MCP_NO_AUTHfalseDisable auth for loopback development only.
SYNAPSE_NOAUTHfalseTrusted-gateway no-auth mode for non-loopback deployments.
SYNAPSE_MCP_ALLOW_DESTRUCTIVEfalseSkip destructive-operation confirmation prompts (loopback only).
SYNAPSE_MCP_MAX_CONCURRENCY50Maximum simultaneous in-flight requests on /mcp and /v1/synapse2. Excess requests are queued, not rejected. Set to 0 to disable. /health and /status are exempt.

See .env.example for the full list of variables and docs/CONFIG.md for auth configuration details.

Run

# Start MCP server (stdio transport)
cargo run -- mcp

# Start HTTP server
cargo run -- serve

# CLI examples
cargo run -- flux docker info
cargo run -- flux container list
cargo run -- flux compose list --host myhost
cargo run -- scout nodes
cargo run -- scout exec --host myhost --command hostname
cargo run -- scout zfs pools --host myhost
cargo run -- scout logs journal --host myhost --unit docker

MCP examples:

{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"flux","arguments":{"action":"container","subaction":"list","state":"running"}}
{"name":"flux","arguments":{"action":"compose","subaction":"status","host":"myhost","project":"mystack"}}
{"name":"scout","arguments":{"action":"nodes"}}
{"name":"scout","arguments":{"action":"exec","host":"myhost","command":"hostname"}}
{"name":"scout","arguments":{"action":"zfs","subaction":"pools","host":"myhost"}}
{"name":"scout","arguments":{"action":"logs","subaction":"journal","host":"myhost","unit":"docker"}}

Architecture

FluxService   (src/flux_service/)  Docker/container/compose/host ops
ScoutService  (src/scout_service/) SSH/exec/fs/zfs/logs ops
      ↓ via SynapseService facade (src/app.rs)
MCP shims     (src/mcp/tools.rs)  tool args → service → Value
CLI shim      (src/cli.rs)        argv → service → stdout
REST layer    (src/api.rs)        POST /v1/synapse2 → service → JSON

Development

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release

just dev     # serve with no auth (loopback, dev mode)
just test    # cargo test
just lint    # clippy
just fmt     # cargo fmt

Useful docs:

  • docs/API.md for full tool contracts
  • docs/CONFIG.md for environment and auth
  • docs/QUICKSTART.md for local smoke tests
  • plugins/synapse2/skills/synapse2/SKILL.md for agent usage guidance
  • tests/parity.rs for automated parity verification against synapse-mcp INVENTORY
Ver o original no GitHub

Bom para

Relacionados