petri-pilot MCP Server

This endpoint serves the Model Context Protocol (MCP) over Streamable HTTP at https://pilot.pflow.xyz/mcp.

OpenAPI Spec (JSON) GitHub

Add to Claude Code

One command in your terminal:

claude mcp add --transport http petri-pilot https://pilot.pflow.xyz/mcp

Verify it registered:

claude mcp list

Or add it manually by editing ~/.claude.json (user scope) or .mcp.json in your project root:

{
  "mcpServers": {
    "petri-pilot": {
      "type": "http",
      "url": "https://pilot.pflow.xyz/mcp"
    }
  }
}

Once added, restart Claude Code and the tools below will be available.

Add to Other MCP Clients

For Claude Desktop, Cursor, or any MCP-compatible client, use this config snippet:

{
  "mcpServers": {
    "petri-pilot": {
      "url": "https://pilot.pflow.xyz/mcp"
    }
  }
}

Available Tools

petri_analyze petri
Analyze a Petri net model for behavioral properties including reachability, deadlocks, liveness, boundedness, and element importance.
full — Include sensitivity analysis (element importance, symmetry groups)
model required — The Petri net model as JSON or tokenmodel DSL (S-expression format starting with '(')
petri_application petri
Generate a complete full-stack application from an Application specification. This accepts the high-level Application DSL with entities, roles, pages, and workflows.
backend — Backend language: go, javascript (default: go)
database — Database: postgres, sqlite (default: sqlite)
frontend — Frontend framework: esm (ES modules), none (default: esm)
spec required — Complete Application specification as JSON (with entities, roles, pages, workflows)
petri_code_to_flow petri
Convert source code into a formal Petri net model. Analyzes code structure (control flow, state machines, resource management, concurrency) and produces an executable, verifiable Petri net — not just a diagram.
code required — Source code to analyze and convert into a Petri net model
focus — Analysis focus: control-flow (function call sequences), state-machine (state transitions), resources (resource allocation/consumption), concurrency (parallel processes, synchronization). Defaults to auto-detect.
language — Programming language of the source code (e.g., go, python, javascript, java). Auto-detected if omitted.
name — Name for the generated model. Defaults to a name derived from the code.
petri_codegen petri
Generate executable code from a validated Petri net model. Produces event-sourced application code with state machine, events, and API handlers.
extensions — Optional JSON object with extensions: {"roles":[...], "views":[...], "admin":{...}, "navigation":{...}}. These add authentication, views, and UI features to the generated code.
language — Target language: go, javascript, python (default: go)
model required — The Petri net model as JSON or tokenmodel DSL (S-expression format starting with '(')
package — Package/module name for generated code
petri_diff petri
Compare two Petri net models and show structural differences. Reports added, removed, and modified places, transitions, arcs, roles, and access rules.
model_a required — First model as JSON (the 'before' or 'base' model)
model_b required — Second model as JSON (the 'after' or 'new' model)
petri_docs petri
Generate markdown documentation from a Petri net model with mermaid diagrams for visualization. Useful for exploring and understanding models.
include_metadata — Include model metadata in documentation (default: true)
model required — The Petri net model as JSON or tokenmodel DSL (S-expression format starting with '(')
petri_extend petri
Modify an existing Petri net model by applying operations. Operations: add_place, add_transition, add_arc, add_event, add_event_field, add_binding, remove_place, remove_transition, remove_arc, remove_event, remove_binding. Returns the modified model.
model required — The Petri net model as JSON
operations required — JSON array of operations. Each operation has 'op' (operation type) and operation-specific fields. Examples: {"op":"add_place","id":"new_state"}, {"op":"add_transition","id":"transfer","event":"transferred","guard":"balances[from] >= amount","bindings":[{"name":"from","type":"string","keys":["from"]},{"name":"amount","type":"number","value":true}]}, {"op":"add_arc","from":"pending","to":"approve"}, {"op":"add_event","id":"transferred","fields":[{"name":"from","type":"string"},{"name":"amount","type":"number"}]}, {"op":"add_binding","transition":"transfer","name":"to","type":"string","keys":["to"]}
petri_frontend petri
Generate a vanilla JavaScript ES modules frontend application from a Petri net model. Produces a Vite + ES modules project with API client, state display, and transition forms using plain JavaScript.
api_url — Backend API base URL (default: http://localhost:8080)
extensions — Optional JSON object with extensions: {"roles":[...], "views":[...], "admin":{...}, "navigation":{...}}. These add authentication, views, and UI features to the generated frontend.
model required — The Petri net model as JSON or tokenmodel DSL (S-expression format starting with '(')
project — Project name for package.json (default: model name)
petri_heatmap petri
Render the model's marking as a 2D colored grid heatmap (viridis colormap). Useful for high-place models (TTT boards, zk-ode topologies, grid-structured nets). Each cell shows place ID + value. Returns inline PNG.
cols — Grid columns (0/omit = auto-square)
labels — Show place IDs and values in each cell (default true)
marking — Optional JSON object {place_id: value} overriding the initial marking
model required — Petri net model JSON or tokenmodel DSL
rows — Grid rows (0/omit = auto-square)
title — Optional title shown above the heatmap
petri_migrate petri
Migrate a Petri net model from v1 (flat) to v2 (nested) schema format. V2 format separates the net definition from extensions like roles and views.
model required — The v1 Petri net model as a JSON string
petri_ode petri
Run an ODE (mass-action kinetics) simulation of the Petri net using the Tsit5 solver (matches pflow.xyz). Returns a downsampled time series of place concentrations and an inline PNG plot. Use mode=equilibrium to integrate until the system stabilizes.
layout — Output layout: 'plot' (default, trajectory only), 'combined' (net snapshot at final marking + plot side-by-side), or 'net' (net snapshot only, no plot)
method — 'tsit5' (default), 'rk45', 'rk4', or 'euler'
mode — 'solve' (full trajectory, default) or 'equilibrium' (stop at steady state)
model required — Petri net model JSON or tokenmodel DSL
plot — Include inline PNG plot (default true). Ignored when layout is set.
rates — Optional JSON object mapping transition_id to rate (default 1.0 for each transition)
samples — Max trajectory samples returned (default 200, downsampled if needed)
tspan — Optional JSON array [t0, tf] (default [0, 10])
variables — Optional JSON array of place IDs to plot (default: all places)
petri_ode_sensitivity petri
ODE sensitivity analysis: perturb each transition's rate by a small delta and measure how much an observable's equilibrium value moves. Returns dimensionless elasticities per transition plus an inline net diagram tinted by influence. Use when you want to know which knobs matter for dynamics, not just structure.
base_rates — JSON object of base rates per transition (default 1.0)
delta — Perturbation fraction (default 0.05 = 5%)
model required — Petri net model JSON or tokenmodel DSL
observable required — Place ID whose equilibrium value is the target metric
title — Title shown above the sensitivity diagram
tspan — Per-run integration span (default [0, 50])
petri_ode_sweep petri
Run multiple ODE trajectories at different rates and overlay them on one plot. Useful for seeing how dynamics change with a parameter — regime shifts, peak shifts, time-to-equilibrium. Each rate value gets its own viridis-colored line.
fixed_rates — JSON object of other transition rates (default 1.0)
model required — Petri net model JSON or tokenmodel DSL
observable required — Place ID whose trajectory is shown (one observable per call to keep the plot readable)
range — JSON array [start, stop, n] generating n equally-spaced rates. Alternative to values
samples — Max samples per trajectory after downsampling (default 200)
transition required — Transition ID whose rate is being swept
tspan — Integration span (default [0, 10])
values — JSON array of rate values to sweep. Alternative to range
petri_preview petri
Preview a single generated file without full code generation. Use this to check specific files before committing to full generation. Available templates: main, workflow, events, aggregate, api, openapi, test, config, migrations, auth, middleware, permissions, views, navigation, admin, debug
file required — Template name to preview (e.g., 'api', 'workflow', 'events', 'aggregate', 'main')
model required — The Petri net model as JSON
petri_rate_scan petri
Parameter sweep: vary one transition's mass-action rate over a list of values, run each to equilibrium, plot observables (steady-state place concentrations) vs the swept rate. Returns JSON of all results plus an inline PNG.
fixed_rates — JSON object of other transition rates held constant during the sweep (default 1.0 for unspecified)
model required — Petri net model JSON or tokenmodel DSL
observables — JSON array of place IDs to track at equilibrium (default: all places)
plot — Include inline PNG plot (default true)
range — JSON array [start, stop, n] generating n equally-spaced rate values from start to stop. Alternative to 'values'
transition required — Transition ID whose rate is being swept
tspan — Per-run integration span (default [0, 50]). Must be long enough for the system to settle at each rate
values — JSON array of rate values to test (e.g. [0.1, 0.5, 1.0, 2.0, 5.0]). Either this or 'range' is required
petri_simulate petri
Simulate firing transitions and see state changes. Returns detailed step-by-step state trace. Use this to verify workflow behavior before code generation.
model required — The Petri net model as JSON
steps — JSON array of simulation steps with optional bindings: [{"transition":"id","bindings":{...}}]. For simple cases, you can also use 'transitions' parameter.
transitions — JSON array of transition IDs to fire in order (simple alternative to 'steps')
petri_validate petri
Validate a Petri net model for structural correctness. Checks for empty models, unconnected elements, and invalid arc references.
model required — The Petri net model as JSON or tokenmodel DSL (S-expression format starting with '(')
petri_visualize petri
Generate an SVG visualization of a Petri net model showing places, transitions, and arcs. Returns both SVG text and an inline PNG. Supports shading: 'sensitivity' (run analyzer and tint by element importance) or 'marking' (color places by user-supplied values).
marking — Optional JSON object {place_id: value} overriding the initial marking. Used as both label values and (with shade=marking) fill saturation
model required — The Petri net model as JSON or tokenmodel DSL (S-expression format starting with '(')
shade — 'none' (default), 'sensitivity' (color by analyzer importance), or 'marking' (color places by marking values)
title — Optional title shown above the diagram

Usage

Connect via MCP client:

{
  "mcpServers": {
    "petri-pilot": {
      "url": "https://pilot.pflow.xyz/mcp"
    }
  }
}

Or use the OpenAPI spec for REST-style tool invocation.

18 tools registered