sourcerer

Sourcerer MCP is a semantic code search and navigation server designed to help AI agents work with codebases efficiently by indexing code chunks and enabling semantic retrieval rather than brute-force text matching. It builds a searchable vector database of code chunks (functions, classes, methods, types) using Tree-sitter-based parsing, stores embeddings, and exposes MCP tools for semantic queries and chunk retrieval. The available MCP tools let you perform semantic searches, fetch specific chunks by ID, find similar chunks, and manually trigger or monitor indexing. To use it, configure the server via mcp.json (or rely on environment variables), start the sourcerer binary, and then issue MCP tool commands like semantic_search or get_chunk_code through your MCP client. This setup reduces token usage for AI agents by returning contextual code chunks instead of entire files.

Prerequisites:

• Go installed (go1.16+ or newer)
• Git installed
• A Git repository with your codebase and a .gitignore (including a .sourcerer/ directory if you plan to store embeddings locally)

Installation steps:

1. Install the Sourcerer MCP binary:

   go install github.com/st3v3nmw/sourcerer-mcp/cmd/sourcerer@latest

2. Ensure the binary is available in your PATH:

   export PATH=$PATH:$(go env GOPATH)/bin

3. Create an mcp.json configuration (see example below) to run Sourcerer as an MCP server:

   { "mcpServers": { "sourcerer": { "command": "sourcerer", "env": { "OPENAI_API_KEY": "your-openai-api-key", "SOURCERER_WORKSPACE_ROOT": "/path/to/your/project" } } } }

4. Start or initialize indexing as needed via the provided MCP tools once the server is running.

Notes:

• If you prefer using Homebrew, you can also install via the provided taps and then ensure the binary is on your PATH.
• If you want to automate startup, you can wrap the command in a script or a container invocation that uses the mcp.json configuration.

Tips and considerations:

• OPENAI_API_KEY is required for generating embeddings; ensure it has appropriate access and usage limits.
• The workspace root (SOURCERER_WORKSPACE_ROOT) should point to the root of the git repository you want to index.
• The vector database is stored in .sourcerer/db/; ensure you have sufficient disk space for large codebases.
• Sourcerer respects .gitignore and can watch filesystem changes to re-index automatically via fsnotify; ensure your environment allows filesystem events.
• The MCP tools available include:
  • semantic_search: perform semantic queries over code chunks
  • get_chunk_code: retrieve specific chunk by its ID
  • find_similar_chunks: locate chunks similar to a given chunk
  • index_workspace: manually trigger re-indexing of the workspace
  • get_index_status: monitor indexing progress
• Language support relies on Tree-sitter queries per language; current support includes Go, JavaScript, Markdown, Python, and TypeScript with planned expansion.