# synapse-mcp – MCP-Server für Synapse

[![CI](https://gitlab.com/schaefer-services/synapse-mcp/badges/main/pipeline.svg)](https://gitlab.com/schaefer-services/synapse-mcp/-/pipelines)
[![Coverage](https://gitlab.com/schaefer-services/synapse-mcp/badges/main/coverage.svg)](https://gitlab.com/schaefer-services/synapse-mcp/-/jobs)
[![npm version](https://img.shields.io/npm/v/synapse-mcp.svg)](https://www.npmjs.com/package/synapse-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Model Context Protocol (MCP) Server für das
[Synapse](https://gitlab.com/schaefer-services/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:

```bash
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):

```text
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`):

```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)**:

```json
{
  "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](https://gitlab.com/schaefer-services/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](https://gitlab.com/schaefer-services/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

```text
┌─────────────────────────────────────────────────────────────┐
│  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

```bash
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](https://gitlab.com/schaefer-services/synapse) | 12800 | Memory API, Chat, Tasks, Scripts, Webhooks, Scheduler |
| Browser-Proxy | [browser-proxy-api](https://gitlab.com/schaefer-services/browser-proxy-api) | 13000 | LLM-kontrolliertes Chrome (Browserless + Redis) |
| SSH-Proxy | [ssh-proxy-api](https://gitlab.com/schaefer-services/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](LICENSE).

## Autor

Michael Schäfer · Schäfer Services · [michael@schaefer.zone](mailto:michael@schaefer.zone)


## 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.