Skip to main content
Glama
poietic-mcp

poietic-mcp

by soobrosa

poietic-mcp

An MCP server that lets an agent read, edit, validate and simulate Poietic Stock and Flow designs, alongside a human working in Poietic Playground.

The design file is the integration point. The agent edits a .poietic file through this server by driving the poietic CLI; the human opens or reloads the same file in the playground. Agent edits, human views and direct-manipulates; both sides re-read.

Install

# 1. Build and install the poietic CLI (Swift 6.x, macOS 15+ or Linux)
git clone https://github.com/OpenPoiesis/poietic-tool
cd poietic-tool && git checkout v0.9 && ./install  # installs to ~/.swiftpm/bin/poietic

# 2. Build this server
git clone https://github.com/soobrosa/poietic-mcp
cd poietic-mcp && npm install && npm run build

Related MCP server: a0

Configure

The server works with any MCP client. The command to register is always:

node <absolute-path-to>/poietic-mcp/dist/index.js

with optional environment variables (see below). Environment:

  • POIETIC_MCP_WORKSPACE - allowlist root. Design paths and export outputs must live inside it. Defaults to the server's working directory. Set it to a dedicated designs folder (e.g. ~/Documents/poietic-designs) for a tight fence, or your home directory to work with designs anywhere.

  • POIETIC_BIN - path to the poietic binary. Defaults to ~/.swiftpm/bin/poietic.

  • POIETIC_DESIGN - optional default design path, used when no current design is set.

Claude Code

claude mcp add --scope user poietic \
  --env POIETIC_MCP_WORKSPACE=$HOME \
  --env POIETIC_BIN=$HOME/.swiftpm/bin/poietic \
  -- /opt/homebrew/bin/node /absolute/path/to/poietic-mcp/dist/index.js

Verify with claude mcp list (should show poietic: ... - ✔ Connected) or /mcp inside a session. --scope user makes it available in all projects; use --scope project to register it only for one repository (writes to that repo's .mcp.json).

Claude Desktop

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (create the mcpServers key if absent), then fully quit and reopen the app (Cmd+Q; MCP servers only start at launch):

{
  "mcpServers": {
    "poietic": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/poietic-mcp/dist/index.js"],
      "env": {
        "POIETIC_MCP_WORKSPACE": "/Users/you",
        "POIETIC_BIN": "/Users/you/.swiftpm/bin/poietic"
      }
    }
  }
}

The poietic tools appear under the tools icon in a chat.

Factory Droid / other clients

Register the same command in the client's MCP settings (e.g. .mcp.json in the workspace for Droid, project config for other clients):

{
  "mcpServers": {
    "poietic": {
      "command": "node",
      "args": ["/absolute/path/to/poietic-mcp/dist/index.js"],
      "env": {
        "POIETIC_MCP_WORKSPACE": "/Users/you/Documents/poietic-designs",
        "POIETIC_BIN": "/Users/you/.swiftpm/bin/poietic"
      }
    }
  }
}

Verifying the setup

From a terminal, drive the server directly like an MCP client would:

node src/test/smoke.mjs   # registers, builds a tiny model, simulates

Using it

You do not invoke tools by name; you talk, and the agent picks the poietic_* tools as the conversation turns to building models.

A typical build request:

Create a new Poietic design called fishing.poietic in ~/Documents/poietic-designs and model the fishing economy from Thinking in Systems: a fleet (capital) that grows 5% per year, fish that regenerate as a function of fish density, harvest yield falling as fish get scarce, price rising as fish get scarce. Validate and simulate 200 years.

A typical inspect-and-modify request:

Open Capital.poietic in ~/Downloads/_Converted/ThinkingInSystems, show me the structure, then double the initial resource and re-run the simulation.

Working alongside Poietic Playground: open the same design file in the playground to see and edit the agent's work by hand. After saving in the playground, the agent's next write is refused with a fingerprint conflict; tell it to re-read the design (poietic_get_design) and continue. See PLAYGROUND.md for the handoff protocol.

The guided recipe: ask the agent to use the build_stock_and_flow_model prompt for a description of a system. It encodes node roles (Stock vs FlowRate vs Auxiliary), Flow vs Parameter edge semantics, formula syntax, and the validate-then-run ordering - including two lessons learned the hard way:

  • Node names can contain spaces. In formulas, wrap those names in curly braces, for example {account balance} * {interest rate}. Name matching is case-insensitive, and spaces and underscores normalize to the same name.

  • poietic_auto_parameters does not wire Parameter edges into or out of GraphicalFunction nodes. After auto-parameters, validate; for each issue, connect the missing edge explicitly and re-validate.

  • A stated growth-rate goal is usually a net rate. An investment goal of g% of the stock with d% depreciation yields net growth of (g - d)%; setting g = d freezes the stock. Gross goal = depreciation + desired growth.

Tips:

  • Mention the design's folder so the agent stays inside the workspace fence.

  • Ask for poietic_validate before simulating; the agent will usually do it unprompted, but a broken model fails in poietic_run with the same issues.

  • Ask for results as summaries, not raw dumps - poietic_run already returns a per-variable summary with capped sample rows, and can write the full CSV to a file if you give it an outputPath.

Tools

Session: poietic_use_design binds the current design (and snapshots a content-hash fingerprint as the session baseline); every other tool takes an optional design override.

Tool

Purpose

poietic_metamodel(type?)

Metamodel as markdown (cached). Schema discovery.

poietic_get_design()

Normalized design JSON: {nodes[], edges[], unstructured[]}.

poietic_validate()

{ok, issues[]} with per-object formula/parameter errors.

poietic_new_design({path, import?})

Create an empty design; becomes current.

poietic_add_node({type, attributes})

Create a node; returns {objectId, planeId}.

poietic_connect({type, origin, target, attributes?})

Create an edge, optionally with v0.9 attributes; returns {edgeId}.

poietic_set_attributes({ref, attributes})

Set attributes; one undo entry (single transaction on poietic-tool v0.8+).

poietic_unset_attributes({ref, attributes})

Remove stored attribute values in one transaction (v0.9+).

poietic_remove({ref})

Remove a node or edge (cascades edges).

poietic_auto_parameters()

Wire required parameter edges, drop unused ones.

poietic_undo() / poietic_redo()

One tool call = one transaction.

poietic_arrange({mode, refs?})

circle layout or align modes.

poietic_run({...})

Simulate with startTime, finalTime, timeStep, euler/rk4, and display/normalized names; summarize results or write full CSV.

poietic_export_svg({outputPath})

SVG diagram export.

poietic_write_dot({outputPath?})

Graphviz DOT (stdout if no path).

poietic_export_plane / poietic_import_plane

Plane exchange between design files.

Resources: poietic://metamodel, poietic://builtins (formula operators, functions and variables; poietic-tool v0.8+), poietic://design/current, poietic://design/current/diagram.svg.

For a v0.9 Simulation settings object, use start_time, time_step, and final_time (replacing initial_time, time_delta, and end_time). solver_type accepts euler or the fixed rk4 solver. flow_scaling accepts outflow_first or inflow_first; set it when competing flows may exceed available stock. The steps run option is deprecated, so prefer finalTime.

Prompt: build_stock_and_flow_model - encodes node roles, Flow vs Parameter edge semantics, formula syntax, and the validate-then-run ordering.

Safety model

  • Argv only. The CLI is spawned with an argv array; formulas containing *, spaces or parentheses are never interpreted by a shell.

  • Per-design mutex. Every CLI invocation is a whole-file read-modify-write; concurrent calls are serialized per design.

  • Fingerprint guard. After the first bind, any external change to the design file (e.g. the human saving in the playground) blocks writes with a clear error until the agent re-reads the design. Conflicts are detected, never merged.

  • Path allowlist. Designs and outputs must be inside POIETIC_MCP_WORKSPACE.

  • Verbatim errors. Non-zero CLI exits surface the CLI's stderr unchanged.

  • No silent nulls. A create whose output cannot be parsed for the new object ID is a hard error.

Development

npm run build        # tsc
npm test             # parser fixtures + integration (needs the poietic binary)
node src/test/smoke.mjs   # drives the built server over stdio
node src/test/from-description.mjs   # builds a model from prose only

fixtures/raw/ holds recorded stdout/stderr from the real CLI (see fixtures/FINDINGS.md for observed behavior and deviations from the docs); fixtures/capture.sh reproduces them. src/test/capital.test.mjs rebuilds the Thinking in Systems Capital model through the MCP tools and asserts the rebuilt simulation reproduces the committed original variable by variable.

Troubleshooting

  • poietic binary not found - build and install poietic-tool, or point POIETIC_BIN at the binary.

  • Path is outside the allowed workspace - the design path is not under POIETIC_MCP_WORKSPACE; move the file, or update the server's env in the client config (restart the client afterwards).

  • The design changed outside this session - the file was saved externally (playground, another agent). Re-read it with poietic_get_design, then retry the write.

  • Validation issues about graphical functions - run poietic_auto_parameters, then connect the missing GraphicalFunction edges explicitly (see the from-prose lessons under "Using it").

  • Claude Desktop shows no poietic tools - the app loads MCP servers only at launch; quit fully (Cmd+Q) and reopen. Logs: ~/Library/Logs/Claude/mcp*.log.

Known limitations

  • No live playground drive. The human reopens the file; the playground has no reload-on-change.

  • Concurrent editing is detected, not merged. The fingerprint guard refuses the write; re-read and re-apply.

  • Multi-step agent edits are not atomic. Each tool call is one transaction; one undo reverses one call. (poietic_set_attributes with several attributes is a single transaction on poietic-tool v0.8+; older builds create one entry per attribute.)

  • Duplicate object names resolve arbitrarily upstream, so name-based references are only safe when uniqueness is known. Prefer numeric IDs.

Available Tools

18 tools
poietic_add_nodeAdd Poietic nodeA

Create a new node (e.g. type Stock, FlowRate, or Auxiliary) with attributes. Typical attributes: name (string, required), formula (string, required - a constant like "100" or an expression like "account * rate"), position ([x, y]). Returns {objectId, planeId}. Thread the returned objectId into later calls; duplicate names resolve arbitrarily upstream, so prefer IDs.

Inputs: type (required), design, attributes.

poietic_arrangeArrange Poietic objectsA

Arrange nodes on the canvas. mode 'circle' lays out all (or the given) nodes in a circle; align modes (left, center-horizontal, right, top, center-vertical, bottom, offset-horizontal, offset-vertical, spread-horizontal, spread-vertical) align the given nodes.

Inputs: mode (required), refs, design, spacing.

poietic_auto_parametersAuto-connect Poietic parametersA

Automatically wire Parameter edges: connect required parameter edges for every formula variable, and disconnect unused parameter edges. Stock and Flow models stay consistent only if every formula parameter is wired and no stale parameter edges remain - run this after editing formulas and connections. Returns the created and removed edge IDs.

Inputs: design.

poietic_connectConnect Poietic nodesA

Create an edge between two nodes. Edge types: Flow (between a FlowRate and a Stock; direction is flow direction) and Parameter (from a value node to the node whose formula uses it). NOTE: edge attributes cannot be set at creation; use poietic_set_attributes afterwards if needed. Returns {edgeId}.

Inputs: type (required), origin (required), target (required), design.

poietic_export_planeExport Poietic planeA

Export the current (or given) plane as a poietic design file for later import.

Inputs: outputPath (required), plane, design.

poietic_export_svgExport design as SVGA

Export the current plane as an SVG diagram. Note: pictograms require a pictogram collection file (from the Diagramming package); without it the diagram renders with plain shapes.

Inputs: outputPath (required), zoom, plane, design, +2 more.

poietic_get_designGet Poietic designA

Read the current Poietic design as normalized JSON: {formatVersion, metamodel, planeId, undoDepth, redoDepth, nodes[], edges[], unstructured[]}. Each node is {id, type, name, attributes}; each edge is {id, type, origin, target, attributes}. Replaces list and show. Prefer numeric IDs over names for references (duplicate names resolve arbitrarily upstream).

Inputs: design.

poietic_import_planeImport Poietic planeA

Import a plane from another poietic design file into the current design. identity mode: 'require' (default; object IDs must match), 'auto', or 'new' (re-identify objects).

Inputs: file (required), plane, design, identity.

poietic_metamodelPoietic metamodelA

Describe the Poietic metamodel (object types, traits, attributes, edge types) as markdown. Pass a type name (e.g. Stock, FlowRate, Auxiliary, Flow, Parameter) for a single type, or omit it for all types. This is the schema-discovery path: check attribute names and types here before setting attributes.

Inputs: type.

poietic_new_designNew Poietic designA

Create a new empty Stock and Flow design at the given path and make it the current design. Optionally import one or more poietic planes into the first plane.

Inputs: path (required), import.

poietic_redoRedo Poietic editA

Redo the last undone edit transaction on the design.

Inputs: design.

poietic_removeRemove Poietic objectA

Remove an object (node or edge) by ID (preferred) or unique name. Removing a node also removes its connected edges (the CLI reports 'Removed cascading').

Inputs: ref (required), design.

poietic_runRun Poietic simulationA

Run the Stock and Flow simulation and return a per-variable summary (initial, final, min, max) plus capped sample rows of the CSV output. Use 'variables' to observe specific nodes (names or IDs); with no 'variables', output contains time plus all object variables (poietic-tool v0.8+; use 'allVariables' to also include internal/built-in variables). Use 'parameters' to override node values for the run: stocks get a new initial value, other nodes are affected only at t=0 and then recomputed from their formulas. Pass 'outputPath' to also save the full CSV (inside the workspace). Validate the design first: a model with formula errors fails here.

Inputs: plane, steps, design, solver, +7 more.

poietic_set_attributesSet Poietic attributesA

Set one or more attributes on an object (node or edge), referenced by ID (preferred) or unique name. On poietic-tool v0.8+ all attributes are applied in a single transaction (one undo history entry). On older builds each attribute is a separate CLI transaction (N entries); the response states which mode was used. To set an edge attribute, use the edge's numeric ID (edges have no names).

Inputs: ref (required), attributes (required), design.

poietic_undoUndo Poietic editA

Undo the last edit transaction on the design. Note: each edit tool call is one transaction, so one undo reverses one tool call (poietic_set_attributes with N attributes created N entries).

Inputs: design.

poietic_use_designUse Poietic designA

Set the current design file for subsequent tools. The path must be inside the configured workspace (POIETIC_MCP_WORKSPACE or the server's working directory). Snapshots the design's content hash as the session baseline: if it changes externally (e.g. saved in the playground), writes will be refused until you re-read the design.

Inputs: design (required).

poietic_validateValidate Poietic designA

Validate the design for errors (formula errors, unknown parameters). Returns {ok, issues[], summary} where each issue is {objectId, typeName, name, severity, message}. Run this after editing and before simulating.

Inputs: design.

poietic_write_dotWrite Graphviz DOTA

Write the design graph as a Graphviz DOT file (no pictogram dependency). Omit outputPath to receive the DOT source in the response.

Inputs: design, labels, outputPath.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 18 tools

    Disambiguation5/5

    Each tool targets a distinct capability: schema discovery, design lifecycle, node/edge editing, validation, simulation, layout, and export/import. Even the export tools are clearly separated by output format, and the manual edge creation vs auto-wiring tools serve different workflow stages.

    Naming Consistency4/5

    All tools share the poietic_ prefix and mostly use imperative/snake_case names (get_design, add_node, set_attributes, export_svg). A few names are verb-only (validate, connect, run) and poietic_metamodel is a noun-only outlier, so the pattern is not perfectly uniform.

    Tool Count4/5

    Eighteen tools is slightly above the typical comfortable range, but each maps to a needed operation across model editing, simulation, and exchange. The count feels justified rather than bloated for a domain with both editing and simulation/export workflows.

    Completeness5/5

    The set covers schema discovery, design creation/loading/reading, node and edge CRUD-style operations, attribute updates, validation, undo/redo, simulation, layout, and multiple export/import paths. There are no obvious dead ends for a stock-and-flow modeling workflow.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to load, simulate, inspect, and edit EPANET hydraulic/water-quality models locally via stdio.
      33
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to open, edit, check, run, emit, and save source programs through structured, revision-checked tools over stdio, confining paths to the launch root and returning diagnostics with fixes for rejected edits.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to build, validate, calibrate, and export versioned scientific models with mandatory units, dimensional and numerical checks, and uncertainty analysis over stdio. Models can be simulated and exported to portable formats such as SBML, CellML, and Modelica.
      27 npm
      9
      MIT