archmcp

archmcp provides a pre-generated architectural snapshot of your codebase to feed MCP-enabled AI agents. It analyzes repositories to produce structured context including modules, symbols, dependencies, routes, and architectural patterns. Once a snapshot exists, your MCP client (such as Cursor, Claude Code, Copilot, or any MCP-compatible tool) can access the architectural context via the arch://snapshot/context resource and use on-demand tools to query facts, regenerate snapshots when the codebase changes, and reason about architecture before delving into file contents. The server is designed to run locally and be invoked once per repository (or per multi-repo bundle) to create a compact summary that accelerates subsequent AI-assisted exploration.

Prerequisites:

• Go 1.22+ installed on your machine
• A Go-enabled environment (for building or installing the binary)

Install and build from source:

# (optional) clone the repository
# git clone https://github.com/your-org/archmcp.git
# cd archmcp

# Build the archmcp binary
go build -o archmcp ./cmd/archmcp

Or install globally if you have Go modules workspace configured:

go install ./cmd/archmcp

Run or connect to the MCP server:

• Build output will produce an executable named archmcp. You can run it directly or connect via an MCP client by configuring mcpServers with the appropriate command and optional config path
• Example run (one-shot snapshot via CLI):

# Generate a snapshot for a project (default config path if not provided)
archmcp --generate mcp-arch.yaml

Configuration example for an MCP client:

{
  "mcpServers": {
    "archmcp": {
      "command": "/path/to/archmcp",
      "args": ["/path/to/mcp-arch.yaml"]
    }
  }
}

Tips and considerations:

• Regenerate snapshots after significant code changes to keep context fresh for the AI agent.
• Use the MCP client’s query_facts tool to precisely retrieve interfaces, imports, or call sites filtered by your needs.
• The generated snapshot is intended as upfront context and is not a replacement for running grep, file searches, or actual code reading when needed.
• For multi-repo setups, archmcp supports append mode to combine snapshots across repositories for cross-repo analysis.