synapse-mcp – MCP-Server für Synapse

Model Context Protocol (MCP) Server für das Synapse-Ökosystem – exponiert die Synapse Memory API, den Browser-Proxy und den SSH-Proxy als MCP-Tools. Mehrmandantenfähig, unterstützt stdio- und HTTP/SSE-Transporte (WebSocket: experimentell, nicht produktivtauglich). Funktioniert mit Claude Desktop, Cline, Cursor, Continue und jedem MCP-kompatiblen Client.

Aktuelle Version: 1.4.2 – 124 Tools in 15 Kategorien (120 kanonisch + 4 deprecated Aliasse). 100 % API-Coverage aller Schaefer-Services-HTTP- Endpunkte.

Übersicht

synapse-mcp ist die Brücke zwischen MCP-kompatiblen KI-Clients (Claude Desktop, Cline, Cursor etc.) und der Synapse-Memory-API. Statt dass jeder Client die HTTP-Endpunkte von Synapse direkt ansteuert, kapselt dieser Server alle Endpunkte als MCP-Tools und bietet zusätzlich AutoSync-Push- Benachrichtigungen für aktive Sessions. Der Server ist bewusst schlank gehalten: Er enthält keine eigene Persistenz, sondern leitet alle Aufrufe an die konfigurierten Upstream-Services (Synapse, Browser-Proxy, SSH-Proxy) weiter. Dadurch bleibt er zustandslos und einfach zu betreiben.

Quick Start

Voraussetzung: Mind Key besorgen

Ein Mind Key ist das Auth-Token – jeder MCP-Tool-Aufruf benötigt ihn.

1. Registrieren an der Synapse-Instanz (Default: https://synapse.schaefer.zone)
2. Mind anlegen im Web-UI – das liefert den Mind Key
3. Mind Key kopieren – wird im nächsten Schritt gebraucht

Option 1: zentraler HTTP/SSE-Service (mehrmandantenfähig, empfohlen)

Einmal deployen, alle Nutzer verwenden ihn mit ihrem eigenen Mind Key:

docker service create \
  --name synapse-mcp \
  --network synapse-net \
  --publish 13100:13100 \
  --env SYNAPSE_URL=http://memory-api:12800 \
  --env SYNAPSE_PUBLIC_URL=https://synapse.schaefer.zone \
  --env BROWSER_PROXY_URL=http://browser-proxy:13000 \
  --env SSH_PROXY_URL=http://ssh-proxy:12900 \
  --env MCP_TRANSPORT=http \
  registry.gitlab.com/schaefer-services/synapse-mcp:latest

MCP-Client verbinden (Streamable HTTP, empfohlen):

URL: https://synapse-mcp.schaefer.zone/mcp
Headers: Authorization: Bearer <YOUR_MIND_KEY>
         Accept: application/json, text/event-stream

Option 2: lokaler stdio-Modus (Single-User)

Als Subprocess des MCP-Cients laufen. Jeder Container = ein Mind.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp"],
      "env": {
        "SYNAPSE_URL": "https://synapse.schaefer.zone",
        "SYNAPSE_MIND_KEY": "<YOUR_MIND_KEY>",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Cline (VS Code):

{
  "mcpServers": {
    "synapse": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "SYNAPSE_URL=https://synapse.schaefer.zone",
               "-e", "SYNAPSE_MIND_KEY=<YOUR_MIND_KEY>",
               "-e", "MCP_TRANSPORT=stdio",
               "registry.gitlab.com/schaefer-services/synapse-mcp:latest"]
    }
  }
}

Setup verifizieren

1. Konnektivität prüfen – das Tool synapse_health aufrufen. Es spricht Synapses /health-Endpunkt an und liefert Memory-Stats, DB-Status und Version. Schlägt es mit „Cannot reach Synapse" fehl, ist SYNAPSE_URL falsch oder Synapse ist offline.
2. Erste Erinnerung speichern – memory_store { content: "..." } aufrufen. Sollte das Memory-Objekt mit ID zurückgeben.
3. Recall – memory_recall aufrufen. Sollte die gerade gespeicherte Erinnerung zurückliefern.

| Fehlermeldung | Ursache | Lösung | |---|---|---| | Cannot reach Synapse at <url> | SYNAPSE_URL falsch oder Synapse down | URL prüfen, Synapse-Erreichbarkeit verifizieren | | Authentication failed | Mind Key ungültig/fehlend | Mind Key aus Synapse-Web-UI kopieren, SYNAPSE_MIND_KEY bzw. Authorization: Bearer-Header setzen | | Too many concurrent sessions | Mehr als 10 Sessions mit gleichem Mind Key | Ungenutzte Sessions schließen (DELETE /mcp) oder 30 min warten | | Rate limit exceeded | Mehr als 60 Requests/min | Slow down, AutoSync-Polling-Frequenz reduzieren | | SYNAPSE_MIND_KEY appears to be a placeholder | Beispiel-Config wörtlich kopiert | <YOUR_MIND_KEY> durch echten Key ersetzen |

Tools (124 gesamt: 120 kanonisch + 4 deprecated, 15 Kategorien)

Memory (24)

memory_recall, memory_list, memory_store, memory_store_get, memory_search, memory_semantic_search, memory_update, memory_delete, memory_bulk_delete, memory_stats, memory_unverified, memory_contradictions, memory_audit, memory_related, memory_by_tag, memory_diff, memory_expiring, memory_health, memory_sync, memory_embed_batch, memory_embed_batch_status, memory_verify (JWT), memory_unverify (JWT), memory_export.

Chat (10)

chat_poll, chat_reply, chat_reply_with_file, chat_status, chat_history (JWT), chat_unread (JWT), chat_send (JWT), chat_upload (JWT), chat_file_get, chat_files_list (JWT).

Scheduler (8)

cron_list, cron_create, cron_delete, cron_toggle, var_list, var_get, var_set, var_delete.

Tasks (6)

task_list, task_get, task_create, task_update, task_complete, task_delete.

Scripts (5)

script_list, script_get, script_info, script_store, script_delete.

Computers (12)

User-facing (Mind Key): computer_list, computer_get, computer_install_code, computer_screenshot, computer_command_queue, computer_command_status, computer_commands_list, computer_disable, computer_delete. Agent-facing (computer_token): computer_register, computer_me_poll, computer_me_command_result.

Push (4, nur JWT)

push_vapid_public_key, push_subscribe, push_unsubscribe, push_test.

User/Mind-Verwaltung (6)

user_register, user_login, user_logout, user_minds_list (JWT), user_mind_create (JWT), user_mind_delete (JWT).

Webhooks (6)

webhook_create, webhook_list, webhook_get, webhook_update, webhook_delete, webhook_test.

Visualization (4)

memory_compact, memory_graph, memory_tags, memory_timeline.

Sharing (5, nur JWT, neu in v1.3.0)

mind_share_create, mind_share_list, mind_share_update, mind_share_delete, minds_shared_list. ACL-Level: read, write, admin.

Utility (7)

server_time, math_calc, random_value, auth_status, synapse_health, synapse_endpoints, synapse_openapi.

Documentation (1, neu in v1.4.2)

documentation_query — durchsucht die Synapse-Dokumentation und ruft Artikel ab.

Browser-Proxy (11, neu in v1.2.0)

browser_health, browser_new, browser_navigate, browser_dom, browser_screenshot, browser_sessions, browser_close, browser_search, browser_fetch, browser_git_urls, browser_git_all. Diese Tools proxyn auf den browser-proxy-api-Service (Browserless + Redis) und stellen LLM-kontrollierte Chrome-Sessions bereit. Jeder Mind Key bekommt einen isolierten Tab-Store (Mehrmandantenfähigkeit). Tabs schließen nach 24 Stunden Inaktivität automatisch.

Typischer Workflow: browser_new { url: "..." } → tab_id, dann browser_dom { tab_id }, browser_screenshot { tab_id, format: "jpeg" }, abschließend browser_close { tab_id }. Für Code-Reviews ganzer Repos eignet sich browser_git_all { url: "...", ext: ".ts,.js" }, das das komplette Repo als konkatenierten Text zurückliefert.

SSH-Proxy (11, neu in v1.2.0)

ssh_health, ssh_new, ssh_connect, ssh_exec, ssh_exec_poll, ssh_output, ssh_sessions, ssh_close, ssh_target_register, ssh_target_list, ssh_target_delete. Diese Tools proxyn auf den ssh-proxy-api-Service und bieten persistente SSH-Sessions für LLM-Agenten, ohne dass ein lokaler SSH-Client installiert sein muss.

Zwei Verbindungsmodi: Direct (Credentials im Request) oder Pre-registered target (sicherer, keine Credentials im Request). Kommandos sind asynchron – ssh_exec liefert sofort eine exec_id zurück, dann muss ssh_exec_poll aufgerufen werden, um das Ergebnis abzuholen. Sessions sind Single-Tasking (409 „session_busy" bedeutet, dass ein voriges Kommando noch läuft) und schließen nach 30 Minuten Inaktivität automatisch. Niemals ssh_exec für interaktive Kommandos (vim, top, sudo mit Passwort-Prompt) verwenden.

AutoSync (Push-Benachrichtigungen)

Der MCP-Server benachrichtigt Clients proaktiv über Änderungen via des Transport-Mechanismus des Clients. Es ist keine Client-Subscription notwendig – Benachrichtigungen erfolgen automatisch für jede aktive Session. Unterstützte Event-Typen sind memory.created, memory.updated, memory.deleted, task.created, task.updated, task.completed, chat.message_received und chat.message_sent.

Phase A (Polling): Der Server pollt Synapse alle 5 Sekunden pro Session und emittiert Notifications, wenn Änderungen erkannt werden. Das ist der Default und aktuell aktive Mechanismus. Phase B (Webhook): Synapse kann Events via HTTP-Webhook an den MCP-Server pushen für Near-Realtime-Notifications (<100 ms Latenz). Diese Variante ist implementiert, aber noch nicht in den Main-Server-Startup eingehängt (siehe docs/adr/0004-autosync-poll-vs-webhook.md).

Umgebungsvariablen

| Variable | Default | Beschreibung | |---|---|---| | MCP_TRANSPORT | http | stdio oder http (WebSocket in src/server-ws.ts vorhanden, aber nicht produktiv) | | SYNAPSE_URL | https://synapse.schaefer.zone | Synapse-API-Basis-URL (in Swarm-Deployments intern) | | SYNAPSE_PUBLIC_URL | https://synapse.schaefer.zone | Öffentliche Synapse-URL für Onboarding-Anzeige | | SYNAPSE_MIND_KEY | – | Mind Key (Pflicht im stdio-Modus) | | SYNAPSE_JWT | – | JWT für Mensch-only-Tools (optional) | | BROWSER_PROXY_URL | http://browser-proxy:13000 | Browser-Proxy-API-URL | | SSH_PROXY_URL | http://ssh-proxy:12900 | SSH-Proxy-API-URL | | PORT | 13100 | HTTP/SSE-Listen-Port | | LOG_LEVEL | info | debug, info, warn, error | | ALLOWED_ORIGINS | * | Kommaseparierte CORS-Origins | | NODE_ENV | production | development für pretty-Logs | | MAX_SESSIONS_PER_MIND_KEY | 10 (hardcoded) | Max gleichzeitige Sessions pro Mind Key | | WEBHOOK_PORT | 13101 | Webhook-Listen-Port (Phase B AutoSync) | | WEBHOOK_HOST | synapse-mcp | Hostname für Webhook-URLs (Docker-DNS) | | WEBHOOK_SECRET | – | Secret zum Signieren von Webhook-Payloads |

Architektur

┌─────────────────────────────────────────────────────────────┐
│  MCP-Client (Claude Desktop, Cline, Cursor, custom App)     │
│  Auth: Authorization: Bearer <MIND_KEY>                     │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
              https://synapse-mcp.schaefer.zone
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  synapse-mcp (dieser Server)                                │
│  - 124 MCP-Tools in 15 Kategorien (120 + 4 deprecated)      │
│  - Mehrmandantenfähig: reicht Mind Key an Upstream weiter   │
│  - Transporte: HTTP/SSE (prod), WebSocket (exp.), stdio      │
│  - AutoSync-Push-Notifications (Poll oder Webhook)          │
└─────┬───────────────┬───────────────────────┬──────────────┘
      │               │                       │
      ▼               ▼                       ▼
┌───────────┐  ┌──────────────┐  ┌─────────────────────────┐
│ Synapse   │  │ Browser-Proxy│  │ SSH-Proxy               │
│ :12800    │  │ :13000       │  │ :12900                  │
│ 97 Tools  │  │ 11 browser_* │  │ 11 ssh_* tools          │
└───────────┘  └──────────────┘  └─────────────────────────┘

Architektur-Entscheidungen sind in vier ADRs dokumentiert (docs/adr/0001-multi-tenant-architecture.md, 0002-transport-strategy-stdio-http-ws.md, 0003-auth-strategy-mind-key-per-request.md, 0004-autosync-poll-vs-webhook.md).

CI/CD

Die Pipeline in .gitlab-ci.yml inkludiert die Templates schaeferms/ci-templates/templates/master.yml und templates/deploy-swarm.yml und durchläuft die Stages lint, test, build, publish und deploy. Der test:unit-Job läuft im Image node:22-slim, führt npm ci, npm run typecheck und npm run test:coverage aus und lädt das Cobertura-Coverage-XML als Artifact hoch. Coverage-Ziel ist >80 % für neue Module.

Der publish:npm-Job läuft nur auf main, prüft, ob NPM_TOKEN gesetzt und kein Platzhalter ist, und führt npm publish --access public aus. Ist NPM_TOKEN nicht gesetzt, bricht der Job sauber mit einer Hinweismeldung ab (kein Pipeline-Fehler). Der deploy:swarm-Job verwendet das Template templates/deploy-swarm.yml und aktualisiert den Service schaefer_synapse-mcp über SSH mit docker service update --detach. Die Health-URL ist http://localhost:13100/health, die Wartezeit 30 Sekunden. Wöchentliche Pipelines (Montag 09:00 UTC) fangen Dependency-Breakage früh ab.

Deployment

Das Produktivsystem läuft als Docker-Swarm-Service schaefer_synapse-mcp auf dem schaefer-Swarm (vps1/vps3). Der Service ist öffentlich unter https://synapse-mcp.schaefer.zone erreichbar und verbindet sich intern über das synapse-net-Docker-Netzwerk mit den Upstream-Services (memory-api:12800, browser-proxy:13000, ssh-proxy:12900). Vor dem Start prüft der Healthcheck im Dockerfile beide Endpunkte: den lokalen MCP-Server unter http://localhost:13100/health und den Upstream-Synapse unter SYNAPSE_URL/health. Schlägt einer der beiden fehl, markiert Docker den Container als unhealthy und startet ihn neu.

Der entrypoint.sh-Mechanismus zieht bei jedem Container-Start den origin/main und baut bei Änderungen an src/, tsconfig.json oder package.json intern neu. Das erlaubt Hotfix-Deployments ohne neues Docker-Image, sollte aber nur in Notfällen genutzt werden. Für ein neues Produktivdeployment muss das Image aus der GitLab-Container-Registry gezogen werden (docker service update --image registry.gitlab.com/schaefer-services/synapse-mcp:latest schaefer_synapse-mcp), anschließend verifiziert der Healthcheck innerhalb von 30 Sekunden die Erreichbarkeit. Für Rollbacks kann auf einen früheren Image-Tag zurückgegangen werden.

Entwicklung

git clone https://gitlab.com/schaefer-services/synapse-mcp.git
cd synapse-mcp
npm install
npm run build
npm run test:coverage
npm run typecheck

# Dev-Modus (HTTP/SSE)
SYNAPSE_URL=https://synapse.schaefer.zone \
SYNAPSE_MIND_KEY=<your-key> \
MCP_TRANSPORT=http \
npm run dev

Für Tests der browser_*- und ssh_*-Tools können die Proxy-URLs auf lokale Instanzen oder auf den Produktivservice zeigen. Anschließend in einem MCP-Client (z. B. Cline) http://localhost:13100/mcp anbinden und browser_health bzw. ssh_health testen. Der npm run dev-Befehl nutzt tsx watch für Hot-Reload; Änderungen an src/*.ts werden sofort übernommen. Vor jedem Commit sollten npm run typecheck && npm run test:coverage lokal durchlaufen werden, weil die CI identisch vorgeht.

Qualitätssicherung

Dieses Projekt folgt strikten Qualitätsstandards: Tests (>80 % Coverage für neue Module), ADRs (Architectural Decision Records unter docs/adr/), CHANGELOG (jede Änderung dokumentiert), Code Review (Self-Review-Checkliste vor Merge), Definition of Done (Code + Tests + Doku + CHANGELOG + verifiziert). Der Default-Branch main ist geschützt; direkte Pushes sind nicht erlaubt, alle Änderungen laufen über Merge Requests.

Verwandte Services

Dieser MCP-Server integriert drei Sibling-Services aus der schaefer-services-Gruppe:

| Service | Repo | Port | Zweck | |---------|------|------|-------| | Synapse | synapse | 12800 | Memory API, Chat, Tasks, Scripts, Webhooks, Scheduler | | Browser-Proxy | browser-proxy-api | 13000 | LLM-kontrolliertes Chrome (Browserless + Redis) | | SSH-Proxy | ssh-proxy-api | 12900 | Persistente SSH-Sessions, pre-registrierte Targets |

Alle drei Services werden zusammen im schaefer-Docker-Swarm-Stack auf vps1/vps3 ausgerollt.

Lizenz

MIT – siehe LICENSE.

Autor

Michael Schäfer · Schäfer Services · [email protected]

Dokumentation

Die weiterführende Doku liegt in documentation/ und richtet sich an unterschiedliche Leser:innen: architecture.md dokumentiert die Schichten (Entry, Transport, Session, Tool, Client), die Mehrmandantenfähigkeit und die Auth-Strategie; deployment.md behandelt die Produktivumgebung, Docker-Konfiguration, Erstinitalisierung und das Rollback; development.md erklärt das Setup, die NPM-Skripte, die Testsuite, die Tool-Entwicklung und den Merge-Request-Workflow. Ergänzend liegen in docs/adr/ vier Architecture Decision Records (Multi-Tenant, Transport-Strategie, Auth-Strategie, AutoSync-Poll-vs-Webhook), die Designentscheidungen nachvollziehbar machen. Beispiel-Konfigurationen für Claude Desktop und Cline liegen unter examples/.

| Datei | Inhalt | |---|---| | documentation/architecture.md | Schichten, Multi-Tenancy, Auth, AutoSync | | documentation/deployment.md | Produktivsetup, Docker, CI/CD, Rollback | | documentation/development.md | Setup, NPM-Skripte, Tests, Tool-Entwicklung | | docs/adr/0001-multi-tenant-architecture.md | ADR: Multi-Tenant mit Mind Key als Tenant-ID | | docs/adr/0002-transport-strategy-stdio-http-ws.md | ADR: stdio + HTTP produktiv, WS experimentell | | docs/adr/0003-auth-strategy-mind-key-per-request.md | ADR: Mind Key pro Request, JWT optional | | docs/adr/0004-autosync-poll-vs-webhook.md | ADR: Polling statt Webhook für AutoSync | | examples/ | Beispiel-Konfigurationen für Claude Desktop, Cline, VS Code |

Roadmap

Die weitere Entwicklung konzentriert sich auf vier Stränge: (1) Aktivierung des WebSocket-Transports in src/index.ts, der aktuell in server-ws.ts implementiert, aber nicht eingehängt ist – das wird Realtime-Anwendungen wie Live-Browser-Steuerung und SSH-Session-Pipelining ermöglichen; (2) Ausbau der AutoSync-Webhook-Variante, die aktuell nur polling-basiert ist, sodass Synapse den MCP-Server bei Memory-Änderungen aktiv benachrichtigt statt ihn pollen zu lassen; (3) Erweiterung des Tool-Profilsystems in src/tools/profiles.ts um benutzerdefinierte Profile, die über eine Konfigurationsdatei geladen werden; (4) Stabilisierung der SSRF-Prävention in tests/ssrf.test.ts, die aktuell im grünen Bereich ist, aber bei neuen Tool-Implementierungen immer wieder randständig wird. Konkrete Releases werden in CHANGELOG.md nachverfolgt.