OpenSysML MCP server

Advance the debuggers' simulation clock (%advance), running every state event, action token, change-condition poll and do behavior that comes due, in due order, and report what ran and where the debuggers stand. The clock is the session's: a debugged action and machine both move.

Apply source-preserving edits to a parsed model and return the edited notation (the ApplyEdits RPC): set a value, rename with every reference, add a member, import, documentation, comment, connection, transition, satisfy or metadata, delete, move. Edits are located from the parsed spans, so comments and layout outside them are kept, and the result is re-parsed and validated before it is answered; a refused batch answers `error` and `failure` naming why, and nothing is applied. Nothing is written to disk: the edited text comes back as `content` (one document) or `documents` for the agent to write. The result is the ApplyEditsResponse as protojson writes it.

Edit a model by operations on its elements rather than by text: setValue, rename, addMember, addConnection, addSequence (action-body items), delete, move, and the diagram-layout annotations setLayout, setRoute, setCanvas, setStyle, setNote, setPicture. Targets and owners are qualified names as render_view reports them in nodes[].fqn. Returns the text edits the operations amount to, per document, and the operations refused with why; writes the files only with apply=true.

Ask an SMT solver whether a constraint, requirement or satisfaction can be satisfied at all (%check, experimental), with a satisfying assignment when it can. Needs z3 or cvc5 installed; the status is unavailable otherwise.

Search every schedule of an action or state machine (the CheckBehavior RPC, the REPL's %check-property/%check-diverge settings about %action/%state): a property false at a stable state, a deadlock, a failure or a feature whose final value the schedule decides is witnessed and replayed. `verdict` is holds, fails or undecided; `violations`, `divergences` and `finals` carry each witness as its replay schedule, draws and choices, and the witness file when asked for. With checkInput or checkAssume the symbolic engine answers with `claim`, the inputs it ranged over and its witnesses. Bounded by checkDepth, checkStates and checkTimeout. The result is the CheckBehaviorResponse as protojson writes it.

Release a document held open by open_document: the server goes back to the file on disk (or forgets the document when there is no file). Nothing is written.

List the quick fixes and refactorings available for a range of a document, each with the edits it would make. Nothing is applied; write the edits with your own file tools or use the rename/format/apply_model_edit tools with apply=true.

Run every configuration a SysML v1 tool's results sidecar indexes against the migrated model (the CompareResults RPC, the CLI's -compare-results with -action, -runs, -seed, -draws, -clock-step and -observe): each on its target, for its recorded run count under its duration mode, or the runs and draws given, and table the tool's and OpenSysML's min, mean, p50, p90 and max of each observable with their relative difference. `configurations` carry each one's status (holds, fails, unresolved), its rows, the distributions compared, the errors and notes, and the lines the CLI prints. The result is the CompareResultsResponse as protojson writes it.

Propose completions at a position: keywords, names in scope and members of the type being accessed.

Ask an SMT solver which variants an element's conditions permit (%configure, experimental): a consistent selection, the check of the selections given, or every consistent selection up to a limit. A part or definition is configured over every assertion about its objects. Read-only: no variant is bound.

Convert a SysML v2 model between the representations OpenSysML writes — textual notation, RDF Turtle, the API's JSON element form — (the Convert RPC, the CLI's -convert). Name the model by modelHash, paths or sources (the source the parse read is converted), or by filePath or inline content read afresh. Nothing is written to disk: the converted document comes back as `content` for the agent to write. A SysML v1 model is refused with INVALID_ARGUMENT: use migrate. The result is the ConvertResponse as protojson writes it.

Set breakpoints at nodes of the debugged action (%break), optionally clearing the earlier ones, and report the breakpoints it then has; with nothing to set, lists them. A node the action has none of fails, naming its nodes.

Run the debugged action to completion, or to the first breakpoint a token reaches (%continue), and report its results.

Report where the debugging session stands without changing it: the action's execution state, tokens, breakpoints and feature values (%tokens), or the machine's current state, clock, event queue, signals in flight and state data (%current, %events).

Start a debugging session on an action (%action) or a state machine (%state), performed by an object when one is named. The action is not stepped: debug_step advances one token step, debug_continue runs to completion or a breakpoint. A machine takes its entry; debug_step, advance and send drive it. Starting again replaces the session.

Advance the debugged action one token step, or the debugged state machine one step (%step): one event dispatched, one change event, one round of do actions. A token waiting only on the clock is not stepped; advance moves the clock.

End the debugging session (%stop), letting go of its run; objects the session holds stay.

Find where the name at a position is declared. Standard library declarations are reported as sysml://stdlib/<file> resources.

Report every diagnostic of a parsed model (the GetDiagnostics RPC), as `sysml -validate` does: each with its severity, code, message and position. Parse with `strictConformance` for the strict mode of `sysml -validate -strict`; `disableLint` and `enableLint` select the lints as `sysml -disable-lint`/`-enable-lint` do. The result is the DiagnosticsResponse as protojson writes it.

Outline a document: the elements it declares, nested as they are owned, with their kinds and ranges.

List the document definitions (doc def) declared across the workspace, which render_document renders to Markdown.

Takes no parameters.

Evaluate a SysML expression against a parsed model (the Evaluate RPC, the REPL's %eval): arithmetic, feature reads, quantities with units, collection operators. The result is the EvaluateResponse as protojson writes it: `result` is a Value (64-bit integers are JSON strings, as the proto3 JSON mapping writes them), `error` is set when the expression could not be evaluated. The text spells the value as the REPL prints it.

Invoke a calculation (the EvaluateCalc RPC, the REPL's %calc): a calc definition with positional arguments answers its `result`; a calc usage named with no arguments binds its inputs from its own members and answers every output feature in `outputs`. The result is the EvaluateCalcResponse as protojson writes it.

Run an action definition or usage to completion and report its output parameters (the ExecuteAction RPC, the REPL's %run). Inputs are bound by parameter name. Under an explore schedule every linearization the model admits is run and the answer is the set of distinct `outcomes` with how the exploration ended, instead of one run's outputs. The run is bounded by the service's OPENSYSML_MAX_* budgets; a budget hit is reported in `error`. `advance`, `seed`, `draws` and `clockStep` are the run options of `sysml -advance`, `-seed`, `-draws` and `-clock-step`. With `trace` the answer also carries every record the run made (token steps, waits, accepts, decisions, assignments, completion), up to a failure; `events` are posted to the performer in order, each once every token waits. The result is the ExecuteActionResponse as protojson writes it.

Run a state machine over a sequence of events and report the states visited, the final context and the simulation clock (the ExecuteState RPC, the REPL's %run on a state). With trace the answer also carries every record the run made (entry, exit, transition, accept, send, choice), up to a failure. Under an explore schedule every linearization is run and the answer is the set of distinct `outcomes`. With `advance` the events are sent and the clock then moved by that much, as `sysml -state X -advance T` does; without it the machine runs to quiescence. The run is bounded by the service's OPENSYSML_MAX_* budgets. The result is the ExecuteStateResponse as protojson writes it.

Ask an SMT solver which conditions of an unsatisfiable element conflict (%explain, experimental): a minimal set of conditions, each with the element declaring it and its location.

Explain a diagnostic code (as the CLI's -explain does): what it means, how to resolve it and the specification clause or validation constraint behind it. Every diagnostic the `parse`, `diagnostics` and `workspace_diagnostics` tools report carries one of these codes. With no code, list every code with its one-line summary.

Export the lowered graph of an action or state machine — the subject's and every behavior it performs — as the canonical graphs:<version> JSON external analysis engines read (the ExportGraphs RPC). The result is the ExportGraphsResponse as protojson writes it, the JSON in `content`; the text names the subject and version on its first line and carries the JSON after it.

Show an object's feature values and what its behaviors are doing (%features): the values its attributes hold, the objects its parts and ports hold, its connectors, and the state of each machine it exhibits and action it performs. Objects come from repl_command `%instantiate <name>` or from runs.

Format a SysML v2 / KerML document, or only the lines of a range, in the canonical style. Returns the edits and the resulting text; writes the file only with apply=true. A document that does not parse is left unchanged.

Explain the element at a position: its kind, qualified name, type, value and documentation, as Markdown.

Set the feature values a CSV, TSV, JSON or JSON Lines file assigns, one row per element (the ImportData RPC, the CLI's -import with -import-as, -import-map, -import-format and -import-dry-run): a feature the element declares has its value set, one it inherits is redefined in the element's body with the value, as one edit per file; a value the model refuses leaves every row unapplied and answers `error`. `files` carry each assignment with the element, feature, value and the inherited feature it redefines; the edited text comes back as `content` (one document) or `documents` with the `modelHash` of the imported model, nothing is written to disk. A dry run answers the assignments alone. The result is the ImportDataResponse as protojson writes it.

Import a draw.io (diagrams.net) file that render_view wrote with form drawio and a user edited in draw.io: what moved, resized, folded, re-routed or recoloured, the page size, a note's text and a picture's file become DiagramLayout annotations (Layout, Route, Style, Canvas, Note, Picture) in the view's body, and a name retyped in a node, port or edge label becomes a rename of the element, declaration and references alike, applied as apply_model_edit applies its operations. Cells the rendering lacks, cells naming no element, deleted cells, a label edited beyond its name, an invalid or taken name, an emptied note and a picture source no file under the view's directory names are reported, never created, deleted or guessed. Answers the planned edits and text changes; writes the files only with apply=true.

List the inferred types and values the editor would show inline for the features of a document or range.

List the objects a session holds (%instances): each with its id, type and lifetime, the ones a later instantiation displaced included.

Build an object of a part definition or usage and report its feature values (the Instantiate RPC, the REPL's %instantiate): every attribute's value or default, nested parts as instance ids, with every reachable instance in `instances`. The service keeps the object for the model: run_document_query on the same modelHash can bind it. The result is the InstantiateResponse as protojson writes it.

List the analysis engines this build registers (the ListEngines RPC, as the CLI's -engines does): each with the questions it answers (evaluate, outcomes, holds, sensitive, satisfiable, sweep, compute), the strongest evidence it can produce, the bounds it takes, and whether it can run here. The names are what the verification tools' `engine` argument takes; empty there means auto. With `probe` each external engine is started once and checked against its manifest, as `sysml -engines -probe` does. The result is the ListEnginesResponse as protojson writes it.

Migrate a SysML v1 model — UML XMI with the SysML profile, an Eclipse UML2 .uml file or a Cameo/MagicDraw .mdzip archive — to SysML v2 in one of the representations convert writes (the Migrate RPC, the CLI's -migrate). Migration is not lossless: every v1 element is mapped, approximated, left unmapped or skipped, and `report` accounts for each. Nothing is written to disk: the migrated model comes back as `content`, with any image files it refers to in `files`. The result is the MigrateResponse as protojson writes it.

Hold a document open with the given text, as an editor buffer the server analyzes instead of the file on disk, so text can be checked (diagnostics, hover, render) before it is written. Nothing is written to disk; close_document reverts to the file. format, rename and apply_model_edit with apply=true write the buffer, unless the file changed on disk since it was opened. Returns the diagnostics of the text.

Ask an SMT solver for the best values an analysis case's objectives admit (%optimize, experimental), each objective improved as its trade-study definition says, within the case's conditions.

Parse SysML v2 / KerML documents as one model and return its modelHash, the root namespace of each document and every diagnostic (the ParseSources RPC). Parsing is content-addressed: the same documents give the same modelHash, and the hash is what every other runtime tool takes as modelHash, so parse once and pass the hash, or give those tools the same paths/sources and they parse implicitly. A model is only readable when no diagnostic has severity error. The result is the ParseSourcesResponse as protojson writes it; the text lists each root and the diagnostics as the CLI prints them.

Select elements of a parsed model with a SysML v2 API & Services Query — scope, select, where, orderBy — or OSLC query text (the Query RPC). Each matched element answers its qualified name, metamodel type and the properties select asked for. A query the service cannot evaluate fails with INVALID_ARGUMENT rather than answering empty. The result is the QueryResponse as protojson writes it.

Run an analysis case — once, over the rows of a sweep (`ranges`), or as a Monte Carlo sample (`runs`) — and record the runs into the model as AnalysisRecords declarations (the RecordRun RPC, the CLI's -record-run/-record-into, the REPL's %record). `run`, `sweep` or `sample` is the runs' own report; `package`, `definition` and `records` name what the model gained and `source` is the declarations generated; `documents` (and `content` for a single document) is the notation of the document the records merged into, or the records as a document of their own, and `modelHash` names the recorded model, cached for the next request. A recording that would error or drop a declaration leaves the model unchanged and is the `error`. The result is the RecordRunResponse as protojson writes it.

Find every place in the workspace that refers to the element at a position.

Rename the element declared or referenced at a position, everywhere in the workspace. Returns the edits per document; writes the files only with apply=true.

Render a document definition (doc def) to Markdown, its queries evaluated over the workspace and its diagrams embedded.

Render a named document of a model given by modelHash, paths or sources (the workspace group's render_document renders by name over the root) — a part def specializing DocumentQueries::Document — to Markdown, HTML or AsciiDoc (the RenderDocument RPC, the CLI's -render-document), byte for byte what the CLI writes. The text is the rendered document; the result is the RenderDocumentResponse as protojson writes it.

Render a declared view or a targeted pseudo-view of a model given by modelHash, paths or sources as diagram data (the RenderView RPC; the workspace group's render_view renders by name over the root): nodes flattened parents first, edges with their ports, table columns and rows, canvas, notes and notices. The result is the RenderViewResponse as protojson writes it; the text lists the nodes and edges.

Render the run a session recorded as a state timeline or a message sequence (%render-run), in a text, diagram or SVG form. Recording must be on before the run: repl_command `%trace on`.

Render a diagram or table of a document: a declared view or a pseudo-view, as Mermaid, Graphviz dot, PlantUML, D2, draw.io (diagrams.net XML), text, Markdown, CSV or TSV. The result also lists the nodes and edges drawn with their qualified names (for apply_model_edit) and their declaration ranges in LSP form (0-based).

Run one sysml prompt command (a % line) in a session and return what it printed. Prefer the typed tools, which return the same data structured: session_load/session_submit/session_eval/session_print/session_save/session_clear, session_run, debug_*, send, advance, features, instances, check/explain/solve/configure/optimize, sweep, runs, render_run. This tool reaches everything else the prompt can do — %instantiate, %invoke, %constraint, %requirement, %satisfy, %validate, %calc, %analysis, %record, %import, %run-query, %render, %viz, %render-document, %trace, %schedule, %seed, %engine, %jobs, %budget, %verbosity, %strict, %lint, %search, %views, %documents, %list, the %check-* settings and the repository commands. Discover the commands with `%help` (every command with its arguments) and the settings with the command alone (`%schedule`, `%engine`). A command that reports an error fails the call with its output.

Run an analysis case (the RunAnalysis RPC, the REPL's %analysis): its subject and inputs bound from the arguments and its own declarations, its body run, every declared output answered with the verdict of its objective and of each assertion in its body; a verification case also answers its own verdict. A trade study's evaluations of each alternative are in `evaluations`. Under an explore schedule the answer is the set of distinct `outcomes`. Bounded by the service's OPENSYSML_MAX_* budgets. The result is the RunAnalysisResponse as protojson writes it.

Run a named document query with parameter bindings and answer its typed rows (the RunDocumentQuery RPC, the REPL's %run-query). The query runs over the model and over the objects instantiate created for the same modelHash, which a binding may name. The result is the RunDocumentQueryResponse as protojson writes it; the text is the table.

Run an action, or a Simulation::MonteCarlo analysis case, a number of times (the RunRuns RPC, the CLI's -runs/-observe, the REPL's %runs): every run is an ordinary run in a context of its own, drawing its modeled randomness from a seed derived from `seed`. `rows` is the table, one row per run with the run number as its input and what it observed as its outputs; `distributions` summarises each observable over the completed runs (extremes, mean, deviation, percentiles, histogram, or the count of each distinct value); for a case `outputs` and `verdicts` are its conclusion over the sample and `unconcluded` why it has none. A run that failed is its row's error. The result is the RunRunsResponse as protojson writes it.

Run an analysis case or calc once per row of a parameter sweep (the RunSweep RPC, the CLI's -sweep): each row an ordinary run with the swept parameters bound to that row's values, stepped through the ranges' cartesian product or drawn with samples and seed. A failed row is a row with `error`, not a failed table. Bounded by the service's OPENSYSML_MAX_* budgets. The result is the RunSweepResponse as protojson writes it; the text is the table.

Run an action count times, each run's modeled randomness seeded on its own, and return the table of the observables with each one's distribution (%runs); or run a Simulation::MonteCarlo analysis case count times on fresh subjects and conclude it.

Apply the SysMLValidation constraints, and those of any rule packages named, reflectively to every element of a model (the SelfCheck RPC, the CLI's -self-check and -self-check-package): each element is handed to every constraint whose input its metaclass conforms to. `status` is holds, fails or unresolved; `findings` carry each violation, evaluation the runtime could not make, error and skipped rule constraint with the element's location and the line the CLI prints; the counts and `applications` say how much was checked. The result is the SelfCheckResponse as protojson writes it.

Send a signal to an object through the runtime's message bus (%send), for the state machine it exhibits or the action parked at a matching accept to take; by default to the object whose behavior is being debugged. The signal is refused when no behavior of the object accepts it now. It is dispatched by the next debug_step or advance.

Report the OpenSysML runtime's version and the named capabilities this build supports.

Takes no parameters.

Reset a session, as %clear does: every declaration, object and debugging session goes; the session stays open and empty.

Close a REPL session, discarding its model, instances and any run in progress.

Evaluate an expression in a session, as %eval does: a literal, a declared feature or qualified name, an enumeration literal, a unit, or a compound expression over the session's declarations. Returns the value as data and as the prompt prints it.

List the open REPL sessions.

Takes no parameters.

Load model files into a session, as %load does: files, directories or globs, resolved against the workspace root and refused outside it. Every file is accepted before the model is analyzed, so load order does not matter, and files beside the paths that declare a namespace they import load too. Returns what loaded and the diagnostics.

Open a named REPL session: an empty model that declarations, instances and runs accumulate into across calls. The default session opens itself on first use, so this is only needed for a second, independent session, or for one with a root: a directory under the workspace root whose model files load on demand, as %load would load them, when a submission imports or qualifies a root namespace that neither the session nor the library declares.

Print a session's model as SysML notation, or one named element with its body, as %print does. Comments are kept, and what is printed can be submitted back.

Run a behavior in a session to completion and report what it produced: an action (%action then %continue), a state machine (%state, then %advance when a duration is given), a calc (%calc) or an analysis case (%analysis). Objects the run creates stay in the session, and the run's executor stays inspectable with debug_current until the next run or debug_stop. Under %engine check the behavior is checked over every schedule instead.

Write a session's model to a file under the workspace root, as %save does: .sysml notation with comments preserved, or .ttl/.json RDF (experimental). A path outside the root is refused. Without apply nothing is written and the file's content, in the format the extension names, is returned as content.

Submit SysML declarations to a session, as typing them at the prompt does: the text joins the model, the whole model is re-analyzed, and what it declared and the diagnostics about it come back. Submitting a name again replaces its earlier declaration. For an expression use session_eval; for a % command use repl_command.

Describe the invocation enclosing a position: the callable's parameters and which one the position is at.

Ask an SMT solver for values satisfying an element's conditions (%solve, experimental), keeping the values the model already fixes; reports the conflict when the fixed values admit none.

Run a calc or analysis case once per row of the ranges given (%sweep), or over rows drawn from them (%samples), and return the table: each row's inputs, outputs, verdicts and timing. The verdict holds when every run completed and every objective was satisfied.

Describe one element of a parsed model by qualified name (the GetSymbol RPC): its kind, metadata, children, attributes with their declared values, static type facts, multiplicity and specializations. An unknown name answers with `error` set rather than failing. The result is the SymbolResponse as protojson writes it.

List the tools this server serves: each tool's name, group, the sysml-grpc RPC or `sysml` CLI flag it stands for, and a one-line summary. Pass `group` (lsp, runtime, session) to narrow the list. The same catalog generates the Tools section of the sysml-mcp manual page.

Replace the text of a document held open by open_document and re-analyze it. Nothing is written to disk. Returns the diagnostics of the new text.

Validate an object of a part as a whole (the ValidateInstance RPC, the REPL's %validate): every assertion about an object of symbolId and about the objects it holds — asserted constraints of their types, the requirements they carry, the satisfactions they are the subject of — each answered on the concrete object, with a `summary` verdict about the object as a whole. The result is the ValidateInstanceResponse as protojson writes it.

Ask whether a constraint holds (the VerifyConstraint RPC, the REPL's %constraint): against its declared values, or against an object of subjectSymbolId built for the call. The answer is a Verdict: `holds`, the violated `condition`, or an `error` when nothing was decided, with the engine and strength of evidence. The question holds or satisfiable puts it to a solver over the free variables and answers with a witness assignment. The result is the VerifyConstraintResponse as protojson writes it.

Ask whether a requirement is satisfied (the VerifyRequirement RPC, the REPL's %requirement): its require constraints evaluated against declared values or against an object of subjectSymbolId. Beside the Verdict the answer carries what every verification case verifying the requirement concluded (pass, fail, inconclusive, error). The result is the VerifyRequirementResponse as protojson writes it.

Evaluate the satisfy assertions a model states (the VerifySatisfaction RPC, the REPL's %satisfy): each against an object of its subject built for the call, answering one Verdict per assertion in declaration order. A model stating no assertion answers an empty list, not an error. The result is the VerifySatisfactionResponse as protojson writes it.

List the views a document declares and the pseudo-views (#tree, #interconnection, ...) render_view can draw of it.

Analyze a SysML v2 / KerML document, or the whole workspace, and list the errors, warnings and hints: syntax, unresolved names, type and constraint violations. Positions are 1-based lines and columns.

Describe the SysML v2 workspace the server has indexed: its root folder and the model documents found under it.

Takes no parameters.

Search the workspace's declared elements by name substring.