3DEC

License: MIT Python 3.10+ 3DEC 7.0 MCP

3dec>model new ;now, with LLM.

threedec-mcp connects AI agents to ITASCA 3DEC through the Model Context Protocol -- browse 3DEC command, Python API, and FISH documentation, execute code in the live 3DEC GUI, and manage long-running simulation tasks through natural conversation.

3dec>model cycle 1000 ;agent monitors.

Tools (12)

7 documentation tools -- browse and search 3DEC commands, Python API, FISH functions, and reference docs. No bridge required.

• threedec_browse_commands
• threedec_query_command
• threedec_browse_python_api
• threedec_query_python_api
• threedec_browse_fish
• threedec_query_fish
• threedec_browse_reference

5 execution tools -- synchronous code execution, task submission, progress/status checks, interruption, and task history. Requires the bridge running inside 3DEC GUI.

• threedec_execute_code
• threedec_execute_task
• threedec_check_task_status
• threedec_interrupt_task
• threedec_list_tasks

First-Time Setup

Prerequisites

• ITASCA 3DEC 7.0 installed
• Python 3.10+ for the MCP server environment
• 3DEC embedded Python 3.6 for the in-GUI bridge runtime
• Optional: uv for development workflows

Agentic Setup

Ask your coding agent to follow the setup guide end-to-end:

Read docs/3dec_setup.md and configure threedec-mcp for my 3DEC GUI and MCP client.
Verify with threedec_query_fish and threedec_execute_code.

Manual Setup

1. Install the MCP server from source

Run from this repository root:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e .

2. Install the bridge dependency in 3DEC Python

In PowerShell, from your 3DEC install directory:

cd "C:\path\to\3DEC\exe64"
.\python36.exe -m ensurepip
.\python36.exe -m pip install "websockets==9.1"

3. Start the bridge inside 3DEC

In the 3DEC IPython console:

import sys
bridge_src = r"C:\path\to\threedec-mcp-main\threedec-mcp-bridge\src"
if bridge_src not in sys.path:
    sys.path.insert(0, bridge_src)

import threedec_mcp_bridge
threedec_mcp_bridge.start(port=9001, mode="gui")

4. Register the MCP server

Example for Codex CLI / VSCode Codex:

codex mcp add threedec -- "C:\path\to\threedec-mcp-main\.venv\Scripts\threedec-mcp.exe" --bridge-url ws://localhost:9001
codex mcp list

If codex is not on PATH, use the full path to codex.exe.

5. Verify

Ask your MCP client to call:

import itasca as it
print("connected to embedded ITASCA Python")

Successful output confirms the agent is executing inside the live 3DEC GUI process through the bridge.

See 3DEC MCP Setup for the full Windows setup and troubleshooting flow.

Daily Startup

Once first-time setup is done, each new 3DEC session only needs the bridge restarted from the 3DEC IPython console:

import sys
bridge_src = r"C:\path\to\threedec-mcp-main\threedec-mcp-bridge\src"
if bridge_src not in sys.path:
    sys.path.insert(0, bridge_src)

import threedec_mcp_bridge
threedec_mcp_bridge.start(port=9001, mode="gui")

The MCP client configuration persists. After the bridge is running, documentation tools and execution tools are available to your agent.

Features

• 3DEC-focused MCP tools -- tool names, package names, bridge prompts, and docs resources use the threedec_* / threedec_mcp naming scheme.
• Hierarchical command browsing -- agents can browse command categories and exact command pages before generating command scripts.
• Python API search -- generated from official 3DEC 7.0 Python API pages, with runtime compatibility notes for embedded 3DEC Python.
• FISH function search -- browse official-grouped FISH docs or search by function names such as block.area and zone.stress.prin.
• Interactive REPL -- use threedec_execute_code for quick probes before committing to full model scripts.
• Task lifecycle management -- submit long-running simulations, monitor progress, interrupt tasks, and list task history.
• Bridge/runtime separation -- MCP runs in modern Python; the bridge runs inside the 3DEC GUI and owns all live itasca interaction.
• Version/source transparency -- command and FISH resources include compatibility notes so agents do not mistake parsed docs for a complete official mirror.

Documentation Data

The bundled docs are useful searchable resources, not a complete offline copy of the official manuals.

• Python API docs target 3DEC 7.0 and include runtime compatibility notes.
• Command docs combine official 3DEC 7.0 and Itasca 9.4 pages; source scope is tracked in command source compatibility.
• FISH docs are parsed from official Itasca HTML and include a generated prefix index; source scope is tracked in FISH source compatibility.

See 3DEC Documentation Data for resource layout and rebuild commands.

Troubleshooting

See 3DEC MCP Setup for the detailed checklist.

Common issues:

• ModuleNotFoundError: No module named 'threedec_mcp' -- install the MCP package with .\.venv\Scripts\python.exe -m pip install -e ..
• ModuleNotFoundError: No module named 'websockets' -- install websockets==9.1 into 3DEC embedded Python, not only into the project venv.
• codex is not recognized -- run the command with the full path to codex.exe, or add Codex CLI to PATH.
• Bridge unavailable -- start threedec_mcp_bridge inside the 3DEC GUI and confirm the MCP server uses ws://localhost:9001.
• import itasca.block fails -- use import itasca as it; in 3DEC 7.0, submodule imports are not the tested runtime pattern.

Development

Run tests from the repository root:

.\.venv\Scripts\python.exe -m pytest tests

Focused checks:

.\.venv\Scripts\python.exe -m pytest tests/test_docs_tool_contracts.py tests/test_phase2_tools.py
.\.venv\Scripts\python.exe -m pytest tests/test_versioned_schema.py tests/test_itasca_python_api.py

If you use uv:

uv sync --group dev
uv run pytest tests

Contributing

PRs and issues are welcome. Please keep MCP-side code and 3DEC GUI bridge code separate, and avoid mechanical PFC-to-3DEC documentation rewrites. New command/API/FISH docs should come from verified local or official Itasca sources.

License

MIT - see LICENSE.