gen-orb-mcp

Generate MCP (Model Context Protocol) servers from CircleCI orb definitions.

Overview

gen-orb-mcp enables AI coding assistants to understand and work with private CircleCI orbs. It parses an orb YAML definition and generates a standalone MCP server that exposes the orb's commands, jobs, and executors as MCP Resources. When conformance rules are provided, the generated server also gains plan_migration and apply_migration MCP Tools, allowing an AI assistant to guide users through orb version migrations interactively.

Features

Parse any CircleCI orb — supports commands, jobs, executors, and parameters
Generate MCP servers — produces Rust source code or a compiled native binary
Orb documentation as Resources — commands, jobs, executors, and an overview exposed as MCP resources at orb://commands/{name}, orb://jobs/{name}, orb://executors/{name}
Multi-version embedding — embed prior orb version snapshots alongside the current version so an AI assistant can answer cross-version questions (e.g. "what did job X look like in v4.7.1?")
Migration Tools — when conformance rules are supplied, the generated server exposes plan_migration and apply_migration MCP Tools that call back into gen-orb-mcp at runtime
Offline operation — generated servers run entirely offline with no external calls
Conformance-based migration CLI — diff and migrate commands for scripted bulk migration

Installation

cargo install gen-orb-mcp

Or with cargo-binstall:

cargo binstall gen-orb-mcp

Quick Start

1. Generate a basic MCP server

gen-orb-mcp generate \
  --orb-path ./circleci-toolkit/src/@orb.yml \
  --output ./circleci-toolkit-mcp \
  --version 4.9.6

This generates Rust source code in ./circleci-toolkit-mcp/. To compile it:

cd circleci-toolkit-mcp && cargo build --release

2. Automatically populate prior-version history

Use prime to discover version tags from git history, snapshot each version's orb, and compute conformance rule diffs — all in one step. The sliding window keeps only the last 6 months (or from a fixed anchor) to keep binary size bounded.

# Populate prior-versions/ and migrations/ from the last 6 months of tags
gen-orb-mcp prime \
  --orb-path ./circleci-toolkit/src/@orb.yml

# Anchor at a specific earliest version (covers your full estate)
gen-orb-mcp prime \
  --orb-path ./circleci-toolkit/src/@orb.yml \
  --earliest-version 4.1.0

# In CI: write to /tmp (ephemeral) and print paths for the next step
eval "$(gen-orb-mcp prime \
  --orb-path ./src/@orb.yml \
  --earliest-version 4.1.0 \
  --ephemeral)"
# → PRIME_PV_DIR and PRIME_MIG_DIR are now set; pass them to generate:
gen-orb-mcp generate \
  --orb-path ./src/@orb.yml \
  --output ./mcp-build \
  --version "${ORB_VERSION}" \
  --prior-versions "${PRIME_PV_DIR}" \
  --migrations "${PRIME_MIG_DIR}"

prime is idempotent: existing files are not overwritten; out-of-window files are removed.

3. Generate with migration Tools embedded

First compute conformance rules by diffing two orb versions:

gen-orb-mcp diff \
  --current ./circleci-toolkit/src/@orb.yml \
  --previous ./circleci-toolkit-4.7.1.yml \
  --since-version 4.9.6 \
  --output ./migrations/4.9.6.json

Then generate the server with rules and prior-version snapshots embedded:

gen-orb-mcp generate \
  --orb-path ./circleci-toolkit/src/@orb.yml \
  --output ./circleci-toolkit-mcp \
  --version 4.9.6 \
  --migrations ./migrations/ \
  --prior-versions ./prior-versions/

The --prior-versions directory should contain <version>.yml files (e.g. 4.7.1.yml).

The generated server now exposes:

All current-version Resources (orb://commands/..., orb://jobs/...)
Prior-version Resources (orb://v4.7.1/commands/..., orb://v4.7.1/jobs/...)
A version index at orb://versions
plan_migration and apply_migration MCP Tools

4. Migrate a consumer CI directory

Apply migration rules directly from the CLI (no MCP server required):

# Dry run — show what would change
gen-orb-mcp migrate \
  --ci-dir ./.circleci \
  --orb toolkit \
  --rules ./migrations/4.9.6.json \
  --dry-run

# Apply changes
gen-orb-mcp migrate \
  --ci-dir ./.circleci \
  --orb toolkit \
  --rules ./migrations/4.9.6.json

CircleCI Orb

gen-orb-mcp is published as a CircleCI orb at jerus-org/gen-orb-mcp. The orb exposes each subcommand as a reusable job running inside the pre-built Docker image with gen-orb-mcp pre-installed — no manual installation required.

Add to your config

orbs:
  gen-orb-mcp: jerus-org/gen-orb-mcp@0.1.11

Available jobs

Job	Required parameters	Description
`generate`	`orb_path`	Generate an MCP server from an orb YAML file
`validate`	`orb_path`	Validate an orb definition
`diff`	`current`, `previous`, `since_version`	Compute conformance rules between two orb versions
`migrate`	`orb`, `rules`	Apply migration rules to a consumer CI directory
`prime`	—	Populate `prior-versions/` and `migrations/` from git history
`build`	`input`	Compile generated MCP server source to a native binary
`publish`	`binary`, `asset_name`	Upload compiled binary to an existing GitHub release
`save`	`paths`	Stage, commit, and push generated artifacts back to the repo

Example: generate an MCP server from your orb in CI

orbs:
  gen-orb-mcp: jerus-org/gen-orb-mcp@0.1.11

workflows:
  build:
    jobs:
      - gen-orb-mcp/generate:
          orb_path: src/@orb.yml
          output: ./mcp-server
          version: "1.0.0"

Example: complete release pipeline

Generate, compile, upload, and save in one automated workflow:

orbs:
  gen-orb-mcp: jerus-org/gen-orb-mcp@0.1.11

workflows:
  release:
    jobs:
      - gen-orb-mcp/prime:
          orb_path: src/@orb.yml
          earliest_version: "1.0.0"
          ephemeral: true

      - gen-orb-mcp/generate:
          requires: [gen-orb-mcp/prime]
          orb_path: src/@orb.yml
          output: /tmp/mcp-build
          version: "${CIRCLE_TAG#v}"
          migrations: /tmp/gen-orb-mcp-prime/migrations
          prior_versions: /tmp/gen-orb-mcp-prime/prior-versions

      - gen-orb-mcp/build:
          requires: [gen-orb-mcp/generate]
          input: /tmp/mcp-build

      - gen-orb-mcp/publish:
          requires: [gen-orb-mcp/build]
          binary: /tmp/mcp-build/target/release/my_orb_mcp
          asset_name: my-orb-mcp-linux-x86_64
          context: github-release  # must provide GITHUB_TOKEN

      - gen-orb-mcp/save:
          requires: [gen-orb-mcp/generate]
          paths: prior-versions migrations
          context: github-push     # must provide push credentials

save runs in parallel with build (both require generate), so the artifact commit does not block the binary upload.

The orb source is regenerated automatically on every build by gen-circleci-orb, which introspects gen-orb-mcp's --help output and keeps the orb in sync whenever the CLI changes.

CLI Reference

`generate` — Generate an MCP server

gen-orb-mcp generate [OPTIONS] --orb-path <PATH>

Options:
  -p, --orb-path <PATH>          Path to the orb YAML file (e.g. src/@orb.yml)
  -o, --output <DIR>             Output directory [default: ./dist]
  -f, --format <FORMAT>          Output format: source | binary [default: source]
  -n, --name <NAME>              Orb name (defaults to directory/filename)
  -V, --version <VERSION>        Version for the generated crate (e.g. 1.0.0)
      --force                    Overwrite existing output without confirmation
      --migrations <DIR>         Directory of conformance rule JSON files to embed
                                 (enables plan_migration / apply_migration Tools)
      --prior-versions <DIR>     Directory of prior orb YAML snapshots to embed
                                 (files named <version>.yml, e.g. 4.7.1.yml)

`validate` — Validate an orb definition

gen-orb-mcp validate --orb-path <PATH>

`diff` — Compute conformance rules between two orb versions

gen-orb-mcp diff --current <PATH> --previous <PATH> --since-version <VERSION> [--output <FILE>]

Emits a JSON array of ConformanceRule values describing what changed between versions. These rules drive both the migrate CLI command and the MCP Tools in generated servers.

`prime` — Populate prior-versions/ and migrations/ from git history

gen-orb-mcp prime [OPTIONS]

Options:
  -p, --orb-path <PATH>            Path to the orb YAML entry point [default: src/@orb.yml]
      --git-repo <PATH>            Git repository root (default: walk up from orb-path to .git)
      --tag-prefix <PREFIX>        Git tag prefix [default: v]
      --earliest-version <VER>     Fixed anchor (e.g. "4.1.0"); conflicts with --since
      --since <DURATION>           Rolling window (e.g. "6 months") [default when neither set: 6 months]
      --prior-versions-dir <DIR>   Output dir for snapshots [default: prior-versions]
      --migrations-dir <DIR>       Output dir for rule JSON files [default: migrations]
      --ephemeral                  Write to /tmp/gen-orb-mcp-prime-<pid>/ and print
                                   PRIME_PV_DIR=... / PRIME_MIG_DIR=... to stdout
      --dry-run                    Describe actions without writing any files

Discovers all semver tags matching <tag-prefix><version> in the repository, filters to those within the window, and for each version:

Checks out the tag into a temporary git worktree (RAII cleanup, safe on panic)
Saves the parsed orb to prior-versions/<version>.yml
Computes conformance-rule diff vs the previous version, writes migrations/<version>.json (only if diff is non-empty)

Out-of-window snapshots and their matching migration files are removed. Idempotent: existing files are not overwritten.

`migrate` — Apply migration rules to a consumer CI directory

gen-orb-mcp migrate [OPTIONS] --orb <ALIAS> --rules <FILE>

Options:
      --ci-dir <DIR>    Path to consumer .circleci/ directory [default: .circleci]
      --orb <ALIAS>     Orb alias used in the consumer's orbs: section (e.g. toolkit)
      --rules <FILE>    Path to conformance rules JSON (produced by diff)
      --dry-run         Show planned changes without modifying files

`build` — Compile generated MCP server source

gen-orb-mcp build [OPTIONS] --input <DIR>

Options:
  -i, --input <DIR>     Directory containing generated Cargo.toml (required)
  -n, --name <NAME>     Binary name (default: read from Cargo.toml [package] name)
      --target <TRIPLE> Cargo target triple for cross-compilation (optional)
      --dry-run         Print what would run without executing cargo build

Runs cargo build --release inside <input>. On success, prints the path to the compiled binary. The release does not need a pre-existing Rust toolchain beyond what is available in the CI executor.

`publish` — Upload a binary to a GitHub release

gen-orb-mcp publish [OPTIONS] --binary <PATH> --asset-name <NAME>

Options:
  -b, --binary <PATH>       Path to the compiled binary file (required)
  -a, --asset-name <NAME>   Name of the release asset as it appears on GitHub (required)
      --tag <TAG>            Git tag identifying the release [default: $CIRCLE_TAG]
      --dry-run              Print what would be uploaded without calling the API

Prerequisite: the GitHub release must already exist. publish only adds an asset — it does not create the release. Environment variables read at runtime:

Variable	Purpose
`GITHUB_TOKEN`	Personal access token with `contents: write`
`CIRCLE_PROJECT_USERNAME`	Repository owner
`CIRCLE_PROJECT_REPONAME`	Repository name
`CIRCLE_TAG`	Tag used to locate the release (overridden by `--tag`)

`save` — Stage, commit, and push generated artifacts

gen-orb-mcp save [OPTIONS] <PATHS>...

Arguments:
  <PATHS>...   Paths to stage (files or directories)

Options:
  -m, --message <MSG>   Commit message [default: "chore: update generated MCP server artifacts [skip ci]"]
      --push            Push to origin after committing [default: true]
      --no-push         Skip the push step
      --dry-run         Stage and diff without creating a commit

Idempotent: if the working tree is clean after staging all paths (no changes), save exits 0 without creating a commit. The default commit message includes [skip ci] to prevent CI from triggering a new pipeline on the generated artifact commit.

How Generated MCP Servers Work

Resources

The generated server exposes the following MCP Resources:

URI pattern	Content
`orb://overview`	Full markdown documentation of the orb
`orb://commands/{name}`	JSON definition of a command
`orb://jobs/{name}`	JSON definition of a job
`orb://executors/{name}`	JSON definition of an executor
`orb://versions`	List of all embedded versions (when prior versions are present)
`orb://v{version}/commands/{name}`	Command definition for a prior version
`orb://v{version}/jobs/{name}`	Job definition for a prior version
`orb://v{version}/executors/{name}`	Executor definition for a prior version

Tools (when `--migrations` is provided)

Tool	Description
`plan_migration`	Analyse a consumer `.circleci/` directory and return a summary of changes needed
`apply_migration`	Apply the migration plan; pass `dry_run: true` to preview without writing

Both tools accept ci_dir (path to the consumer's .circleci/ directory) and orb_alias (the alias used in the consumer's orbs: section). apply_migration also accepts dry_run (boolean, default false).

Using with Claude Code

Add the generated binary to your claude_desktop_config.json (or .claude.json):

{
  "mcpServers": {
    "circleci-toolkit": {
      "command": "/path/to/circleci_toolkit_mcp"
    }
  }
}

Once connected, Claude Code can answer questions about your private orb and guide migrations interactively.

Migration Design

Migrations are conformance-based, not path-dependent. The diff command computes what the target version's contract requires, regardless of which intermediate versions a consumer has skipped. The migrate command (and the embedded Tools) then inspect the consumer's actual CI state and fix all non-conformant patterns in one pass.

This means migrating from v4.7.0 directly to v5.0.0 is handled correctly even if v4.8.0 through v4.11.0 were never used.

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing Guide

gen-orb-mcp 0.1.23