MCP Server: AI-driven fire modeling via Model Context Protocol

[spydmobile]

Summary

Add an optional MCP (Model Context Protocol) server to Nomad, enabling AI agents to create, configure, execute, and interpret fire modeling simulations through conversational interfaces. Available in all deployment modes (SAN and ACN).

Motivation

Fire modeling currently requires specialized GUI knowledge. An MCP server exposes Nomad's capabilities as AI-consumable tools, enabling:

• Fire analysts: Conversational modeling - natural language to simulation to interpreted results
• Automated batch: Sensitivity analysis, scenario comparison, overnight runs
• Training: AI-guided learning for new modelers

Architecture

• Mounts on the existing Express app at /mcp (same port, same process)
• Uses Streamable HTTP transport (current MCP standard)
• Tool handlers call the same service layer as the REST API - zero business logic duplication
• Opt-in via NOMAD_ENABLE_MCP=true environment variable
• Respects existing auth middleware in both SAN and ACN modes

Scope

v1 tools: list-models, create-model, set-ignition, set-weather, set-fuel-type, set-simulation-time, execute-model, get-job-status, get-results-summary, get-results-data

v1 resources: Dynamic model/job/result resources + static domain knowledge (fuel types, FWI system, model parameters)

New dependency: @modelcontextprotocol/sdk

Design Document

Documentation/Nomad/design/mcp-fire-modeling-server.md

Implementation Phases

1. Foundation - MCP server, transport, mounting, 3 core tools
2. Full workflow - complete tool catalog, job polling, results
3. Domain knowledge - fuel types, FWI, model parameter resources
4. Batch and comparison - clone, compare, batch execute
5. Spatial intelligence - fuel/elevation/weather queries at coordinates

[spydmobile]

Execution Plan: MCP Phase 1 Rewrite — Real FireSTARR Integration

Plan file: plans/mcp-phase1-rewrite.md (in Sage planning directory)
Branch: mcp_integration

Problem

Phase 1 MCP implementation built tool schemas from the design doc abstractions without matching the real Nomad REST API or FireSTARR engine:

1. execute-model calls a stub shell script, not FireSTARREngine
2. set-weather collects a single scalar snapshot, not hourly FWI time series
3. set-fuel-type is a dead end - FireSTARR reads fuel from raster grids
4. Missing tools: get-results-summary, get-results-data
5. In-memory config store is volatile and leaks across sessions

Solution

Rewrite MCP tools to wrap the real POST /models/run execution path through FireSTARREngine.initialize() then execute() then getResults().

Key Changes

• Remove set-fuel-type (fuel comes from raster grid)
• Rewrite set-ignition - accept GeoJSON point OR polygon
• Rewrite set-weather - three sources: firestarr_csv, raw_weather, spotwx
• Rewrite set-simulation-time - startTime + endTime (not duration)
• Rewrite execute-model - build ExecutionOptions, call FireSTARREngine directly
• Add get-results-summary - deterministic templated output
• Add get-results-data - structured result file inventory
• Add DB migration 003_add_model_config - persist config in fire_models.config_json
• Add knowledge resources: fuel types, FWI system, model parameters
• Add dynamic resources: jobs, results

Team Execution (3 waves)

Wave	Agent	Work
1 (parallel)	agent-migration	DB migration + config storage + tests
1 (parallel)	agent-resources	All resources (knowledge + dynamic) + tests
2	agent-tools	Full tool rewrite + TDD test suite
3	Sage (lead)	Merge, verify, update design doc

Final Tool Count: 9

list-models, create-model, set-ignition, set-weather, set-simulation-time, execute-model, get-job-status, get-results-summary, get-results-data

Verification

• npx tsc --noEmit - zero errors
• npx vitest run src/mcp/ - all tests green
• Integration test: create then polygon ignition then CFFDRS CSV weather then time range then execute then poll then results

[spydmobile]

Phase 1+2 Complete — E2E Tested (2026-02-28)

What was done

Executed the full MCP E2E test plan (6 waves) against the live backend on mcp_integration branch. Fixed 5 bugs discovered during testing. The MCP pipeline now works cradle-to-grave: create → configure → execute → poll → results.

Bugs Fixed

Bug	Fix	File
PROJ_DATA not in .env — binary fails	Added PROJ_DATA=/Volumes/KINGSTON/firestarr_app	.env
Job status never updates (fire-and-forget)	Replaced with lifecycle chain wiring engine completion to JobQueue	execution.ts
Model status stuck at "queued"	Same lifecycle chain updates model status on completion/failure	execution.ts
Results never persisted to DB	Lifecycle chain harvests engine results and saves via ResultRepository	execution.ts
Results tools calling deprecated repo.getResults()	Changed to resultRepo.findByModelId()	execution.ts

Test Results

Wave	Test	Result
0	Pre-flight fixes + 63/63 unit tests	PASS
1	Smoke test — all 9 tools return structured JSON	PASS
2	Model config — 874-vertex polygon, 241-row weather CSV, 72h sim	PASS
3	Execution — FireSTARR binary exit 0, job+model lifecycle complete	PASS
4	Results — 3 probability GeoTIFFs persisted, summary+data queryable	PASS
5	Error paths — 5 validation cases return structured error codes	PASS
6	Clean cradle-to-grave — point ignition, 5 seconds, fully reproduced	PASS

Verification

• npx tsc --noEmit — zero errors
• npx vitest run src/mcp/ — 63 tests passing
• Two successful fire model runs in the database (polygon + point ignition)
• Job lifecycle: pending → running → completed
• Model lifecycle: draft → queued → completed
• Results persisted and queryable via MCP tools
• Error taxonomy works for all validation cases

Phase Status

• Phase 1 — Foundation: MCP server, Streamable HTTP transport, mounting, core tools
• Phase 2 — Full workflow: all 9 tools, 5 resources, job polling, results persistence, E2E tested
• Phase 3 — Domain knowledge: fuel types, FWI, model parameter resources
• Phase 4 — Batch and comparison: clone, compare, batch execute
• Phase 5 — Spatial intelligence: fuel/elevation/weather queries at coordinates