Skip to main content
Glama
octopilot

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceYesAbsolute path to the repository root (must contain skaffold.yaml).

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility for behavioral disclosure. It only states the tool parses a file and returns JSON, but omits critical details such as side effects (none implied), error handling for missing or malformed skaffold.yaml, and any permissions required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no redundancy. The first sentence states the core action, and the second adds valuable context about consumption. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description does not need to detail return values. However, it could be improved by noting prerequisites (e.g., file existence) or edge cases. Overall, it is sufficient for a simple parsing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single parameter 'workspace' is already well documented in the input schema. The description adds no extra semantic information beyond the schema, earning the baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Parse') and resource ('skaffold.yaml'), clearly stating the tool's action and output. It distinguishes itself from sibling tools like tool_generate_ci_workflow and tool_generate_skaffold_yaml by focusing on parsing an existing file rather than generating or modifying.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the downstream use of the output ('consumed by lint, test, janitor, and ci workflow generation'), indicating when the tool is typically invoked. However, it does not explicitly state when to avoid using it or provide alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_generate_ci_workflowB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
registryYesTarget container registry and org, e.g. "ghcr.io/my-org".
platformsNoComma-separated platform list (default: linux/amd64,linux/arm64).linux/amd64,linux/arm64
pipeline_contextYesOutput from detect_project_contexts().
golangci_lint_timeoutNoTimeout for golangci-lint; increase for large vendor trees.10m

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description does not disclose behavioral traits such as whether the tool overwrites existing files, requires authentication, or has side effects, leaving the agent unaware of important constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that is front-loaded, but it could benefit from a structured list or additional context that earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema and a nested object parameter, the description does not explain what the generated workflow contains, nor does it mention that the file will be created or overwritten, which is critical for a generation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Generate' and the specific resource '.github/workflows/ci.yml', and it distinguishes from sibling tools like tool_generate_skaffold_yaml which targets a different output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor are any prerequisites, exclusions, or when-not-to-use conditions mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_generate_skaffold_yamlB

Generate a skaffold.yaml for the given build artifacts.

ParametersJSON Schema
NameRequiredDescriptionDefault
builderNoCloud Native Buildpack builder image to use.ghcr.io/octopilot/builder-jammy-base:latest
artifactsYesList of {"name": str, "context": str} dicts. 'name' is the image name; 'context' is the relative path to the source.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only says 'generate' without specifying if it overwrites, requires existing files, or any side effects. Behavioral traits are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, no waste, and front-loaded. Could include more detail without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema and two parameters, the description is minimal. It doesn't explain the output or any behavior. Not complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description repeats 'given build artifacts' but adds no extra meaning beyond the schema's descriptions for 'builder' and 'artifacts'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a skaffold.yaml for build artifacts. It is specific and distinct from sibling tools like tool_generate_ci_workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives, or any prerequisites or exclusions. The description is silent on context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
action_idYesAction identifier, e.g. "octopilot", "lint", "test", "janitor", "detect-contexts", "release", "sops-decrypt", "setup-tools", "rotate-secret", "kubernetes-auth", "gke-allow-runner", "eks-allow-runner", "aks-allow-runner".

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It lists what the return includes but does not disclose behavioral traits like read-only nature, authentication needs, or side effects. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and every sentence adds value. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (1 param, has output schema), the description is adequate and covers the essential return content. Could mention return format or when the action_id is invalid, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter (action_id) well-described. The description adds no further semantic value beyond the schema, meeting the baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the full spec for a single Octopilot GitHub Action, with specific content. It distinguishes from siblings like tool_list_actions by focusing on a single action's details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when needing detailed info on a specific action but does not provide explicit when-to-use, when-not-to-use, or alternatives. Siblings exist (e.g., tool_list_actions) but no guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the return structure but does not mention potential side effects, authentication, or rate limits. However, as a read-only list operation, this is sufficient for behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the main purpose, and includes necessary details without any fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list operation with no parameters and an existing output schema, the description completely covers the tool's behavior, including what each returned entry contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema description coverage is 100% (trivially). The description adds value by detailing the return fields, which goes beyond the empty input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns all Octopilot GitHub Actions from the bundled registry, listing the fields included. It distinguishes itself from sibling tool get_action_details by directing users there for examples and gotchas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance to use get_action_details for examples and gotchas, indicating when to choose an alternative. It does not specify when not to use this tool, but the context is clear for a listing operation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
builderNoBuildpack builder image.ghcr.io/octopilot/builder-jammy-base:latest
registryYesContainer registry and org, e.g. "ghcr.io/my-org".
platformsNoTarget build platforms.linux/amd64,linux/arm64
workspaceYesAbsolute path to the repository root.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It mentions returning a file set and checklist but lacks details on side effects (e.g., does it write to disk?), required permissions, or error conditions. More transparency is needed for a mutation-like operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences. The first sentence states the high-level purpose, and the second adds specific actions and outputs. No redundancy or unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of end-to-end onboarding and the presence of an output schema, the description covers key actions and outputs but omits prerequisites, error scenarios, and details about what is included in the returned file set. It is adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100%, with each parameter having a description. The tool description adds no additional information beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Onboard a repository end-to-end in a single call.' It lists specific actions (detects languages, generates skaffold.yaml and CI workflow) and outputs, distinguishing it from sibling tools like tool_generate_ci_workflow and tool_generate_skaffold_yaml by being a composite operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies 'end-to-end' usage but does not explicitly state when to use this tool versus the more granular sibling tools. No guidance is given on prerequisites or when not to use it, leaving the agent to infer from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pushNoIf True, push images to the registry after building.
registryYesTarget registry/org, e.g. "ghcr.io/my-org".
platformsNoComma-separated platform list.linux/amd64
workspaceYesAbsolute path to the repository root (must contain skaffold.yaml).

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that Docker/Colima must be running, the image is pulled each run, and OP_IMAGE can pin a version. However, it does not mention that the workspace must contain skaffold.yaml (implied by schema but not in description), nor what the tool modifies or creates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: first states the core action, second adds prerequisite, third adds configuration. No superfluous words, front-loaded with the primary purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the basic usage and prerequisites. However, it fails to mention that the workspace must contain skaffold.yaml (a required file per the schema description for workspace). Given that an output schema exists, return values are not needed, but the missing prerequisite is a notable gap for a build tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All four parameters are fully described in the input schema (100% coverage), so the description adds no additional semantic value beyond what the schema already provides. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs 'op build' in the workspace using the official op container. The verb 'run' and resource 'op build' are specific, and it distinguishes from sibling tools which are about detection, CI generation, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: Docker or Colima must be running, and the container image is always pulled. However, it does not explicitly state when not to use this tool or mention alternatives, though siblings are for different tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 7 tool updatesv0.1.0
    • First observedtool_detect_project_contexts
    • First observedtool_generate_ci_workflow
    • First observedtool_generate_skaffold_yaml
    • First observedtool_get_action_details
    • First observedtool_list_actions
    • First observedtool_onboard_repository
    • First observedtool_run_op_build

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
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers