io.github.tiago-marques/x-openapi-flow-mcp

Official

by tiago-marques · JavaScript

OpenAPI lifecycle guard and MCP sidecar for policy-driven API orchestration.

Manages OpenAPI lifecycle and enforces policy-driven API orchestration rules.

Topics

clilifecycleoasopenapivalidationworkflow

README.md29 KBView on GitHub

OpenAPI describes APIs. x-openapi-flow turns them into executable workflows — for developers and AI agents.

Define your API workflows in openapi.x.json and execute them without writing custom clients or orchestration logic

npm total downloads license

🚀 2,100+ downloads in the first 3 weeks!

⚡ Get started in seconds

code

npx x-openapi-flow init --suggest-transitions

This generates an openapi.x.json file where you can declaratively define how your API should be executed — not just described.

See your API lifecycle come alive from your OpenAPI spec, with one simple command

Validate, document, and generate flow-aware SDKs automatically.

x-openapi-flow in action

What is this?

x-openapi-flow extends your OpenAPI specification with a workflow layer.

openapi.json → describes your API
openapi.x.json → describes how to use it (flows)

Instead of writing imperative code to orchestrate API calls, you define workflows declaratively and run them anywhere.

x-openapi-flow adds a declarative state machine to your OpenAPI spec.

Model resource lifecycles, enforce valid transitions, and generate flow-aware artifacts for documentation, SDKs, and automation.

🚀 Example

Define stateful workflows and lifecycle transitions directly inside your OpenAPI operations:

json

{
  "operationId": "createOrder",
  "x-openapi-flow": {
    "version": "1.0",
    "id": "create-order",
    "current_state": "created",
    "description": "Creates an order and starts the lifecycle",
    "transitions": [
      {
        "transition_id": "order-created-to-paid",
        "trigger_type": "synchronous",
        "condition": "Payment is confirmed",
        "decision_rule": "payOrder:response.200.body.payment_status == 'approved'",
        "target_state": "paid",
        "next_operation_id": "payOrder",
        "operation_role": "mutate",
        "prerequisite_operation_ids": ["createOrder"],
        "evidence_refs": [
          "payOrder:response.200.body.payment_status"
        ],
        "propagated_field_refs": [
          "createOrder:response.201.body.order_id"
        ],
        "failure_paths": [
          {
            "reason": "Payment denied",
            "target_state": "payment_failed",
            "next_operation_id": "getOrder"
          }
        ]
      }
    ]
  }
}

This flow defines an order lifecycle directly inside your OpenAPI:

Starts in the created state
Transitions to paid when payment is confirmed
Supports both synchronous and polling-based transitions
Propagates data between operations automatically
Can include explicit decision/evidence and failure-path metadata for AI-guided orchestration

Instead of manually orchestrating API calls, the workflow is fully described alongside your API specification.

Why This Exists

Building APIs is cheap. Building complex, multi-step APIs that teams actually use correctly is hard.

Teams face recurring problems:

📄 Manual documentation is brittle – OpenAPI specs are static, often out of sync with real workflows
🤖 AI agents can hallucinate – LLMs and code-generating agents may produce invalid calls if workflows are unclear or undocumented
🤯 Workflows are confusing – multi-step operations are hard to track for humans and AI agents
⚠️ Invalid calls slip through – developers make mistakes because lifecycle rules aren’t enforced
⏱️ Integration slows down – SDKs, Postman collections, and docs need constant manual updates
🛡️ Hard to prevent errors in production – without explicit lifecycle rules, invalid operations can reach live systems, causing outages or inconsistencies

x-openapi-flow exists to solve these pains: it makes lifecycles explicit, validates transitions automatically, and generates flow-aware docs and SDKs — so teams move faster, make fewer mistakes, and ship confident integrations.

What This Enables

Turn your OpenAPI spec into a single source of truth for API behavior:

Visualize API lifecycles directly in Swagger UI and Redoc
Validate flows and state transitions in CI pipelines
Generate lifecycle diagrams automatically from your OpenAPI spec
Build SDKs that understand and respect API workflows
Export Postman and Insomnia collections organized by lifecycle
Create AI-ready API contracts for agentic integrations

Quick Start (without OpenAPI file)

Start in 2 Minutes (Online Playground)

Prefer no local setup? Open the minimal runtime-guard demo directly in your browser:

StackBlitz: https://stackblitz.com/github/tiago-marques/x-openapi-flow/tree/main/example/runtime-guard/minimal-order
Codespaces (repo): https://github.com/tiago-marques/x-openapi-flow

Once open, run:

bash

npm install
npm run start

Then in another terminal:

bash

curl -s -X POST http://localhost:3110/orders
curl -i -X POST http://localhost:3110/orders/<id>/ship

Expected: 409 INVALID_STATE_TRANSITION.

Fastest way to see value (guided scaffold):

bash

npx x-openapi-flow quickstart
cd x-openapi-flow-quickstart
npm install
npm start

Optional runtime:

bash

npx x-openapi-flow quickstart --runtime fastify

Then run:

bash

curl -s -X POST http://localhost:3110/orders
curl -i -X POST http://localhost:3110/orders/<id>/ship

Expected: 409 INVALID_STATE_TRANSITION.

If you already have an OpenAPI file, use the sidecar workflow:

Initialize flow support in your project:

bash

npx x-openapi-flow init
# optional: infer suggested transitions using naming heuristics
npx x-openapi-flow init --suggest-transitions

After regenerating your OpenAPI file, apply and validate the flow (optional):

bash

npx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml

npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality

This will:

enrich your OpenAPI spec with flow metadata
validate lifecycle consistency
catch invalid transitions early

💡 Tip: run this in CI to enforce API workflow correctness

Less Verbose DSL for Large Flows

For larger APIs, you can define flow rules by resource (with shared transitions/defaults) and reduce duplication in sidecar files.

See: Sidecar Contract

GitHub Action (One-Step CI Validation)

Use the official reusable action to validate lifecycle rules in CI with a single step:

yaml

- name: Validate OpenAPI flow rules
  uses: tiago-marques/x-openapi-flow@v1
  with:
    openapi-file: openapi.flow.yaml
    profile: strict
    strict-quality: "true"

Integration guide: GitHub-Actions-Integration.md

Real Lifecycle Example

Here’s a real-world payment lifecycle represented in x-openapi-flow:

code

CREATED -> AUTHORIZED -> CAPTURED -> REFUNDED

Generate a visual graph of the lifecycle:

bash

npx x-openapi-flow graph openapi.flow.yaml --format mermaid

Resulting diagram:

mermaid

graph TD
CREATED --> AUTHORIZED
AUTHORIZED --> CAPTURED
CAPTURED --> REFUNDED

This visualization makes your API workflow explicit, easy to communicate, and ready for documentation or demos.

Generate Flow-Aware SDKs

Create a TypeScript SDK that respects your API’s lifecycle and transition rules, following best practices seen in leading companies like Stripe and Adyen:

Orchestrator by model: each resource exposes methods that enforce valid transitions
Chainable API calls: perform sequences naturally and safely

bash

npx x-openapi-flow generate-sdk openapi.flow.yaml --lang typescript --output ./sdk

Example usage:

const payment = await sdk.payments.create({ amount: 1000 });
await payment.authorize();
await payment.capture();

This SDK guides developers through valid transition paths, following patterns used by market leaders to ensure safe and intuitive integrations.

Runtime Enforcement (Express + Fastify)

CI validation is important, but production safety needs request-time enforcement.

x-openapi-flow now includes an official runtime guard for Node.js that can block invalid state transitions during request handling.

Works with Express and Fastify
Resolves operations by operationId (when available) or by method + route
Reads current resource state using your own persistence callback
Blocks invalid transitions with explicit 409 error payloads

Install and use directly in your API server:

const {
  createExpressFlowGuard,
  createFastifyFlowGuard,
} = require("x-openapi-flow/lib/runtime-guard");

Express example:

const express = require("express");
const { createExpressFlowGuard } = require("x-openapi-flow/lib/runtime-guard");
const openapi = require("./openapi.flow.json");

const app = express();

app.use(
  createExpressFlowGuard({
    openapi,
    async getCurrentState({ resourceId }) {
      if (!resourceId) return null;
      return paymentStore.getState(resourceId); // your DB/service lookup
    },
    resolveResourceId: ({ params }) => params.id || null,
  })
);

Fastify example:

const fastify = require("fastify")();
const { createFastifyFlowGuard } = require("x-openapi-flow/lib/runtime-guard");
const openapi = require("./openapi.flow.json");

fastify.addHook(
  "preHandler",
  createFastifyFlowGuard({
    openapi,
    async getCurrentState({ resourceId }) {
      if (!resourceId) return null;
      return paymentStore.getState(resourceId);
    },
    resolveResourceId: ({ params }) => params.id || null,
  })
);

Error payload for blocked transition:

json

{
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "Blocked invalid transition for operation 'capturePayment'. Current state 'CREATED' cannot transition to this operation.",
    "operation_id": "capturePayment",
    "current_state": "CREATED",
    "allowed_from_states": ["AUTHORIZED"],
    "resource_id": "pay_123"
  }
}

More details: Runtime Guard

Built-in Persistence Adapters

No need to write your own getCurrentState from scratch. x-openapi-flow ships four ready-made adapters:

const {
  MemoryAdapter,   // in-process Map — ideal for tests and single-instance dev
  FileAdapter,     // JSON file on disk — great for demos and local servers
  RedisAdapter,    // ioredis-backed — production-ready, requires: npm install ioredis
  GenericSQLAdapter, // any SQL DB (pg, mysql2, knex…) via query callback
} = require("x-openapi-flow/lib/runtime-guard");

// in-memory (testing / local)
const store = new MemoryAdapter();
app.use(createExpressFlowGuard({ openapi, ...store.forGuard() }));

// persist every transition to Redis
const Redis = require("ioredis");
const redisStore = new RedisAdapter({ client: new Redis(), prefix: "orders:" });
app.use(createExpressFlowGuard({ openapi, ...redisStore.forGuard() }));

// call setState after each successful request to keep the state in sync
app.post("/orders/:id/pay", async (req, res) => {
  await redisStore.setState({ resourceId: req.params.id, state: "paid" });
  res.json({ ok: true });
});

GenericSQLAdapter example with pg:

const { Pool } = require("pg");
const pool = new Pool();
const sqlStore = new GenericSQLAdapter({
  query: (sql, params) => pool.query(sql, params).then(r => r.rows),
  dialect: "pg",
});
await sqlStore.ensureTable(); // CREATE TABLE IF NOT EXISTS xflow_state (…)
app.use(createExpressFlowGuard({ openapi, ...sqlStore.forGuard() }));

All adapters implement getCurrentState, setState, deleteState and forGuard() — a convenience method that returns the exact shape expected by the guard options.

Observability Hooks (Metrics/Audit)

You can instrument runtime decisions with onDecision to feed Prometheus, logs, or tracing.

const { Counter } = require("prom-client");
const { createExpressFlowGuard } = require("x-openapi-flow/lib/runtime-guard");

const flowDecisions = new Counter({
  name: "xflow_runtime_guard_decisions_total",
  help: "Runtime guard decisions by type and operation",
  labelNames: ["decision", "operation_id"],
});

app.use(
  createExpressFlowGuard({
    openapi,
    ...store.forGuard(),
    onDecision(event) {
      flowDecisions.inc({
        decision: event.decision,
        operation_id: event.operationId || "unknown",
      });
    },
  })
);

Common decision values include:

allowed_transition
allowed_idempotent_state
allowed_initial_state
denied_invalid_transition
denied_missing_resource_id
denied_unknown_operation
skipped_unknown_operation

Want to see the value immediately? Use the official minimal demo:

example/runtime-guard/minimal-order/README.md

Run in under 5 minutes:

bash

cd example/runtime-guard/minimal-order
npm install
npm start

Create an order, then try to ship before payment (must return 409 INVALID_STATE_TRANSITION):

bash

curl -s -X POST http://localhost:3110/orders
curl -i -X POST http://localhost:3110/orders/<id>/ship

HTTPie equivalent:

bash

http POST :3110/orders
http -v POST :3110/orders/<id>/ship

Programmatic State Machine Engine

Use a reusable deterministic engine independently of CLI and OpenAPI parsing:

const { createStateMachineEngine } = require("x-openapi-flow/lib/state-machine-engine");

const engine = createStateMachineEngine({
  transitions: [
    { from: "CREATED", action: "confirm", to: "CONFIRMED" },
    { from: "CONFIRMED", action: "ship", to: "SHIPPED" },
  ],
});

engine.canTransition("CREATED", "confirm");
engine.getNextState("CREATED", "confirm");
engine.validateFlow({ startState: "CREATED", actions: ["confirm", "ship"] });

More details: State Machine Engine

OpenAPI to Engine Adapter

Convert x-openapi-flow metadata to a pure engine definition:

const { createStateMachineAdapterModel } = require("x-openapi-flow/lib/openapi-state-machine-adapter");
const { createStateMachineEngine } = require("x-openapi-flow/lib/state-machine-engine");

const model = createStateMachineAdapterModel({ openapiPath: "./openapi.flow.yaml" });
const engine = createStateMachineEngine(model.definition);

More details: OpenAPI State Machine Adapter

Who Benefits Most

x-openapi-flow is ideal for teams and organizations that want clear, enforceable API workflows:

API-first organizations – maintain a single source of truth for API behavior
Teams building AI agents – provide AI-friendly contracts and enforce correct API usage, so agents can safely call endpoints in the right order without guessing or violating workflow rules
API platform teams – ensure consistent lifecycle rules across endpoints
Companies with complex API workflows – reduce errors and ambiguity in multi-step processes
SDK teams – generate flow-aware SDKs that guide developers

Why x-openapi-flow?

See how x-openapi-flow extends OpenAPI to make your API workflows explicit, enforceable, and actionable:

Capability	OpenAPI	x-openapi-flow
Endpoint contracts	✅ Yes	✅ Yes (fully compatible, extended)
Lifecycle states	❌ No	✅ Yes – define states for each resource
Transition validation	❌ No	✅ Yes – catch invalid calls before runtime
Flow diagrams	❌ No	✅ Yes – generate visual lifecycle graphs
Usage guidance (next valid actions)	Limited/manual	✅ Built-in via lifecycle metadata – guides developers and AI agents

How does it compare to OpenAPI Workflows (Arazzo) and AsyncAPI?

Dimension	x-openapi-flow	OpenAPI Workflows (Arazzo)	AsyncAPI
Primary focus	Resource lifecycle states & runtime enforcement	Multi-step API workflows (orchestration scripts)	Event-driven / async messaging APIs
Lifecycle states	✅ Explicit states per resource	❌ No state model	❌ No state model
Runtime enforcement	✅ Express/Fastify middleware (409 on invalid transitions)	❌ Spec-only, no runtime guard	❌ Spec-only
SDK generation	✅ TypeScript, Kotlin, Python, Go	❌ No codegen	Limited
Postman / Insomnia export	✅ Built-in adapters	❌ No	❌ No
AI agent support	✅ MCP sidecar + structured sidecar contract	❌ No	❌ No
Breaking change detection	✅ `diff --breaking-only --fail-on-breaking`	❌ No	❌ No
CI validation	✅ CLI + GitHub Action	❌ No official CLI	Limited
OpenAPI compatibility	✅ Sidecar extends existing specs	Separate Arazzo spec	Separate AsyncAPI spec

In short: use x-openapi-flow when you need enforceable, stateful API lifecycles that go beyond documentation into runtime safety, SDK generation, and AI-ready contracts. Use Arazzo for scripting multi-step HTTP journeys. Use AsyncAPI for documenting event/message-driven systems.

Integration Demos

Explore how x-openapi-flow integrates with popular API tools, making lifecycles and flows explicit for documentation and testing.

Swagger UI – Visualize Flows in Your Docs

bash

cd example/swagger-ui
npm install
npm run apply
npm start

Swagger UI Flow Lifecycle 1

Lifecycle panel shows valid states and transitions

Swagger UI Flow Lifecycle 2

Detailed view of transitions per operation

Redoc – Flow-Aware Documentation

bash

cd example/redoc
npm install
npm run apply
npm run generate

Redoc Flow Lifecycle 1 Redoc Flow Lifecycle 2 Redoc Flow Lifecycle 3

Auto-generated lifecycle diagrams make documentation clear and consistent

Postman – Organized API Collections

bash

cd example/postman
npm install
npm run apply
npm run generate

Postman Flow Lifecycle 1 Postman Flow Lifecycle 2

Collections reflect lifecycle order, reducing integration errors

Insomnia – Organized API Collections

bash

cd example/insomnia
npm install
npm run apply
npm run generate

Insomnia Flow Lifecycle 1 Insomnia Flow Lifecycle 2

Requests are pre-organized according to lifecycle transitions

CLI Reference – Common Commands

Use x-openapi-flow from the command line to manage, validate, visualize, and generate SDKs/docs for your API workflows.

General

bash

npx x-openapi-flow help [command]         # show help for a specific command

npx x-openapi-flow --help                 # general help

npx x-openapi-flow version                # show version

npx x-openapi-flow doctor [--config path] # check setup and config

npx x-openapi-flow completion [bash|zsh]  # enable shell autocompletion

npx x-openapi-flow quickstart [--dir path] [--runtime express|fastify] [--force] # scaffold runnable onboarding project

Workflow Management

bash

# initialize flow support
npx x-openapi-flow init [--flows path] [--force] [--dry-run]   

# apply flows to OpenAPI
npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]  

# validate transitions
npx x-openapi-flow validate <openapi-file> [--profile core|relaxed|strict] [--strict-quality] [--semantic]  

# preview sidecar changes
npx x-openapi-flow diff [openapi-file] [--format pretty|json]

# detect breaking flow changes (use in CI to fail PRs)
npx x-openapi-flow diff [openapi-file] --breaking-only --fail-on-breaking

Visualization & Documentation

bash

# generate lifecycle diagrams
npx x-openapi-flow graph [openapi-file] [--format mermaid|json]   

# generate Redoc docs
npx x-openapi-flow generate-redoc [openapi-file] [--output path]   

# export flows
npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]

SDK Generation

bash

# generate flow-aware SDK
npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]

Test Generation

bash

# generate executable flow tests (happy path + invalid transitions)
npx x-openapi-flow generate-flow-tests [openapi-file] [--format jest|vitest|postman] [--output path]

# postman/newman-oriented collection with flow scripts
npx x-openapi-flow generate-flow-tests [openapi-file] --format postman [--output path] [--with-scripts]

Full details:

NestJS Integration

Dedicated package: x-openapi-flow-nestjs-kit

bash

npm install x-openapi-flow x-openapi-flow-nestjs-kit

Then import from x-openapi-flow-nestjs-kit.

This package wraps the official runtime-guard helpers and exposes a NestJS-first API.

Release automation for this package uses dedicated tags in the format nestjs-v<version> (example: nestjs-v0.1.1) so it does not conflict with x-openapi-flow tags.

Option A: Middleware (drop-in)

// flow-guard.middleware.ts
import { Injectable, NestMiddleware } from "@nestjs/common";
import { createFlowMiddleware, MemoryAdapter } from "x-openapi-flow-nestjs-kit";
import openapi from "./openapi.flow.json";

const store = new MemoryAdapter(); // swap for RedisAdapter or GenericSQLAdapter in production
const guard = createFlowMiddleware({ openapi, ...store.forGuard() });

@Injectable()
export class FlowGuardMiddleware implements NestMiddleware {
  use(req: any, res: any, next: () => void) {
    guard.use(req, res, next);
  }
}

// app.module.ts — apply to specific routes
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(FlowGuardMiddleware).forRoutes("orders");
  }
}

Option B: CanActivate Guard

// flow.guard.ts
import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
import { createFlowGuard, MemoryAdapter } from "x-openapi-flow-nestjs-kit";
import openapi from "./openapi.flow.json";

const store = new MemoryAdapter();
const flowGuard = createFlowGuard({ openapi, ...store.forGuard() });

@Injectable()
export class FlowGuard implements CanActivate {
  canActivate(context: ExecutionContext) {
    return flowGuard.canActivate(context);
  }
}

After each successful state-changing request, call store.setState to advance the resource:

@Post(":id/pay")
async pay(@Param("id") id: string) {
  // … business logic …
  await store.setState({ resourceId: id, state: "paid" });
  return { ok: true };
}

Documentation and Guides

Get the most out of x-openapi-flow with detailed guides, examples, and integration instructions:

Adoption Guide – docs/wiki/getting-started/Adoption-Playbook.md
Learn how to introduce x-openapi-flow into your API workflow efficiently
Troubleshooting – docs/wiki/reference/Troubleshooting.md
Quick solutions to common issues and validation errors
Real Examples – docs/wiki/engineering/Real-Examples.md
Explore real OpenAPI specs enhanced with lifecycle metadata
Integrations:
- GitHub Actions – docs/wiki/integrations/GitHub-Actions-Integration.md
  Validate flow rules in CI in one reusable workflow step
- Swagger UI – docs/wiki/integrations/Swagger-UI-Integration.md
  See flow-aware panels in Swagger UI
- Redoc – docs/wiki/integrations/Redoc-Integration.md
  Generate lifecycle diagrams in Redoc documentation
- Postman – docs/wiki/integrations/Postman-Integration.md
  Organize collections according to valid transitions
- Insomnia – docs/wiki/integrations/Insomnia-Integration.md
  Pre-configure requests according to lifecycle flows

Community and Proof

Share your case study – docs/wiki/community/Case-Study-Template.md
Open discussions and ideas – use GitHub Issues to share adoption blockers, metrics, and integration stories : use the structured forms at .github/ISSUE_TEMPLATE/case-study.yml and .github/ISSUE_TEMPLATE/adoption-blocker.yml
Prove impact with metrics – track denied_invalid_transition, onboarding lead time, and CI catch rate before/after adoption

Roadmap

We’re actively expanding x-openapi-flow to support multiple platforms and SDKs. Check our progress:

🗂 Roadmap Overview – #2
See planned features and high-level goals
🐍 Python SDK MVP – #3
Enable Python developers to use flow-aware SDKs
🏎 Go SDK MVP – #4
Bring lifecycle-aware SDKs to Go projects
☕ Kotlin SDK MVP – #5
Support Android and JVM developers with flow-aware SDKs

Changelog

Keep track of updates and improvements in x-openapi-flow:

Latest Version (v1.7.0) – CHANGELOG.md#170---2026-04-02
See what shipped in the current release
Version History – CHANGELOG.md
Review the full version history and past updates
Release Notes – GitHub Release v1.7.0
See detailed notes for the latest release, including new features and fixes

Documentation Language Policy

To ensure clarity and accessibility for the global developer community, all project documentation should be written in English. This helps contributors, users, and AI agents understand and use x-openapi-flow consistently.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "x-openapi-flow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "x-openapi-flow@1.7.4"
      ]
    }
  }
}