Vulcan MCP

Quick Start • Capabilities • MCP Tools • Practical Examples • Tutorial • How-To Guides • Documentation • Contributing

Connect **Vulcan 12 ** directly to Artificial Intelligence assistants (Google Antigravity, Claude Desktop, Claude Code, Cursor, VS Code) via the open Model Context Protocol (MCP) standard.

Seamlessly query block models (.bmf), audit 3D triangulations and solids (.00t), explore ISIS drillhole databases (.dhd.isis), interact with CAD design layers (.dgd.isis), inspect color legends (.scd), capture the Envisage 3D viewport, and execute native PyVulcan automation scripts using natural language.

Key Capabilities

Project Structure

The repository uses a decoupled architecture to guarantee 100% compatibility between Vulcan's embedded legacy interpreter and modern AI clients:

vulcan-mcp/
├── assets/                         # Visual identity and branding
├── plugin/                         # Internal plugin for Maptek Vulcan 12 (Python 3.5.2)
│   ├── server.py                   # Synchronous TCP socket listener in Vulcan's main thread
│   ├── wire.py                     # Custom JSON serializer for SWIG/C++ types & uint32 protocol
│   └── handlers/                   # Mining domain controllers (block models, drillholes, CAD, etc.)
│
├── src/vulcan_mcp/                 # External MCP Server (Python 3.11+ / FastMCP)
│   ├── server.py                   # The 9 Master Compound Tools exposed to AI agents
│   ├── client.py                   # Asynchronous TCP client communicating with Vulcan plugin
│   └── protocol.py                 # Binary framing network protocol & environment config
│
├── docs/                           # Diátaxis Documentation Center
│   ├── README.md                   # Documentation index and Diátaxis matrix
│   ├── TUTORIAL_FIRST_STEPS.md     # Tutorial: 15-minute hands-on guide from 0 to 100
│   ├── HOW_TO_GUIDES.md            # How-To Guides: Step-by-step recipes for mining tasks
│   ├── MCP_TOOLS_REFERENCE.md      # Full parameter reference for all 9 MCP tools
│   ├── MAPTEK_PYTHON_SDK.md        # Maptek Vulcan Python SDK & SDK 2.0 mapping catalog
│   ├── VULCAN_FILE_FORMATS.md      # Technical specification of Vulcan file formats
│   └── ARCHITECTURE_AND_SECURITY.md# In-depth architecture, memory management & security
│
├── .agents/plugins/vulcan-mcp/     # Packaged plugin for Google Antigravity
├── tests/                          # 3-Layer Automated Test Suite
├── LICENSE                         # Apache License 2.0
├── NOTICE                          # Legal notices and Maptek Pty Ltd trademarks
└── pyproject.toml                  # Packaging, Ruff, Mypy, and Pytest configuration

Communication Architecture

Maptek Vulcan 12 Desktop embeds Python 3.5.2 tightly linked to its C++/SWIG graphics engine (maptek.vulcan). Modern MCP servers require Python 3.11+.

The system bridges both worlds across two processes using a local TCP loopback socket on 127.0.0.1:9877:

flowchart LR
    A["AI Agent<br/>(Antigravity / Claude / Cursor)"] <-->|"MCP (Stdio)<br/>uvx vulcan-mcp-server"| B["MCP Server<br/>(src/vulcan_mcp)"]
    B <-->|"TCP 127.0.0.1:9877<br/>uint32 framing + JSON"| C["Vulcan Plugin<br/>(plugin/server.py)"]
    C <-->|"C++ / SWIG Bindings"| D["Maptek Vulcan 12 Desktop<br/>(maptek.vulcan & vulcan_gui)"]

Quick Start (in 2 Steps)

You don't need to manually create or configure virtual environments if you have uv / uvx installed.

Step 1: Start the Plugin inside Maptek Vulcan 12

1. Open your mining project in Maptek Vulcan 12 Desktop (Envisage).
2. In Vulcan's top menu, go to File > Python Script (or type py in Vulcan's command window).
3. Select the file plugin/server.py.
4. Check the box "Run in shell window" and click OK.
5. A Windows console window will open confirming the listener is running:

==============================================================
[Vulcan MCP] Vulcan MCP Listener started on 127.0.0.1:9877
[Vulcan MCP] Working directory: C:\your_mining_project
[Vulcan MCP] Registered domains: block_model, canvas, design, drillholes, execute_code, legend, system, triangulation
[Vulcan MCP] Token authentication: DISABLED (localhost open mode)
[Vulcan MCP] Keep this window open while using your AI client. Ctrl+C to stop.
==============================================================

Step 2: Connect your AI Client

Choose the mode that best fits your workflow:

Mode A: For End Users (Zero-Install via uvx)

No repository cloning required. The AI client pulls and runs the MCP server on the fly:

• In Claude Desktop / Cursor / VS Code: Add this block to your MCP config file (claude_desktop_config.json, .cursor/mcp.json, etc.):

  {
    "mcpServers": {
      "vulcan": {
        "command": "uvx",
        "args": [
          "luiccian-vulcan-mcp"
        ]
      }
    }
  }
  

• In Claude Code (CLI):

  claude mcp add -s user vulcan -- uvx luiccian-vulcan-mcp
  

Mode B: For Developers (with uv run on a local clone)

If you are developing or modifying the codebase and want hot-reloading:

• In Google Antigravity: The plugin in .agents/plugins/vulcan-mcp/ is already preconfigured dynamically with ${workspaceFolder}.

• Manual Local Configuration:

  {
    "mcpServers": {
      "vulcan": {
        "command": "uv",
        "args": [
          "run",
          "--directory",
          "C:\\path\\to\\vulcan-mcp",
          "vulcan-mcp-server"
        ]
      }
    }
  }
  

The 9 Master Tools Catalog

See complete parameter specifications and JSON schemas in docs/MCP_TOOLS_REFERENCE.md.

Practical & Simple Examples

Here are 4 representative mining workflows demonstrating the natural language user prompt, the resulting MCP tool call in JSON, and the returned data.

1. Project Health Diagnostic & File Inventory

• Natural Language Prompt:

  "What mining files and block models are available in the open Vulcan project?"

• MCP Tool Call:

  {
    "tool": "vulcan_system",
    "arguments": {
      "action": "project_info"
    }
  }
  

• Returned Response:

  {
    "connected": true,
    "project_dir": "C:\\MiningProjects\\Deposit_Cu_Au",
    "inventory": {
      "block_models": { "count": 2, "files": ["global_deposit.bmf", "phase1.bmf"] },
      "triangulations": { "count": 4, "files": ["topo_2026.00t", "final_pit.00t"] },
      "drillhole_dbs": { "count": 1, "files": ["rc_drilling.dhd.isis"] }
    }
  }
  

2. Mineral Resource Estimation with Cutoff Grade

• Natural Language Prompt:

  "Calculate the tonnage and mean copper grade (CUT) in 'phase1.bmf' using a cutoff >= 0.40% and density of 2.7 t/m³."

• MCP Tool Call:

  {
    "tool": "vulcan_block_model",
    "arguments": {
      "action": "stats",
      "name": "phase1.bmf",
      "variable": "CUT",
      "cutoff": 0.40,
      "default_density": 2.7
    }
  }
  

• Returned Response:

  {
    "total_blocks": 120500,
    "blocks_above_cutoff": 35210,
    "total_volume": 2816800.0,
    "tonnage": 7605360.0,
    "mean_grade": 0.785,
    "variable": "CUT",
    "cutoff": 0.4
  }
  

3. High-Grade Intercept Detection & 3D Display

• Natural Language Prompt:

  "Find the top 5 gold intercepts in the ASSAYS table of 'rc_drilling.dhd.isis' and display them in Envisage."

• MCP Tool Call:

  {
    "tool": "vulcan_drillholes",
    "arguments": {
      "action": "high_grade",
      "name": "rc_drilling.dhd.isis",
      "table": "ASSAYS",
      "field": "AU",
      "top_n": 5
    }
  }
  

• Returned Response:

  {
    "database": "rc_drilling.dhd.isis",
    "table": "ASSAYS",
    "field": "AU",
    "intercepts": [
      { "hole_id": "RC-104", "from": 84.0, "to": 88.0, "grade": 12.45, "length": 4.0 },
      { "hole_id": "RC-112", "from": 120.0, "to": 126.0, "grade": 8.70, "length": 6.0 }
    ]
  }
  

4. Direct Automation with PyVulcan Scripting

• Natural Language Prompt:

  "Run a script inside Vulcan that reports the active window title in the report console."

• MCP Tool Call:

  {
    "tool": "vulcan_execute_code",
    "arguments": {
      "code": "import maptek.vulcan_gui as vg\nresult = {'window_name': vg.get_window_name() if hasattr(vg, 'get_window_name') else 'Envisage'}"
    }
  }
  

• Returned Response:

  {
    "success": true,
    "result": { "window_name": "Envisage - [C:\\MiningProjects\\Deposit_Cu_Au]" }
  }
  

Configuration & Environment Variables

Both the plugin inside Maptek Vulcan and the external MCP server automatically read operating system environment variables (os.environ):

Authentication & Security

Zero .env Philosophy

You do not need to create or manage insecure .env files containing plain text passwords that might accidentally be committed to Git. Tokens are managed at the Windows OS environment level:

# 1. Generate and save a token permanently in your Windows user account:
$token = python -c "import secrets; print(secrets.token_urlsafe(32))"
[System.Environment]::SetEnvironmentVariable('VULCAN_MCP_TOKEN', $token, 'User')

# 2. Verify that it was stored correctly:
[System.Environment]::GetEnvironmentVariable('VULCAN_MCP_TOKEN', 'User')

# 3. (Optional) To revoke and revert to open mode:
[System.Environment]::SetEnvironmentVariable('VULCAN_MCP_TOKEN', $null, 'User')

Strict Non-Loopback Network Rule

• If you bind VULCAN_MCP_HOST to a non-loopback interface (e.g., 0.0.0.0 or a LAN IP), the plugin strictly refuses to start (RuntimeError) unless VULCAN_MCP_TOKEN is set, preventing unauthorized remote script execution.

🛠️ Diagnostics & FAQ

3-Layer Automated Testing Harness

The project includes automated testing infrastructure organized across 3 validation tiers:

Code Coverage Metrics

uv run --no-sync pytest tests/test_vulcan_mcp.py tests/test_mcp_tools.py tests/test_agent_eval.py -v --cov=src/vulcan_mcp

🔄 CI/CD & Automated Workflows

The repository uses coordinated, path-filtered GitHub Actions to ensure maximum speed, security, and reproducibility on Windows:

🏷️ Release Cadence, Versioning & Tag Creation

We strictly adhere to Semantic Versioning (SemVer 2.0.0):

• MAJOR (X.0.0): Incompatible API breaks or major protocol overhaul.
• MINOR (0.X.0): Backwards-compatible new MCP tools, handlers, or capabilities.
• PATCH (0.0.X): Bug fixes, dependency bumps, performance optimizations, and documentation updates.

5-Target Synchronized Versioning (scripts/bump_version.py)

To prevent version discrepancies between metadata files, use the unified version bumper:

# Preview changes without modifying files:
python scripts/bump_version.py patch --dry-run

# Execute version bump (patch, minor, major, or explicit version):
python scripts/bump_version.py patch
python scripts/bump_version.py minor
python scripts/bump_version.py 0.3.1

The script automatically synchronizes all 5 points in a single atomic pass:

1. pyproject.toml ([project] version = "...")
2. src/vulcan_mcp/__init__.py (__version__ = "...")
3. .agents/plugins/vulcan-mcp/plugin.json ("version": "...")
4. uv.lock (root package version updated)
5. CHANGELOG.md (moves [Unreleased] into [X.Y.Z] - YYYY-MM-DD and creates a fresh empty [Unreleased] section).

How to Cut a Release & Publish to PyPI

# 1. Update version and changelog
python scripts/bump_version.py 0.3.1

# 2. Commit the version bump
git add .
git commit -m "chore(release): bump version to 0.3.1"

# 3. Create an annotated Git tag
git tag -a v0.3.1 -m "Release v0.3.1: Windows CI, PyPI packaging & English docs"

# 4. Push branch and tag to GitHub
git push origin master
git push origin v0.3.1

🤝 Contributing

Contributions, bug reports, and suggestions are warmly welcomed! Please read our Contributing Guide (CONTRIBUTING.md) to learn about:

• Setting up the local development environment with uv.
• Feature branch workflows (feat/*, fix/*) to keep master stable.
• Strict Python 3.5.2 compatibility in plugin/ (no f-strings).
• Conventional Commits and submitting Pull Requests with GitHub CLI (gh).