Log inSubmit server
Codebase Context logo

Codebase Context

by PatrickSys

Local MCP server for searching repositories, identifying team patterns, tracking project memory, and preparing safer code changes.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Codebase Context

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "patricksys-codebase-context": {
      "command": "npx",
      "args": [
        "-y",
        "codebase-context"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

PatrickSys/codebase-context gives coding agents a local map of a repository, combining hybrid code search with project structure, patterns, memory, and dependency information. Its MCP tools can identify relevant files, show symbol references, surface conventions, detect circular imports, and provide an edit decision card when the agent declares an edit intent. Reach for it when an agent needs repository-specific context before changing code, especially across projects using different conventions. The default stdio setup keeps indexing and embeddings on the developer's machine.

Use cases

  • Search a large repository before implementing a feature
  • Identify representative files and recurring team patterns
  • Check symbol references before changing shared code
  • Record and retrieve project conventions or past failures
  • Find circular imports and inspect dependency structure

Key features

  • Hybrid keyword and semantic code search
  • Pattern frequency and representative-file analysis
  • Project memory with confidence decay
  • Style guide and repository metadata discovery
  • Symbol reference and circular dependency analysis
  • Local full or incremental indexing

Tools10

What Codebase Context lets your agent do. Expand a tool for its parameters.

Self-reported~155 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

21/22 checks healthy over the last 79d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 12d ago via OSV.dev · codebase-context (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars67Stargazers on the source repository.
npm downloads560Package downloads in the last 30 days.
Last commit7d agoMost recent push to the default branch.
Tools exposed10Callable tools this server registers over MCP.
Directory activity4 viewsConfig copies, upvotes, and views on AllMCPs.

How Codebase Context works

What PatrickSys/codebase-context does

PatrickSys/codebase-context helps coding agents understand an existing repository before they search, modify, or review code. It indexes project files locally and exposes repository context through MCP, including ranked search results, representative team patterns, style rules, project metadata, symbol references, and recorded engineering decisions.

The server is aimed at local coding workflows and supports more than 30 languages. Its search can return a compact set of relevant files and symbols rather than an unstructured repository dump. When called with an edit intent, search_codebase also returns a decision card that helps the agent judge whether it has enough context to proceed.

How it works

The first run downloads a local model and builds an index. Codebase Context combines keyword matching, semantic embeddings, and result ranking to find code by both exact terms and meaning. A client can pass an absolute project path to select the repository; after a successful selection, that project becomes the default for later calls in the same server process.

The MCP connection uses stdio by default, so the client starts the process when needed. One process can route requests to multiple repositories when each call identifies its project. Some clients may provide workspace roots, but explicit project selection is the documented way to avoid ambiguous repository choices.

The repository can also be queried from the terminal with commands for reindexing, producing a map, searching, and viewing patterns. refresh_index supports full or incremental indexing and can extract memory from Git history.

Setup and configuration

Node.js 22 or newer is required. The published npm package can be launched with npx -y codebase-context. Claude Code and Codex CLI provide direct MCP add commands; Gemini CLI has its own add command as well. Cursor, VS Code with GitHub Copilot, and Windsurf use their respective MCP configuration files. Codex Desktop can use a project-level .codex/config.toml entry with a 120-second startup timeout.

After adding the server, start a new agent session in the target project. A useful first request supplies the repository's absolute path, asks Codebase Context to find a feature, and tells the agent to wait for indexing before opening relevant source files. A fixed default folder can be appended to the npm command as an absolute path.

Tools and capabilities

  • search_codebase performs hybrid search and can produce an edit-oriented decision card.
  • get_team_patterns reports pattern frequencies, representative files, and conflicts.
  • get_symbol_references returns concrete references, counts, and snippets for a symbol.
  • remember records conventions, decisions, gotchas, or failures for the project.
  • get_memory retrieves stored project knowledge using confidence-decay scoring.
  • get_codebase_metadata describes project structure, frameworks, and dependencies.
  • get_style_guide returns style rules detected for the current project.
  • detect_circular_dependencies finds import cycles between files.
  • refresh_index rebuilds or incrementally updates the index and extracts Git memory.
  • get_indexing_status reports indexing progress and statistics.

Limitations and notes

The default local provider keeps code and indexes on the machine, and does not require Docker, a GPU, or an API key. Cloud embedding providers are optional; selecting one sends code chunks to that provider. The AI client may separately send search results or file contents to its configured model provider.

Generated index files should be ignored by Git. Teams can choose to commit .codebase-context/memory.json when they want to share recorded project memory. Open issues include an Intel Mac indexing crash, custom OpenAI endpoint support, and Ollama support. The published benchmark reports 25.7% expected-file recovery versus 27.1% for jCodeMunch in a fixed retrieval comparison; it does not measure coding quality or establish an overall winner.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Codebase Context

PatrickSys/codebase-context is an MCP server that connects coding agents to local repositories through indexed code context. Its main tools search the codebase, identify team patterns, retrieve symbol references, manage project memory, inspect metadata and style rules, detect circular dependencies, and refresh or monitor the index.

Install it through an MCP client's setup command using Node.js 22 or newer and `npx -y codebase-context`. Claude Code, Codex CLI, and Gemini CLI provide add commands, while Cursor, VS Code, Windsurf, and Codex Desktop use their own configuration files.

Yes, PatrickSys/codebase-context works with Cursor through the client's `.cursor/mcp.json` configuration file. After adding the server, start a new session in the repository and provide its absolute path when asking the agent to search.

Not by default. The default embedding provider runs locally and keeps code and indexes on the machine. Choosing a cloud embedding provider sends code chunks to that provider, and the connected AI client may independently send returned context to its configured model provider.

Use the `refresh_index` MCP tool for a full or incremental update, or run `npx -y codebase-context reindex` from the project root. `get_indexing_status` reports progress and current index statistics.

Related MCP servers

All in Knowledge & Memory All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewCodebase Context AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/patricksys-codebase-context?style=directory)](https://allmcps.com/mcp/patricksys-codebase-context)
HTML Embed
<a href="https://allmcps.com/mcp/patricksys-codebase-context"><img src="https://allmcps.com/api/badge/patricksys-codebase-context?style=directory" alt="Codebase Context on AllMCPs" /></a>