devflows-mcp
Run developer release workflows as BPMN processes on a local CIB seven engine from an MCP client.
Check that the engine is reachable and report its version.
Deploy the release process to the engine.
List deployed process definitions.
Start a release run for a repository, with optional dry run and approval timeout.
Inspect a run's state, current activity, gate report, and variables.
List the gates a repository would run without touching the engine.
Approve or reject a waiting release gate (the human decision).
List recent release runs with their state.
Retry a run stuck on an incident.
Cancel a running release, keeping the reason in history.
Run a doctor check for engine, process, decision, and config readiness.
Provides tools to interact with a Camunda-compatible process engine (CIB seven), enabling management of BPMN process definitions, starting release processes, querying run state, and approving user tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@devflows-mcp start a dry run release for version 0.3.0"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cibseven-devflows
Run your developer workflows as BPMN processes on a local CIB seven engine, and drive them from AI coding agents such as Claude Code through an MCP server.
One workflow so far: the release ritual of a repository. Run the quality gates, draft the release notes, decide whether a human even needs to look, tag, publish. This repository cuts its own releases by running that process on itself.
Why
Cutting a release is a process with a human decision in the middle of it. Normally that process lives in someone's head and in a terminal scrollback. Nothing records that the gates ran, that a person approved, or what was published.
A process engine is exactly the right tool for that shape of problem. CIB seven keeps the state, keeps the history, and knows how to wait for a human. Your machine still does the work, and an AI agent can start a run and watch it, but it cannot skip the approval, because the approval is a step in the process rather than a promise in a prompt.
Four things here are the reason this is a process and not a shell script:
The approval policy is data, not code. A DMN decision table decides whether a release needs a human at all. Change the rules without touching a line of Python.
An AI drafts the release notes, and a human owns them. The draft appears in the approval form, and whatever is approved is what gets published.
A failed publish undoes its own tag. BPMN compensation, so a broken release leaves nothing behind.
A forgotten approval ends itself. A boundary timer rejects a release nobody answered.
Related MCP server: jt-mcp-server
Architecture
flowchart LR
agent["Claude Code<br/>(any MCP client)"] -- stdio --> mcpserver["devflows-mcp"]
mcpserver -- REST --> engine["CIB seven engine<br/>Docker, H2, localhost:8080"]
human["You, in the web UI"] -- approve --> engine
engine -- fetchAndLock --> worker["devflows-worker"]
worker -- shell --> repo["your repository<br/>pytest, ruff, git, gh"]The engine never runs a shell command and never touches your repository. It hands out work; the worker on your machine polls for it and does it. That is the standard Camunda 7 external task pattern, and it is what makes it safe to let a process drive a developer machine.
The release process
flowchart LR
start((start)) --> gates["Run gates<br/><i>devflows.gates</i>"]
gates --> q1{Gates passed?}
q1 -- no --> failed((Gates failed))
q1 -- yes --> notes["Draft release notes<br/><i>devflows.notes</i>"]
notes --> policy["Decide policy<br/><i>DMN release-policy</i>"]
policy --> q2{Approval required?}
q2 -- "policy says ship" --> tag
q2 -- "ask a human" --> approve["Approve release<br/><i>user task</i>"]
approve -. timer .-> expired((Approval expired))
approve --> q3{Approved?}
q3 -- stop --> rejected((Release rejected))
q3 -- ship --> tag["Tag<br/><i>devflows.tag</i>"]
tag --> publish["Publish<br/><i>devflows.publish</i>"]
publish -. "publish failed" .-> undo["Delete the tag<br/><i>devflows.untag</i>"]
undo --> pubfail((Publish failed))
publish --> released((Released))The rectangles with a topic name are external tasks. "Decide policy" is a business rule task that
calls the DMN decision. "Approve release" is a BPMN user task, so it waits, it survives an engine
restart, and it can be answered either in the web UI or through the approve_gate MCP tool.
dry_run=true runs the gates for real and changes nothing else: no tag, no push, no release.
The approval policy
processes/release-policy.dmn is a decision table with a FIRST hit policy:
|
| Approval required | Reason |
any |
|
| Gates failed, a human has to look |
|
|
| Patch release with green gates, approved by policy |
any | any |
| Minor or major release, a human decides |
release_kind comes from comparing the candidate version against the newest tag in the repository.
With no previous tag it is major, so a first release always asks a human. Edit the table in
Camunda Modeler and redeploy; no code changes.
On the auto-approved path approved is never set, because no human said yes. The history records
approval_required=false and policy_reason instead.
Release notes
draft_notes collects the commits since the previous tag and asks the local claude CLI to write
markdown release notes. The draft lands in the approval form as an editable field, and whatever is
approved becomes the body of the GitHub Release.
If claude is not installed, or the call fails, the notes fall back to the plain commit list.
notes_source records which happened. Nothing leaves your machine except through the CLI you
already run, and this project holds no API key of its own.
When a step fails
Two different failures, handled two different ways.
A step that might work next time, such as a network blip or gh not being logged in, is
reported to the engine as an external task failure with retries left. The worker backs off 5 s,
15 s, then 60 s, and only then does an incident appear.
A step that will not work next time, such as a publish that was refused, is reported as a BPMN
error with the code PUBLISH_FAILED. An error boundary event catches it, throws compensation, and
the undo_tag handler deletes the tag locally and on the remote. No incident is raised, because
nothing is broken; the release simply did not happen.
What it looks like
The process stops and waits for a person. The approval carries the gate results and the drafted
release notes, and it belongs to the camunda-admin group rather than to one named user, so
whoever is around can pick it up.

Afterwards the whole run is in the history: which gates ran, what the policy decided, who approved, what was tagged and where it was published.

Quickstart
docker compose -f engine/docker-compose.yml up -duv syncuv run pytest -m "not integration" && uv run ruff check .Deploy the process and the decision table (once per engine):
curl -s -X POST http://localhost:8080/engine-rest/deployment/create -F "deployment-name=cibseven-devflows" -F "release.bpmn=@processes/release.bpmn" -F "release-policy.dmn=@processes/release-policy.dmn"Check that everything a release needs is in place:
uv run devflows-doctorStart the worker and leave it running in its own terminal:
uv run devflows-workerStart a dry release of this repository. Replace repo_path with this repository's absolute path.
Use forward slashes even on Windows (C:/Users/you/repos/cibseven-devflows): they work, and they
save you from fighting your shell over backslash escaping.
curl -s -X POST http://localhost:8080/engine-rest/process-definition/key/devflows-release/start -H "Content-Type: application/json" -d '{"variables":{"repo_path":{"value":"ABSOLUTE/PATH/TO/cibseven-devflows","type":"String"},"version":{"value":"0.2.0","type":"String"},"dry_run":{"value":true,"type":"Boolean"}}}'Then approve it at http://localhost:8080/webapp/#/seven/auth/tasks as demo / demo:
filter My Group Tasks, claim Approve release, tick approve, submit.
In practice you start runs through the MCP server instead of curl. See docs/DEMO.md for the full walkthrough, or docs/DEMO.de.md auf Deutsch.
devflows.yaml
Each repository describes its own release in a devflows.yaml at its root:
gates:
- name: tests
run: uv run pytest -q
- name: lint
run: uv run ruff check .
tag:
format: "v{version}"
publish:
run: gh release create v{version} --notes-file {notes_file}Key | Meaning |
| Ordered list of quality gates. Each needs a |
| How the tag name is built. |
| The shell command that publishes the release. Placeholders: |
Use {notes_file} to publish the notes the human approved. Leave it out and use
--generate-notes if you would rather GitHub wrote them.
Unknown top-level keys are ignored, so a newer version of devflows can add steps without breaking an older file.
The MCP tools
devflows-mcp speaks MCP over stdio and works from any MCP client.
Tool | Arguments | Returns |
| — | Whether the engine answers, its version, its engine names |
|
| Deployment id and the deployed process definition keys |
| — | Deployed process definitions with key, version and id |
|
| Process instance id and a link to it in the web UI |
|
| State, current activity, open tasks, the gate report, all variables |
|
| The gates that repository would run. Does not touch the engine |
|
| Confirmation that the approval task was completed |
|
| Recent runs with their state, newest first |
|
| Gives a run stuck on an incident another attempt |
|
| Stops a run; the reason stays in the history |
|
| Engine, process, decision and config in one call |
Every tool returns a dictionary with an ok flag, and an error string when ok is false.
No tool raises, because the caller is a language model that has to explain the failure to a person.
Using it from Claude Code
plugin/ is a Claude Code plugin around the same server:
plugin/.mcp.jsonstartsdevflows-mcpwithuv run --projectpointed at this repository, so the server starts no matter which repository the session is in. Load the plugin in place, for exampleclaude --plugin-dir /path/to/cibseven-devflows/plugin; it needs the Python project beside it.plugin/skills/release-with-devflows/SKILL.mdtells the agent when to use the engine and in what order to call the tools, including the rule that it must stop and ask before approving.plugin/commands/release.mdprovides/cibseven-devflows:release <version> [--real].
To wire the server into any other MCP client directly:
{
"mcpServers": {
"cibseven-devflows": {
"command": "uv",
"args": ["run", "--project", "/path/to/cibseven-devflows", "devflows-mcp"]
}
}
}Configuration
Variable | Default | Used by |
|
| worker, MCP server |
|
| worker |
|
| worker |
|
| worker |
| found next to the package | MCP server |
Variables you can set when starting a run:
Variable | Default | Meaning |
| — | Absolute path of the repository to release |
| — | Version without the tag prefix, for example |
| — | When true, nothing is tagged or published |
|
| ISO 8601 duration before an unanswered approval expires |
A short approval_timeout such as PT2M makes the timer easy to demonstrate.
Security
Two things about this project are deliberate, and both assume it runs on your own machine:
The engine has no authentication. The REST API on
localhost:8080accepts anything that can reach it. Do not expose that port to a network you do not control.The worker runs shell commands. They come from the
devflows.yamlof the repository you asked it to release, they run as you, in that repository, and they are the same commands you would type. Only point it at repositories you trust.
There is no cloud service, no telemetry and no account beyond the GitHub credentials gh already
has.
Repository layout
Directory | What is in it |
| Docker Compose for a local CIB seven 2.2.0 engine |
|
|
|
|
|
|
|
|
| The Claude Code plugin |
| Unit tests, plus |
| The demo script, and the design and plan documents |
Requirements
Docker Desktop, for the engine
Python 3.12 and uv
git, andghauthenticated, for the tag and publish stepsThe
claudeCLI, optionally, for AI-drafted release notesCamunda Modeler 5.x if you want to edit the diagrams (optional). Open
processes/release.bpmnandprocesses/release-policy.dmnas Camunda 7 files.
License
Apache License 2.0. See LICENSE.
Available Tools
11 toolsapprove_gateB
Approve or reject a waiting release. This is the human decision in the process.
Inputs: approve (required), task_id (required), comment. Returns: object
cancel_runB
Stop a running release. The reason is kept in the engine history.
Inputs: process_instance_id (required), reason. Returns: object
deploy_processC
Deploy the release process to the engine. Deploying it twice is harmless.
Inputs: bpmn_path. Returns: object
doctorC
Check whether a release can run: engine, process, decision, config.
Inputs: repo_path. Returns: object
engine_statusA
Check that the local CIB seven engine is reachable and report its version.
Inputs: no named parameters. Returns: object
get_runB
Report the state, the current activity, the gate report and the variables of a run.
Inputs: process_instance_id (required). Returns: object
list_gatesB
List the gates a release of this repository would run. Does not touch the engine.
Inputs: repo_path (required). Returns: object
list_processesA
List the process definitions the engine currently knows about.
Inputs: no named parameters. Returns: object
list_runsB
List the most recent release runs, newest first, with their state.
Inputs: limit. Returns: object
retry_runC
Give a run that is stuck on an incident another attempt.
Inputs: process_instance_id (required). Returns: object
start_releaseA
Start a release run for a repository.
Runs the gates, drafts release notes, then asks the policy whether a human
is needed. With dry_run true, which is the default, nothing is tagged or
published. approval_timeout is an ISO 8601 duration after which an
unanswered approval expires.
Inputs: version (required), repo_path (required), dry_run, approval_timeout. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct resource and action: engine health, process deployment/listing, release run lifecycle, gate approval, and diagnostics. There is no meaningful overlap or risk of selecting the wrong tool for a given intent.
Most tools follow a clear verb_noun pattern (deploy_process, list_processes, start_release, approve_gate, cancel_run). The deviations are minor: engine_status reverses the order and doctor is a bare noun, but the names remain intuitive and predictable.
Eleven tools is well-scoped for a release automation server. Each tool covers a distinct aspect of the release workflow without unnecessary bloat or noticeable duplication.
The tool surface covers the core release lifecycle well: checking the engine, deploying processes, starting runs, monitoring runs, approving gates, retrying, canceling, and running diagnostics. There is no explicit process update/delete, but that is a minor gap since the workflow does not clearly require it.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Human-in-the-loop for AI agents over MCP: durable approvals with a hosted review page & audit trail
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI coding environments to enforce engineering governance through MCP tools and resources for init, check, route, and review workflows.10 npm2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that equips AI agents with dev workflow tools including GitHub project management, conventional commits, visual regression testing, Jira/Confluence integration, and a persistent memory knowledge graph.14 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents and external systems to programmatically trigger and monitor Jenkins jobs, retrieve build status and logs via MCP standards.-
- AlicenseNot gradedqualityBmaintenanceExposes a governed, provenance-grounded autonomous delivery pipeline as an MCP server, enabling AI coding assistants like Claude Code or Codex to initiate requirements-to-PR workflows with human approval gates and full audit.549 PyPI13MIT