itasca-mcp-bridge

English | 简体中文

Runtime bridge that runs inside an ITASCA product process (PFC, FLAC3D, 3DEC, MPoint, MassFlow) and exposes the product's Python SDK as an HTTP API, enabling execution tools for MCP servers such as itasca-mcp.

The bridge is product-neutral: it drives the host through the shared ITASCA command language / Python SDK rather than any product-specific API.

Features

• Async tasks with progress polling. Submit a long simulation script (execute_task message) and poll its status and paginated output while it runs (check_task_status).
• Live REPL during a run. Send execute_code against the running task's namespace at any time to inspect state or tune parameters mid-cycle — no need to bake probes into the script up front.
• Graceful interrupt. Stop a long cycling task on request (interrupt_task) without killing the product.
• Unified output capture. Python print and product console output (itasca.command() tables, list dumps, summaries) are interleaved in execution order in the task log.
• User console history. What the person types into the product GUI — cells in the IPython pane and lines at the command prompt — is recorded with its output and handed to the client on request (console_history), so an agent sees what happened in the GUI between its own calls.
• GUI activity. The plots and data files the person opens, closes or switches to, the items added to a plot, and the data files executed from the editor are recorded alongside, by name.

Architecture

ITASCA's Python SDK is main-thread-only, so the bridge keeps the simulation on the main thread and serves remote requests around it with three parts:

flowchart TD
    C[MCP client] -->|HTTP + SSE| S[HTTP server<br/>thread-per-request]
    S -->|submit → Future| Q[MainThreadExecutor<br/>queue]
    Q -->|Qt timer / blocking poll| M[product main thread<br/>itasca SDK + solver]
    M -.->|callback at cycle| CB[interrupt check<br/>+ snippet executor]
    CB -.-> M

• HTTP server (thread-per-request). A stdlib http.server (no asyncio, no third-party dependency) serves each request on its own thread, hands the work to the main thread, and awaits a Future. It never touches the SDK directly, so lightweight calls (status, interrupt) stay responsive even while a long task runs. Request/response is plain POST /<command>; the one server→client doorbell (task_status_changed) is pushed over a single long-lived GET /events Server-Sent Events stream.
• Main-thread queue. MainThreadExecutor holds a thread-safe queue that the main thread drains — via a Qt timer in GUI mode, or a blocking poll in console mode. Submitted task scripts (execute_task) run here.
• Cycle-gap callbacks. A cycling task holds the main thread, so two itasca.set_callback hooks keep it reachable: an interrupt check that stops the run (interrupt_task), and a snippet executor that runs execute_code REPL calls in the gaps between cycles — sharing the task's __main__ namespace for live inspection and tuning.

HTTP protocol

The bridge is the source of truth for the wire contract — MCP servers such as itasca-mcp are clients of it. Each request is a POST /<command> whose body is a JSON object carrying a request_id; the JSON response echoes the request_id. The server→client doorbells ride a single long-lived GET /events SSE stream (payload-free task_status_changed and console_entry events that prompt the client to re-poll), and GET /health is a liveness probe. The commands are product-neutral:

Quick Start

Run inside the product's Python (GUI IPython console or console CLI):

Install from PyPI

In the product's IPython console:

from pip._internal.cli.main import main as pip_main
pip_main(["install", "--user", "itasca-mcp-bridge"])

import itasca_mcp_bridge
itasca_mcp_bridge.start()

itasca_mcp_bridge.status() tells you the version, the address and whether the engine is idle or busy with a task. itasca_mcp_bridge.stop() shuts the bridge down and leaves the product as it was before start(); start() brings it back in the same session.

Headless, agent-launched

A console build runs the data file passed as its first argument, so an agent can bring the stack up itself — no GUI, nobody at the keyboard:

model new
python import itasca_mcp_bridge
python itasca_mcp_bridge.start(mode="console")

$ <product>_console.exe start_bridge.dat    # e.g. pfc3d900_console.exe, flac3d900_console.exe

start() does not return, so nothing after that line runs; everything else goes through the MCP tools.

The bridge is stdlib-only (http.server + Server-Sent Events), so there is no third-party dependency to install or version-match — it lands cleanly in any ITASCA embedded Python (3.6+) with no pins.

On every start() the bridge checks PyPI for a newer release (5-second timeout; the Tsinghua mirror is tried when pypi.org is unreachable) and self-upgrades before starting. The check is best-effort -- offline machines and failed installs fall back to the installed version. To pin the installed version, call start(auto_upgrade=False) or set the environment variable ITASCA_MCP_BRIDGE_AUTO_UPGRADE=0. Corporate mirrors can be configured with ITASCA_MCP_PIP_INDEX_URL.

After a self-upgrade the banner is followed by a short "What's new" list of the release highlights you just received; call itasca_mcp_bridge.whats_new() to reprint it anytime.

Run from a source checkout

%run C:/path/to/itasca-mcp-bridge/start_bridge.py

Use forward slashes in the path. Do not wrap it in quotes.

Code changes take effect on the next %run, so this is the preferred workflow during development.

The bridge auto-detects the runtime: a Qt timer when the host is a GUI application, a blocking loop otherwise. The banner reports which pump won, so Mode is the first thing to check if a console start looks unreachable.

Expected output:

============================================================
Itasca MCP Bridge Server
============================================================
  Version:  0.6.2
  URL:      http://localhost:9001
  Log:      /your-working-dir/.itasca-mcp-bridge/bridge.log
  Mode:     Qt timer
============================================================

Requirements

• An ITASCA product with an embedded Python interpreter. Verified on PFC, FLAC3D, 3DEC, MPoint and MassFlow, GUI and console builds, across the 6.0, 7.0 and 9.x product generations.
• Python >= 3.6 (6.0/7.0 products embed Python 3.6; 9.x products embed Python 3.10).
• No third-party runtime dependency: the transport is stdlib-only (http.server + Server-Sent Events).

Troubleshooting

Relationship to MCP servers

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

License: MIT.