code-analyze-mcp

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, Kotlin, 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.

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

Two transports are available. Streamable HTTP is recommended when using orchestrators that spawn delegates (e.g. goose coder): a single server process is shared across the orchestrator and all agents, eliminating extension-drift that occurs when each stdio subprocess gets its own isolated instance.

Streamable HTTP (recommended for multi-agent setups)

With Homebrew, one command starts the server on login and keeps it running:

brew services start aptu-coder

The Homebrew formula starts the server on port 49200 by default. Then add the extension once to ~/.config/goose/config.yaml:

extensions:
  aptu-coder:
    type: streamable_http
    uri: http://127.0.0.1:49200/mcp
    name: aptu-coder
    timeout: 300

Or for Claude Code:

claude mcp add --transport http aptu-coder http://127.0.0.1:49200/mcp

To use a different port, set APTU_CODER_PORT before restarting:

APTU_CODER_PORT=4000 brew services restart aptu-coder

To start directly without brew services:

aptu-coder --port 49200
# or equivalently
APTU_CODER_PORT=49200 aptu-coder

stdio (single-client use)

Suitable when only one process needs the server. The client owns the process lifecycle and spawns it automatically:

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

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:

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

Output Management

For large codebases, several 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==

exec_command output caps

exec_command applies three independent byte-level caps to prevent large command outputs from flooding the context:

The 30k stdout cap is data-driven: analysis of 27,981 observed exec_command calls shows only 0.33% exceed this limit. When any cap fires, output_truncated: true is set in the response and recorded in the JSONL metrics.

exec_command output filters

A built-in filter table suppresses per-file noise from chatty CLI tools before output reaches the model. Filters apply on success only; raw output is always preserved on failure.

Project-local rules can be added in .aptu/filters.toml. Parse errors fall back to the built-in table (no crash). When a filter fires, filter_applied in structuredContent identifies which rule matched.

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

Cache and runtime

Telemetry

Observability

The server emits two parallel, independent telemetry streams.

JSONL metrics (always-on) are written daily-rotated to $XDG_DATA_HOME/aptu-coder/ (fallback: ~/.local/share/aptu-coder/) regardless of configuration. 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.

OpenTelemetry export (opt-in) is enabled when OTEL_EXPORTER_OTLP_ENDPOINT is set to an OTLP HTTP endpoint URL. When set, the server initializes OpenTelemetry trace, log, and meter providers and exports asynchronously via OTLP/HTTP. When unset, noop providers are used with zero runtime overhead.

Each tool invocation is wrapped in a span carrying OpenTelemetry GenAI semantic attributes (gen_ai.system, gen_ai.operation.name, gen_ai.tool.name). W3C Trace Context is extracted from the MCP _meta field on each call, allowing MCP clients to propagate their trace context so tool spans appear as children in a distributed trace.

For the span attribute policy, the never-record list, and details on what is instrumented, see OBSERVABILITY.md at the repository root.

Documentation

• AGENTS.md - Contributor reference: project structure, commands, rmcp footguns, tool parameter constraints

• ARCHITECTURE.md - Design goals, module map, data flow, language handler system, caching strategy

• CONTRIBUTING.md - Development workflow, commit conventions, PR checklist

• DESIGN-GUIDE.md - Design decisions, rationale, and replication guide for building high-performance MCP servers

• 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

• SECURITY.md - Security policy and vulnerability reporting

License

Apache-2.0. See LICENSE for details.