petri-pilot MCP Server

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

Add to Claude Code

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

Add to Other MCP Clients

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

Available Tools

petri_amm_depth petri

Depth chart for a constant-product AMM: plots slippage (or output price) as a function of trade size. Use to answer 'how big can I trade before paying X% slippage?' and to size positions against pool depth.

fee_bps — Pool fee in basis points (default 30)
reserve_x required — Reserve of token X (input)
reserve_y required — Reserve of token Y (output)
size_range — JSON array [min_pct, max_pct, n] where pcts are fractions of reserve_x. Default [0.001, 0.5, 80]
trade_sizes — JSON array of trade sizes (in X). Alternative to size_range

petri_amm_il petri

Impermanent loss curve for a Uniswap V2-style LP. Plots IL(r) = 2·√r/(1+r) − 1 over a range of price ratios r = P_new/P_old. Optionally overlays a 'breakeven' line for a given fee APY to show where fees compensate for IL.

fee_apy — Fee APY (as decimal, e.g. 0.20 = 20%). If supplied, draws a breakeven horizontal at this level
holding_period_days — Holding period in days (default 365). Used with fee_apy to compute realized fee return
price_ratios — JSON array of price ratios to evaluate (e.g. [0.25, 0.5, 1, 2, 4]). Alternative to 'range'
range — JSON array [start, stop, n] generating n log-spaced ratios from start to stop. Default: [0.25, 4, 80] covers a 16x range each direction
verbose — Include the IL derivation alongside the numeric curve. Default false

petri_amm_quote petri

Single-trade math for a Uniswap V2-style constant-product AMM. Given reserves and a trade size, returns the output amount, effective price, spot price, slippage, and fee paid. Pure algebra — no model required.

amount_in required — Amount of token X being swapped in
fee_bps — Pool fee in basis points (default 30 = 0.3%, Uniswap V2 standard)
reserve_x required — Reserve of token X (input token)
reserve_y required — Reserve of token Y (output token)
verbose — Include the math derivation (formula + substitution) alongside the numeric result. Default false. Use when explaining to a user how the swap was priced

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_corr_matrix petri

Render a correlation matrix as a heatmap. Useful as a pre-flight check on petri_sde correlation inputs and as a general visualization of asset/observable relationships. Accepts pairwise rho format or a full matrix array.

correlations — JSON object of pairwise correlations keyed by "A-B" with values in [-1, 1]. Place IDs/names are extracted from the keys. e.g. {"btc-eth": 0.85, "btc-sol": 0.7, "eth-sol": 0.75}. Alternative to 'matrix'
labels — JSON array of axis labels. Required when using 'matrix'. Optional when using 'correlations' (auto-extracted from keys)
matrix — JSON nested array (full NxN matrix). Alternative to 'correlations'
title — Optional title shown above the heatmap

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_distribution petri

Run N stochastic paths and visualize the distribution of an observable at the final time. Output: histogram + percentile band (P5 / P25 / P50 / P75 / P95) + mean and stdev. Answers questions like 'what's the probability the LP ends below $X' or 'what's the 5th-percentile worst case'. Mode selects SDE (continuous noise, for prices) or SSA (discrete events, for counts).

bins — Histogram bin count (default 30, max 100)
mode — 'sde' (continuous-noise GBM, requires volatility) or 'ssa' (discrete Gillespie events). Default 'sde'
model required — Petri net model JSON or tokenmodel DSL
observable required — Place ID whose final-time distribution is plotted
paths — Number of paths (default 500, max 5000). Higher = tighter percentile estimates
rates — JSON object of rate constants (default 1.0 per transition)
seed — Random seed for reproducibility (default 42)
tspan — Integration span (default [0, 1])
volatility — Required for mode=sde. JSON object mapping place_id → sigma

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_explain petri

Explain the math behind any concept used in this MCP — formulas, intuition, derivations, worked examples, and what tool to try next. Without arguments, lists all available concepts. With a topic name, returns the full explanation.

topic — Concept name (e.g. 'impermanent_loss', 'constant_product_amm'). Omit to list all available topics with one-line summaries

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_fit petri

Fit transition rates to observed data. Given (t, value) measurements for one or more places, finds rates that minimize squared error under mass-action ODE. Uses Nelder-Mead simplex. Returns fitted rates plus a plot of observations (dots) over the fitted trajectory.

fixed_rates — JSON object of rates for transitions NOT being fit (default 1.0)
initial_guess — JSON object of starting rates for parameters being fit (default: midpoint of bounds)
max_iter — Max Nelder-Mead iterations (default 200, max 1000)
model required — Petri net model JSON or tokenmodel DSL
observations required — JSON object: {place_id: [[t1, v1], [t2, v2], ...], ...}. Times are interpreted in model time units
parameters required — JSON object mapping transition_id → [min, max] bounds, e.g. {"deliver": [0.01, 10]}
tol — Convergence tolerance on simplex spread (default 1e-6)
verbose — Include the Nelder-Mead algorithm description in the response. Default false

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)
verbose — Include the algorithm description and formula in the response. Default false. Use to teach a user what the solver actually computed

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_optimize petri

Multi-objective optimization over transition rates. Monte Carlo samples the parameter space, runs each combo to equilibrium, identifies the Pareto frontier (non-dominated points), and visualizes it. Returns JSON of every sample (with is_pareto flag) plus a scatter plot (2 objectives) or parallel-coordinates chart (3+).

fixed_rates — JSON object of transition rates held constant during the sweep (default 1.0 for unspecified)
model required — Petri net model JSON or tokenmodel DSL
objectives required — JSON array of objectives. Each entry: {"place": "place_id", "direction": "max"|"min"}. e.g. [{"place":"delivered","direction":"max"}, {"place":"refunded","direction":"min"}]
parameters required — JSON object mapping transition_id → [min, max] rate range. e.g. {"start_brew": [0.1, 5.0], "deliver": [0.5, 2.0]}
samples — Number of Monte Carlo samples (default 200, max 2000)
seed — Random seed for reproducibility (default 42)
tspan — Per-run integration span (default [0, 50])
verbose — Include the Monte Carlo / Pareto algorithm description in the response. Default false

petri_param_heatmap petri

2D parameter sweep: vary two rate constants over a grid, run each combo to equilibrium, render the observable as a viridis heatmap. Answers 'how does APY depend on fee_tier × liquidity?' or 'which parameter regime gives me the equilibrium I want?'.

fixed_rates — JSON object of other transition rates held constant
log_scale — Sweep parameters in log space (better for ranges spanning orders of magnitude). Default false
model required — Petri net model JSON or tokenmodel DSL
observable required — Place ID whose equilibrium value is the heatmap color
param_x required — First transition ID to sweep
param_y required — Second transition ID to sweep
range_x required — JSON array [start, stop, n] for x sweep (e.g. [0.1, 5.0, 20])
range_y required — JSON array [start, stop, n] for y sweep
tspan — Per-run integration span (default [0, 50])

petri_phase_plot petri

Phase-space portrait: run an ODE, project trajectory into the (place_x, place_y) plane (no time axis). Reveals attractors, limit cycles, and geometric structure of two-state dynamics. Optionally overlays multiple trajectories from different initial conditions to map the basin structure.

initial_conditions — Optional JSON array of starting marking overrides, one per trajectory to draw. e.g. [{"place_x": 0.5}, {"place_x": 1.5}, {"place_x": 2.5}]. Default: a single trajectory from the model's initial marking
model required — Petri net model JSON or tokenmodel DSL
place_x required — Place ID for the x-axis
place_y required — Place ID for the y-axis
rates — JSON object of rate constants (default 1.0 per transition)
title — Optional title shown above the plot
tspan — Integration span (default [0, 20])

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_risk petri

Risk dashboard for an observable under SDE simulation. Runs N paths, computes mean / stdev / P5 / P50 / P95 of final values, plus max drawdown and CVaR (expected shortfall in the worst 5% of paths). Output: composite card with stats panel and drawdown distribution histogram. Answers 'what's the worst-case loss?' and 'how bad does it usually get?'.

correlations — Optional pairwise correlation dict (same format as petri_sde)
model required — Petri net model JSON or tokenmodel DSL
observable required — Place ID to monitor as the asset/portfolio value
paths — Number of SDE paths (default 500, max 5000)
rates — JSON object of rate constants (default 1.0)
seed — Random seed (default 42)
steps — Euler-Maruyama step count per path (default 200)
tspan — Integration span (default [0, 1])
volatility required — JSON object {place_id: sigma} for SDE noise

petri_sankey petri

Sankey-style flow diagram: run an ODE, compute integrated flow through each arc, render the net with arc widths proportional to flow magnitude. Reads as 'where is the money going' rather than 'which transitions fire'. Use to communicate token flow to non-Petri-net audiences.

model required — Petri net model JSON or tokenmodel DSL
rates — JSON object of rate constants (default 1.0 per transition)
title — Optional title shown above the diagram
tspan — Integration span (default [0, 10])

petri_sde petri

Stochastic Differential Equation simulation. Mass-action drift (as in petri_ode) plus geometric Brownian motion on user-selected places — for DeFi price processes, interest rate models, anywhere continuous noise scales with state value. Returns mean ± stdev band over N paths.

correlations — Optional JSON object of pairwise correlation coefficients in [-1, 1], keyed by "placeA-placeB" (sorted alphabetically). e.g. {"btc-eth": 0.7, "btc-sol": 0.6, "eth-sol": 0.5}. Missing pairs default to 0 (independent). Matrix must be positive semi-definite or the call errors.
model required — Petri net model JSON or tokenmodel DSL
paths — Number of independent SDE paths (default 20, max 100). Mean and ±stdev are computed across paths
rates — JSON object of mass-action rate constants (default 1.0 per transition)
samples — Output sample count (default 200, downsampled from steps)
seed — Random seed for reproducibility (default 42)
steps — Euler-Maruyama step count (default 500). Higher = more accurate noise integration
tspan — Integration span (default [0, 1])
variables — JSON array of place IDs to plot (default: all places)
verbose — Include the Euler-Maruyama algorithm description in the response. Default false
volatility required — JSON object mapping place_id → sigma (annualized vol). Places not in this map evolve deterministically. e.g. {"price_token_a": 0.6, "price_token_b": 0.4}

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_stochastic petri

Gillespie Stochastic Simulation Algorithm (SSA) over the Petri net's discrete marking. Distinct from petri_ode's continuous ODE — token counts stay integer, firings are random events, results have visible noise. Use when token counts are small enough that variance matters. Multiple realizations show mean ± stdev band.

model required — Petri net model JSON or tokenmodel DSL
rates — JSON object of mass-action rate constants per transition (default 1.0)
realizations — Number of independent SSA runs (default 1, max 50). With >1, mean and ±stdev band are plotted
samples — Number of time points to record per realization (default 200)
seed — Random seed for reproducibility (default 42)
tspan — Integration span [t0, tf] (default [0, 10])
variables — JSON array of place IDs to plot (default: all places)
verbose — Include the Gillespie SSA algorithm description in the response. Default false

petri_template petri

DeFi/tokenomics model templates ready for analysis. Without a name argument, lists all available templates with one-line descriptions. With a name, returns the full model JSON ready to feed into petri_visualize / petri_ode / petri_optimize / etc.

name — Template name (e.g. 'constant_product_amm'). Omit to list all templates with descriptions

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

petri-pilot MCP Server

Add to Claude Code

Add to Other MCP Clients

Available Tools

Usage