{"id":49593396,"url":"https://github.com/clouatre-labs/aptu-coder","last_synced_at":"2026-06-01T00:01:21.141Z","repository":{"id":343825487,"uuid":"1168822754","full_name":"clouatre-labs/aptu-coder","owner":"clouatre-labs","description":"aptu-coder: MCP server for AST analysis, call graphs, and code structure (tree-sitter)","archived":false,"fork":false,"pushed_at":"2026-05-31T05:26:17.000Z","size":3433,"stargazers_count":4,"open_issues_count":8,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T07:12:06.407Z","etag":null,"topics":["ai","aptu","ast","call-graph","code-analysis","developer-tools","mcp","mcp-server","model-context-protocol","rust","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clouatre-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-27T20:53:09.000Z","updated_at":"2026-05-31T05:26:21.000Z","dependencies_parsed_at":"2026-05-10T13:03:55.505Z","dependency_job_id":null,"html_url":"https://github.com/clouatre-labs/aptu-coder","commit_stats":null,"previous_names":["clouatre-labs/code-analyze-mcp","clouatre-labs/aptu-coder"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/clouatre-labs/aptu-coder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Faptu-coder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Faptu-coder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Faptu-coder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Faptu-coder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clouatre-labs","download_url":"https://codeload.github.com/clouatre-labs/aptu-coder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Faptu-coder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33753925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","aptu","ast","call-graph","code-analysis","developer-tools","mcp","mcp-server","model-context-protocol","rust","tree-sitter"],"created_at":"2026-05-04T02:01:04.634Z","updated_at":"2026-06-01T00:01:21.115Z","avatar_url":"https://github.com/clouatre-labs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\n\u003ch1 align=\"center\"\u003eaptu-coder\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://crates.io/crates/aptu-coder\"\u003e\u003cimg alt=\"crates.io\" src=\"https://img.shields.io/crates/v/aptu-coder.svg?style=for-the-badge\u0026color=fc8d62\u0026logo=rust\" height=\"20\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://slsa.dev\"\u003e\u003cimg alt=\"SLSA Level 3\" src=\"https://img.shields.io/badge/SLSA-Level%203-green?style=for-the-badge\" height=\"20\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.bestpractices.dev/projects/12275\"\u003e\u003cimg alt=\"OpenSSF Best Practices\" src=\"https://img.shields.io/cii/level/12275?style=for-the-badge\" height=\"20\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eStandalone MCP server for code structure analysis using tree-sitter. OpenSSF silver certified: fewer than 1% of open source projects reach this level.\u003c/p\u003e\n\n\u003c!-- mcp-name: io.github.clouatre-labs/aptu-coder --\u003e\n\n\u003e [!NOTE]\n\u003e 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.\n\n## Benchmarks\n\nAuth migration task on Claude Code against [Django](https://github.com/django/django) (Python) source tree. [Full methodology](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/benchmarks/v12/methodology.md).\n\n| Mode | Sonnet 4.6 | Haiku 4.5 |\n|---|---|---|\n| MCP | 112k tokens, $0.39 | 406k tokens, $0.42 |\n| Native | 276k tokens, $0.95 | 473k tokens, $0.53 |\n| **Savings** | **59% fewer tokens, 59% cheaper** | **14% fewer tokens, 21% cheaper** |\n\nAeroDyn integration audit task on Claude Code against [OpenFAST](https://github.com/OpenFAST/openfast) (Fortran) source tree. [Full methodology](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/benchmarks/v13/methodology.md).\n\n| Mode | Sonnet 4.6 | Haiku 4.5 |\n|---|---|---|\n| MCP | 472k tokens, $1.65 | 687k tokens, $0.72 |\n| Native | 877k tokens, $2.85 | 2162k tokens, $2.21 |\n| **Savings** | **46% fewer tokens, 42% cheaper** | **68% fewer tokens, 68% cheaper** |\n\n## Overview\n\naptu-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.\n\n## Supported Languages\n\nAll languages are enabled by default. Disable individual languages at compile time via Cargo feature flags.\n\n| Language | Extensions | Feature flag |\n|----------|------------|--------------|\n| Rust | `.rs` | `lang-rust` |\n| Python | `.py` | `lang-python` |\n| TypeScript | `.ts` | `lang-typescript` |\n| TSX | `.tsx` | `lang-tsx` |\n| Go | `.go` | `lang-go` |\n| Java | `.java` | `lang-java` |\n| Kotlin | `.kt`, `.kts` | `lang-kotlin` |\n| Fortran | `.f`, `.f77`, `.f90`, `.f95`, `.f03`, `.f08`, `.for`, `.ftn` | `lang-fortran` |\n| JavaScript | `.js`, `.mjs`, `.cjs` | `lang-javascript` |\n| C/C++ | `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, `.hpp`, `.hxx` | `lang-cpp` |\n| C# | `.cs` | `lang-csharp` |\n\n## Installation\n\n### Homebrew (macOS and Linux)\n\n```bash\nbrew install clouatre-labs/tap/aptu-coder\n```\n\nUpdate: `brew upgrade aptu-coder`\n\n### cargo-binstall (no Rust required)\n\n```bash\ncargo binstall aptu-coder\n```\n\n### cargo install (requires Rust toolchain)\n\n```bash\ncargo install aptu-coder\n```\n\n## Quick Start\n\n### Build from source\n\n```bash\ncargo build --release\n```\n\nThe binary is at `target/release/aptu-coder`.\n\n### Configure MCP Client\n\nTwo 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.\n\n**Streamable HTTP (recommended for multi-agent setups)**\n\nWith Homebrew, one command starts the server on login and keeps it running:\n\n```bash\nbrew services start aptu-coder\n```\n\nThe Homebrew formula starts the server on port `49200` by default. Then add the extension once to `~/.config/goose/config.yaml`:\n\n```yaml\nextensions:\n  aptu-coder:\n    type: streamable_http\n    uri: http://127.0.0.1:49200/mcp\n    name: aptu-coder\n    timeout: 300\n```\n\nOr for Claude Code:\n\n```bash\nclaude mcp add --transport http aptu-coder http://127.0.0.1:49200/mcp\n```\n\nTo use a different port, set `APTU_CODER_PORT` before restarting:\n\n```bash\nAPTU_CODER_PORT=4000 brew services restart aptu-coder\n```\n\nTo start directly without brew services:\n\n```bash\naptu-coder --port 49200\n# or equivalently\nAPTU_CODER_PORT=49200 aptu-coder\n```\n\n**stdio (single-client use)**\n\nSuitable when only one process needs the server. The client owns the process lifecycle and spawns it automatically:\n\n```bash\nclaude mcp add --transport stdio aptu-coder -- aptu-coder\n```\n\nOr add manually to `.mcp.json` at your project root (shared with your team via version control):\n\n```json\n{\n  \"mcpServers\": {\n    \"aptu-coder\": {\n      \"command\": \"aptu-coder\",\n      \"args\": []\n    }\n  }\n}\n```\n\n## Tools\n\nAll optional parameters may be omitted. Shared optional parameters for `analyze_directory`, `analyze_file`, and `analyze_symbol`:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `summary` | boolean | auto | Compact output; auto-triggers above 50K chars |\n| `cursor` | string | -- | Pagination cursor from a previous response's `next_cursor` |\n| `page_size` | integer | 100 | Items per page |\n| `force` | boolean | false | Bypass output size warning |\n| `verbose` | boolean | false | Full output with section headers and imports |\n\n| Tool | Purpose | Languages |\n|------|---------|-----------|\n| `analyze_directory` | Directory tree with LOC, function, and class counts; respects `.gitignore` | all |\n| `analyze_file` | Functions, classes, and imports with signatures and line ranges; returns `INVALID_PARAMS` for unsupported extensions | all |\n| `analyze_module` | Lightweight function and import index (~75% smaller than `analyze_file`); returns `INVALID_PARAMS` for unsupported extensions | all |\n| `analyze_symbol` | Call graph for a named symbol across a directory; callers, callees, call depth | all |\n| `edit_overwrite` | Create or overwrite a file; creates parent directories | any file |\n| `edit_replace` | Replace a unique exact text block; errors if zero or multiple matches | all |\n| `exec_command` | Run a shell command; returns stdout, stderr, exit code, and timeout status; supports progress notifications; output capped and filtered automatically | any |\n\nTool parameters, constraints, and examples are available via your MCP client's tool inspector or `tools/list` response.\n\n## Output Management\n\nFor large codebases, several mechanisms prevent context overflow.\n\n**Pagination**\n\n`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.\n\n```\n# Response ends with:\nNEXT_CURSOR: eyJvZmZzZXQiOjUwfQ==\n\n# Fetch next page:\nanalyze_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ==\n```\n\n**exec_command output caps**\n\n`exec_command` applies three independent byte-level caps to prevent large command outputs from flooding the context:\n\n| Stream | Cap | Behavior |\n|--------|-----|----------|\n| stdout | 30,000 chars | Tail-preserving; keeps the last 30k chars |\n| stderr | 10,000 chars | Tail-preserving; errors appear at the end |\n| combined `output_text` | 50,000 chars | Safety net after interleaving |\n\nThe 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.\n\n**exec_command output filters**\n\nA 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.\n\n| Command | Behavior |\n|---------|----------|\n| `git pull` | Injects `--no-stat` before execution; strips diff-stat noise |\n| `git fetch` | Strips `From` / ref lines; caps at 10 lines |\n| `git push` | Strips `remote:` lines; caps at 10 lines |\n| `git log` | Caps at 20 lines |\n| `git status` | Caps at 20 lines |\n| `cargo build` | Strips `Compiling` / `Checking` / `Downloading` / `Fresh` lines |\n| `cargo test` | Strips `Compiling` / `Checking` / `Fresh` lines |\n\nProject-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.\n\n## Non-Interactive Pipelines\n\nIn 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.\n\nThe 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.\n\n## Environment Variables\n\n### Cache and runtime\n\n| Variable | Default | Description |\n|---|---|---|\n| `APTU_CODER_DIR_CACHE_CAPACITY` | `20` | LRU cache size for directory-analysis results. |\n| `APTU_CODER_PORT` | unset | Port for streamable HTTP mode. Equivalent to `--port N`; `--port` takes precedence. When unset and `--port` is not passed, stdio mode is used. |\n| `APTU_CODER_EXEC_CACHE_CAPACITY` | `64` | LRU cache size for `exec_command` results. |\n| `APTU_CODER_EXEC_CACHE_TTL_SECS` | `10` | TTL in seconds for `exec_command` result cache. |\n| `APTU_CODER_FILE_CACHE_CAPACITY` | `100` | LRU cache size for file-analysis results. |\n| `APTU_CODER_METRICS_EXPORT_FILE` | unset | Absolute path for a one-shot JSONL metrics export on shutdown. |\n| `APTU_CODER_PROFILE` | unset | Tool 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`. |\n| `APTU_SHELL` | unset | Shell for `exec_command`. Defaults to `bash` then `/bin/sh`. |\n\n### Telemetry\n\n| Variable | Default | Description |\n|---|---|---|\n| `DISABLE_PROMPT_CACHING` | unset | Set to `1` to disable prompt caching (recommended for single-pass subagent sessions). |\n| `DISABLE_PROMPT_CACHING_HAIKU` | unset | Set to `1` to disable prompt caching for Haiku-specific pipelines only. |\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | OTLP HTTP endpoint URL (e.g., `http://localhost:4318`). When set, enables trace, log, and metric export via OTLP/HTTP; noop providers when unset. |\n| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | unset | Reserved per OTel GenAI conventions; aptu-coder does not implement this -- bounded parameters are recorded as span attributes instead. |\n| `XDG_DATA_HOME` | `~/.local/share` | Base directory for daily-rotated JSONL metrics files (`$XDG_DATA_HOME/aptu-coder/metrics-YYYY-MM-DD.jsonl`, 30-day retention). |\n\n## Observability\n\nThe server emits two parallel, independent telemetry streams.\n\n**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](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/OBSERVABILITY.md) for the full schema.\n\n**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.\n\nEach 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.\n\nFor the span attribute policy, the never-record list, and details on what is instrumented, see [OBSERVABILITY.md](https://github.com/clouatre-labs/aptu-coder/blob/main/OBSERVABILITY.md) at the repository root.\n\n## Documentation\n\n- **[AGENTS.md](https://github.com/clouatre-labs/aptu-coder/blob/main/AGENTS.md)** - Contributor reference: project structure, commands, rmcp footguns, tool parameter constraints\n- **[ARCHITECTURE.md](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/ARCHITECTURE.md)** - Design goals, module map, data flow, language handler system, caching strategy\n- **[CONTRIBUTING.md](https://github.com/clouatre-labs/aptu-coder/blob/main/CONTRIBUTING.md)** - Development workflow, commit conventions, PR checklist\n- **[DESIGN-GUIDE.md](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/DESIGN-GUIDE.md)** - Design decisions, rationale, and replication guide for building high-performance MCP servers\n- **[MCP Best Practices](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/MCP-BEST-PRACTICES.md)** - Best practices for agentic loops, orchestration patterns, MCP tool design, memory management, and safety controls\n- **[OBSERVABILITY.md](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/OBSERVABILITY.md)** - Metrics schema, JSONL format, and retention policy\n- **[ROADMAP.md](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/ROADMAP.md)** - Development history and future direction\n- **[SECURITY.md](https://github.com/clouatre-labs/aptu-coder/blob/main/SECURITY.md)** - Security policy and vulnerability reporting\n\n## License\n\nApache-2.0. See [LICENSE](https://github.com/clouatre-labs/aptu-coder/blob/main/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclouatre-labs%2Faptu-coder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclouatre-labs%2Faptu-coder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclouatre-labs%2Faptu-coder/lists"}