agentic-codebase

The AgenticCodebase MCP server exposes a set of graph-based code intelligence tools that operate on a persistent, queryable representation of your repository. It provides grounding and evidence capabilities for code claims, as well as workspace features to compare and migrate between multiple .acb graphs. With the server running, MCP clients can issue structured tools like codebase_ground to verify a claim about a symbol, codebase_evidence to retrieve file-and-line evidence, and codebase_suggest to surface similar symbols when a claim isn’t grounded. Additionally, multi-context workspaces let you load multiple .acb graphs and run cross-repo queries using workspace_create, workspace_add, workspace_query, and related tools, enabling cross-project analysis and migration tracking via translation tools. Typical workflows include asserting a symbol’s existence with grounding, inspecting the supporting files, and then coordinating changes across repositories through workspace comparisons. The MCP client interface mirrors the command examples shown in the README, so you can send JSON payloads that specify the claim or workspace operation you want executed against the agentic-codebase graph.

To use the server, start it through the agentic-codebase-mcp CLI, then connect an MCP client to issue tool invocations. For a grounding workflow, you would run a codebase_ground call with a claim like “UserService has method getProfile,” then fetch codebase_evidence to locate the exact file paths and lines supporting the claim. For cross-repo work, initialize a workspace, add both old and new graphs, and issue workspace_query or workspace_compare to examine symbol mappings across repos. The tools are designed to be composable and fast, enabling iterative, structured reasoning over code structure rather than plain text search.

Prerequisites:

• Python 3.10+ (optional if you use the Python/MCP bindings)
• Rust toolchain (optional if you install via cargo)
• Cargo (Rust) for Rust-based installs
• pip or pipx for Python-based installs (optional)

Install methods (choose one):

1. Python/pip-based installation (recommended for quick start):

python3 -m pip install --upgrade pip
pip install agentic-codebase

This installs the agentic-codebase package which also provides MCP tooling wrappers including the agentic-codebase-mcp CLI if packaged accordingly.

2. Rust/cargo installation (high performance / binary):

cargo install agentic-codebase

This builds and installs the MCP tooling as a binary you can invoke as agentic-codebase-mcp.

3. Node/npx or other package managers (alternative paths if provided by the project):

npx -y agentic-codebase-mcp

Note: If you use npm/yarn, ensure the package name corresponds to the MCP binary distribution provided by the project.

4. Running the MCP server locally (example patterns):

• Python-based run (if available):

python -m agentic_codebase_mcp

• Rust-based run (if the binary is named accordingly):

agentic-codebase-mcp

After installation, verify the CLI is reachable:

agentic-codebase-mcp --help

Tips and common issues:

• Ensure your environment PATH includes the location where the agentic-codebase-mcp binary is installed.
• If you plan to load multiple graphs in the same session, look into workspace-related commands (workspace_create, workspace_add, workspace_list, workspace_query, workspace_compare, workspace_xref) for cross-repo analysis.
• grounding results include evidence paths to files and line numbers; if you see ungrounded claims, try codebase_evidence or codebase_suggest to refine your inputs.
• When using MV (multi-context workspaces), remember to assign meaningful workspace names and manage IDs carefully to avoid collisions.
• If you encounter performance issues, ensure you’re running the latest binary from the project’s releases and consider using a Rust/cargo install for best binary performance.
• Documentation and API references live under docs/api-reference.md and INSTALL.md in the repo; refer to those for exact tool invocation syntax and JSON payload formats.