Gmat Server

An MCP (Model Context Protocol) server that turns NASA's GMAT (General Mission Analysis Tool) into a tool an AI agent can actually use — not just talk about. Any MCP client (Claude Code, Claude Desktop, Cursor, custom apps) gets:

• runGmat — the validation loop. Runs a GMAT mission script headless via GmatConsole and returns a classified outcome (completed | parse | convergence | run) with extracted errors and report-file contents. The agent writes a script, runs it, reads what broke, and fixes it — the same loop a mission designer uses.
• getGmatIdioms — curated knowledge. A hand-built knowledge base of GMAT gotchas discovered through that loop (cumulative ElapsedSecs, no parentheses in conditionals, Propagate Synchronized for two-spacecraft burns, …), so the agent stops making the classic mistakes.
• listGmatSamples / getGmatSample — known-good templates. The NASA sample-script corpus as a retrieval source for vetted mission patterns, plus an optional local corpus of community scripts (harvested from public repos, kept only if they pass a headless runGmat validation; listed with a community/ prefix). The harvested corpus stays local — it is gitignored because licenses vary.
• searchDocs — semantic search over the GMAT documentation, embedded locally and cached in data/embeddings.json.

Example of what this enables: asked for a two-burn phasing rendezvous (700 km circular orbit, 30° separation), the agent derived the textbook solution, verified it exactly under two-body dynamics, discovered it misses by 47 km under J2 gravity by actually running it, and re-targeted the burns with GMAT's differential corrector to converge at 2.96 km — autonomously, in a handful of tool calls.

Requirements

• Node.js 18+ (ESM)
• pnpm (project uses pnpm@10 per package.json)
• A local GMAT install (R2025a tested) — for the runGmat and sample tools
• An OpenAI API key — only if you want to rebuild the docs-search cache from scratch; the repo ships a prebuilt data/embeddings.json and queries are embedded with a local model

Quick Start

1. Clone the repo

git clone https://github.com/ginomoretta-creator/gmat-mcp-server.git
cd gmat-mcp-server

2. Install dependencies

pnpm install

3. Configure environment Create a .env.local at the repo root pointing at your GMAT install:

echo "GMAT_BIN=C:\Path\To\GMAT_R2025a\bin" > .env.local

See .env.example for all variables. The server loads .env.local / .env from the repo root automatically, so it works even when an MCP client spawns it with an empty environment.

4. Build the project

pnpm build

5. (Optional) Rebuild the docs cache from the live docs — requires OPENAI_API_KEY in .env.local; skip this to use the prebuilt cache

pnpm run setup

6. Start the MCP server

pnpm start

The server runs over stdio and exposes the searchDocs tool to your MCP client.

Scripts

• pnpm build: compile TypeScript to dist/
• pnpm start: run server from dist/index.js (loads .env.local)
• pnpm dev: run server in watch mode with ts-node
• pnpm run setup: build cache from live docs (requires OpenAI API key)
• pnpm run setup:test: build a smaller test cache using pages-test.json

Pass --force to setup to rebuild the cache from scratch:

pnpm run setup -- --force

Environment Variables

• GMAT_BIN (required for runGmat/samples): GMAT bin folder containing GmatConsole(.exe)
• GMAT_SAMPLES (optional): samples dir (default: <GMAT_BIN>\..\samples)
• GMAT_IDIOMS (optional): idioms file (default: ./data/gmat_idioms.md)
• OPENAI_API_KEY (setup only): used to rebuild the docs-embedding cache
• CACHE_DIR (optional): directory for embeddings.json (default: ./data)
• BASE_URL (optional): docs base URL (default: https://documentation.help/gmat/)
• NODE_ENV (optional): set to test to use pages-test.json during setup
• MCP_PORT (optional): for wrappers/adapters that expose this stdio server via TCP/SSE. This server itself communicates over stdio and does not bind to a port; some clients or adapters may read MCP_PORT to decide which port to listen on.

Files read for env values:

• Setup reads both .env and .env.local
• Runtime reads .env.local (via pnpm start) or your shell env

Using with MCP Clients

Claude Code

claude mcp add gmat -- node C:\path\to\gmat-docs-mcp-server\dist\index.js

(.env.local at the repo root is picked up automatically.)

Other stdio clients

This server communicates via stdio. Point your MCP client to execute the server in your project directory. Two common approaches:

Option A: Use the start script

pnpm start

Your MCP client should spawn this command in the repo root (ensures .env.local is picked up).

Option B: Use the wrapper

There is a convenience wrapper that ensures env loading, then starts the compiled server:

node start-mcp.js

Note: If you run the server behind an adapter that serves MCP over SSE/TCP, you can set MCP_PORT to guide that adapter. The server code here still talks over stdio.

Tool: searchDocs

Inputs:

• query (string, required)
• topK (number, default 10, 1–50)
• minScore (number, default 0.1, 0–1)

Output: formatted text with page name, source URL, similarity score, and extracted content.

GMAT copilot tools (execution + knowledge)

Beyond doc search, the server exposes the GMAT validation loop and curated knowledge so an MCP client (Claude) can write → run → diagnose → fix GMAT missions autonomously:

• runGmat — runs a GMAT .script (passed as text) headless via GmatConsole.exe and returns { ok, stage, errors, reports, raw_tail }. stage ∈ completed | parse | convergence | run. Inputs: script (string, required), timeoutSec (number, default 600 — raise for multi-day low-thrust propagations). This is the closed validation loop.
• getGmatIdioms — returns the curated GMAT idioms/gotchas knowledge base (data/gmat_idioms.md). Read it before generating scripts to avoid common pitfalls.
• listGmatSamples — lists the bundled NASA sample .script names plus any validated community scripts (prefixed community/) — a retrieval corpus of known-good patterns.
• getGmatSample — returns one sample's full text by name, to seed a phase from a vetted template.

These require a local GMAT install; see GMAT_BIN / GMAT_SAMPLES / GMAT_EXTRA_SAMPLES / GMAT_IDIOMS in .env.example (defaults match a standard GMAT R2025a install).

Extending the corpus (harvest pipeline)

The retrieval corpus is extensible. scripts/harvest-corpus.mjs turns a manifest of public-repo pointers into a validated local corpus, using the same runGmat the MCP uses as the gate:

node scripts/harvest-corpus.mjs --manifest data/community-scripts/manifest.example.json --validate

Pipeline: download each script → scan (reject Python/MATLAB interface calls) → normalize (rewrite hardcoded absolute ReportFile paths — the #1 portability killer) → validate headless (keep only scripts that reach stage completed) → index each survivor by detected technique into data/community-scripts/INDEX.md.

Without --validate it downloads, scans and normalizes only — nothing is executed. --validate runs untrusted scripts through GmatConsole, so vet the manifest and prefer a sandbox. The harvested scripts stay local (gitignored — licenses vary); only the pipeline and the example manifest of public-repo pointers are committed, so the corpus is reproducible without redistributing anyone's code.

Skills

The skills/ directory holds Claude skills that teach an agent how to drive these tools — the procedural layer on top of the MCP's tools:

• gmat-mission-design — the design-and-verify workflow: read the idioms first, seed from a sample, write analytic expectations as the acceptance test, run, triage failures by stage, and never cite a number that didn't come from a GMAT report. Benchmarked against a no-skill baseline across three mission scenarios (Hohmann→GEO, electric orbit-raise, drag decay): 100% vs 92% assertion pass rate, with far lower run-to-run variance.
• gmat-improve — a run→diagnose→fix loop for existing scripts: baseline run as a regression test, diagnosis against the failure catalog (hardcoded paths, non-ASCII, magic-number burns, degenerate stop conditions), one re-run per change, before/after delivery.

Point your skill-aware client at the skills/ directory to load them.

Data and Cache

• Cache file: data/embeddings.json (or ${CACHE_DIR}/embeddings.json)
• To rebuild: pnpm run setup -- --force
• To use a smaller test set: pnpm run setup:test

Customizing Pages

The list of pages to scrape is defined in:

• pages.json (full set)
• pages-test.json (smaller set for tests)

You can edit these files to change the crawl scope. The parser attempts to extract meaningful sections by headings and convert them to Markdown for embedding.

Troubleshooting

• Error: OPENAI_API_KEY environment variable is required
  • Create .env.local (and optionally .env) with OPENAI_API_KEY
• Cache not found at data/embeddings.json. Run setup first.
  • Run pnpm build && pnpm run setup to generate the cache
• Network timeouts while scraping
  • The scraper retries with exponential backoff; rerun setup or adjust your network
• MCP client can’t see tools
  • Ensure the server is started from the project directory and connected via stdio
  • Confirm pnpm start logs show the server is running and the cache is loaded

Project Structure

src/
  index.ts        # MCP server entry (stdio)
  setup.ts        # Setup pipeline: scrape → parse/chunk → embed → cache
  tools/          # MCP tool definitions and handlers
  utils/          # scraper, parser, embedder, cache, search
data/             # Default cache directory (embeddings.json)
pages.json        # Full list of pages to scrape
pages-test.json   # Smaller list for testing
dist/             # Compiled JavaScript (after pnpm build)
start-mcp.js      # Wrapper to load env and run the server

Credits

The documentation-search foundation (scrape → parse/chunk → embed → cache pipeline) was originally built by Ignacio García as gmat-docs-mcp-server. The GMAT execution copilot tools (runGmat, idioms knowledge base, sample corpus) and the local-embedding runtime were added on top.

License

ISC