Aptu Coder

[!NOTE] Native agent tools (regex search, path matching, file reading) handle targeted lookups well. aptu-coder handles the mechanical, non-AI work: mapping directory structure, extracting symbols, and tracing call graphs. Offloading this to a dedicated tool reduces token usage and speeds up coding with better accuracy.

Benchmarks

Auth migration task on Claude Code against Django (Python) source tree. Full methodology.

AeroDyn integration audit task on Claude Code against OpenFAST (Fortran) source tree. Full methodology.

Overview

aptu-coder is a Model Context Protocol server that gives AI agents precise structural context about a codebase: directory trees, symbol definitions, and call graphs, without reading raw files. It supports Rust, Python, Go, Java, TypeScript, TSX, Fortran, JavaScript, C/C++, and C#, and integrates with any MCP-compatible orchestrator.

Supported Languages

All languages are enabled by default. Disable individual languages at compile time via Cargo feature flags.

To build with a subset of languages, disable default features and opt in:

[dependencies]
aptu-coder-core = { version = "*", default-features = false, features = ["lang-rust", "lang-python"] }

The current version is published on crates.io. Replace "*" with the latest version string if you prefer a pinned dependency.

Installation

Homebrew (macOS and Linux)

brew install clouatre-labs/tap/aptu-coder

Update: brew upgrade aptu-coder

cargo-binstall (no Rust required)

cargo binstall aptu-coder

cargo install (requires Rust toolchain)

cargo install aptu-coder

Quick Start

Build from source

cargo build --release

The binary is at target/release/aptu-coder.

Configure MCP Client

After installation via brew or cargo, register with the Claude Code CLI:

claude mcp add --transport stdio aptu-coder -- aptu-coder

If you built from source, use the binary path directly:

claude mcp add --transport stdio aptu-coder -- /path/to/repo/target/release/aptu-coder

stdio is intentional: this server runs locally and processes files directly on disk. The low-latency, zero-network-overhead transport matches the use case. Streamable HTTP adds a network hop with no benefit for a local tool.

Or add manually to .mcp.json at your project root (shared with your team via version control):

{
  "mcpServers": {
    "aptu-coder": {
      "command": "aptu-coder",
      "args": []
    }
  }
}

Tools

All optional parameters may be omitted. Shared optional parameters for analyze_directory, analyze_file, and analyze_symbol:

summary=true and cursor are mutually exclusive. Passing both returns an error.

Tool parameters, constraints, and examples are available via your MCP client's tool inspector or tools/list response.

Output Management

For large codebases, two mechanisms prevent context overflow:

Pagination

analyze_file and analyze_symbol append a NEXT_CURSOR: line when output is truncated. Pass the token back as cursor to fetch the next page. summary=true and cursor are mutually exclusive; passing both returns an error.

# Response ends with:
NEXT_CURSOR: eyJvZmZzZXQiOjUwfQ==

# Fetch next page:
analyze_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ==

Summary Mode

When output exceeds 50K chars, the server auto-compacts results using aggregate statistics. Override with summary: true (force compact) or summary: false (disable).

# Force summary for large project
analyze_directory path: /huge/codebase summary: true

# Disable summary (get full details, may be large)
analyze_directory path: /project summary: false

Non-Interactive Pipelines

In single-pass subagent sessions, prompt caches are written but never reused. Benchmarks showed MCP responses writing ~2x more to cache than native-only workflows, adding cost with no quality gain. Set DISABLE_PROMPT_CACHING=1 (or DISABLE_PROMPT_CACHING_HAIKU=1 for Haiku-specific pipelines) to avoid this overhead.

The server's own instructions expose a 4-step recommended workflow for unknown repositories: survey the repo root with analyze_directory at max_depth=2, drill into the source package, run analyze_module on key files for a function/import index (or analyze_file when signatures and types are needed), then use analyze_symbol to trace call graphs. MCP clients that surface server instructions will present this workflow automatically to the agent.

Environment Variables

Observability

All seven tools emit metrics to daily-rotated JSONL files at $XDG_DATA_HOME/aptu-coder/ (fallback: ~/.local/share/aptu-coder/). Each record captures tool name, duration, output size, and result status. Files are retained for 30 days. See docs/OBSERVABILITY.md for the full schema.

Documentation

• ARCHITECTURE.md - Design goals, module map, data flow, language handler system, caching strategy
• MCP Best Practices - Best practices for agentic loops, orchestration patterns, MCP tool design, memory management, and safety controls
• OBSERVABILITY.md - Metrics schema, JSONL format, and retention policy
• ROADMAP.md - Development history and future direction
• DESIGN-GUIDE.md - Design decisions, rationale, and replication guide for building high-performance MCP servers
• CONTRIBUTING.md - Development workflow, commit conventions, PR checklist
• SECURITY.md - Security policy and vulnerability reporting

License

Apache-2.0. See LICENSE for details.