Skip to content

source-install.md

Latest commit

 

History

History
154 lines (101 loc) · 6.01 KB

source-install.md

File metadata and controls

154 lines (101 loc) · 6.01 KB
Raw

Developer Guide: Install and Run from Source

This guide is for contributors who want to run itasca-mcp from a local checkout, test changes before publishing to PyPI, or install the bridge from local source into a PFC embedded Python environment.

Runtime Split

This repository contains two separate runtimes:

  • itasca-mcp The MCP server package under src/itasca_mcp, running on standard Python >=3.10
  • itasca-mcp-bridge The bridge package under itasca-mcp-bridge, running inside PFC embedded Python. This directory is a git submodule: its own repository (yusong652/itasca-mcp-bridge) with an independent release cycle. itasca-mcp only records which bridge commit to use, not the bridge's files.

Treat them as separate installation targets even though they appear in the same working tree.

1. Clone and Install Dev Dependencies

Clone with the bridge submodule (it is required for Steps 3–7):

git clone --recurse-submodules https://github.com/yusong652/itasca-mcp.git

Already cloned without --recurse-submodules? itasca-mcp-bridge/ is empty until you initialize it:

git submodule update --init --recursive

Then, from the repository root:

uv sync --group dev

Run tests:

uv run pytest tests

Working with the bridge submodule

itasca-mcp-bridge/ is a pinned pointer (a gitlink, mode 160000) to one commit of the separate yusong652/itasca-mcp-bridge repo — itasca-mcp tracks a single SHA there, not the bridge's source files. Practical consequences:

  • After pulling itasca-mcp, re-sync the pin — the submodule working tree does not move on its own:

    git submodule update --init --recursive

  • To bump the bridge version, check out the desired commit inside itasca-mcp-bridge/, then stage the moved pointer explicitly in itasca-mcp:

    git add itasca-mcp-bridge && git commit -m "chore: bump itasca-mcp-bridge pin"

  • Push order matters: push the bridge repo first. The pinned commit must already exist on the public bridge repo, or other clones cannot fetch it.

  • git status showing modified: itasca-mcp-bridge (untracked content) usually just means the submodule working tree has local/untracked files relative to the pin — not that itasca-mcp is tracking bridge sources. Bump the pin only when you intend to.

2. Point Your MCP Client at the Local Checkout

If you want your MCP client to use local source instead of the published PyPI package, point it at the repository with uv run --directory:

{
  "mcpServers": {
    "itasca-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/itasca-mcp", "itasca-mcp", "--bridge-url", "ws://localhost:9001"]
    }
  }
}

The --bridge-url argument is optional (defaults to ws://localhost:9001). To connect to a bridge on a non-default port, pass --bridge-port instead of spelling out the whole URL — e.g. "args": [..., "itasca-mcp", "--bridge-port", "9002"] when the bridge was started with itasca_mcp_bridge.start(port=9002).

This is the simplest way to test MCP-side changes without building or publishing packages.

3. Run the Bridge Directly from Source

If you only need bridge-side changes to take effect in PFC, you do not need to install the bridge package at all. In the PFC IPython console:

%run C:/path/to/itasca-mcp/itasca-mcp-bridge/start_bridge.py

Notes:

  • Use forward slashes in the path.
  • Do not wrap the %run path in quotes.
  • Restart the bridge after source changes.

This is the fastest workflow for bridge development.

4. Install the Bridge from Local Source into Embedded Python

If you want to test the package installation path itself, install itasca-mcp-bridge from local source using the embedded Python interpreter from a terminal.

Pick the correct interpreter for your PFC version:

  • PFC 6.0 / 7.0: C:/Program Files/Itasca/.../exe64/python36/python.exe
  • PFC 9.0: C:/Program Files/Itasca/.../exe64/python310/python.exe

Example commands:

& "C:\Program Files\Itasca\PFC700\exe64\python36\python.exe" -m pip install --user -e C:\path\to\itasca-mcp\itasca-mcp-bridge
& "C:\Program Files\Itasca\ItascaSoftware900\exe64\python310\python.exe" -m pip install --user -e C:\path\to\itasca-mcp\itasca-mcp-bridge

Why use the embedded interpreter from a terminal:

  • It installs into the exact Python environment used by PFC.
  • It avoids relying on subprocess calls from inside the PFC console.
  • It is the most reliable workflow for editable installs.

The bridge package will pull a matching websockets version automatically:

  • Python 3.6 -> websockets==9.1
  • Python 3.10 -> websockets==16.0

5. Install from Inside PFC IPython

For PyPI-based installation inside the PFC console, use the addon.py at the repository root — it handles both pip.main(...) (PFC 6/7) and pip._internal.cli.main.main(...) (PFC 9) automatically and starts the bridge.

For source installs, prefer the terminal-based embedded-interpreter workflow from Step 4 instead of trying to drive an editable install from inside the PFC GUI console.

6. Verify the Environment

Verify the bridge package inside embedded Python:

& "C:\Program Files\Itasca\ItascaSoftware900\exe64\python310\python.exe" -c "import itasca_mcp_bridge, websockets; print(itasca_mcp_bridge.__version__); print(websockets.__version__)"

Then start the bridge in PFC and verify from your MCP client:

  1. Start the bridge in PFC with itasca_mcp_bridge.start() or %run .../start_bridge.py
  2. Restart the MCP client session
  3. Call itasca_list_tasks

7. Recommended Dev Loop

For most day-to-day work:

  1. Run uv sync --group dev
  2. Point your MCP client at the local checkout with uv run --directory
  3. Use %run .../itasca-mcp-bridge/start_bridge.py inside PFC
  4. Run uv run pytest tests
  5. Restart the MCP client and bridge after changes when needed