convez.ai
MCP ServerProdutividadeIntermediário
clouatre-labs

aptu-coder

clouatre-labs/aptu-coder

Análise estrutural de código com tree-sitter para reduzir tokens em agentes IA

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server especializado em análise estrutural de código via tree-sitter, extraindo árvores de diretórios, definições de símbolos e grafos de chamadas sem ler arquivos brutos. Reduz consumo de tokens em 46-68% comparado a análise nativa, com suporte a 12+ linguagens (Rust, Python, Go, Java, TypeScript, Fortran, etc).

Instalação

$npx convez-ai clouatre-labs/aptu-coder

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
2
Acompanhando
0
Saúde
87%
Último commit
há 2 dias
Versão
v0.46.0
Issues abertas
5
Contribuidores
4

Casos de uso

  • Mapeamento de estrutura de diretórios e símbolos em bases de código grandes
  • Rastreamento de grafos de chamadas para auditorias de integração e refatoração
  • Análise de migrações de código reduzindo custo de tokens do modelo

Veredito

Ferramenta sólida e bem certificada (OpenSSF silver) para contexto estrutural eficiente em agentes. Ideal para projetos com codebases grandes onde redução de tokens é crítica; overhead de instalação MCP vale a pena em uso intensivo.

README

A tradução para o português deste README ainda está na fila.

[!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.

ModeSonnet 4.6Haiku 4.5
MCP112k tokens, $0.39406k tokens, $0.42
Native276k tokens, $0.95473k tokens, $0.53
Savings59% fewer tokens, 59% cheaper14% fewer tokens, 21% cheaper

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

ModeSonnet 4.6Haiku 4.5
MCP472k tokens, $1.65687k tokens, $0.72
Native877k tokens, $2.852162k tokens, $2.21
Savings46% fewer tokens, 42% cheaper68% fewer tokens, 68% cheaper

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.

LanguageExtensionsFeature flag
Rust.rslang-rust
Python.pylang-python
TypeScript.tslang-typescript
TSX.tsxlang-tsx
Go.golang-go
Java.javalang-java
Kotlin.kt, .ktslang-kotlin
Fortran.f, .f77, .f90, .f95, .f03, .f08, .for, .ftnlang-fortran
JavaScript.js, .mjs, .cjslang-javascript
C/C++.c, .cc, .cpp, .cxx, .h, .hpp, .hxxlang-cpp
C#.cslang-csharp
Markdown.md, .mdxlang-markdown
HTML.html, .htmlang-html (stub; no extraction)

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:

ParameterTypeDefaultDescription
summarybooleanautoCompact output; auto-triggers above 50K chars
cursorstring--Pagination cursor from a previous response's next_cursor
page_sizeinteger100Items per page
forcebooleanfalseBypass output size warning
verbosebooleanfalseFull output with section headers and imports
ToolPurposeLanguages
analyze_directoryDirectory tree with LOC, function, and class counts; respects .gitignoreall
analyze_fileFunctions, classes, and imports with signatures and line ranges; returns graceful fallback (line count, file head, no AST) for unsupported extensionsall
analyze_moduleLightweight function and import index (~75% smaller than analyze_file); returns INVALID_PARAMS for unsupported extensionsall
analyze_symbolCall graph for a named symbol across a directory; callers, callees, call depthall
edit_overwriteCreate or overwrite a file; creates parent directoriesany file
edit_replaceReplace a unique exact text block; errors if zero or multiple matchesall
exec_commandRun a shell command; returns stdout, stderr, exit code, and timeout status; supports progress notifications; output capped and filtered automaticallyany

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:

StreamCapBehavior
stdout30,000 charsTail-preserving; keeps the last 30k chars
stderr10,000 charsTail-preserving; errors appear at the end
combined output_text50,000 charsSafety net after interleaving

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 to stdout, stderr, and interleaved output on success only; raw output is always preserved on failure.

CommandBehavior
git pullStrips diff-stat noise (pipe bars, create mode, delete mode, rename, mode change lines); empty output replaced with ok (up-to-date)
git fetchStrips From and ref-range lines; caps at 10 lines; empty output replaced with ok fetched
git pushStrips remote: progress lines and To destination lines; caps at 10 lines; empty output replaced with ok pushed
git logCaps at 20 lines
git statusCaps at 20 lines
git showStrips patch hunks (@@ headers and +/- diff lines); caps at 200 lines
git commitStrips GPG signing and gitleaks hook output; caps at 10 lines; empty output replaced with ok committed
git diffStrips ANSI escape sequences; caps at 100 lines; empty output replaced with ok (working tree clean)
git addStrips gitleaks hook output; caps at 5 lines; empty output replaced with ok staged
cargo buildStrips Compiling / Checking / Downloading / Fresh lines; empty output replaced with ok (build clean)
cargo testStrips Compiling / Checking / Fresh lines

Project-local rules can be added in .aptu/filters.toml. Parse errors and unrecognized schema_version values (version != 1) fall back to the built-in table with a logged warning; no crash occurs. 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

VariableDefaultDescription
APTU_CODER_DIR_CACHE_CAPACITY20LRU cache size for directory-analysis results.
APTU_CODER_PORTunsetPort for streamable HTTP mode. Equivalent to --port N; --port takes precedence. When unset and --port is not passed, stdio mode is used.
APTU_CODER_EXEC_CACHE_CAPACITY64LRU cache size for exec_command results.
APTU_CODER_EXEC_CACHE_TTL_SECS10TTL in seconds for exec_command result cache.
APTU_CODER_FILE_CACHE_CAPACITY100LRU cache size for file-analysis results.
APTU_CODER_METRICS_EXPORT_FILEunsetAbsolute path for a one-shot JSONL metrics export on shutdown.
APTU_CODER_PROFILEunsetTool subset: edit (edit tools + exec_command only), analyze (analyze tools + exec_command only). Also settable per-session via io.clouatre-labs/profile in MCP _meta.
APTU_SHELLunsetShell for exec_command. Defaults to bash then /bin/sh.

Telemetry

VariableDefaultDescription
DISABLE_PROMPT_CACHINGunsetSet to 1 to disable prompt caching (recommended for single-pass subagent sessions).
DISABLE_PROMPT_CACHING_HAIKUunsetSet to 1 to disable prompt caching for Haiku-specific pipelines only.
OTEL_EXPORTER_OTLP_ENDPOINTunsetOTLP HTTP endpoint URL (e.g., http://localhost:4318). When set, enables trace, log, and metric export via OTLP/HTTP; noop providers when unset.
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTunsetReserved per OTel GenAI conventions; aptu-coder does not implement this -- bounded parameters are recorded as span attributes instead.
XDG_DATA_HOME~/.local/shareBase directory for daily-rotated JSONL metrics files ($XDG_DATA_HOME/aptu-coder/metrics-YYYY-MM-DD.jsonl, 30-day retention).

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.

Ver o original no GitHub

Bom para

Relacionados