itasca-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| ITASCA_MCP_BRIDGE_URL | No | The URL of the active ITASCA bridge service (e.g., http://localhost:9002). This is required for execution tools to connect to a running PFC process. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
ITASCA MCP server for PFC, FLAC, 3DEC, MPoint, and MassFlow. Provides tools for browsing/searching engine documentation (select the engine via the required 'software' parameter) and for executing simulation tasks and managing runs through an itasca-mcp-bridge service running inside the Itasca engine GUI, or in a console build started unattended.
Documentation is four trees behind two tools: itasca_browse_doc walks one tree by path (source = commands, python_api, fish or reference) and itasca_query_doc searches by keywords, across all trees unless a source is given. Version defaults to 9.0; pass 6.0/7.0 for older PFC, FLAC or 3DEC installs.
Execution tool responses may carry _context: what happened in the engine GUI since the previous call. It is not part of the tool's result; read it to follow what the user is doing. _context.user_console lists what the USER typed: 'python' = IPython pane, 'command' = command prompt; 'queued' = not run yet (engine busy), its output follows later as 'ran'. _context.gui lists plots and data files opened or switched to, by the user or your own code ('active' = the one in front), and plot items added, removed or changed. 'executed' = the USER ran that data file from its editor ('master' = the project's master files); 'saved' = the USER saved it, 'diff' being their changes since you last saw the file. To see one, read the file or export the plot as an image. 'unsaved' = data files the USER is editing right now, with changes not yet on disk: tell them before writing one. kind 'dialog' = a modal dialog came up in the GUI ('open') or went away ('closed'); while one is open the engine may be waiting on the USER, who has to answer it.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| extensions | {
"io.modelcontextprotocol/ui": {}
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| itasca_browse_docA | Browse ITASCA documentation by path, like ls + cat over one documentation tree. source picks the tree: commands (Itasca command syntax and keywords), python_api (the itasca Python SDK), fish (FISH intrinsic functions: name, signature, which versions have it, whether it is 2D or 3D only), reference (contact/constitutive/joint model properties, range elements, plot items). Each level lists what is below it, so start at the top of a tree when unsure and descend. Use itasca_query_doc when you only have keywords; its results are paths for this tool. |
| itasca_query_docA | Search ITASCA documentation by keywords, like grep; every hit carries a path for itasca_browse_doc. Without source it searches commands, python_api, fish and reference together, so 'ball pos' shows the FISH intrinsic and the Python method side by side. With source it searches one tree and adds that tree's hints (available categories or namespaces, SDK fallback hints) when nothing matches. |
| itasca_execute_taskA | Submit a Python script file for asynchronous execution in the Itasca engine. Returns a task_id immediately; the script runs in the background. Companion tools manage the lifecycle:
While the task is cycling, itasca_execute_code shares the same main namespace in the engine's main thread, so you can inspect or modify simulation state live — probe progress, tune parameters mid-run, swap callbacks, or trigger early termination via a sentinel variable. Submit with reasonable starting values and refine as the task runs. Console output from itasca.command() inside the script (table dumps, list output, command summaries) is captured into the task log alongside Python prints, visible through itasca_check_task_status. Script-writing rules:
|
| itasca_check_task_statusA | Check status and paginated output for a submitted Itasca task. Output combines Python prints and Itasca console output from itasca.command() calls (table dumps, list output, command summaries) interleaved in execution order. Use skip_newest / limit to paginate, or filter to keep only matching lines. |
| itasca_list_tasksA | List tasks tracked by the bridge, newest first. Read-only. Each entry carries task_id, status (pending / running / completed / failed / interrupted), description, entry_script, start_time, end_time and elapsed_time; total_count gives the size of the full history for paging via skip_newest + limit. Task history is persisted in the engine working directory and survives GUI restarts. Use this to recover a task_id from an earlier session, to see what is running or recently finished, or as a cheap bridge-connectivity check. For a task's output and result use itasca_check_task_status; to submit a script use itasca_execute_task. |
| itasca_interrupt_taskA | Request interruption of a pending or running Itasca task. Returns as soon as the request is accepted; it does not wait for the task to stop. Confirm the stop and read the output produced so far with itasca_check_task_status. Only the script stops; the engine state is preserved, so you can inspect it with itasca_execute_code or continue from it with a new itasca_execute_task. Tasks already completed, failed or interrupted return an error. If the task_id is unknown, find it with itasca_list_tasks. |
| itasca_execute_codeA | Execute Python code synchronously in the running Itasca engine process. Returns stdout and an optional result variable immediately. Code runs in the engine's main thread, sharing the same main namespace as any running task — side effects persist and are immediately visible to the task on its next cycle. The tool stays responsive while a task submitted via itasca_execute_task is cycling (calls interleave at cycle gaps), so use it as a live REPL — nothing has to be pre-scripted into the task up front. Typical uses:
Environment: the engine's embedded Python interpreter (Itasca 9+ → Python 3.10, pre-9 → Python 3.6 or older; the product+version is encoded in sys.executable, e.g. PFC900). When unsure, check sys.version_info before relying on newer syntax. Code-writing rules (shared with itasca_execute_task):
Synchronous semantics: the request blocks until the code finishes or hits the timeout (default 10s, max 20s), and output is returned in full. The call is not tracked by itasca_list_tasks and cannot be interrupted mid-execution. For cancellable, pollable, or background work, submit via itasca_execute_task instead. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 7 tools
Each tool occupies a clearly distinct slot: query_doc (keyword search) vs browse_doc (path traversal), execute_code (synchronous inline) vs execute_task (async script file), and the task trio check_task_status / interrupt_task / list_tasks. The descriptions explicitly contrast the potentially confusable pairs and cross-reference each other for next steps, leaving no room for misselection.
Every tool uses the same itasca_ prefix plus a verb_noun pattern (browse_doc, query_doc, execute_code, execute_task, check_task_status, interrupt_task, list_tasks). The lifecycle tools even share the _task suffix, making the grouping obvious from names alone.
Seven tools is tightly scoped for an engine bridge: two for docs, two for code execution, three for async task lifecycle. Nothing feels redundant and no tool is a trivial wrapper, since each has a separate mechanism (sync/async, poll/interrupt/history).
The surface covers docs lookup, sync and async execution, plus full task lifecycle including status output, interruption, and persisted history — a solid closed loop. Minor gaps remain: there is no dedicated tool to write/upload the script file that execute_task consumes, and no way to wait/join on a task or prune task history, though both are workable via execute_code or polling.