Spark
Sign In
MCP Connector

Semantically Search and Navigate Codebases

MCP server for semantic code search: jump straight to relevant functions and classes instead of reading whole files.

Connect
Works with openai
Stephen Mwangi
Maintainer?
90
Spark score
out of 100
Updated 8 months ago
Fresher alternatives ↓
Version 0.5.5
Models
universal
Add to Favorites

Why it matters

Enhance AI agent efficiency by enabling conceptual code search and navigation, drastically reducing token usage and improving understanding of complex codebases.

Outcomes

What it gets done

01

Perform semantic code search across your entire codebase.

02

Retrieve specific code chunks by stable IDs.

03

Find semantically similar code snippets.

04

Automatically index and re-index your workspace.

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/vb-sourcerer | bash

Capabilities

Tools your agent gets

semantic_search

Search for relevant code using semantic search across your codebase

get_chunk_code

Retrieve specific code chunks by their ID

find_similar_chunks

Find similar code chunks based on semantic similarity

index_workspace

Manually trigger re-indexing of the workspace

get_index_status

Check the current indexing progress and status

Overview

Sourcerer MCP Server

An MCP server that builds a semantic vector index of a codebase with Tree-sitter and chromem-go, letting AI agents search by concept and retrieve specific code chunks instead of reading whole files. Use in large codebases where an agent needs to find relevant code by concept. Requires an OpenAI API key, a git repository, and Tree-sitter support for the target language (currently Go/JS/Markdown/Python/TS).

What it does

Sourcerer MCP is an MCP server for semantic code search and navigation that helps AI agents work efficiently without burning through tokens reading entire files - agents search conceptually and jump directly to the specific functions, classes, and code chunks they need.

It works in four stages. Code parsing and chunking uses Tree-sitter to parse source files into ASTs, extracting meaningful chunks (functions, classes, methods, types) with stable IDs in the format file.ext::Type::method, each including source code, location info, and a contextual summary. File system integration watches for changes via fsnotify, respects .gitignore through git check-ignore, and automatically re-indexes changed files while tracking modification times. Vector storage uses chromem-go for a persistent vector database in .sourcerer/db/, generating embeddings via OpenAI's API to enable conceptual similarity search rather than plain text matching.

claude mcp add sourcerer -e OPENAI_API_KEY=your-openai-api-key -e SOURCERER_WORKSPACE_ROOT=$(pwd) -- sourcerer

It exposes five MCP tools: semantic_search (find relevant code by meaning), get_chunk_code (retrieve a specific chunk by its stable ID), find_similar_chunks (locate code similar to a given chunk), index_workspace (manually trigger re-indexing), and get_index_status (check indexing progress).

When to use - and when NOT to

Use this connector when working in a large codebase where an agent needs to find relevant code by concept rather than exact text match - locating the right function or class without reading every file in a directory, which both wastes tokens and adds cognitive overhead.

It requires an OpenAI API key for generating embeddings (local embedding support is planned but not yet available), and the target project must be a git repository since it relies on .gitignore and git check-ignore for scoping what gets indexed - the .sourcerer/ directory storing the vector database should itself be added to .gitignore. Language support depends on Tree-sitter queries being written for each language; currently Go, JavaScript, Markdown, Python, and TypeScript are supported, with C, C++, Java, Ruby, and Rust planned.

Capabilities

semantic_search: find relevant code by meaning rather than exact text. get_chunk_code: retrieve a specific code chunk by stable ID. find_similar_chunks: find code similar to a given chunk. index_workspace: manually trigger re-indexing. get_index_status: check indexing progress.

How to install

Install via Go (go install github.com/st3v3nmw/sourcerer-mcp/cmd/sourcerer@latest) or Homebrew (brew tap st3v3nmw/tap && brew install st3v3nmw/tap/sourcerer). Configure via Claude Code CLI (claude mcp add sourcerer -e OPENAI_API_KEY=... -e SOURCERER_WORKSPACE_ROOT=$(pwd) -- sourcerer) or by adding the server to mcp.json with OPENAI_API_KEY and SOURCERER_WORKSPACE_ROOT environment variables.

Who it's for

Developers working with AI coding agents in large codebases who want semantic, token-efficient code search instead of having the agent read whole files to find relevant code.

Source README

Sourcerer MCP 🧙

An MCP server for semantic code search & navigation that helps AI agents work
efficiently without burning through costly tokens.
Instead of reading entire files, agents can search conceptually and
jump directly to the specific functions, classes, and code chunks they need.

Demo

asciicast

Requirements

  • OpenAI API Key: Required for generating embeddings (local embedding support planned)
  • Git: Must be a git repository (respects .gitignore files)
  • Add .sourcerer/ to .gitignore: This directory stores the embedded vector database

Installation

Go

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

Homebrew

brew tap st3v3nmw/tap
brew install st3v3nmw/tap/sourcerer

Configuration

Claude Code

claude mcp add sourcerer -e OPENAI_API_KEY=your-openai-api-key -e SOURCERER_WORKSPACE_ROOT=$(pwd) -- sourcerer

mcp.json

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

How it Works

Sourcerer 🧙 builds a semantic search index of your codebase:

1. Code Parsing & Chunking

  • Uses Tree-sitter to parse source files into ASTs
  • Extracts meaningful chunks (functions, classes, methods, types) with stable IDs
  • Each chunk includes source code, location info, and contextual summaries
  • Chunk IDs follow the format: file.ext::Type::method

2. File System Integration

  • Watches for file changes using fsnotify
  • Respects .gitignore files via git check-ignore
  • Automatically re-indexes changed files
  • Stores metadata to track modification times

3. Vector Database

  • Uses chromem-go for persistent vector storage in .sourcerer/db/
  • Generates embeddings via OpenAI's API for semantic similarity
  • Enables conceptual search rather than just text matching
  • Maintains chunks, their embeddings, and metadata

4. MCP Tools

  • semantic_search: Find relevant code using semantic search
  • get_chunk_code: Retrieve specific chunks by ID
  • find_similar_chunks: Find similar chunks
  • index_workspace: Manually trigger re-indexing
  • get_index_status: Check indexing progress

This approach allows AI agents to find relevant code without reading entire files,
dramatically reducing token usage and cognitive load.

Supported Languages

Language support requires writing Tree-sitter queries to
identify functions, classes, interfaces, and other code structures for each language.

Supported: Go, JavaScript, Markdown, Python, TypeScript

Planned: C, C++, Java, Ruby, Rust, and others

FAQ

Common questions

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.