elm-mcp v2 — one MCP server, the hub's correctness + our authoring brain

⚠️ Personal passion project. NOT an official IBM product. Use at your own risk.

elm-mcp v2 is a single MCP server you install once. Behind the scenes it is itself a client of IBM's official engineering-ai-hub MCP server — it re-exposes the hub's tools (correct, config-aware reads/writes, OSLC linking, and SysML) and adds elm-mcp's own authoring / orchestration tools on top.

So your AI host (Bob, Claude, Cursor) connects to one server and sees the whole toolset.

            ┌──────────── 1 install ────────────┐
 Bob ─────► │  elm-mcp v2  (this server)         │
            │   • elm_*  authoring/orchestration │
            │   • the hub's tools (federated)    │
            └───────────────┬───────────────────┘
                            │  hub token (configured once)
                            ▼
                  engineering-ai-hub  ──►  IBM ELM

Why

	The hub	elm-mcp v2 adds
Reads / search / schemas	✅ correct, config-aware	— (we defer to it)
Create / update / link / changesets	✅ correct	— (we defer to it)
SysML v2 models	✅ (its big strength)	—
Login	✅ gateway token	reused (one login)
Drafting · quality lint · interviews	—	✅ elm_lint_requirement, …
Build orchestration, compliance, gap/impact reports, exports	—	✅ (rolling in)

The hub is the reliable scribe; elm-mcp is the opinionated author. We don't re-implement the primitives the hub already does correctly — we orchestrate them and add the authoring intelligence on top.

Two modes

• Federated (preferred): set ELM_HUB_URL + ELM_HUB_TOKEN and the hub's tools light up alongside ours.
• Standalone: no hub configured → only elm-mcp's own tools (degraded but functional). The single install works either way.

The hub is IBM-hosted and must be provisioned for you (that's where the token comes from). v2 can't bundle it — it federates it.

Install — download + point at the file

No pip, no uv, no terminal commands you have to type. This works on locked-down machines: the server installs its own dependencies on first launch inside the process your host spawns — not as a command you run.

1. Download — green Code button → Download ZIP → Extract All → folder elm-mcp-v2-main. Keep it somewhere stable (your host runs the server from here — don't delete it).
2. Point your host at run_server.py with any Python 3.10+:

   {
     "mcpServers": {
       "elm-mcp-v2": {
         "command": "python3",
         "args": ["/path/to/elm-mcp-v2-main/run_server.py"],
         "env": {
           "ELM_HUB_URL": "https://your-hub-host/mcp/",
           "ELM_HUB_TOKEN": "your-hub-bearer-token"
         }
       }
     }
   }
   

   • macOS (Anaconda): "command": "/opt/anaconda3/bin/python3"
   • Windows: "command": "py"
3. Fully quit + reopen your host. Ask "run elm_health" → expect 🟢 Federated.

First launch self-installs mcp + httpx (~15–30s; needs PyPI access once), then instant. No ELM_HUB_TOKEN? It runs standalone with just elm-mcp's own tools. Fully air-gapped (no PyPI at all)? See bundled deps in the roadmap.

Updating

Say "update yourself" in your host (calls elm_update). It downloads the latest release from GitHub and replaces the files in the folder your host points at — no git, no manual re-download. Then fully restart your host. (Prefer doing it by hand? Re-download the ZIP and replace the folder.)

Dev / uv users: pip install -e ., or uvx --from git+https://github.com/brettscharm/elm-mcp-v2 elm-mcp-v2, also work.

Config (env)

var	meaning
ELM_HUB_URL	the hub's /mcp/ endpoint
ELM_HUB_TOKEN	bearer token for the hub gateway
ELM_HUB_VERIFY_SSL	1 to verify TLS (default 0 — test hubs use self-signed certs)

Never commit the token. Keep it in your host's MCP env block (or a local .env, which is gitignored).

How it works

• On startup the server opens one streamable-HTTP MCP session to the hub and holds it open (elm_mcp_v2/hub.py).
• list_tools returns our tools + the hub's (curated by _HIDE_HUB_TOOLS).
• call_tool runs our elm_* tools locally and forwards everything else to the hub, streaming its content back unchanged (elm_mcp_v2/server.py).

Status — v0.3.0

What's here:

• ✅ The federation core (connect → mirror tools → forward calls).
• ✅ Native tools: elm_health (federation status), elm_lint_requirement (quality gate), elm_update (in-place self-update for the download install).
• ✅ run_server.py — self-heal launcher (download + point-at-a-file; installs its own deps on first launch).
• ✅ Standalone fallback.

Roadmap (porting elm-mcp's authoring value on top of the hub):

• [ ] bundled-deps build for fully air-gapped machines
• [ ] elm_draft_requirements / Plan-Mode deep-drill → structured draft
• [ ] commit orchestration (drive the hub's create_requirement + changeset flow)
• [ ] elm_find_similar (semantic dedup over hub reads)
• [ ] elm_compliance_packet, elm_traceability_gaps, elm_change_impact
• [ ] export_module_to_xlsx, charts, trace/audit reports
• [ ] Jira import, PDF intake, team-activity log
• [ ] Bob modes / NL concierge tuned for the federated toolset
• [ ] tool-name curation (hide hub primitives we supersede)
• [ ] CI: build + connect-to-hub smoke test + routing eval

(elm-mcp v1, the standalone server, lives at github.com/brettscharm/elm-mcp.)