# tigl-mcp

[![CI](https://github.com/cmudrc/tigl-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cmudrc/tigl-mcp/actions/workflows/ci.yml)
[![Docs](https://github.com/cmudrc/tigl-mcp/actions/workflows/docs-pages.yml/badge.svg)](https://github.com/cmudrc/tigl-mcp/actions/workflows/docs-pages.yml)
[![Examples](https://github.com/cmudrc/tigl-mcp/actions/workflows/examples.yml/badge.svg)](https://github.com/cmudrc/tigl-mcp/actions/workflows/examples.yml)

`tigl-mcp` is a Model Context Protocol server for CPACS-oriented TiGL
workflows. CAD and mesh export drive the real TiGL library (natively, or in a
container). Geometry queries that need a TiGL kernel raise a structured
`GeometryUnavailable` error when none is present; nothing returns synthetic
values.

## Overview

The project currently provides:

- A FastMCP-powered server with stdio and HTTP-compatible transports
- A curated set of CPACS lifecycle, inspection, export, sampling, and parameter
  tools
- Pydantic-backed tool validation with structured MCP error payloads
- Structured `GeometryUnavailable` errors when no TiGL kernel is present, never synthetic geometry

## Quickstart

Requires Python 3.12+.

```bash
python3 -m venv .venv
source .venv/bin/activate
make dev
make test
make ci
```

Start the server over stdio:

```bash
tigl-mcp --transport stdio
```

Inspect the non-blocking HTTP transport configuration example:

```bash
PYTHONPATH=src python3 examples/server/http_launch_config.py
```

## Examples

The examples are deterministic and do not need a TiGL kernel: geometry tools
raise a structured error rather than returning made-up values.

- Examples index: [`examples/README.md`](examples/README.md)
- Tool discovery: [`examples/client/tool_discovery.py`](examples/client/tool_discovery.py)
- Session lifecycle: [`examples/cpacs/session_lifecycle.py`](examples/cpacs/session_lifecycle.py)
- Export snapshot: [`examples/cpacs/export_snapshot.py`](examples/cpacs/export_snapshot.py)

## Docs

- Docs source: [`docs/index.rst`](docs/index.rst)
- Published docs: <https://cmudrc.github.io/tigl-mcp/>

Build the docs locally with:

```bash
make docs
```

## Current Capability Boundaries

This is the authoritative statement of which paths run real TiGL and which do
not. Nothing here estimates geometry.

**Real TiGL, always.** CAD export (`export_configuration_cad`, STEP and IGES)
and mesh export (`export_component_mesh`) drive the real TiGL library, either
through native `tigl3`/`tixi3` bindings or through the `tigl-mcp:dev` Docker
image. The route actually taken is recorded in CPACS as `stepExportSource`, so
exported geometry is traceable. On the D150 this produces a 3.2 MB STEP file
and per-component surface meshes of a few thousand triangles.

**Read from the CPACS file, so always available.** Component UIDs, names,
symmetry flags, wing/fuselage/rotor/engine counts, per-component section and
segment counts, and the reference area and length. These are values the file
states directly.

**Computed by real TiGL, natively or inside the Docker image.** Bounding
boxes, wing spans, planform and wetted areas, fuselage length and volume
come from `check_geometry` and the exports. These run TiGL scripts through
the native `tigl3`/`tixi3` bindings when they are installed in the server's
Python (DLR's conda package; the route for a Windows laptop without Docker,
added 2026-10-28) and otherwise in the `tigl-mcp:dev` container; the result
says which (`geometry_source`, `stepExportSource`). Deriving any of these
means evaluating profile geometry through the CPACS positioning and
transformation chain, which is what TiGL is for. Without either kernel these
tools raise a structured error naming the missing dependency; nothing
returns an estimate.

The former `get_wing_summary`, `get_fuselage_summary`,
`sample_component_surface`, `intersect_with_plane` and
`intersect_components` tools were removed on 2026-10-22. They needed the
native TiGL bindings, which no install provided at the time, so they could
only refuse; every participant of a user-study pilot saw that refusal as an
error before the assistant found the values through `check_geometry`.

> Until 2026-08-15 several of these returned values derived from a component's
> index in an array — a wing's bounding box was literally its position in the
> list. Those were removed, along with a synthetic single-triangle mesh and a
> CAD "export" that returned the CPACS text relabelled. If you are reading
> older notes or output that mention stub geometry, they predate this.

## Shared-CPACS Integration

This MCP includes a **CPACS adapter** (`src/tigl_mcp/cpacs_adapter.py`) that
bridges TiGL to the shared-CPACS aircraft analysis pipeline.

### What it does

The adapter reads CPACS geometry (wings, fuselages, profiles) and writes
analysis results — component counts, per-component section and segment counts,
and STEP export metadata — into `//analysisResults/tigl`. A `boundingBox`
element is written only when a real geometry kernel supplied one, and is
omitted otherwise.

| Direction | XPath |
|-----------|-------|
| **Reads** | `.//vehicles/aircraft/model`, `.//vehicles/profiles` |
| **Writes** | `.//vehicles/aircraft/model/analysisResults/tigl` |
| **Records** | one `header/updates/update` entry per write: what was written, `tigl-mcp <version>`, UTC timestamp, running version, cpacsVersion |

### Running as part of the pipeline

```bash
# As part of the full five-MCP pipeline (with SU2, pyCycle, NSEG)
python pipeline/shared_cpacs_orchestrator.py D150_v30.xml --mcps tigl su2 pycycle nseg

# TiGL only
python pipeline/shared_cpacs_orchestrator.py D150_v30.xml --mcps tigl
```

See [cmudrc/aircraft-analysis](https://github.com/cmudrc/aircraft-analysis) for
full pipeline documentation, versioning details, and installation instructions.

### Related MCP servers

| MCP | Repository |
|-----|-----------|
| SU2 (CFD aerodynamics) | [cmudrc/su2-mcp](https://github.com/cmudrc/su2-mcp) |
| pyCycle (engine cycle) | [cmudrc/pycycle-mcp](https://github.com/cmudrc/pycycle-mcp) |
| Mission, segment/Breguet | [cmudrc/nseg-mcp](https://github.com/cmudrc/nseg-mcp) |
| Mission, trajectory-level | [cmudrc/aviary-cpacs-mcp](https://github.com/cmudrc/aviary-cpacs-mcp) |

## Contributing

Contribution guidelines live in [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Maintainers

Mayank Dixit ([@Kugel-Blitz-13](https://github.com/Kugel-Blitz-13)), Carnegie
Mellon University — mayankd@cmu.edu
Christopher McComb, Carnegie Mellon University — Design Research Collective