Penstock

Command line / Automation

The MCP server

Let an AI assistant read, check and, if you allow it, edit the diagrams in your project, with the same checks a person gets.

Free Reading, checking, searching, comparing, the Camunda 8 analysis, drawing, connections, AI agents, drift, importing, a single rename and previews are free. Flow analysis, scenarios, code links, auto layout, running test cases, editing and creating files, bulk refactoring and the evidence pack need Pro, and Team in a pipeline.

What it is

MCP (Model Context Protocol) is a way for an AI assistant to use a program's tools. penstock mcp starts a small server on your machine that talks to the assistant over standard input and output. It offers thirty tools, the diagrams of the open folders as resources, and two prompts. It reads BPMN diagrams, DMN decision files and Camunda forms. An assistant that edits a diagram can check straight away that it still runs to its end.

Connect an AI assistant

The CLI needs Node.js. Node.js 22.22 or later must be on the PATH of your assistant. The tools that read, check, search, compare, analyse for Camunda 8 and draw are free, with no time limit: list_diagrams, show_diagram, element_context, check_diagram, search_elements, diff_diagrams, migrate_analyze, export_image, connections, agents, drift (for one environment), import_diagram, refactor_rename, test_dmn (up to 3 cases per decision) and the previews of migrate_agents and incident_to_scenario. The other tools, and the writes behind the free ones, are part of Penstock Pro, and Team in a pipeline, as penstock mcp --help states.

Running penstock mcp --config prints the standard client configuration. There is no project folder in the entry: you configure it once, and the server finds each project from the files the assistant asks about. The entry names the exact version of the command line that printed it, as npx --yes @kern0x1b/penstock-cli@<version> mcp, so the assistant runs the version you have. A development build of the command line has no published version, and prints penstock mcp instead. The entries below, written by hand, run whatever version npm serves; paste the printed one to pin it. With the command line installed (npm install -g @kern0x1b/penstock-cli), claude mcp add penstock -- penstock mcp adds it to Claude Code.

Two other ways to give an agent the tools need no entry in its settings. penstock agent claude, codex, gemini or opencode starts that agent in your terminal with the server set up for that one run and nothing written to the agent's configuration. See agent. And the AI chat in the Penstock editors starts your agent with the same server, so it reads diagrams, rules, scenarios and code links as the command line does.

penstock mcp --project <dir> fixes the project: every tool works on that folder, the assistant does not have to name it, and nothing outside it is read.

Claude Code

Run this command in your terminal:

claude mcp add penstock -- npx --yes @kern0x1b/penstock-cli mcp

Claude Desktop

In claude_desktop_config.json (under ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows), add penstock under mcpServers:

{
  "mcpServers": {
    "penstock": {
      "command": "npx",
      "args": ["--yes", "@kern0x1b/penstock-cli", "mcp"]
    }
  }
}

Cursor

In .cursor/mcp.json in your project, or in ~/.cursor/mcp.json for all projects, add the server under mcpServers:

{
  "mcpServers": {
    "penstock": {
      "command": "npx",
      "args": ["--yes", "@kern0x1b/penstock-cli", "mcp"]
    }
  }
}

VS Code

In VS Code 1.101 or later with GitHub Copilot agent mode, the Penstock extension registers the MCP server automatically in trusted workspaces when Node.js and npm are on the PATH. The extension launches ./penstockw mcp if the project has the wrapper, or npx @kern0x1b/penstock-cli mcp if not.

For manual setup in .vscode/mcp.json, VS Code uses the servers key and requires type: "stdio" rather than mcpServers:

{
  "servers": {
    "penstock": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@kern0x1b/penstock-cli", "mcp"]
    }
  }
}

JetBrains AI Assistant and Junie

For JetBrains AI Assistant, go to Settings | Tools | AI Assistant | Model Context Protocol (MCP), click Add, choose STDIO, and supply this JSON configuration:

{
  "mcpServers": {
    "penstock": {
      "command": "npx",
      "args": ["--yes", "@kern0x1b/penstock-cli", "mcp"]
    }
  }
}

For JetBrains Junie, add the entry under mcpServers in ~/.junie/mcp/mcp.json (global) or .junie/mcp/mcp.json (project root), or configure it in Settings | Tools | Junie | MCP Settings.

How the server finds your project

The server serves diagrams across projects. For each request it starts from the file or folder the assistant names, walks up to the nearest penstock.yaml (or the repository root), and uses that project's engine, settings and conventions.

Kind of toolHow you point it at a project
Tools that read any kind of file: show_diagram, element_context, check_diagram, diff_diagramsThe assistant passes the absolute path of a .bpmn, .dmn or .form file, in file. diff_diagrams also takes a second file of the same kind in other.
BPMN-only tools: analyze_flow, list_scenarios, edit_diagram, layout_diagram, export_imageThe assistant passes the absolute path of a .bpmn or .bpmn20.xml file, in file.
Whole-project tools: list_diagrams, search_elements, check_code_links, run_scenarios, migrate_analyzeThe assistant passes an absolute folder in the optional project. Without it, the tool uses the folders the AI client has open. run_scenarios and migrate_analyze also take a single file in file; migrate_analyze takes either file or project, not both.
The tool that makes a file: create_diagramThe assistant passes the absolute path of the new .bpmn, .dmn or .form file, in file. The path must not exist yet.

The folders the client has open (MCP roots)

Many AI clients tell the server which folders are open in their workspace. MCP calls these roots. When the client does, the server:

When the client sends no roots, the whole-project tools need an explicit absolute project. The file tools then accept any valid diagram whose path resolves to a project.

The tools

ToolWhat it doesNeeds
list_diagramsLists the BPMN diagrams, DMN decision files and Camunda forms of a project, as absolute paths, each with its kind: process, decision or form.Free
show_diagramDescribes a file. For a BPMN diagram: every element and flow with id, type, name, connections and engine properties. Read this before editing. Edits refer to these ids. For a DMN file: each decision with its hit policy, inputs, outputs, rules and the decisions, input data and knowledge it requires. For a form: its components with id, type, key, label, options and group.Free
element_contextSays what surrounds one element: the variables that reach it, what it reads and writes, its job types, and the job types, processes and decisions the project already uses. For a DMN file the element is a decision id and the answer is its table, the decisions that need it and the process elements that call it. For a form it is a component key or id, with the process elements that open the form.Free
check_diagramReports what is wrong, as the editor's check does: the drawing, your bpmnlint rules and, with a licence, how the process runs. For a form it reports duplicate or missing keys, and for a DMN file one that cannot be read, free of charge. Gaps and overlaps between the rules of a decision table need Pro, and Team in a pipeline; without it the answer says they were left out.Free
search_elementsFinds where a name is used across the project, by id or name and ignoring case: elements, processes, messages, decisions and their outputs, variables with the elements that write and read them, and form fields. It takes query and the optional project, kinds and limit.Free
diff_diagramsSays what changed between two files of the same kind (BPMN, DMN or form), or between a file and its committed version (HEAD, or the revision in ref): the elements added, removed and changed, and the ids of those that only moved on the canvas or, in a form, were reordered or moved to another group. A decision table is compared by rule and cell id, and a form by component id.Free
migrate_analyzeRuns the Camunda 7 to 8 analysis of penstock migrate on one file or on a project, and returns as JSON the findings of each file, the effort and the blockers. It takes file or project, the optional target (a Camunda 8 version from 8.5 to 8.9, 8.8 by default) and verbose. It writes nothing.Free
export_imageDraws a BPMN diagram as SVG, returned as text, or as PNG, returned as an image. PNG needs puppeteer installed, as penstock export does. With out, an absolute folder, the file is written there instead.Free
connectionsShows the secrets and MCP clients the diagrams and element templates of a project name, where the project's own files define them (connector-secrets, .env, Docker Compose, Helm values, Spring Boot properties, MCP client configuration), what is missing, and the Camunda 8.7 property names that 8.8 renamed, as penstock connections does. It reads only; the answer holds names and places, never values. It takes project and the optional environment and against.Free. against (compare two environments): Pro, Team in a pipeline
agentsLists the Camunda 8 AI agents of a project: for each, the model and provider, the prompts, the tools with the fromAi() parameters, the limits, the memory, the MCP clients with whether their configuration is found, the tool filters, and what the agents rules found. Names only, never secret values. It takes project.Free
driftCompares the project's diagrams and decisions with what an environment has deployed, after the same normalisation, and says per resource whether it is in sync, ahead locally, ahead on the engine, only local, only on the engine or changed on both sides, as penstock drift does. It reads only: nothing is deployed or written, and only environments penstock.yaml declares are asked. It takes project and the optional environment and against.Free for one environment. against: Pro, Team in a pipeline
import_diagramImports a draw.io, Visio, Signavio, Bizagi or Flowable file as BPMN 2.0, or with from set to modeler reads a Camunda Modeler project folder, as penstock import does. It only previews: it returns what was converted, kept and could not be mapped. It writes only with write true, a new file inside the project root, and never over an existing one without force. It takes file and the optional from, to, write, out and force. Nothing in the imported file is ever run.Free
refactor_renamePreviews or applies the rename of a process variable, message, signal, error code, escalation, job type, topic, decision id, form key or process id across the project, as penstock refactor rename does. Without apply it returns the plan: every edit, and every place it refuses to touch with the reason. Applying needs the planId of that preview, so an agent cannot write what it has not shown, and it refuses when the git tree has uncommitted changes unless force is true. It takes kind, from, to and the optional project, apply, planId, acknowledge and force.Free
test_dmnRuns the saved test cases of the decision tables in one DMN file, or in every DMN file of the project, and returns the outcome of each case, the rules that matched and the rules no case covers. It takes file or project. With case it saves a new case next to the file, which is a write.Free up to 3 cases per decision. More cases and saving a case: Pro, Team in a pipeline
migrate_agentsMoves the AI agent elements from the template versions of Camunda 8.9 and earlier to the 8.10 agent task and agent sub-process templates, as penstock migrate agents does. By default it is a dry run that previews the first 3 elements; write true replaces the files atomically. An element whose mapping cannot be proven is left untouched and listed with the reason.Preview: Free. write: Pro, Team in a pipeline
incident_to_scenarioTurns an incident of the project's engine into a scenario that reproduces it, as penstock incident scenario does. It takes the key of the incident or of its instance. Anything that looks like a secret is replaced by a placeholder. Reading and previewing write nothing; write saves the scenario next to the diagram's other scenarios, and run also runs it on the engine of the project, which has to be marked for tests. It stays inside the roots the client gave.Preview: Free. write, run: Pro, Team in a pipeline
migrate_verifyRuns the project's scenarios on the original Camunda 7 diagram on one test engine and on the converted Camunda 8 diagram on another, and reports per scenario equivalent, differs or cannot be compared, as penstock migrate verify does. Both engines must be marked for tests. It takes the optional project, target, scenarios, originalProfile and convertedProfile.Pro, Team in a pipeline
generate_templatesMakes one REST connector element template per operation from an OpenAPI 3, Swagger 2.0 or Postman collection file, as penstock templates generate does. It writes nothing unless write is true; the answer lists every template, whether it would be created or replaced, and the secrets to create. It takes spec and the optional out, write and secretPrefix, and stays inside the roots the client gave.Pro, Team in a pipeline
evidence_buildBuilds the audit evidence pack of the project, as penstock evidence build does, and writes a zip or a folder inside the project. It takes the optional project, out, since, format (zip or dir) and force. It never holds a secret value.Pro, Team in a pipeline
refactor_bulkPreviews or applies the renames of a mapping file in order, with the same plan, refusals and limits as refactor_rename, and the same planId rule. It takes mapping and the optional project, apply, planId, acknowledge and force.Pro, Team in a pipeline
refactor_extractPreviews or applies moving a subprocess, or elements with one way in and one way out, into a new process file, replaced by a call activity wired through variable mappings. It refuses, with the reason, when the selection is not safe to move. It takes file, elements and processId, and the optional project, name, apply, planId and force.Pro, Team in a pipeline
migrate_applyApplies the Camunda 7 to Camunda 8 migration, as penstock migrate apply does. By default it is a dry run that returns the diff and writes nothing; write true writes. only and exclude take the change ids of penstock migrate plan; an id the plan does not have, an empty list or an over-long id is refused before anything is written. It never deletes a file and never follows a symbolic link out of the project.Pro, Team in a pipeline
analyze_flowFinds deadlocks, branches that run twice, elements that never run and loops with no way out, with the path of ids that leads there. Run it after edit_diagram.Pro, Team in a pipeline
list_scenariosLists every distinct way through a diagram: the decisions taken, their conditions, the steps and where it ends.Pro, Team in a pipeline
check_code_linksChecks every diagram against the code, with file and line.Pro, Team in a pipeline
edit_diagramChanges a diagram through the editor's own modelling. Operations apply together or not at all. An edit that would break the drawing is refused, and so is a write over a diagram that changed on disk while the edit was made. dryRun shows the result without writing. It edits BPMN diagrams only.Pro, Team in a pipeline
layout_diagramRuns the editor's auto layout on a BPMN diagram and writes the result in one atomic step. Elements and flows stay the same; only positions change. dryRun lists the elements that would move without writing.Pro, Team in a pipeline
create_diagramCreates a BPMN diagram, a DMN decision or a Camunda form at a path that does not exist yet; the extension says which. The file is empty, or built from a spec, described below. It takes file and the optional name, description and spec. It never overwrites a file, writes atomically, and refuses a path outside the workspace roots or through a link. A file whose drawing or flow check finds an error is not written; the other findings of the check are returned with the result.Pro, Team in a pipeline
run_scenariosRuns the saved test cases of a project, or of one diagram, as penstock scenarios run does, and returns which passed, failed or were skipped. The engine must be marked for tests. Traces are kept under .penstock/runs.Pro, Team in a pipeline
test_taskRuns one element of a diagram on the local engine the project marks for tests, as penstock test task does: the process is deployed as a test build, the path to the element is completed or mocked, then the element is completed, made to throw a BPMN error or left waiting. It returns the state of the element, what it received and sent, the variables, the incidents and the state of the instance, and removes the build. It takes file and element, and the optional variables, complete, error, hold, process and timeout. Use only one of complete, error and hold. Traces are kept under .penstock/runs.Pro, Team in a pipeline

edit_diagram takes file, operations and the optional dryRun. The operations are the same contract as penstock edit --ops: add, connect, set, remove and move, which shifts an element by dx and dy. A business rule task names its decision with decisionRef on Camunda 7, Operaton and CIB seven, and with decisionId on Camunda 8. penstock edit <file> --schema prints the contract for the file's engine. The whole-project tools take project. The others take file.

Receipts and the scenarios argument

Whenever an agent changes project files through one of the writing tools (edit_diagram, layout_diagram, create_diagram, migrate_apply, migrate_agents, refactor_*, generate_templates, incident_to_scenario and the saving of a case by test_dmn), Penstock records what changed and returns it in the receipt field of the result: each file with a SHA-256 before and after, the diff in the diagram's own terms, the Check result before and after with the new findings named by rule and element id, and a verdict (verified, has new findings, or not verified with the reason). It holds names, hashes and ids, never file contents or secret values. With Penstock Pro, new Check errors are handed back to the agent in the tool result, up to ai.verify.attempts times (3 by default, 0 turns it off). The saved scenarios of a change run only with scenarios: true, and only on an engine marked deployment.forTests. See AI receipt and auto-repair.

The spec of create_diagram

Without spec the file is empty, for the engine in penstock.yaml. name is the name of the diagram, the file name by default. description is the documentation of a BPMN process, or the description of a DMN decision; a form has none, and a description for one is refused. A spec that has an unknown key, or a value of the wrong kind, is refused with the place named, and nothing is written.

FileThe spec
.bpmnExactly one of two keys. steps is a list of elements in a line, each after the one before and the first after the start event. A step has element (one of task, user-task, service-task, script-task, send-task, receive-task, business-rule-task, manual-task, call-activity, sub-process, end-event, intermediate-catch-event, intermediate-throw-event, exclusive-gateway, parallel-gateway, inclusive-gateway or event-based-gateway) and the optional name, event (message, timer, signal, error, escalation, conditional or terminate), id (Step_<n> by default) and properties. operations is a list of the operations of edit_diagram, applied to the empty diagram.
.dmninputs, a list with expression and the optional label and typeRef; outputs, a list with name and the optional label and typeRef; the optional hitPolicy (UNIQUE by default, FIRST, PRIORITY, ANY, COLLECT, RULE ORDER or OUTPUT ORDER); and the optional rules, each with when (one text for each input, in order), then (one text for each output) and an optional description. typeRef is string (the default), number, boolean, integer, long, double, date, time or dateTime.
.formfields, a list. A field has type: textfield, textarea, number, checkbox, checklist, radio, select, taglist, datetime, text or button. An input field has a key, unique in the form, and the optional label and required. A checklist, radio, select or taglist also has options, each with label and value. A text field has text. A button has label and submits the form.
{
  "file": "/work/shop/src/main/resources/ship-order.bpmn",
  "spec": {
    "steps": [
      { "element": "service-task", "name": "Reserve stock" },
      { "element": "user-task", "name": "Pack the order" },
      { "element": "end-event", "name": "Order shipped" }
    ]
  }
}

Resources and prompts

Besides tools, the server lists the diagrams, decision files and forms of the folders the client has open as MCP resources, each with its kind, and returns the text of one when the client reads it. Clients that show resources let you attach a diagram to a conversation without a tool call. Paths outside the open folders are refused, as for the tools. Without roots nothing is listed.

Two prompts are offered, both taking file: review_diagram asks the assistant to read a file, run the checks and list what to fix, most serious first, without editing; explain_process asks it to explain a process in plain language from its scenarios. Resources and prompts are free.

A tool that needs a licence you do not have appears in the tool list with a note on what it needs. Called without the licence, it says so in its error result, with how to buy or sign in. In a pipeline the paid tools need Team. See Plans and licence.

A result is bounded. When it is longer than 100,000 characters it is cut and says The result was cut at 100000 of … characters. Ask for less: one process, or a smaller diagram.

Safety

What you see

Common problems

The assistant does not see the tools.
Check the command and args in the entry. Node.js 22.22 or later must be on the PATH of the assistant. Run penstock mcp by hand: it should wait silently for input.
"must be an absolute path to a diagram" or "\"project\" must be an absolute path".
The tools take absolute paths. Ask the assistant to pass the full path, as list_diagrams prints it.
"is outside the workspace roots".
The path is not inside a folder the client has open. Open the project in the client, or give a path inside an open folder.
"is not a Penstock project".
The folder has no penstock.yaml and no repository root above it. Run penstock init there.
A paid tool says it needs a licence.
Sign in on the machine that runs the server: penstock license login.