Skip to main content
Glama
rhyne1012

OpenVSP MCP (Maintained Fork)

openvsp.run_vspaero

Destructive

Run one steady subsonic VSPAERO condition after geometry preflight, using a private model copy and retaining solver artifacts and coefficients without altering the source.

Instructions

Run one steady subsonic VSPAERO condition after geometry-set preflight. Runs native processes on a private model copy, retaining solver artifacts, coefficients and verified settings without replacing the source; the native timeout excludes preparation, CPU admission and validation. Failures retain run/log paths, and success does not certify convergence; use openvsp.sweep for sequential conditions or openvsp.batch_submit for independent jobs.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
requestYesModel, optional private-copy edits and one flight condition.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
timingsNoMeasured operation phase durations in seconds; available phase keys depend on execution.
log_pathYesAbsolute path to the retained OpenVSP process log.
versionsNoPackage version, MCP SDK version and package SHA-256, with observed native versions when available. Package identity changes on source/metadata updates.
warningsNoReference/unit/atmospheric consistency warnings and omitted undefined ratios; no automatic corrections.
artifactsNoMapping of run-relative artifact names to absolute file paths; files remain after the call.
operationNoExecuted operation: create, modify, preview, preflight or run_vspaero; reflects the enforced operation rather than the legacy input flag.run_vspaero
preflightNoSelected thick/thin geometry IDs and requested settings when preflight ran; empty otherwise. Does not certify mesh quality.
result_pathNoAbsolute path to the solver .adb result; null for operations without a VSPAERO solve.
script_pathYesAbsolute path to the retained AngelScript automation script.
coefficientsNoNative polar column names and finite unscaled values for a verified solve; empty otherwise. Undefined ratios are omitted with reasons in numerical_quality.unavailable_coefficients. Includes condition columns; AoA/Beta are degrees and Re/1e6 is Reynolds in millions.
geometry_pathYesAbsolute path to the validated model saved in the run directory, including for source-replacing edits.
manifest_pathYesAbsolute path to this operation's manifest.json; pass as manifest_file to openvsp.read_results.
run_directoryYesAbsolute path to the unique persistent directory containing this operation's artifacts.
analysis_inputsNoRequested analysis settings for solve/preflight, including defaults; empty for other operations. Units follow VSPAeroSettings and no conversion is applied.
parameter_valuesNoFinal native readback values keyed by edited parameter ID; native units, empty when no parameters were edited.
numerical_qualityNoObserved iteration-history diagnostics for a solve; convergence is not_assessed and mesh study not_performed. Empty for non-solver operations.
effective_settingsNoVerified solver-file values and observed CPU-thread information for a solve; empty before solving. Separate from requested analysis_inputs.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.8.0
    • changedOutput schema / properties / coefficients / description
      Previous value: -"Native polar column names and unscaled numeric values for a verified solve; empty otherwise. Includes condition columns as well as dimensionless aerodynamic coefficients; AoA/Beta are degrees and Re/1e6 is Reynolds in millions."New value: +"Native polar column names and finite unscaled values for a verified solve; empty otherwise. Undefined ratios are omitted with reasons in numerical_quality.unavailable_coefficients. Includes condition columns; AoA/Beta are degrees and Re/1e6 is Reynolds in millions."
    • changedOutput schema / properties / warnings / description
      Previous value: -"Reference/unit/atmospheric consistency warnings from existing checks; no automatic corrections."New value: +"Reference/unit/atmospheric consistency warnings and omitted undefined ratios; no automatic corrections."
  2. Changed49 schema fields changedv0.7.0
    • addedInput schema / $defs / OpenVSPRequest / properties / analysis / description
      Added value: +"One complete flight/solver settings object. Defaults do not come from the model; used by preflight and run_vspaero, ignored by modify/preview."
    • addedInput schema / $defs / OpenVSPRequest / properties / case_name / description
      Added value: +"Run-directory prefix and artifact filename stem, not a path. Defaults to case; use output_dir to choose the parent directory."
    • changedInput schema / $defs / OpenVSPRequest / properties / geometry_file / description
      Previous value: -"Existing .vsp3 input; run_vspaero leaves it unchanged"New value: +"Existing .vsp3 path; tilde expands and relative paths use the server working directory. modify replaces this source after validation; preview, preflight and run_vspaero use private copies."
    • changedInput schema / $defs / OpenVSPRequest / properties / output_dir / description
      Previous value: -"Parent directory for unique, persistent runs"New value: +"Parent for a unique persistent run directory. Omitted/null uses openvsp_runs beside the resolved source; tilde and relative paths resolve on the server. Existing run directories are not reused."
    • addedInput schema / $defs / OpenVSPRequest / properties / parameter_edits / description
      Added value: +"Parameter ID/value edits applied after set_commands, before one Update; defaults to none. Limits and final values are verified; obtain IDs with openvsp.query."
    • addedInput schema / $defs / OpenVSPRequest / properties / run_vspaero / description
      Added value: +"Legacy shared-request selector (default true). MCP modify/preview/preflight/run_vspaero force their named operation regardless of this value; it selects solve versus modify only when execute_openvsp has no explicit operation."
    • addedInput schema / $defs / OpenVSPRequest / properties / set_commands / description
      Added value: +"Ordered trusted AngelScript statements applied to the snapshot before parameter_edits and Update. Defaults to none; statements may perform their own I/O with server privileges."
    • addedInput schema / $defs / OpenVSPRequest / properties / timeout_seconds / description
      Added value: +"Native OpenVSP process timeout in seconds (default 600), including an invoked solver. Preparation, CPU admission and validation are outside this per-call native timeout."
    • addedInput schema / $defs / ParameterEdit / properties / parm_id / description
      Added value: +"Native parameter ID obtained from openvsp.query for the target model; not a display name."
    • addedInput schema / $defs / ParameterEdit / properties / value / description
      Added value: +"Requested finite value in the native units of that parameter, without conversion. Native limits and post-Update readback must accept the value."
    • addedInput schema / $defs / VSPAeroSettings / properties / alpha / description
      Added value: +"Angle of attack in degrees, passed to VSPAERO AlphaStart/AlphaEnd for one condition."
    • addedInput schema / $defs / VSPAeroSettings / properties / beta / description
      Added value: +"Sideslip angle in degrees, passed to VSPAERO BetaStart/BetaEnd for one condition."
    • addedInput schema / $defs / VSPAeroSettings / properties / bref / description
      Added value: +"Reference span in model length units; passed unchanged as bref. Supply a model-specific value; the default is 1."
    • addedInput schema / $defs / VSPAeroSettings / properties / cref / description
      Added value: +"Reference chord in model length units; passed unchanged as cref. Also identifies the chord basis of reynolds."
    • addedInput schema / $defs / VSPAeroSettings / properties / fixed_wake / description
      Added value: +"Use the official FixedWakeFlag; true requires WakeIters=0 in the generated solver file. Does not certify convergence."
    • addedInput schema / $defs / VSPAeroSettings / properties / forward_gmres_tolerance_factor / description
      Added value: +"Positive factor passed unchanged as ForwardGMRESConvergenceFactor, at most 1e12 (default 1); not an absolute residual tolerance."
    • addedInput schema / $defs / VSPAeroSettings / properties / length_unit / description
      Added value: +"Documentation only: m, ft or unspecified (default). Does not scale geometry or convert any input; all dimensional quantities must already be consistent."
    • addedInput schema / $defs / VSPAeroSettings / properties / mach / description
      Added value: +"Dimensionless Mach number for this steady subsonic case (0 <= Mach < 1). Independent of vinf, rho and reynolds; no atmosphere is derived."
    • addedInput schema / $defs / VSPAeroSettings / properties / ncpu / description
      Added value: +"Requested native CPU threads per solve, 1-255 (default 4). Must fit the server CPU budget and, for batch cases, the batch cpu_budget."
    • addedInput schema / $defs / VSPAeroSettings / properties / reynolds / description
      Added value: +"Dimensionless Reynolds number based on cref, passed as ReCref (not in millions). Independent of Mach, vinf and rho."
    • addedInput schema / $defs / VSPAeroSettings / properties / rho / description
      Added value: +"Freestream mass density in mass/volume units consistent with geometry and vinf (e.g. kg/m^3 in SI). Passed unchanged; no atmosphere or unit conversion."
    • addedInput schema / $defs / VSPAeroSettings / properties / sref / description
      Added value: +"Reference area in squared model length units; passed unchanged as Sref. Supply a model-specific value; the default is 1."
    • addedInput schema / $defs / VSPAeroSettings / properties / thick_geom_set / description
      Added value: +"OpenVSP set index for thick surfaces; -1 disables thick surfaces (default). Selected sets must exist, be nonempty and share no geometry with the thin set."
    • addedInput schema / $defs / VSPAeroSettings / properties / thin_geom_set / description
      Added value: +"OpenVSP set index for thin surfaces; 0 selects all geometry by default, -1 disables thin surfaces. Must differ from the thick set; at least one surface type must be selected."
    • addedInput schema / $defs / VSPAeroSettings / properties / vinf / description
      Added value: +"Freestream speed in length/time units consistent with the model and rho (e.g. m/s in SI). Passed unchanged; not computed from Mach and not converted by length_unit."
    • addedInput schema / $defs / VSPAeroSettings / properties / wake_iterations / description
      Added value: +"Requested WakeNumIter, 3-255 (default 30). When fixed_wake is true, the verified solver file instead has WakeIters=0."
    • addedInput schema / $defs / VSPAeroSettings / properties / wake_nodes / description
      Added value: +"Number of wake nodes passed as NumWakeNodes, 4-1024 (default 32)."
    • addedInput schema / $defs / VSPAeroSettings / properties / xcg / description
      Added value: +"X coordinate of the VSPAERO moment reference in model length units and model coordinates; passed unchanged as Xcg."
    • addedInput schema / $defs / VSPAeroSettings / properties / ycg / description
      Added value: +"Y coordinate of the VSPAERO moment reference in model length units and model coordinates; passed unchanged as Ycg."
    • addedInput schema / $defs / VSPAeroSettings / properties / zcg / description
      Added value: +"Z coordinate of the VSPAERO moment reference in model length units and model coordinates; passed unchanged as Zcg."
    • changedInput schema / $defs / VSPCommand / properties / command / description
      Previous value: -"Trusted AngelScript statement; runs with server privileges"New value: +"Trusted AngelScript statement executed with server-process privileges. May perform arbitrary file or external I/O; private-copy/source-preservation guarantees do not constrain the statement itself."
    • addedInput schema / properties / request / description
      Added value: +"Model, optional private-copy edits and one flight condition."
    • addedOutput schema / properties / analysis_inputs / description
      Added value: +"Requested analysis settings for solve/preflight, including defaults; empty for other operations. Units follow VSPAeroSettings and no conversion is applied."
    • addedOutput schema / properties / artifacts / description
      Added value: +"Mapping of run-relative artifact names to absolute file paths; files remain after the call."
    • addedOutput schema / properties / coefficients / description
      Added value: +"Native polar column names and unscaled numeric values for a verified solve; empty otherwise. Includes condition columns as well as dimensionless aerodynamic coefficients; AoA/Beta are degrees and Re/1e6 is Reynolds in millions."
    • addedOutput schema / properties / effective_settings / description
      Added value: +"Verified solver-file values and observed CPU-thread information for a solve; empty before solving. Separate from requested analysis_inputs."
    • addedOutput schema / properties / geometry_path / description
      Added value: +"Absolute path to the validated model saved in the run directory, including for source-replacing edits."
    • addedOutput schema / properties / log_path / description
      Added value: +"Absolute path to the retained OpenVSP process log."
    • addedOutput schema / properties / manifest_path / description
      Added value: +"Absolute path to this operation's manifest.json; pass as manifest_file to openvsp.read_results."
    • addedOutput schema / properties / numerical_quality / description
      Added value: +"Observed iteration-history diagnostics for a solve; convergence is not_assessed and mesh study not_performed. Empty for non-solver operations."
    • addedOutput schema / properties / operation / description
      Added value: +"Executed operation: create, modify, preview, preflight or run_vspaero; reflects the enforced operation rather than the legacy input flag."
    • addedOutput schema / properties / parameter_values / description
      Added value: +"Final native readback values keyed by edited parameter ID; native units, empty when no parameters were edited."
    • addedOutput schema / properties / preflight / description
      Added value: +"Selected thick/thin geometry IDs and requested settings when preflight ran; empty otherwise. Does not certify mesh quality."
    • addedOutput schema / properties / result_path / description
      Added value: +"Absolute path to the solver .adb result; null for operations without a VSPAERO solve."
    • addedOutput schema / properties / run_directory / description
      Added value: +"Absolute path to the unique persistent directory containing this operation's artifacts."
    • addedOutput schema / properties / script_path / description
      Added value: +"Absolute path to the retained AngelScript automation script."
    • addedOutput schema / properties / timings / description
      Added value: +"Measured operation phase durations in seconds; available phase keys depend on execution."
    • addedOutput schema / properties / versions / description
      Added value: +"Package version, MCP SDK version and package SHA-256, with observed native versions when available. Package identity changes on source/metadata updates."
    • addedOutput schema / properties / warnings / description
      Added value: +"Reference/unit/atmospheric consistency warnings from existing checks; no automatic corrections."
  3. First observedv0.6.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations give the safety profile (destructive, non-idempotent, open-world), but the description adds real context beyond them: work happens on a private model copy so the source is not replaced, solver artifacts/coefficients/verified settings are retained, the native timeout excludes preparation, CPU admission and validation, and success does not certify convergence. Failure-retention of run/log paths is also stated - all material an agent cannot get from the hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then scope/side effects, and ends with alternative-tool routing - nothing is wasted. It is clause-dense (semicolon-chained caveats) but still scannable and appropriately sized for a heavy solver call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description needs to supply scope, side effects and routing - and it does all three, including non-convergence caveats and failure artifact retention. Nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single top-level parameter (request) is fully documented in the schema, including the nested VSPAeroSettings fields. The description adds no per-parameter meaning beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run one steady subsonic VSPAERO condition') plus the precondition ('after geometry-set preflight'), and explicitly distinguishes itself from openvsp.sweep and openvsp.batch_submit by name. An agent can select it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: use openvsp.sweep for sequential conditions, or openvsp.batch_submit for independent jobs. The precondition (preflight first) is also named, so both when-to-use and alternatives are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.