Build Hierarchical AST Codebase Context Tree
build_project_contextGenerates read-only repository architecture, symbol maps, or focus-file skeletons with AST pruning to cut context tokens by up to 95% at session start or during refactors.
Instructions
Returns repository-wide context or a selected context view without persisting an index; distinguishing from 'build_ast_snapshot' which writes a cache and 'generate_architectural_passport' which analyzes one Python file.
Parameters:
project_root: File system directory path; accepts relative or absolute paths, resolving symlinks and automatically skipping .git, node_modules, venv, and binary artifacts.context_type: Structural format selector: 'tree' emits full 4-tier AST architecture; 'repo_map' builds compact PageRank-ranked symbol table; 'skeleton' outputs target file implementation with 1st-degree callers/callees; 'zero_waste_prompt' formats prompt-ready AST prefix; 'incremental_diff' isolates git diff context.focus_file: Relative or absolute file path to anchor 1st-degree dependency skeletons when context_type is 'skeleton' or 'incremental_diff'; ignored when context_type is 'tree'.reduction_mode: AST pruning depth: 'ultra' preserves type signatures, classes, methods, and docstrings while removing function bodies (80-95% compression); 'balanced' retains control-flow branch headers; 'none' includes raw source code without pruning.max_tokens: Soft token ceiling (1,000 to 128,000); tree generation prioritizes core architectural layers and truncates leaf utility modules first if budget binds.include_file_contents: Set True to append AST-pruned source bodies; set False for pure directory and class hierarchy outlines with lowest token footprint.
Behavior:
Mutability: Strictly read-only; reads filesystem AST without modifying files, caches, or disk state.
Idempotency: Deterministic; identical workspace revisions yield bit-for-bit identical context payloads.
Privacy & Network: 100% offline local processing; zero cloud API calls, telemetry, or external network egress.
Performance & Resources: Executes in <500ms for 500 files consuming <50MB RAM; thread-safe with zero rate limits.
Auth: Zero authentication, API keys, or cloud credentials required.
Return Structure: Emits complete Markdown document with '# Repository Architecture', '# Module Dependencies', and token telemetry; no pagination required.
Error Handling: Returns non-crashing warning document with troubleshooting steps if path is empty or contains no supported language source files.
Usage Guidelines:
When to use: Ingest codebase architecture, symbol tables, focus file skeletons, or zero-waste prompt context at the start of an agent session or major refactor to save 80-95% context tokens.
When NOT to use: Do not use for stripping implementation bodies from an in-memory code string or diff patch (use 'prune_code_snippet' instead); do not use for targeted keyword or semantic identifier lookup across code (use 'search_codebase' instead).
Returns: Structured Markdown document featuring '# Repository Architecture (T-1)', '# Module Dependencies (T-2)', '# AST Signatures (T-3)', '# Architectural Rules (T-4)', and quantitative token savings metrics.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "build_project_context"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| focus_file | No | Optional path to a focus file when context_type is 'skeleton' or 'incremental_diff'. | |
| max_tokens | No | Upper token budget threshold for returned context. | |
| context_type | No | Context generation mode: 'tree' for hierarchical multi-tier AST tree, 'repo_map' for compact symbol index, 'skeleton' for focus-file implementation with 1st-degree caller/callee skeletons, 'zero_waste_prompt' for agent prompt prefix with pruned AST, 'incremental_diff' for git diff context. | tree |
| project_root | No | Target repository root path to scan (default: current working directory). | . |
| reduction_mode | No | AST reduction level: 'ultra' for signatures & docstrings (80-95% reduction), 'balanced' for signatures + control headers, 'none' for verbatim source. | ultra |
| include_file_contents | No | When True, includes AST-reduced file bodies; when False, emits directory hierarchy only. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |