mcp-server

ACF MCP Server

An MCP (Model Context Protocol) server that exposes the ACF (Agent Context Forge) pipeline as tools to any MCP-compatible agent — including agents that do not support the SKILL.md skill format, such as GitHub Copilot, Aider, Continue, Zed, and others.

This lets agents that speak MCP but don't load agent skills still use ACF's context-loading, stack-auditing, issue/PR crafting, and context-compaction capabilities.

Why

ACF ships as a set of Markdown skill files (SKILL.md) that agents like Claude Code, Cursor, Codex CLI, OpenCode, and Devin load natively. Agents without a skill loader can't consume them. The MCP server bridges that gap: it wraps the same pipeline logic behind standard MCP tools reachable over stdio by any MCP client.

Tools

Tool	ACF phase	What it does
acf_graph_scope	Phase 0	Decompose a project into a dependency graph; compute blast radius + context scope for a target file
acf_context_load	Phase 1	Load project context from a path and return a compressed snapshot (architecture, tests, CI, conventions)
acf_stack_audit	Phase 2	Audit a GitHub repo's open stack: orphan PRs, stale issues, close gaps (uses gh CLI)
acf_issue_craft	Phase 3	Craft a context-rich issue with labels, acceptance criteria, test/CI references; optionally create it
acf_pr_context	Phase 4	Build a PR body carrying the issue's AC, test commands, CI checks, and scope lock; optionally create it
acf_compact	Phase 7	Compact a context snapshot (Kimi-inspired: head+tail preservation, elision markers)
acf_caveman	Phase 8	Extreme compression to <500 tokens (bare paths, counts, labels, commands); bare=true for ~100-token last resort

Requirements

• Python 3.9+ (uses only the standard library — zero pip dependencies)
• gh CLI — for acf_stack_audit, acf_issue_craft (create), and acf_pr_context (create). Not required for the read-only tools.
• git — optional, used by acf_context_load to detect the current branch

Installation

From source (editable)

cd mcp-server
pip install -e .

This installs the acf-mcp console script.

Run directly (no install)

python -m acf_mcp.server

With uv

cd mcp-server
uv run acf-mcp

Usage

The server speaks MCP over stdio (JSON-RPC 2.0). Start it from your MCP client's config; you don't run it manually in normal use.

Claude Desktop / Claude Code

Add to claude_desktop_config.json (or .mcp.json):

{
  "mcpServers": {
    "acf": {
      "command": "acf-mcp",
      "args": []
    }
  }
}

Continue / Zed / other MCP clients

Point the client at the server command. Examples:

{ "command": "acf-mcp" }

or if running from source without installing:

{ "command": "python", "args": ["-m", "acf_mcp.server"], "cwd": "/path/to/contextforge/mcp-server" }

Manual protocol test

You can drive the server by piping JSON-RPC messages on stdin:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | acf-mcp

Architecture

mcp-server/
├── pyproject.toml          # package metadata + console script (zero deps)
├── README.md               # this file
├── acf_mcp/
│   ├── __init__.py
│   ├── server.py           # JSON-RPC 2.0 over stdio, tool registry, dispatch
│   └── tools.py            # the 7 ACF tool implementations
└── tests/
    ├── __init__.py
    ├── test_server.py      # protocol + registry tests
    └── test_tools.py       # tool logic tests (no network)

The server is a thin wrapper that implements the ACF phase logic directly in Python (graph building, snapshot extraction, compaction, caveman) and delegates GitHub operations to the gh CLI. It does not modify or depend on the skills/ directory — the skill Markdown remains the source of truth for agents that support it; the MCP server is a parallel interface.

Token budgets

Mode	Tool	Target	Notes
Full	acf_context_load	~2000	Default snapshot
Compacted	acf_compact	~800	Head+tail preservation, elision markers
Caveman	acf_caveman	<500	No prose, symbols over words
Bare caveman	acf_caveman (bare=true)	~100	Only NOW + NEXT + TESTS + CI

Tests

cd mcp-server
pip install -e ".[dev]"
pytest

Or without pytest:

python -m pytest tests/

License

MIT — same as the ACF project.