Skip to content

Reference

validate

Validates an Arazzo specification for correctness and completeness.

Uses Spectral (via npx @stoplight/spectral-cli) with the official spectral:arazzo ruleset as the primary validator when available. Falls back to the built-in Go validator when Node.js is not installed, showing install instructions.

arazzo-mcp-gen validate -f <file-or-folder>
Flag Short Description Default
--file -f Path to an Arazzo file, or a folder that the CLI scans to find one —
--check-remote Also probe remote source URLs for accessibility false
--strict Treat warnings as errors (exits with code 1 on warnings) false

Examples

# Validate all files in a folder
arazzo-mcp-gen validate -f ./my-arazzo-folder

# Validate a single file
arazzo-mcp-gen validate -f ./workflow.yaml

# Validate and also check that remote OpenAPI URLs are reachable
arazzo-mcp-gen validate -f ./my-arazzo-folder --check-remote

# Strict mode: fail if there are any warnings
arazzo-mcp-gen validate -f ./my-arazzo-folder --strict

What it checks (Spectral ruleset)

  • Full JSON Schema validation against the Arazzo 1.0.x spec
  • Unique workflowId and stepId values
  • Step targets (operationId, operationPath, workflowId) are present and valid
  • Parameter name, in, and value fields
  • Success criteria condition syntax
  • Unique onSuccess / onFailure action names
  • Output expression syntax
  • dependsOn cross-references

Additional built-in checks (always run)

  • Local source file existence
  • Remote URL accessibility (only with --check-remote)
  • Multiple $statusCode criteria that are AND-ed together (a common mistake)

Exit codes

Code Meaning
0 Passed (no errors)
1 Errors found, or warnings in --strict mode

inspect

Parses and prints a detailed, colour-coded overview of an Arazzo spec — without generating anything. Use this to understand a spec or debug step-flow routing before generating an MCP server.

arazzo-mcp-gen inspect -f <file-or-folder>
Flag Short Description
--file -f Path to an Arazzo file, or a folder that the CLI scans to find one

Examples

# Inspect a folder (auto-detects the Arazzo file)
arazzo-mcp-gen inspect -f ./my-arazzo-folder

# Inspect a specific file
arazzo-mcp-gen inspect -f ./workflow.yaml

Output includes

  • Spec metadata: title, version, Arazzo version
  • All source descriptions with types and URLs
  • For each workflow:
    • Input schema with types
    • Each step: operation target, parameter bindings, success criteria
    • onSuccess / onFailure routing with conditions (GOTO, END, RETRY)
    • Step outputs and their expressions
    • Workflow-level outputs

visualize

Generates a Mermaid flowchart diagram of the Arazzo spec's workflow logic. By default opens the rendered diagram in your browser (no extra tools needed). Can also save to a file.

arazzo-mcp-gen visualize -f <file-or-folder> [-o <output-file>]

Alias: viz

Flag Short Description
--file -f Path to an Arazzo file, or a folder that the CLI scans to find one
--output -o Output file path. .md → Mermaid in fenced code block; .mmd → raw Mermaid syntax

Examples

# Open diagram in browser (default)
arazzo-mcp-gen visualize -f ./my-arazzo-folder

# Save to GitHub-renderable Markdown
arazzo-mcp-gen visualize -f ./workflow.yaml -o diagram.md

# Save raw Mermaid source
arazzo-mcp-gen visualize -f ./my-arazzo-folder -o flow.mmd

# Short alias
arazzo-mcp-gen viz -f ./my-arazzo-folder

Diagram shows

  • Start and end nodes for each workflow
  • Steps with operation targets
  • onSuccess / onFailure branches labelled with conditions
  • Implicit sequential flow and fallthrough paths (dashed arrows)
  • Cross-workflow goto references

Tip

Paste any .mmd file into mermaid.live for a shareable interactive link.

mcp-server generate

The main command. Reads your Arazzo + OpenAPI files, generates a Python MCP server, and builds a Docker image.

arazzo-mcp-gen mcp-server generate -f <file-or-folder> [flags]
Flag Short Description Default
--file -f Path to an Arazzo file, or a folder that the CLI scans to find one. When you give a file, the CLI looks in its parent folder for the referenced OpenAPI files —
--port -p Port the MCP server listens on inside the container and on your host 5000
--output -o Save generated artifacts (mcp_server.py, Dockerfile, arazzo/ folder) to this path for inspection. If omitted a temp directory is used and cleaned up automatically —

Note

--file (-f) is required. Point it at a single Arazzo file when a folder holds more than one and you want to convert only that one.

Examples

# From a folder (auto-detects the Arazzo file)
arazzo-mcp-gen mcp-server generate -f ./my-arazzo-folder

# From a single Arazzo file directly
arazzo-mcp-gen mcp-server generate -f ./my-arazzo-folder/workflow.arazzo.yaml

# Custom port
arazzo-mcp-gen mcp-server generate -f ./my-arazzo-folder -p 8080

# Inspect generated files after build
arazzo-mcp-gen mcp-server generate -f ./workflow.arazzo.yaml -p 8080 -o ./artifacts

Input requirements

  • When -f is a folder: it must contain exactly one .yaml/.yml file with a top-level arazzo: key
  • When -f is a file: point directly to the Arazzo file; the folder can contain multiple Arazzo files
  • Local OpenAPI files referenced in sourceDescriptions[].url must be in the same folder as the Arazzo file. Remote URLs need no local copy, and the generated server fetches them at runtime
  • The Arazzo file must have info.title, info.version, and at least one workflow

What it does

  1. Finds and validates the Arazzo file in the folder
  2. Generates mcp_server.py — each workflow becomes a @mcp.tool() function with typed parameters
  3. Generates a Dockerfile using python:3.11-slim
  4. Runs docker build to produce a tagged image
  5. Prints the docker run command to start the server

Running the generated server

docker run -p 5000:5000 <image-name>

To reach an HTTPS endpoint that uses a self-signed certificate, set ARAZZO_DISABLE_TLS_VERIFY when you start the container:

docker run -p 5000:5000 -e ARAZZO_DISABLE_TLS_VERIFY=1 <image-name>

The MCP endpoint is available at http://localhost:5000/mcp.