acp-mcp

Python package manager and MCP server for Agent Context Protocol (ACP) projects.

What this provides

Substrate operations for ACP projects, available as both CLI commands and MCP tools:

• Project bootstrap: acp init — scaffold a new ACP project from agent-context-protocol's latest templates
• Version management: check and refresh a project's ACP methodology version against agent-context-protocol mainline
• Package management: list, install, update, remove ACP packages from git repositories
• Discovery: enumerate available commands, patterns, designs, and specs across global (~/.acp/agent/) and project (./agent/) contexts

What this does NOT provide

Workflow commands like @acp.proceed, @acp.status, @acp.task-create, etc. remain as markdown directives in agent/commands/. Agents read those files directly — they are intentionally not exposed as CLI or MCP tools. acp-mcp is the substrate; the workflow is the markdown.

Installation

uv tool install agent-context-mcp

This registers:

• CLI command: acp
• MCP server: agent-context-mcp (auto-discovered by Claude Code and compatible MCP clients)

Requirements: git must be installed and on PATH (required by acp init and acp version update).

Usage

CLI

# Bootstrap a new ACP project in the current directory
# Fetches latest templates from agent-context-protocol (GitHub)
acp init .

# Show the project's ACP methodology version
acp version show

# Check if project is behind agent-context-protocol mainline
acp version check

# Refresh the project's ACP templates from agent-context-protocol mainline
# (Only updates templates; your design docs, tasks, milestones are preserved)
acp version update

# Search the ACP package registry
acp package search acp

# Install an ACP package
acp package install https://github.com/user/acp-firebase.git

# List installed packages
acp package list

# Show project status (current milestone, task summary, next task)
acp status

# List all tasks (optionally filter by milestone or status)
acp status --tasks
acp status --tasks --milestone M5
acp status --tasks --status pending

# Show milestone details
acp status --milestone M5

MCP

Once installed via uv tool install, the MCP server is discoverable by your agent runtime. Tools available:

• acp_init(path, force, branch) — bootstrap a new ACP project from templates
• acp_package(action, ...) — package search, install, update, remove, list, info
• acp_version(action) — version management (show/check/update)
• acp_enumerate(scope, kind) — discovery with rich @scry.entry marker metadata
• acp_status(action, project, milestone, status_filter) — structured project status: current milestone, task counts, next actionable task, driver binding info. The fast orientation call for autonomous agent runs.

Note: The PyPI package name is agent-context-mcp (not acp-mcp, which is a different unrelated package by IBM Corp). The CLI binary is still acp.

How acp init works

acp init . performs a shallow git clone of agent-context-protocol to a temp directory, copies the relevant template files into the target project, then cleans up the clone.

What gets copied:

• AGENT.md — ACP methodology documentation
• agent/commands/ — all workflow command files (acp.proceed.md, acp.plan.md, acp.task-create.md, etc.)
• agent/design/ — *.template.md files only
• agent/patterns/, agent/milestones/, agent/tasks/, agent/specs/ — *.template.md files only
• agent/schemas/ — all schema files
• agent/progress.template.yaml — progress tracking template
• agent/progress.yaml — generated fresh with project name and start date
• .gitignore — ACP-recommended gitignore

What is NOT copied: bash scripts (agent/scripts/), reports, clarifications, feedback, drafts, project-specific files.

Templates live in agent-context-protocol's GitHub repo — not bundled with this wheel. This means template fixes and new commands flow to users via acp version update, not via acp-mcp releases.

Runtime-fetch model

acp-mcp does not bundle templates. Instead, acp init and acp version update clone agent-context-protocol/mainline at runtime. This decouples template evolution from acp-mcp release cadence — a typo fix in acp.proceed.md doesn't require a new acp-mcp release.

This mirrors the bash install path (acp.install.sh also curls from GitHub at runtime).

Status

See CHANGELOG.md for shipped features and version history.

License

MIT