threedec-mcp

MCP server and embedded bridge for controlling ITASCA 3DEC from an AI agent.

This repository is a 3DEC-focused fork derived from the pfc-mcp architecture. It keeps the two-runtime design:

src/threedec_mcp/: MCP server package for agent clients and documentation tools.
threedec-mcp-bridge/: bridge runtime that runs inside the 3DEC GUI embedded Python process.

Current Status

This is a working 3DEC MCP fork, but the bundled documentation data is not a complete official manual mirror.

Tool names use the threedec_* prefix.
Bridge package names use threedec_mcp_bridge.
Runtime environment variables use THREEDEC_MCP_*.
Python API resources are generated from official 3DEC 7.0 pages listed in scripts/python_api_new.txt.
Python runtime caveats for 3DEC 7.0 are tracked in src/threedec_mcp/knowledge/resources/python_sdk_docs/runtime_compat_3dec700.json.
Command resources combine official 3DEC 7.0 and Itasca 9.4 pages. Source scope and runtime checks are tracked in src/threedec_mcp/knowledge/resources/command_docs/source_compatibility.json.
FISH resources are parsed from official Itasca HTML and include a generated prefix index. Source scope and runtime caveats are tracked in src/threedec_mcp/knowledge/resources/fish_docs/source_compatibility.json.
The bridge has been tested with 3DEC 7.0 GUI embedded Python 3.6 using websockets==9.1.

Tools

Documentation tools:

threedec_browse_commands
threedec_query_command
threedec_browse_python_api
threedec_query_python_api
threedec_browse_fish
threedec_query_fish
threedec_browse_reference

Execution tools:

threedec_execute_code
threedec_execute_task
threedec_check_task_status
threedec_interrupt_task
threedec_list_tasks

Install From Source

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 .

If you use uv, this is also supported:

uv sync --group dev
uv run threedec-mcp

Direct MCP server smoke test:

.\.venv\Scripts\threedec-mcp.exe --bridge-url ws://localhost:9001

Start The Bridge In 3DEC

The live 3DEC model can only be controlled after the bridge is started inside the 3DEC GUI.

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

See docs/3dec_setup.md for the full Windows + 3DEC GUI + VSCode Codex setup, including dependency installation for the embedded 3DEC Python.

VSCode Codex MCP Config

If codex is available on PATH:

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

If PowerShell says codex is not recognized, run the same command with the full path to codex.exe.

Verify

Ask the MCP client or agent to call threedec_execute_code:

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

Use threedec_execute_code for tiny probes and threedec_execute_task for model creation, long cycling, solves, exports, and parameter sweeps.

Documentation Data

See docs/3dec-docs-data.md for the resource layout, source-status notes, and rebuild commands.

Development

Useful checks:

python -m pytest tests/test_versioned_schema.py tests/test_itasca_python_api.py tests/test_command_splitter.py tests/test_command_log.py

Broader contract checks may also be useful when changing tool payloads:

python -m pytest tests/test_phase2_tools.py tests/test_tool_contracts.py tests/test_docs_tool_contracts.py

License

MIT. See LICENSE.

MCP Servers