Skip to main content
Glama
README.md
# FreeFlyer MCP

Connect an MCP-compatible assistant to a locally licensed copy of **a.i. solutions FreeFlyer** for script execution, mission-plan runs, orbit propagation, and ground-station access analysis.

The bridge uses temporary files and native command-line execution through Python's `subprocess.run()`. It requires no FreeFlyer Runtime API package. A licensed FreeFlyer installation is required separately; this repository contains no proprietary executables, data files, or licenses.

## Features

- Four stdio MCP tools: `run_freeflyer_script`, `run_mission_plan`, `propagate_orbit`, and `calculate_access_times`.
- A fresh temporary workspace for every run, with serialized execution per server instance.
- Captured stdout/stderr, generated reports, explicit execution timeouts, and process-tree termination.
- Windows `ff.exe` and macOS `ff-cli` support through an explicit executable path.
- Structured JSON telemetry and pass events from generated CSV reports.

## Requirements

- Python **3.10 or later**; Python 3.11 or 3.12 is recommended.
- FreeFlyer installed and licensed for the account that launches the MCP client.
- A FreeFlyer command-line executable supporting `-mp` and `-tmps`.
- An MCP client such as Codex, Claude Desktop, or Cursor.

A raw report script and a short TwoBody propagation have been exercised end to end on **FreeFlyer 8.0.1 for macOS with an Engineer license**. Windows process-tree cleanup has unit coverage but still requires validation on a licensed Windows host. The access tool uses approximate one-second sampling; see [modeling limits](#modeling-limits).

## Installation

Clone this repository on the computer with FreeFlyer installed:

```sh
git clone https://github.com/Sammy-Sekhon/freeflyer-mcp.git
cd freeflyer-mcp
```

### macOS

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
export FREEFLYER_EXE_PATH='/Applications/FreeFlyer 8.0.1.76638900.app/Contents/Resources/bin/ff-cli'
export FREEFLYER_CLI_MODE=documented
.venv/bin/python smoke_test.py --with-freeflyer
```

Replace the versioned application path with your installed version. The executable is inside the application bundle; a Windows-style `bin/ff.exe` path will not work on macOS.

### Windows (PowerShell)

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
$env:FREEFLYER_EXE_PATH = 'C:\Program Files\a.i. solutions\FreeFlyer 7.10\bin\ff.exe'
$env:FREEFLYER_CLI_MODE = 'documented'
.\.venv\Scripts\python.exe smoke_test.py --with-freeflyer
```

Replace the example with your actual executable. Newer versions may name the native executable differently; use the CLI executable shipped with your installation and verify its `--help` output.

To run the server manually:

```sh
# macOS
.venv/bin/python server.py
```

```powershell
# Windows
.\.venv\Scripts\python.exe server.py
```

A stdio server waits for MCP messages and may show no output. It is not a web service and does not expose an HTTP port. Stop a manual instance before having your MCP client launch another one.

## Configure your MCP client

Use **absolute paths** to the virtual environment's Python interpreter and `server.py`. Put environment variables directly in the client configuration: desktop applications may not inherit values exported in a terminal.

### Codex

Merge the following tables into `~/.codex/config.toml` (Windows: `%USERPROFILE%\.codex\config.toml`). Substitute your paths. This example is for macOS:

```toml
[mcp_servers.freeflyer]
command = "/absolute/path/freeflyer-mcp/.venv/bin/python"
args = ["/absolute/path/freeflyer-mcp/server.py"]
cwd = "/absolute/path/freeflyer-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 3700

[mcp_servers.freeflyer.env]
FREEFLYER_EXE_PATH = "/Applications/FreeFlyer 8.0.1.76638900.app/Contents/Resources/bin/ff-cli"
FREEFLYER_CLI_MODE = "documented"
```

For Windows, use TOML literal strings for backslash paths:

```toml
[mcp_servers.freeflyer]
command = 'C:\tools\freeflyer-mcp\.venv\Scripts\python.exe'
args = ['C:\tools\freeflyer-mcp\server.py']
cwd = 'C:\tools\freeflyer-mcp'
startup_timeout_sec = 20
tool_timeout_sec = 3700

[mcp_servers.freeflyer.env]
FREEFLYER_EXE_PATH = 'C:\Program Files\a.i. solutions\FreeFlyer 7.10\bin\ff.exe'
FREEFLYER_CLI_MODE = 'documented'
```

Choose one platform's configuration, not both. Reload MCP servers or restart the application after saving. `codex mcp get freeflyer` checks registration; `smoke_test.py` checks actual protocol startup. The client timeout is slightly longer than the server's maximum 3,600-second run timeout to allow cleanup and report collection.

See [Codex MCP configuration](https://developers.openai.com/codex/mcp/).

### Claude Desktop and Cursor

Both use a top-level `mcpServers` JSON object. Merge this macOS example into the appropriate file:

```json
{
  "mcpServers": {
    "freeflyer": {
      "command": "/absolute/path/freeflyer-mcp/.venv/bin/python",
      "args": ["/absolute/path/freeflyer-mcp/server.py"],
      "env": {
        "FREEFLYER_EXE_PATH": "/Applications/FreeFlyer 8.0.1.76638900.app/Contents/Resources/bin/ff-cli",
        "FREEFLYER_CLI_MODE": "documented"
      }
    }
  }
}
```

For Windows, use these path forms inside the same JSON structure:

```json
{
  "mcpServers": {
    "freeflyer": {
      "command": "C:\\tools\\freeflyer-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\tools\\freeflyer-mcp\\server.py"],
      "env": {
        "FREEFLYER_EXE_PATH": "C:\\Program Files\\a.i. solutions\\FreeFlyer 7.10\\bin\\ff.exe",
        "FREEFLYER_CLI_MODE": "documented"
      }
    }
  }
}
```

| Client | Configuration location |
| --- | --- |
| Claude Desktop, macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop, Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor, project | `.cursor/mcp.json` in the project directory |
| Cursor, global | `~/.cursor/mcp.json` |

Restart or reload the client after saving and verify that four tools appear. A client's own tool timeout may need adjustment for long runs. See the [local MCP client guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers) and [Cursor MCP documentation](https://cursor.com/docs/mcp).

## Use the tools

After connecting, ask your assistant to use a specific tool. For example: “Use FreeFlyer to propagate an Earth orbit with a 7,000 km semimajor axis for one hour, sampled every 60 seconds.”

### `run_freeflyer_script`

Parameters: `script_content` (string), `timeout_seconds` (integer, default 60; range 1–3,600).

```json
{
  "script_content": "Report \"Hello from FreeFlyer\" to MCPReport;",
  "timeout_seconds": 60
}
```

The server declares `ReportInterface MCPReport("output.csv")` for you. Explicitly report values to `MCPReport` or create your own report file. The server wraps the script in a standalone text Mission Plan interpreted with `-tmps`; it does not fabricate an XML schema.

The result contains `ok`, `returncode` when available, `stdout`, `stderr`, truncation flags, the executed command, and generated files. For example, `files["output.csv"]["text"]` contains the report text. UI objects and visualization commands in raw scripts are rejected.

### `run_mission_plan`

Parameters: `mission_plan_path` (absolute path), `switches` (optional string list), `timeout_seconds` (default 120; range 1–3,600).

```json
{
  "mission_plan_path": "C:\\missions\\analysis.MissionPlan",
  "timeout_seconds": 120
}
```

The plan is copied into its own workspace and executed headlessly. Dependencies must be self-contained or use absolute paths. Use relative output filenames so results are created in the run directory and collected. Existing XML plans are not rewritten or stripped of UI components; prepare them for headless execution first.

For plan inputs, `switches` currently accepts pairs of `-ni` or `--namelist-input` followed by a namelist path. Prefer absolute namelist paths. Other switches are rejected to avoid changing the selected plan, UI behavior, or license state.

### `propagate_orbit`

```json
{
  "epoch": "Jan 01 2026 00:00:00.000",
  "sma": 7000,
  "ecc": 0.001,
  "inc": 51.6,
  "raan": 0,
  "arg_perigee": 0,
  "true_anomaly": 0,
  "duration_hours": 1,
  "step_size_seconds": 60
}
```

Epochs are UTC, semimajor axis is in km, angles are in degrees, duration is in hours, and the sampling step is in seconds. The tool returns an array of `Epoch, X, Y, Z, Vx, Vy, Vz` objects in Earth-centered ICRF, km, and km/s. It includes the initial epoch and exact end epoch, shortening the final step if needed. Execution timeout: 120 seconds; maximum output: 100,000 samples.

### `calculate_access_times`

Parameters: `tle_line1`, `tle_line2`, `ground_station_lat`, `ground_station_lon`, `ground_station_alt`, `start_time`, and `duration_days`.

Supply two matching, checksum-valid, exactly 69-character TLE lines. Latitude and east longitude are degrees; altitude is km; the start date uses the same UTC calendar format as propagation. Use TLEs appropriate to the requested date. Maximum analysis duration is seven days; execution timeout is 120 seconds.

The tool returns a list of pass events:

```json
[
  {
    "AOS": "Jan 01 2026 12:00:00.000000000",
    "LOS": "Jan 01 2026 12:08:00.000000000",
    "duration_seconds": 480,
    "max_elevation_deg": 42.5,
    "clipped_start": false,
    "clipped_end": false,
    "sample_seconds": 1
  }
]
```

This is an illustrative result, not a computed pass prediction. An empty array means the generated report was valid but contained no passes; a missing or malformed report is an error.

## Executable discovery and command modes

Discovery checks, in order:

1. `FREEFLYER_EXE_PATH` — an explicit absolute path; invalid values produce an error.
2. `FREEFLYER_64_INSTALL_DIRECTORY/bin/ff.exe`.
3. Windows `C:\Program Files\a.i. solutions\FreeFlyer *\bin\ff.exe`, including the older `a.i. solutions, Inc` directory, choosing the highest numeric version.

On macOS, set the explicit path to the installed application's `Contents/Resources/bin/ff-cli`; automatic application-bundle discovery is not implemented.

Set `FREEFLYER_CLI_MODE=documented` for standard installations. This produces `ff.exe -mp <plan>` or `ff-cli -mp <plan>`, with `-tmps` added for raw scripts. The CLI supplies headless execution.

For compatibility with custom installations, `FREEFLYER_CLI_MODE=requested` produces `-m <plan> -headless`. This is the current fallback when the variable is omitted, but those flags are **not supported by the standard CLI version tested**. Always set `documented` as shown above. There is no automatic retry that could execute a plan twice.

Vendor references: [command-line execution](https://freeflyer.com/_help_Files/ff_exe.htm), [script interpretation](https://freeflyer.com/_help_Files/-tmps1.htm), and [ReportInterface](https://freeflyer.com/_help_Files/reportinterfaces.htm).

## Modeling limits

- Propagation uses Earth-centered **TwoBody** dynamics for elliptic orbits. It does not include drag, nonspherical gravity, third-body forces, or maneuvers.
- Access uses **SGP4** and geometric elevation at or above zero degrees, sampled every second. AOS/LOS are sample times, maximum elevation is a sampled lower bound, and subsecond grazing passes can be missed.
- Passes crossing an analysis boundary are clipped and flagged. Terrain, refraction, and antenna masks are not modeled.
- Generated scripts target nanosecond timing mode. Older millisecond-only installations require adaptation.
- These tools support analysis workflows; validate results against a trusted reference before operational use.

## Execution and file handling

Each run owns a `TemporaryDirectory`. The server copies inputs there, sets it as the working directory, collects up to 100 files / 8 MiB of text, and cleans it up. Truncated analysis CSV is an error rather than partial telemetry. Absolute output paths are outside this collection. Binary results are not supported.

A dedicated Python supervisor invokes FreeFlyer with `subprocess.run(..., timeout=...)`. The parent's shorter watchdog terminates the supervisor's process tree on timeout: `taskkill /F /T /PID <supervisor_pid>` on Windows, or an isolated process group on macOS/Linux. This avoids relying on a nonexistent `TimeoutExpired.pid`. Cleanup diagnostics and partial logs are returned. Host crashes or forced termination of the MCP application are outside the watchdog's guarantee.

Runs are serialized within one server instance. Multiple clients or server instances can consume multiple license seats. Logs are spooled to disk, so verbose runs may use disk space until completion or timeout.

Only execute trusted scripts and plans: workspace isolation prevents filename collisions but is not an operating-system sandbox. FreeFlyer scripts can access files and launch programs with the account's permissions. Do not expose this local bridge to untrusted clients.

## Tests and troubleshooting

From the repository directory, with dependencies installed:

```sh
# macOS/Linux
.venv/bin/python -m unittest -v test_server
.venv/bin/python smoke_test.py
.venv/bin/python smoke_test.py --with-freeflyer
```

```powershell
# Windows
.\.venv\Scripts\python.exe -m unittest -v test_server
.\.venv\Scripts\python.exe smoke_test.py
.\.venv\Scripts\python.exe smoke_test.py --with-freeflyer
```

The unit suite and default smoke test need no FreeFlyer installation. The optional licensed smoke test runs a short report script using the configured executable. Unit tests cover subprocess success/failure, timeout termination, discovery, command construction, CSV validation, temporary workspace cleanup, and MCP schemas. They do not certify astrodynamics accuracy.

| Symptom | Check |
| --- | --- |
| Tools do not appear | Use the venv's Python, verify `server.py` exists, run `smoke_test.py`, and reload the MCP client. |
| Executable path error | Use an absolute path. On macOS, use `ff-cli` inside the application bundle. |
| Unknown command-line flag | Set `FREEFLYER_CLI_MODE=documented`; inspect your executable's `--help`. |
| License failure | Confirm FreeFlyer works under the same user account and that a seat is available. |
| Client times out first | Increase the client's MCP tool timeout above the requested execution timeout. |
| Empty/missing output | Report explicitly to `MCPReport`, or use relative output filenames. Inspect stdout/stderr and generated logs. |
| Plan fails after copying | Use absolute dependency paths and remove GUI-only behavior. |

For new FreeFlyer/platform combinations, validate a short report, a known orbit case, an access case, and a deliberate timeout. Confirm the owned processes exit and the seat is released. When reporting bugs, include platform, Python/FreeFlyer versions, and a minimal script; redact license information, credentials, local paths, and proprietary mission data.

## License

This bridge is released under the [MIT License](LICENSE). FreeFlyer is a product of a.i. solutions and requires its own license. This is an independent community project and is not affiliated with or endorsed by a.i. solutions.