Skip to main content
Glama
octopilot-mcp

octopilot-mcp

Official
by octopilot

octopilot-mcp

License

Model Context Protocol (MCP) server for Octopilot — enables AI agents to detect, generate, build, and wire up new repositories end-to-end using the Octopilot CI/CD toolchain.

What it does

Tool

Description

detect_project_contexts

Parse skaffold.yaml → pipeline-context JSON (languages, versions, matrix)

generate_skaffold_yaml

Generate a skaffold.yaml for given artifacts

generate_ci_workflow

Full .github/workflows/ci.yml using the standard octopilot pipeline

onboard_repository

One-call onboarding: detect → generate files → return next steps

run_op_build

Run op build via local binary or ghcr.io/octopilot/op container

list_actions

All Octopilot GitHub Actions from the bundled registry

get_action_details

Full spec, inputs, examples, gotchas for one action

op promote-image is intentionally not exposed. Image promotion between environments is operationally sensitive and must only run through a GitHub Actions workflow (with audit trail, OIDC credentials, and environment protection rules). Use generate_ci_workflow to produce the workflow that handles promotion safely.

Related MCP server: @lex-tools/codebase-context-dumper

Option A — Hosted (zero install)

Connect directly to the public server at https://mcp.octopilot.app — no cloning, no Python, no pip required.

# Cursor
fastmcp install cursor https://mcp.octopilot.app --name octopilot

# Claude Desktop
fastmcp install claude https://mcp.octopilot.app --name octopilot

Available hosted tools (stateless, no local dependencies):

Tool

Description

list_actions

Browse the Octopilot GitHub Actions registry

get_action_details

Full spec, inputs, examples, gotchas for one action

generate_skaffold_yaml

Generate a skaffold.yaml for given artifacts

generate_ci_workflow

Full .github/workflows/ci.yml for a project

Need detect_project_contexts, onboard_repository, or run_op_build? Those tools need Docker and local filesystem access — use Option B below.


Option B — Local install (full suite)

# Clone and install
git clone https://github.com/octopilot/octopilot-mcp
cd octopilot-mcp
uv sync

Usage

Register with your IDE (one command, FastMCP 3 CLI)

Docker or Colima is the only external dependency. Most tools are pure Python; run_op_build pulls ghcr.io/octopilot/op:latest automatically with --pull always, so you always run the latest release.

# Cursor
uv run fastmcp install cursor src/octopilot_mcp/server.py --name octopilot

# Claude Desktop
uv run fastmcp install claude src/octopilot_mcp/server.py --name octopilot

Development (hot-reload)

uv run fastmcp dev src/octopilot_mcp/server.py --reload

Inspect tools from the terminal

# List all available tools
uv run fastmcp list src/octopilot_mcp/server.py

# Call a tool directly
uv run fastmcp call src/octopilot_mcp/server.py tool_list_actions

Run as a server directly

uv run octopilot-mcp

Manual JSON config (alternative to fastmcp install)

{
  "mcpServers": {
    "octopilot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/octopilot-mcp", "octopilot-mcp"]
    }
  }
}

Pin to a specific op release (optional):

{
  "mcpServers": {
    "octopilot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/octopilot-mcp", "octopilot-mcp"],
      "env": { "OP_IMAGE": "ghcr.io/octopilot/op:v1.0.0" }
    }
  }
}

Environment variables

Variable

Default

Description

OP_IMAGE

ghcr.io/octopilot/op:latest

Pin to a specific op release for reproducibility

Example agent interaction

User: Onboard this Rust API project to use Octopilot CI.

Agent: [calls onboard_repository("/path/to/my-api", "ghcr.io/my-org")]
       → Detected: rust (stable) in api/
       → Generated: skaffold.yaml, .github/workflows/ci.yml
       → Next steps: add .pre-commit-config.yaml, push changes

Development

uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src/octopilot_mcp --cov-report=term-missing

Tool module coverage target: ≥95% (actions, detect, generate, op_runner). See CONTRIBUTING.md for details.

Resources

The server also exposes MCP resources for agent context:

  • octopilot://actions — Full actions registry JSON

  • octopilot://pipeline-context-schema — JSON Schema for pipeline-context

  • octopilot://docs/getting-started — Plain-text onboarding guide

  • octopilot://docs/skaffold-patterns — Common skaffold.yaml patterns

Available Tools

7 tools
tool_detect_project_contextsA

Parse skaffold.yaml in the workspace and return a pipeline-context JSON object.

The pipeline-context is consumed by lint, test, janitor, and ci workflow generation. It contains the detected languages, versions, and build matrix.

Inputs: workspace (required). Returns: object

tool_generate_ci_workflowB

Generate a complete .github/workflows/ci.yml for the repository.

Inputs: registry (required), pipeline_context (required), platforms, golangci_lint_timeout. Returns: result

tool_generate_skaffold_yamlB

Generate a skaffold.yaml for the given build artifacts.

Inputs: artifacts (required), builder. Returns: result

tool_get_action_detailsA

Return the full spec for a single Octopilot GitHub Action.

Includes: description, all inputs/outputs, example workflow YAML, and known gotchas with symptoms and fixes.

Inputs: action_id (required). Returns: result

tool_list_actionsA

Return all Octopilot GitHub Actions from the bundled registry.

Each entry includes: id, title, path, description, features, inputs, outputs. Use get_action_details for examples and gotchas.

Inputs: no named parameters. Returns: result

tool_onboard_repositoryA

Onboard a repository end-to-end in a single call.

Detects the project languages, generates skaffold.yaml (if missing) and .github/workflows/ci.yml, and returns a ready-to-commit file set plus a checklist of remaining manual steps.

Inputs: registry (required), workspace (required), builder, platforms. Returns: object

tool_run_op_buildA

Run op build in the workspace using the official op container.

Docker or Colima must be running. The container image is always pulled before each run so the latest op release is used automatically. Set OP_IMAGE in the MCP server env to pin to a specific version.

Inputs: registry (required), workspace (required), push, platforms. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: project detection, CI workflow generation, skaffold generation, action details, action listing, full onboarding, and running builds. There is no functional overlap.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., detect_project_contexts, generate_ci_workflow, list_actions). The naming is predictable and clear.

    Tool Count5/5

    With 7 tools, the set is well-scoped for the domain of CI/CD pipeline management and onboarding. Each tool has a clear purpose and contributes to the overall workflow.

    Completeness4/5

    The tool surface covers core workflows: detection, generation, action interaction, onboarding, and building. Minor gaps exist (e.g., no tool for updating existing configurations or tear-down), but the main use cases are addressed.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers