codebase-context

codebase-context is an MCP server that provides a rich, local-first context for AI agents working on your codebase. It surfaces curated context about your project’s conventions, patterns, and memories, enabling agents to reason with actual team practices rather than generic guidance. The server analyzes your repository to extract team-wide conventions from code and git history, tracks decisions and memories across sessions, and auto-refreshes the index as you edit. When an agent queries the MCP, it receives a structured context that includes code wiring, related files, quality indicators, and adoption trends, helping the agent make safer edits and better decisions.

Common tool commands exposed by this MCP server include metadata, patterns, and memory lists, which let you quickly understand the current state of your codebase. For example, metadata gives a quick overview of the repo, patterns shows current team coding habits and their adoption percentages, and memory list reveals past decisions and why they were made. When using an agent in conjunction with this MCP, you can rely on the one-shot tool call to retrieve that comprehensive context instead of piecing together multiple sources yourself.

Prerequisites:

• Node.js and npm installed on your machine
• Access to the internet to fetch the MCP package

Install steps:

1. Ensure you have Node.js installed. You can verify with:

node -v
npm -v

2. Install or run the MCP server using npx (no permanent installation required):

npx -y codebase-context /path/to/your/project

3. (Optional) Install globally if you want a persistent CLI:

npm install -g codebase-context

4. Verify installation by running a quick metadata query:

npx -y codebase-context metadata

5. Integrate with your preferred client (Claude/VS Code/OpenCode/etc.) using the example configurations in the README.

Tips and caveats:

• The MCP runs locally by default; you can opt into cloud embeddings by configuring EMBEDDING_PROVIDER, but be aware that this may transmit your code.
• The index auto-refreshes as you edit, so you don’t have to manually reindex after every change.
• If you’re using the single-shot integration in an agent, pass the project path as shown in the examples so the server can scope the context correctly.
• If you see stale context, trigger a manual reindex or restart the MCP server to refresh memories and patterns.