From effb534f645d05fa6ea635c4c09a9e6bfadd32c9 Mon Sep 17 00:00:00 2001 From: Molecule AI SDK-Dev Date: Sat, 16 May 2026 22:14:05 +0000 Subject: [PATCH 1/2] docs(mcp): update KI-007 to reflect SDK KI-009 resolution Marks the MCP KI-007 as fully resolved. The Python SDK's run_heartbeat_loop() / run_agent_loop() now accept stop_event, resolving the underlying heartbeat-cleanup issue that KI-007 pointed to as SDK KI-009. Co-Authored-By: Claude Opus 4.7 --- known-issues.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/known-issues.md b/known-issues.md index 5958fbe..96fb27e 100644 --- a/known-issues.md +++ b/known-issues.md @@ -180,21 +180,21 @@ test documenting the known `optional().nullable()` zod-to-json-schema quirk. ## KI-007 — MCP server heartbeat tools are read-only; actual heartbeat lives in the Python SDK **File:** `src/tools/remote_agents.ts` (heartbeat tool) -**Status:** Resolved — clarified scope +**Status:** ✅ Resolved **Severity:** Low -### Clarification +### Resolution The MCP server's remote-agent tools (`list_remote_agents`, `get_remote_agent_state`, `check_remote_agent_freshness`, `get_remote_agent_setup_command`) are **read-only queries** — they do not drive any background heartbeat loop. The actual -`run_heartbeat_loop()` that sends heartbeats from a remote agent lives in the -Python SDK (`molecule_sdk_python/molecule_agent/client.py`). +`run_heartbeat_loop()` lives in the Python SDK's `molecule_agent/client.py` +(standalone `molecule-sdk-python` repo). The heartbeat cleanup issue (heartbeat loop continues after the controlling MCP -client disconnects) is tracked as **SDK KI-009** in `molecule-sdk-python/known-issues.md`. - -### Suggested fix (SDK side) -Expose a `stop_event` parameter or `stop()` method on `RemoteAgentClient` so the -callers (MCP client, shell wrapper) can signal the loop to exit cleanly. The -Python SDK's `run_heartbeat_loop()` should check `threading.Event` or accept a -`stop_on: asyncio.Event` argument. See `molecule-sdk-python/known-issues.md`. \ No newline at end of file +client disconnects) was tracked as **SDK KI-009**. It has been resolved: +`RemoteAgentClient.run_heartbeat_loop()` and `run_agent_loop()` now accept a +`stop_event: threading.Event | None` parameter. Callers signal clean shutdown by +calling `stop_event.set()` from a SIGTERM handler or another thread. The loop +checks the event at the start of each iteration (before `max_iterations`) and +exits with return value `"stopped"`. See `molecule-sdk-python`'s +`known-issues.md` (KI-009 resolved) and `molecule_agent/__init__.py` for usage. \ No newline at end of file -- 2.52.0 From cb01fc24010a5b4cc3ce28f1da84b6ad01cd27aa Mon Sep 17 00:00:00 2001 From: Molecule AI SDK-Dev Date: Sat, 16 May 2026 22:46:17 +0000 Subject: [PATCH 2/2] docs(mcp): fix stale SDK reference in CLAUDE.md Clarifies that the MCP server uses its own TypeScript API client (src/api.ts), not the Python SDK. The Python SDK is for remote agents running outside the platform; the MCP server is an operator- side tool that bridges MCP clients to the platform REST API. Also removes the "via the platform SDK" phrasing from the Postgres section (server reads via REST API, not SDK). Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5451007..6c34089 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -96,7 +96,7 @@ The workflow: ### APIs Connected -The server connects to the Molecule AI platform REST API. See the platform SDK (`../molecule-sdk-python`) for the underlying API client used. +The server connects to the Molecule AI platform REST API via its own TypeScript client (`src/api.ts`). It does not use the Python SDK (`molecule-sdk-python`) — the Python SDK is for remote agents that run outside the platform; this server runs as an MCP bridge *on* the operator side. ### Environment Variables @@ -110,7 +110,7 @@ For local development, copy `.env.example` → `.env` and fill in values. ### Postgres -Platform data lives in Postgres (source of truth). The server reads data via the platform SDK — it does not connect to Postgres directly. +Platform data lives in Postgres (source of truth). The server reads data via the platform REST API — it does not connect to Postgres directly. ## TypeScript Conventions -- 2.52.0