itasca-mcp

Overview Schema Source Related Servers Discussions Admin

itasca_execute_code

Execute Python code synchronously inside a running ITASCA engine to query model state, tune parameters, and export plots live while a simulation task cycles.

Instructions

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:

Query model state and read Itasca command output: itasca.command('ball list') etc. — table dumps, list output, and command summaries are captured and interleaved with Python prints in execution order
Live inspection and tuning during a running task: check forces or contact statistics, modify parameters, swap callbacks, set sentinel variables the task reads each cycle
Create and export plots: itasca.command('plot ...')

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):

Multi-line itasca.command("""...""") batches are normalized to one engine call per command, keeping the bridge reachable mid-batch. Normalization recognizes itasca.command through its import name; call it through that name directly — rebinding via intermediate variables (_it = itasca) bypasses it and the output carries a bridge warning.
Pass each FISH definition block (fish define / fish operator / legacy bare define, through its terminating standalone end) whole, in ONE itasca.command() string; feeding one line-by-line leaves the engine blocked in interactive FISH mode until completed manually in the GUI console. Per-line loops are fine for ordinary commands.
program call '<file>' (.p3dat / .p2dat / .dat / ...) is supported: the bridge runs the file inline, one command per engine call, so the bridge stays reachable, the run stays interruptible, and the file's output arrives command by command.

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.

Input Schema

Name	Required	Description	Default
`code`	Yes	Python code to execute in the Itasca engine user console
`timeout`	No	Seconds before the bridge aborts the snippet; longer work belongs in itasca_execute_task.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.5.1Oct 24, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses main-thread execution, persistent side effects, blocking until completion or timeout, non-trackability by itasca_list_tasks, inability to interrupt mid-execution, and bridge behavior for command batching and FISH definitions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the core synchronous semantics and well-structured with bullets. The code-writing rules are necessary but lengthy, making it less concise than ideal, though not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition is complete for a complex code-execution tool with an output schema. It covers environment, runtime semantics, constraints, failure/interruption behavior, parameter handling, and sibling-tool alternatives.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful execution constraints for the code parameter, including itasca.command normalization, whole FISH blocks, and program call behavior, plus timeout usage guidance pointing longer work to itasca_execute_task.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

It states a precise verb and resource: execute Python code synchronously in the Itasca engine process. It also distinguishes itself from itasca_execute_task by emphasizing synchronous execution and shared engine state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly gives typical uses such as live model inspection, command output capture, parameter tuning, and plot creation. It also names the alternative and condition: cancellable, pollable, or background work should use itasca_execute_task instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server