# 3dec Mcp

> ITASCA 3DEC 7.0 MCP server and 3DEC GUI bridge for ITASCA 3DEC workflows

- **Type:** MCP server
- **Install:** `agentstack add mcp-charlie-945-3dec-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [charlie-945](https://agentstack.voostack.com/s/charlie-945)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [charlie-945](https://github.com/charlie-945)
- **Source:** https://github.com/charlie-945/3dec-mcp

## Install

```sh
agentstack add mcp-charlie-945-3dec-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://www.itascacg.com/software/3dec) through the [Model Context Protocol](https://modelcontextprotocol.io/) -- 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](https://docs.astral.sh/uv/getting-started/installation/)** for development workflows

### Agentic Setup

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

```text
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:

```powershell
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:

```powershell
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:

```python
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:

```powershell
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:

```python
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:

```python
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/threedec_mcp/knowledge/resources/python_sdk_docs/runtime_compat_3dec700.json).
- Command docs combine official **3DEC 7.0** and **Itasca 9.4** pages; source scope is tracked in [command source compatibility](src/threedec_mcp/knowledge/resources/command_docs/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/threedec_mcp/knowledge/resources/fish_docs/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:

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

Focused checks:

```powershell
.\.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`:

```powershell
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](https://github.com/charlie-945)
- **Source:** [charlie-945/3dec-mcp](https://github.com/charlie-945/3dec-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-charlie-945-3dec-mcp
- Seller: https://agentstack.voostack.com/s/charlie-945
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.