Sourcerer MCP 🧙

1# Sourcerer MCP 🧙
2 
3An MCP server for semantic code search & navigation that helps AI agents work
4efficiently without burning through costly tokens.
5Instead of reading entire files, agents can search conceptually and
6jump directly to the specific functions, classes, and code chunks they need.
7 
8## Demo
9 
10[![asciicast](https://asciinema.org/a/736638.svg)](https://asciinema.org/a/736638)
11 
12## Requirements
13 
14- **OpenAI API Key**: Required for generating embeddings (local embedding support planned)
15- **Git**: Must be a git repository (respects `.gitignore` files)
16- **Add `.sourcerer/` to `.gitignore`**: This directory stores the embedded vector database
17 
18## Installation
19 
20### Go
21 
22```shell
23go install github.com/st3v3nmw/sourcerer-mcp/cmd/sourcerer@latest
24```
25 
26### Homebrew
27 
28```shell
29brew tap st3v3nmw/tap
30brew install st3v3nmw/tap/sourcerer
31```
32 
33## Configuration
34 
35### Claude Code
36 
37```shell
38claude mcp add sourcerer -e OPENAI_API_KEY=your-openai-api-key -e SOURCERER_WORKSPACE_ROOT=$(pwd) -- sourcerer
39```
40 
41### mcp.json
42 
43```json
44{
45  "mcpServers": {
46    "sourcerer": {
47      "command": "sourcerer",
48      "env": {
49        "OPENAI_API_KEY": "your-openai-api-key",
50        "SOURCERER_WORKSPACE_ROOT": "/path/to/your/project"
51      }
52    }
53  }
54}
55```
56 
57## How it Works
58 
59Sourcerer 🧙 builds a semantic search index of your codebase:
60 
61### 1. Code Parsing & Chunking
62 
63- Uses [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) to parse source files into ASTs
64- Extracts meaningful chunks (functions, classes, methods, types) with stable IDs
65- Each chunk includes source code, location info, and contextual summaries
66- Chunk IDs follow the format: `file.ext::Type::method`
67 
68### 2. File System Integration
69 
70- Watches for file changes using `fsnotify`
71- Respects `.gitignore` files via `git check-ignore`
72- Automatically re-indexes changed files
73- Stores metadata to track modification times
74 
75### 3. Vector Database
76 
77- Uses [chromem-go](https://github.com/philippgille/chromem-go) for persistent vector storage in `.sourcerer/db/`
78- Generates embeddings via OpenAI's API for semantic similarity
79- Enables conceptual search rather than just text matching
80- Maintains chunks, their embeddings, and metadata
81 
82### 4. MCP Tools
83 
84- `semantic_search`: Find relevant code using semantic search
85- `get_chunk_code`: Retrieve specific chunks by ID
86- `find_similar_chunks`: Find similar chunks
87- `index_workspace`: Manually trigger re-indexing
88- `get_index_status`: Check indexing progress
89 
90This approach allows AI agents to find relevant code without reading entire files,
91dramatically reducing token usage and cognitive load.
92 
93## Supported Languages
94 
95Language support requires writing [Tree-sitter queries](https://github.com/st3v3nmw/sourcerer-mcp/blob/main/internal/parser/go.go) to
96identify functions, classes, interfaces, and other code structures for each language.
97 
98**Supported:** Go, JavaScript, Markdown, Python, TypeScript
99 
100**Planned:** C, C++, Java, Ruby, Rust, and others
101 
102## Contributing
103 
104All contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
105 
106```
107$ ls @stephenmwangi.com
108- gh:st3v3nmw/obsidian-spaced-repetition
109- gh:st3v3nmw/lsfr
110```
111