From 5ef05a89324b29fd4e2492a12a1fb91933043ac6 Mon Sep 17 00:00:00 2001 From: Molecule AI Documentation Specialist Date: Sun, 10 May 2026 11:48:15 +0000 Subject: [PATCH] [app-lead-agent] docs(changelog+runtime): MODEL_PROVIDER deprecation + HTTP/SSE Hermes transport [app-lead-agent] App & Docs Lead approved. Two-file docs update: changelog gets 3 new 2026-05-10 entries (runtime#5 HTTP/SSE, core#280 MODEL_PROVIDER deprecation, core#291 self-delegation guard); runtime-mcp.mdx gets an Environment variables table with the canonical MOLECULE_MODEL var + deprecated MODEL_PROVIDER warning Callout + HTTP/SSE transport section with endpoint table and example. URLs all use git.moleculesai.app. Squash-merging. Co-authored-by: Molecule AI Documentation Specialist Co-committed-by: Molecule AI Documentation Specialist --- content/docs/changelog.mdx | 3 +++ content/docs/runtime-mcp.mdx | 48 ++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/content/docs/changelog.mdx b/content/docs/changelog.mdx index b74e9a4..ce161ad 100644 --- a/content/docs/changelog.mdx +++ b/content/docs/changelog.mdx @@ -89,6 +89,7 @@ Entries are published daily at 23:50 UTC. - **Admin auth runbook**: new `admin-auth.md` runbook documents the test-token route lockdown and `AdminAuth` middleware behaviour for operators. (`molecule-core` [#220](https://git.moleculesai.app/molecule-ai/molecule-core/pull/220)) - **Static `.github-token` fallback to git credential helper**: workspace-server now falls back to a static `.github-token` value when no git credential helper is configured, enabling simpler air-gapped setups. (`molecule-core` [#219](https://git.moleculesai.app/molecule-ai/molecule-core/pull/219)) - **Keyboard shortcuts in Toolbar help dialog**: all keyboard shortcuts are now documented in a Toolbar help dialog accessible from the canvas top bar. (`molecule-core` [#244](https://git.moleculesai.app/molecule-ai/molecule-core/pull/244)) +- **HTTP/SSE transport for Hermes MCP**: `a2a_mcp_server.py` now exposes `--transport=http --port=` for Hermes workspaces that prefer HTTP + SSE over stdio. Endpoints: `POST /mcp` (JSON-RPC), `GET /mcp/stream` (SSE), `GET /health`. (`molecule-ai-workspace-runtime` [#5](https://git.moleculesai.app/molecule-ai/molecule-ai-workspace-runtime/pull/5)) ### 🔧 Fixes @@ -102,6 +103,8 @@ Entries are published daily at 23:50 UTC. - **CI port `publish-runtime.yml` to `.gitea/workflows/`**: `publish-runtime.yml` migrated from `.github/workflows/` to `.gitea/workflows/` for Gitea Actions parity. (`molecule-core` [#211](https://git.moleculesai.app/molecule-ai/molecule-core/pull/211)) - **Docker base image digests pinned**: base image digests pinned in all Dockerfiles to ensure reproducible builds and prevent unexpected base image updates. (`molecule-core` [#199](https://git.moleculesai.app/molecule-ai/molecule-core/pull/199)) - **KeyboardShortcutsDialog corrected**: keyboard shortcuts dialog text corrected and min-clamp test expectations fixed. (`molecule-core` [#200](https://git.moleculesai.app/molecule-ai/molecule-core/pull/200)) +- **`MODEL_PROVIDER` env var deprecated**: the `MODEL_PROVIDER` env var was misnamed — it carried the model ID (e.g. `claude-opus-4-7`) despite its name, and was being misused as a runtime selector. The runtime now accepts `MODEL` and `MOLECULE_MODEL` as the canonical env var for model selection. `MODEL_PROVIDER` still works but emits a deprecation warning. (`molecule-core` [#280](https://git.moleculesai.app/molecule-ai/molecule-core/pull/280)) +- **`delegate_task` self-delegation guard**: calling `delegate_task` with your own workspace ID now returns an early actionable error instead of deadlocking the task lock. Previously self-delegation would hold `_run_lock`, timeout after 30 s, and waste the turn. (`molecule-core` [#291](https://git.moleculesai.app/molecule-ai/molecule-core/pull/291)) ### 📚 Docs diff --git a/content/docs/runtime-mcp.mdx b/content/docs/runtime-mcp.mdx index 60adcf0..12b4be0 100644 --- a/content/docs/runtime-mcp.mdx +++ b/content/docs/runtime-mcp.mdx @@ -102,6 +102,22 @@ example above. Drop it into your client's MCP settings file (typically `~/.cursor/mcp.json` for Cursor, the MCP Servers panel for Cline) and restart the client. +## Environment variables + +The following env vars are supported by the `molecule-mcp` wheel in addition to the +required trio (`WORKSPACE_ID`, `PLATFORM_URL`, `MOLECULE_WORKSPACE_TOKEN`): + +| Env var | What it controls | Default | +|---|---|---| +| `MOLECULE_MODEL` | **Canonical.** The model ID the workspace runtime uses — e.g. `claude-opus-4-7`, `minimax/MiniMax-M2.7-highspeed` | _(unset — template default)_ | +| `MODEL` | **Alias for `MOLECULE_MODEL`.** Accepted for backwards compatibility. | _(unset)_ | +| `MODEL_PROVIDER` | **Deprecated.** This var was previously misread as "runtime selector" (`claude-code`, `minimax`, etc.) but carried the model ID, causing the wrong model to be used. Prefer `MOLECULE_MODEL`. | _(unset — emits deprecation warning)_ | +| `MOLECULE_AGENT_SKILLS` | Comma-separated skill names — e.g. `research,code-review,memory-curation` | `[]` | + + + `MODEL_PROVIDER` is deprecated. It was misnamed — despite its name it carried the **model ID** (e.g. `claude-opus-4-7`), not the runtime/provider name. Setting it caused production incidents where the Claude CLI received `--model MODEL_PROVIDER_VALUE` and returned 404s. Use `MOLECULE_MODEL` instead. + + ## Optional — declare your identity & capabilities Three additional env vars control how your workspace appears on the @@ -206,6 +222,38 @@ Claude Code, Cursor, Cline, OpenCode, hermes-agent, or anything else that opens an MCP stdio connection. If your client speaks MCP, it speaks the wheel. +## HTTP/SSE transport for Hermes workspaces + +Hermes workspaces (which are MCP-native) can connect to the platform MCP +server over **HTTP + Server-Sent Events** instead of stdio. This is the +recommended path when Hermes runs as a standalone service rather than +inside a shell. + +The `a2a_mcp_server.py` in the runtime exposes two endpoints: + +| Endpoint | Method | Purpose | +|---|---|---| +| `/mcp` | `POST` | Receive JSON-RPC requests | +| `/mcp/stream` | `GET` | SSE stream for push-based responses | +| `/health` | `GET` | Health check | + +Start the server with the `--transport=http --port=` flags: + +```bash +python a2a_mcp_server.py \ + --transport=http \ + --port=8080 \ + --workspace-id= \ + --platform-url=https://.moleculesai.app \ + --workspace-token= +``` + + + The stdio transport (described in [Step 2](#step-2--add-it-to-your-runtime)) + remains the default. HTTP/SSE is an alternative for Hermes deployments + where a long-running daemon process is preferred over a stdio subprocess. + + ## Heartbeat & lifecycle The wheel spawns a daemon thread that POSTs `/registry/heartbeat` every