yade-mcp-bridge

HTTP + SSE bridge that runs inside a YADE process and enables execution tools for yade-mcp.

Features

• Async tasks with progress polling. Submit a long simulation script (execute_task) and poll its status and paginated log while it runs (check_task_status).
• Live code during a run. Send execute_code at any time to inspect state or tune parameters mid-cycle — no need to bake probes into the script up front. It shares the simulation's __main__ namespace.
• Graceful interrupt. Stop a long cycling task on request (interrupt_task) without killing the YADE process.
• Unified output capture. Python print and YADE console output are interleaved in execution order in the task log.
• Zero third-party dependencies. Pure stdlib HTTP + SSE.

Architecture

YADE's Qt GUI objects are main-thread-only, so the bridge keeps execute_code on the main thread while running each task on its own thread — a long O.run() then never blocks the server or live code.

flowchart TD
    C[MCP client] -->|POST /command| S[HTTP + SSE server<br/>background thread]
    C -.->|GET /events| S
    S -->|execute_code → queue| Q[CodeExecutor<br/>one at a time]
    Q -->|Qt timer GUI / daemon console| P[pump thread]
    S -->|execute_task| T[ScriptRunner<br/>one thread per task]
    T -->|O.run| Y[YADE C++ sim loop]
    Y -.->|PyRunner callback| I[interrupt check]
    S -.->|doorbells| C

• HTTP + SSE server (background thread). A threaded HTTP server takes POST /<command> request/response calls and serves one long-lived GET /events SSE stream. It hands work off rather than touching YADE directly, so lightweight calls (status, interrupt) stay responsive even while a long task runs.
• execute_code pump. execute_code submissions are serialized through a queue drained by a single pump — so concurrent submissions run one at a time instead of racing on YADE state. The pump is a Qt timer on the main thread in GUI mode (mandatory for yade.qt objects), or a background daemon thread in console mode.
• Per-task threads. ScriptRunner runs each execute_task script on its own background thread, so a cycling O.run() holds that thread, not the server or the main thread.
• Cycle-gap interrupt. A PyRunner callback fires periodically during O.run() to honor a pending interrupt_task within ~one step.
• SSE doorbells. Two no-payload server→client events (task_status_changed, console_entry) tell the client when to re-poll; all data travels over the plain POST/GET calls.

HTTP protocol

The bridge is the source of truth for the wire contract — yade-mcp is a client of it. A request is POST /<command> with a JSON body carrying a request_id; the response echoes the request_id.

Server→client SSE events on GET /events: task_status_changed, console_entry. GET /health reports liveness and runtime mode.

Quick Start

In a YADE Python console, install the bridge using YADE's own interpreter:

import sys, subprocess
subprocess.check_call([sys.executable, "-m", "pip", "install", "--user", "yade-mcp-bridge"])

On PEP 668 externally-managed environments (pip refuses --user), see the bootstrap guide for a portable form.

Restart YADE, then in the Python console:

import yade_mcp_bridge
yade_mcp_bridge.start()

The bridge auto-detects the runtime: Qt timer in GUI mode, blocking poll in console mode.

Expected output (one line):

YADE MCP Bridge on http://localhost:9002, log: /your-working-dir/.yade-mcp/bridge.log

Detailed initialization logs go to bridge.log only (stdout shows warnings and errors).

Options

yade_mcp_bridge.start(
    host="localhost",   # Server host
    port=9002,          # Server port
    mode="auto",        # "auto", "gui", or "console"
)

Requirements

• Python >= 3.8
• YADE with Python bindings
• No third-party dependencies (stdlib HTTP + SSE)

Troubleshooting

Development

Run the bridge from source inside YADE:

import sys
sys.path.insert(0, '/path/to/yade-mcp/yade-mcp-bridge/src')
import yade_mcp_bridge
yade_mcp_bridge.start()

Code changes take effect on the next restart + start().

Relationship to MCP servers

This package is the in-process runtime only. Pair it with an MCP server that speaks its HTTP + SSE protocol — yade-mcp — for full client setup.

License: MIT (LICENSE).