3dec Mcp

3dec-mcp

[](LICENSE) [](https://www.python.org/) [](https://www.itascacg.com/software/3dec) [](https://modelcontextprotocol.io/)

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](docs/3dec_setup.md) 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](src/threedecmcp/knowledge/resources/pythonsdkdocs/runtimecompat_3dec700.json).
• Command docs combine official 3DEC 7.0 and Itasca 9.4 pages; source scope is tracked in [command source compatibility](src/threedecmcp/knowledge/resources/commanddocs/source_compatibility.json).
• FISH docs are parsed from official Itasca HTML and include a generated prefix index; source scope is tracked in [FISH source compatibility](src/threedecmcp/knowledge/resources/fishdocs/source_compatibility.json).

See [3DEC Documentation Data](docs/3dec-docs-data.md) for resource layout and rebuild commands.

Troubleshooting

See [3DEC MCP Setup](docs/3dec_setup.md#troubleshooting) 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](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: charlie-945
• Source: charlie-945/3dec-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.