coupler

FastMCP aggregator — the stable Claude Desktop entry point for all jazz services.

What it does

The coupler acts as a single MCP server that Claude Desktop connects to. It aggregates tool calls from multiple downstream services (notes_db, z3, UI controls) and proxies them through a single SSE endpoint. This decouples Claude Desktop from individual service restarts and version changes.

Claude Desktop → coupler bridge (stdio)
                      ↓
              coupler server (:7770 SSE)
                 ↙       ↘
          notes_db_mcp   z3_mcp
          (subprocess)   (subprocess)
               ↓
          notes_db HTTP (:8765)

Architecture

Two processes cooperate for zero-downtime updates:

- bridge (coupler-bridge) — stdio MCP server, long-lived, stays connected to Claude Desktop. Proxies to the coupler server via SSE. - server (coupler-server) — HTTP SSE MCP server on :7770. Spawns and proxies to downstream subprocess MCPs. Can restart without dropping Claude Desktop. - updater (coupler-update) — polls for new git tags every 5 minutes, pulls, and restarts the server.

Entry points

| Command | Role | |---|---| | coupler-bridge | stdio bridge for Claude Desktop | | coupler-server | HTTP SSE aggregator on :7770 | | coupler-update | auto-update daemon |

Installation

pip install -e .
launchctl load ~/Library/LaunchAgents/com.coupler.server.plist
launchctl load ~/Library/LaunchAgents/com.coupler.updater.plist

Point Claude Desktop at the bridge:

{
  "mcpServers": {
    "jazz": {
      "command": "coupler-bridge"
    }
  }
}

Services proxied

| Namespace | Module | Underlying service | |---|---|---| | notes_db | notes_db_mcp | notes_db HTTP :8765 | | z3 | z3_mcp | subprocess solver |

The coupler reads ~/code/jazz/conf/env/build.json to find the active conda environment for the notes subprocess. If no env is configured or the path doesn't exist, it falls back to the base conda Python.

MCP tools exposed

All tools are prefixed with the service namespace (e.g. notes_db_query_notes).

notes_db tools: - notes_db_add_note — add a note to a collection - notes_db_get_note — fetch a note by ID - notes_db_get_notes — all notes in a collection - notes_db_search_notes — keyword search across title, text, topic, tag - notes_db_query_notes — filter by topic and/or tag (see [#1][issue1]) - notes_db_update_note — update note fields - notes_db_delete_note — delete a note - notes_db_list_collections — list all collections - notes_db_create_collection — create a collection - notes_db_set_alias / get_alias / list_aliases / delete_alias — human-readable note aliases - notes_db_backup / notes_db_restore — JSON export/import

coupler tools: - coupler_status — live-probe all downstream services, returns ok/degraded/down

Versioning

Versions are tagged v{MAJOR}.{MINOR}.{PIPELINE_IID} by CI. MAJOR.MINOR live in conf/env/version.json; patch is the GitLab pipeline counter. setuptools-scm reads the tag at build time — python -c "import coupler; print(coupler.__version__)".

Known issues

See [Issue #1 — query_notes optional parameters dropped by MCP client][issue1].

[issue1]: https://gitlab.com/testmonkeyalpha/coupler/-/issues/1