Skip to main content
Glama

avl-mcp

Run reproducible AVL aerodynamic analyses through the Model Context Protocol. The server validates input, runs AVL in an isolated directory, and returns structured results with the original solver files.

Version: 0.5.0. Supports AVL 3.52 only. Native acceptance covers macOS Apple Silicon and Ubuntu 24.04 x86_64; other platforms are unverified. This project is an independent wrapper, not an official MIT or AVL release.

繁體中文說明 · Documentation index · Validation

Version 0.5.0 adds synchronous and durable background trim batches, retaining each point's acceptance bounds, residual checks and independent replay. It also adds a reproducible Linux native build and acceptance job alongside macOS. It also adds general mesh sensitivity and mass/weight, speed and CG trim inputs, with explicit unit conversion and saved provenance. See batch trim, Ubuntu installation, trim conventions and acceptance. See the 0.5.0 release notes for artifacts and upgrade scope. Installing a release does not update an existing client's configuration automatically.

Tools

Tool

Purpose

avl.health

Diagnose Python/native installation, directory access and headless startup

avl.inspect

Read geometry, references, controls and file dependencies

avl.validate

Check supported grammar, dependency paths and mesh budget

avl.run

Calculate one prescribed condition, loads and ST/SB derivatives

avl.trim

Solve alpha and one CONTROL variable for target CL/Cm, then independently verify

avl.mesh_sensitivity

Compare coefficients across refined surface meshes and save JSON/CSV/Markdown

avl.prepare_trim

Convert explicit mass/weight, airspeed and CG to CL targets and references without running AVL

avl.trim_physical

Run independently verified trim from dimensional inputs and retain conversion provenance

avl.sweep

Calculate 1-10000 prescribed conditions or independently verified trim targets and save CSV

avl.submit

Snapshot prescribed conditions or trim targets and start a detached background job

avl.status

Read progress, counts and the actual job outcome

avl.cancel

Cancel a queued/running job while retaining completed cases

avl.resume

Verify saved inputs/results and recompute only missing or failed cases

avl.results

Page and filter saved results without running AVL

The connector does not expose eigenmodes, general geometry editing, interactive graphics, CAD conversion, or automatic OpenVSP comparison. The model validator checks input structure and basic invariants; it does not prove freedom from intersections or aerodynamic suitability. A successful process exit alone is never accepted as a result.

Related MCP server: tigl-mcp

Installation

Requirements: Python 3.11 or newer and a separately installed AVL 3.52 executable. The Python package does not download or bundle AVL, install system libraries, or modify any MCP client configuration.

python3 -m venv /absolute/local/path/avl-mcp-env
/absolute/local/path/avl-mcp-env/bin/python -m pip install .
/absolute/local/path/avl-mcp-env/bin/avl-mcp --version

For development, install .[dev] in a local environment. Build release artifacts with python -m build; install the resulting wheel for the stdio acceptance test. Keep virtual environments and native libraries on each machine's local disk. Research inputs, results and logs can be stored in a separate project directory.

A compatible prebuilt AVL 3.52 executable can also be used; compiling AVL is not an inherent MCP requirement. See native installation. Python release artifacts are a wheel, source distribution and checksums; AVL remains a separate installation. The existing optional native bundle is retained on the v0.1.0a1 release.

For Ubuntu 24.04 x86_64, use the Linux build and validation guide. It builds verified upstream source with GNU compilers, X11 and the numerical libraries shipped in the AVL archive. Headless analysis does not require an X server.

Building AVL on macOS Apple Silicon

The upstream 3.52 source archive is available at https://web.mit.edu/drela/Public/web/avl/avl3.52.tgz. The archive used for this release has SHA-256 0b588ecea9222f5b625d0af0c87ae31daf3cdba1532cf0bbb36f93d6e854849b.

Upstream requires Fortran/C compilers, a plotting library and numerical libraries. This project includes a helper for a task-local conda-forge environment containing gfortran_osx-arm64=14, xorg-libx11, and xorg-xorgproto. The last package provides the X11 protocol headers needed at build time. Xcode Command Line Tools must already be available. A platform-specific dependency lock records the tested compiler environment in docs/native-dependencies-osx-arm64.lock.

python scripts/build_avl_macos.py \
  --source /absolute/path/to/extracted/AVL3.52rel09032025 \
  --compiler-prefix /absolute/local/path/to/compiler-environment \
  --logs /absolute/path/to/project/logs

The helper modifies only the disposable build copy's plot-library configuration, and overrides compiler/linker flags. It does not patch the numerical solver. scripts/bundle_avl_macos.py can collect the required dylibs into a new local directory and update their relative load paths. The current execution path disables graphics, so a running X server is not required. X11 libraries remain link dependencies. Interactive plotting is not tested or exposed by this MCP.

MCP client configuration

Example Codex configuration, using absolute paths chosen for your machine:

[mcp_servers.avl]
command = "/absolute/local/path/avl-mcp-env/bin/avl-mcp"
args = [
  "--avl-bin", "/absolute/local/path/avl-3.52/bin/avl",
  "--work-root", "/absolute/path/to/project/AVL",
  "--input-root", "/absolute/path/to/approved/model-directory"
]
tool_timeout_sec = 660

--input-root is optional. If supplied, model files must resolve inside that root. Dependencies must remain inside the model's own directory, even without this option. For synchronous calls, set the client timeout above the requested analysis time budget. For long analyses, use avl.submit; its short response does not wait for the solver. Equivalent environment variables are AVL_BIN, AVL_MCP_WORK_ROOT, and AVL_MCP_INPUT_ROOT. The default budget is 5,000 estimated vortices per case; --max-vortices can explicitly raise it up to 20,000. This is an estimate, not a RAM guarantee.

Installing a wheel and testing a standalone MCP process do not register tools in an already running desktop session. Client registration/reload is a separate step.

For connection troubleshooting, run avl-mcp --diagnose or avl-mcp --check-mcp with the same AVL/work-root arguments. They print structured evidence without changing client settings. Diagnostic layers and workflow distinguish native startup, numerical tests, fresh stdio and desktop registration.

Example requests

Inspect an official example:

{"model_path": "/absolute/path/to/avl-mcp/examples/official/vanilla/vanilla.avl"}

Run a prescribed condition with avl.run:

{
  "model_path": "/absolute/path/to/vanilla.avl",
  "condition": {
    "alpha_deg": 3.0,
    "beta_deg": 0.0,
    "mach": 0.2,
    "pb_2v": 0.0,
    "qc_2v": 0.0,
    "rb_2v": 0.0,
    "controls": {"elevator": 1.0}
  },
  "case_name": "vanilla-elevator",
  "timeout_seconds": 120,
  "length_unit": "unspecified"
}

controls maps the CONTROL variable names in the geometry to their values. Local deflection in degrees equals the variable value multiplied by that section's gain; it is not necessarily the physical deflection of every connected surface. Unknown control names are rejected. Omitted controls and angular rates are zero. Omitted Mach uses the geometry header. Nearby .run and .mass files are intentionally not loaded in prescribed-condition analyses.

Longitudinal aerodynamic trim

Call avl.trim to solve alpha and one named CONTROL variable at a required Mach:

{
  "model_path": "/absolute/path/to/vanilla.avl",
  "request": {
    "control": "elevator",
    "target_cl": 0.6,
    "target_cm": 0.0,
    "mach": 0.2,
    "alpha_bounds_deg": [-10.0, 15.0],
    "control_bounds": [-30.0, 30.0],
    "fixed_controls": {"flap": 0.0},
    "cl_tolerance": 0.000001,
    "cm_tolerance": 0.000001
  },
  "case_name": "vanilla-trim",
  "timeout_seconds": 120,
  "outputs": ["total"]
}

Beta and all angular rates are zero. Other controls are fixed at the requested values, defaulting to zero. CONTROL values retain the geometry's gains and signs; they are not automatically physical elevator deflections. Cm refers to the model's moment reference, or an explicit references override, which is not necessarily the aircraft CG. No .mass or .run file is loaded.

AVL's native solver is unconstrained: the required bounds decide whether its solution is acceptable and do not clip the result or constrain its iterations. A successful result must meet CL/Cm residual tolerances and bounds, then pass a fresh fixed-condition run at the solved alpha and control values. The saved trim metadata separates the request, solved condition, residuals, bounds and verification. This is aerodynamic lift/pitch-moment trim, without weight/thrust balance. See the full trim contract and failure behavior.

Use avl.sweep with model_path and exactly one of conditions or trim_requests. For prescribed conditions, its execution budget is 300 seconds by default (one total budget, not a separate allowance per condition). Cases are grouped by Mach to reuse AVL's matrix factorization and returned in the original request order. Each native process handles at most 128 conditions; the connector explicitly resets every angular rate and control at every point. Execution stops on the first error unless stop_on_error=false; remaining cases then use a fresh process. Timeout/cancellation always stops the attempt. The MCP response includes at most 25 case summaries; use avl.results to page the rest. Completed cases and failed-attempt logs remain available. A partial synchronous sweep returns isError=true. Full results are in result.json.

For trim batches, pass trim_requests: [<TrimRequest>, ...] instead of conditions. Each request has the same required targets, control and bounds as avl.trim above. Every point runs a fresh native trim followed by independent prescribed-condition verification; all points and replays share the total timeout budget. The same input works with avl.submit for cancellation, verified resume and progress. See batch examples, saved results and failure semantics.

Select outputs

avl.run, avl.trim, avl.trim_physical, avl.sweep and avl.submit accept outputs. Omit it to retain the previous complete output set. Use ["total"] for forces/moments only, or e.g. ["total", "body"] to add body-axis derivatives. Supported tables are total, stability, body, surfaces, strips. Total output is always retained to verify that AVL used the requested conditions. Skipped tables are not generated or parsed; querying one later reports FIELD_NOT_AVAILABLE rather than rerunning AVL.

Durable background jobs

Call avl.submit with the same model, conditions or trim_requests, and outputs as a sweep. It returns a job_id; use that ID with avl.status, avl.cancel, avl.resume and avl.results. Workers run independently of the MCP connection and keep their state under <work-root>/jobs/. At most two background jobs execute at once per work root; additional workers wait. Synchronous calls are outside this queue.

avl.status returns queued, running, completed, failed, cancelled or interrupted, completed/failed counts, and the last error. success=true means the status query succeeded, not that the solver job passed. Cancellation is cooperative: query until acknowledged. Only that worker's owned AVL process is stopped. Completed cases and all native attempts are retained.

An inactive job can be resumed from another MCP connection using the same work root and implementation. Resume checks original geometry and dependencies, staged input hashes, settings, executable hash, and the MCP implementation hash. Changed inputs/solver/code require a new job. Valid successful case checkpoints are reused; missing/damaged outputs and failed cases are recomputed. Timeouts apply per execution attempt (excluding queue time); resume grants the same budget again. A worker lost during startup may take up to 30 seconds to be identified. Do not edit/remove active job files. Cross-machine/network-filesystem locking is not established; use one host per work root.

Query coefficients without invoking a solver:

{
  "job_id": "<id returned by submit, run, trim or sweep>",
  "indices": [0, 3, 8],
  "fields": ["total.fields.CLtot", "body.derivatives.Cmq"],
  "offset": 0,
  "limit": 20
}

avl.results pages cases in original index order (limit 1-100); indices filters that list. Dotted field names preserve case, e.g. stability.control_derivatives.elevator.Cm. With no fields, each row includes total coefficients and saved artifact paths, including strip CSV/JSON when requested. Unfinished cases are absent, not zeros. Large responses are rejected with a request to narrow the selection. Results can be read even when the AVL executable is unavailable. For older runs, the directory basename is the run ID. Job control tools apply only to background jobs.

Optional references must specify all six values: sref, cref, bref, xref, yref, zref. Overrides affect only the staged copy. Cref, Bref, and the three coordinates use the geometry's length unit; Sref uses its square. length_unit labels the data (m, ft, in, or unspecified); it does not convert geometry. For the official Bubble Dancer example, the supplied mass file documents inches.

Results and conventions

Every successful case adds a versioned result_contract, also saved as result-contract.json: actual reference dimensions/point, units, axes, coefficient normalizations, ST/SB derivative variables and section control gains. Compact result_context accompanies sweep summaries and selected saved-result queries. Unknown units stay Lunit; native coefficients are unchanged. Separately calculated derived.wind_forces records the rotation of native stability totals.

See the complete result contract, including two upstream 3.52 caveats exposed by tests: constant CDp with sideslip can make native stability and body force projections differ, and ST alpha derivatives at nonzero p/r can differ from fixed-stability-rate perturbations. Applicable cases carry explicit limitation codes and warnings; no native number is silently corrected.

Synchronous executions use <work-root>/runs/; background jobs use <work-root>/jobs/. Each job retains native process folders and separate per-case outputs:

  • Original input snapshots, staged geometry and dependencies, and SHA-256 records.

  • manifest.json, exact commands.txt, stdout.log, stderr.log, process.json.

  • Raw total.mrf and the other selected MRF tables.

  • Parsed result.json; selected strips add strips.json/strips.csv, synchronous sweeps add summary.csv.

  • Background input snapshots, atomic per-case checkpoints, attempt records and worker logs.

The parser requires MRF VERSION 1.0, complete tables and finite numerical values. It verifies all 30 ST or 36 SB derivatives, every declared CONTROL/DESIGN column, integer counts, unique fields, load indices and matching load references. Missing rows, duplicate records and truncated DESIGN tails fail instead of returning partial success. It distinguishes missing/truncated output, solver diagnostics, version mismatch, timeouts, changed input, and requested-versus-actual condition mismatch. Logs go to files, never to the MCP protocol's stdout channel.

Quantity

Convention

Geometry coordinates

X aft, Y right, Z up

Input angular rates

Standard body axes: X forward, Y right, Z down; pb/(2V), qc/(2V), rb/(2V)

CXtot, CYtot, CZtot, Cltot, Cmtot, Cntot

Standard body-axis force/moment coefficients

CLtot, CDtot; Cl'tot, Cn'tot

Stability-axis lift/drag; stability-axis roll/yaw moments

stability (ST)

Stability-axis derivatives; alpha/beta derivatives per radian

body (SB)

Body-axis derivatives; normalized velocity and angular-rate variables

Control derivatives

Per CONTROL variable unit, including geometry gains

Moment reference

Xref/Yref/Zref; not necessarily a mass-derived aircraft CG

CDind

Near-field induced contribution

CDff

Trefftz-plane induced drag; keep separate from CDind

CDvis

Supplied profile-drag model; not a viscous flow solution

Raw key case is preserved: CL is lift and Cl is roll moment. At nonzero beta, stability axes and full wind axes differ. Undefined AVL diagnostic sentinels for neutral point/spiral parameter are returned as JSON null, not physical values.

Limits and validation

AVL is a thin lifting-surface, slender-body and quasi-steady potential-flow model. It does not establish stall, separated-flow or transonic accuracy. The connector accepts 0 <= Mach < 0.7 and warns on large angles/high Mach; those limits do not certify physical accuracy. Numerical agreement between wrappers or solvers is not flight validation.

See docs/validation.md for the tested conditions and scope. The included geometries come from the official AVL archive. Regression snapshots are generated outputs on the tested build, not published experimental truth.

AVL_BIN=/absolute/path/to/avl python -m pytest -q
python scripts/verify_stdio.py \
  --command /absolute/path/to/avl-mcp-env/bin/avl-mcp \
  --avl-bin /absolute/path/to/avl \
  --work-root /absolute/path/to/project/AVL \
  --vanilla examples/official/vanilla/vanilla.avl \
  --bd examples/official/bd/bd.avl

Native tests are explicitly skipped if AVL_BIN is absent. Use AVL_TEST_WORK_ROOT to retain native pytest run artifacts in a chosen directory.

Roadmap

  • Add explicit control mixing and mass/inertia-dependent flight trim or eigenmode analysis after their input and verification contracts are defined.

  • Add controlled geometry generation and previews after the analysis interface stabilizes.

Research aircraft models and CFD data are not part of this repository.

License and acknowledgements

This repository is released under GPL-2.0-or-later; see LICENSE. AVL is by Mark Drela and Harold Youngren. The official source and MRF readers carry GPL-2.0-or-later notices, with additional contributor credits in their source files. Example inputs retain their upstream content; see THIRD_PARTY_NOTICES.md. The numerical solver is installed separately. Distributing native binaries requires preserving their applicable notices, licenses and corresponding-source obligations, including those of bundled libraries. No native binary is included in the Python wheel.

Available Tools

14 tools
avl.cancelA
Idempotent

Request cooperative cancellation of this job's worker and its owned AVL process. Completed cases and logs remain. Query status until cancellation is acknowledged.

Inputs: job_id (required).

avl.healthA

Diagnose Python/native dependencies, architecture, directory permissions and AVL startup. Save evidence. Numerical validation and desktop registry refresh remain separate.

Inputs: no named parameters.

avl.inspectA
Read-onlyIdempotent

Read geometry, references, controls and dependencies; original files are unchanged.

Inputs: model_path (required).

avl.mesh_sensitivityA

Compare a fixed flight condition across 2-8 increasing mesh factors starting at 1. Refine surface chord/span counts on staged copies; body discretization stays fixed. Preflight every mesh against the configured vortex budget. Save coefficients, baseline/adjacent differences, JSON, CSV and Markdown with one total timeout. Optional absolute tolerances only assess the final adjacent difference; no automatic mesh-convergence claim, Richardson extrapolation, or geometry suitability proof.

Inputs: request (required), model_path (required), case_name, references, +2 more.

avl.prepare_trimA
Read-onlyIdempotent

Convert explicit SI mass/weight, density and speed to target CL without running AVL. Require geometry length units and a CG with units; set the moment reference to CG. Return a TrimRequest and References usable in trim/sweep/submit, plus provenance. Assumes unbanked steady level lift=weight, zero beta/rates and target Cm=0. Mach is supplied separately; no inferred atmosphere, thrust balance or inertia model.

Inputs: request (required), model_path (required), references.

avl.resultsA
Read-onlyIdempotent

Page saved background or run/sweep results without running AVL. Limit 1-100 cases. Filter by original zero-based indices and dotted fields, e.g. total.fields.CLtot, body.derivatives.Cmq, stability.control_derivatives.elevator.Cm. Missing tables return FIELD_NOT_AVAILABLE; raw/strip artifact paths remain available by default.

Inputs: job_id (required), limit, fields, offset, +1 more.

avl.resumeA

Resume an inactive job after verifying input, solver, implementation and output hashes. Recompute only failed, missing or damaged cases. Active jobs cannot be resumed.

Inputs: job_id (required).

avl.runA

Run one prescribed flight condition. Return forces, ST/SB derivatives, surface loads and links to strip CSV/JSON. Angles in degrees, rates nondimensional BODY axes; CONTROL values use gains defined in geometry. Default controls/rates zero. A references override changes only the staged copy. Ignores nearby .run/.mass.

Inputs: model_path (required), outputs, case_name, condition, +3 more.

avl.statusB
Read-onlyIdempotent

Read queued/running/completed/failed/cancelled/interrupted state and case counts. success=true means the status was read; inspect state/error for solver outcome.

Inputs: job_id (required).

avl.submitA

Snapshot inputs and start a detached local AVL job; return job_id immediately. 1-10000 cases, at most two background workers execute per work root. Workers survive MCP client disconnection. Timeout is the execution budget per attempt, excluding queue. Supply exactly one of conditions or trim_requests. Every trim requires its own fresh verification; cancel interrupts candidate/replay and resume reuses verified cases only. outputs=['total'] skips derivatives/surface/strip output; None requests all tables.

Inputs: model_path (required), outputs, case_name, conditions, +5 more.

avl.sweepA

Supply exactly one of conditions or trim_requests, each containing 1-10000 cases. Prescribed conditions share AVL processes grouped by Mach, resetting rates/controls. Trim requests run sequentially: each solves alpha/CONTROL for CL/Cm and independently replays in a fresh process. All cases and replays share one total timeout budget. Return cases in requested order with trim residuals, bounds and verification metadata. Select outputs (total is always retained); None preserves all previous tables. Preserve successful and failed cases and write summary.csv. For long jobs use submit. Return partial results and isError=true if any requested case is unsuccessful.

Inputs: model_path (required), outputs, case_name, conditions, +5 more.

avl.trimA

Solve alpha and one existing CONTROL for target CL/Cm at zero beta/body rates. CONTROL values retain section gains, not automatically physical deflection degrees. Bounds accept/reject the native solution, not constrain iterations. Success requires residual/bounds checks and a fresh fixed-condition solve. Moments use the explicit geometry/override reference point, not an inferred CG. No mass/thrust balance.

Inputs: request (required), model_path (required), outputs, case_name, +3 more.

avl.trim_physicalA

Prepare lift=weight and zero pitching moment about explicit CG, then verify trim. Takes SI mass/weight, density and speed plus declared geometry/CG length units. Solves alpha and one CONTROL with bounds/residual checks and independent replay. Save dimensional inputs and conversion provenance with native results, including numerical failures. Mach remains explicit. No thrust balance, mass file or eigenmodes.

Inputs: request (required), model_path (required), outputs, case_name, +2 more.

avl.validateA
Read-onlyIdempotent

Validate supported text grammar, dependencies and mesh limits. No solver execution.

Inputs: model_path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools have clearly distinct roles: single-case run, multi-case sweep, detached submit, and job control/status/results are readily separable. The main ambiguity is within the trim family (prepare_trim, trim, trim_physical), though their descriptions clarify whether AVL is executed and what inputs are required.

    Naming Consistency3/5

    All names use lower snake_case under the avl. namespace, which is consistent at the lexical level. However, the set mixes imperative verbs (run, sweep, submit, inspect) with noun-like resource names (status, results, health) and compound descriptive forms (mesh_sensitivity, trim_physical), so it is readable but not a predictable verb_noun convention.

    Tool Count5/5

    Fourteen tools is well within the appropriate range for a complex AVL analysis server. Each major phase—inspection, validation, execution, background job control, and result retrieval—has a dedicated tool without obvious filler.

    Completeness4/5

    The surface covers the core AVL lifecycle: inspect/validate/health, trim preparation, run/sweep/submit, status/cancel/resume, and results retrieval. Minor gaps such as a job-list operation or explicit geometry/setup management are not central to the apparent analysis scope, but there is no obvious dead end.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Provides MCP tools for CPACS-oriented TiGL workflows, enabling lifecycle management, inspection, export, and parameter manipulation of aircraft geometry models without native geometry runtimes.
      11
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Maintained fork of Three-Little-Birds/openvsp-mcp, adding OpenVSP geometry inspection, typed parameter editing, SVG/STL previews, validated VSPAERO analysis, and durable parallel batches with progress, cancellation, resume, and CSV/JSON export. Independently maintained by rhyne1012; not an official OpenVSP or NASA project.
      18
      MIT