MCP Beacon

A fast, token-efficient MCP server for codebase search with 30+ tools. Multi-language AST parsing, semantic search, linting, and git integration.

MCP Beacon exposes powerful codebase search tools to AI assistants (OpenCode, Claude Desktop, Cursor, Antigravity, etc.) via the Model Context Protocol. Instead of LLMs writing ad-hoc scripts to explore codebases, they use these optimized tools directly — saving tokens and time.

Author: Wilber Turcios (@WilTurcios)

Why This Exists

LLMs often write ad-hoc Python/bash scripts to explore codebases. This wastes tokens on boilerplate, risks errors, and floods context with raw output. MCP Codebase Searcher replaces that with:

• 30+ optimized tools — search, definitions, AST, git, lint, semantic search, and more
• Zero LLM calls — the MCP server never calls external APIs; your AI client does the thinking
• Multi-language — Python, TypeScript, JavaScript, C#, Rust, Go, Java, Kotlin, and more
• Token-efficient — ast_structure returns ~200 tokens instead of ~5000 for full file reads
• Persistent semantic search — ChromaDB index with nomic-embed-text-v1.5 embeddings

Quick Install

pip install mcp_beacon

Optional Extras

# Semantic search (embeddings + vector database)
pip install mcp_beacon[semantic]

# Full install (semantic + LSP)
pip install mcp_beacon[all]

Requires Python 3.8+.

Install from .whl file

If you have the package as a .whl file (e.g., downloaded or built locally):

# Install the base package
pip install dist/mcp_beaconer-0.4.0-py3-none-any.whl

# Install with semantic extras (edit the .whl name if needed)
pip install "dist/mcp_beaconer-0.4.0-py3-none-any.whl[semantic]"

# Install with all extras
pip install "dist/mcp_beaconer-0.4.0-py3-none-any.whl[all]"

Building the .whl file:

# Install build tools
pip install build

# Build the package
python -m build

# The .whl file will be in dist/
ls dist/
# mcp_beaconer-0.4.0-py3-none-any.whl

Offline install (no internet):

# Download all dependencies first (on a machine with internet)
pip download mcp_beacon -d ./packages

# Transfer the packages folder to the target machine, then:
pip install --no-index --find-links=./packages mcp_beacon

Installation for MCP Clients

OpenCode

Local (STDIO) — opencode.jsonc:

{
  "mcp": {
    "codebase-searcher": {
      "type": "local",
      "command": ["python", "-m", "mcp_beacon"],
      "enabled": true
    }
  }
}

Remote (Streamable HTTP) — opencode.jsonc:

{
  "mcp": {
    "codebase-searcher": {
      "type": "remote",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "codebase-searcher": {
      "command": "python",
      "args": ["-m", "mcp_beacon"]
    }
  }
}

Antigravity / Web Clients (SSE)

Start the server:

mcp-searcher-server --transport sse --port 8000

Connect to http://localhost:8000/sse.

With Custom Workspace Root

If auto-detection doesn't work, set the env var in your client config:

{
  "command": "python",
  "args": ["-m", "mcp_beacon"],
  "env": {
    "MCP_WORKSPACE_ROOT": "/path/to/your/project"
  }
}

Agent Auto-Discovery Setup

To make your AI agent automatically use MCP Beacon for codebase operations, add this to your AGENTS.md file (global at ~/.config/opencode/AGENTS.md or per-project at ./AGENTS.md):

<!-- mcp_beacon -->

## Codebase Search (mcp_beacon)

The `mcp_beacon` MCP server provides 30+ tools for codebase exploration.
All tools are auto-discovered via MCP — do NOT hardcode tool names.

### When to use
- Searching code (text, regex, definitions, references)
- Understanding file structure (AST parsing)
- Checking code quality (linting)
- Viewing git history (blame, log, conflicts)
- Semantic search by meaning
- Finding tests and coverage

### Workflow preference
1. Use `codebase-beacon_ast_structure` to understand file structure (~200 tokens vs ~5000 for full file)
2. Use `codebase-beacon_search_definitions` or `codebase-beacon_search_references` to find code
3. Use `codebase-beacon_read_file` only for specific sections
4. Use `codebase-beacon_search_and_replace` (dry run first!) for edits

### Rules
- Prefer MCP tools over built-in grep/glob/read
- Use `exclude_pattern` to skip irrelevant files
- ALWAYS preview with `confirm=False` before applying changes
- Do NOT write your own search scripts — use these tools

<!-- /mcp_beacon -->

Why This Works

• No tool listing needed — MCP protocol provides the tool list automatically
• Never outdated — new tools are auto-discovered, no manual updates
• Works with all MCP clients — OpenCode, Claude Desktop, Cursor, etc.

MCP Tools (30+)

Core Search Tools

Tool	Description	Token Cost
search_codebase	Text/regex search with context snippets	Medium
search_codebase_count	Count matches per file (no snippets)	Low
search_codebase_multi	Multi-query search (single scan)	Low
search_definitions	Find function/class definitions by name	Low
search_by_pattern	Structural search (signatures, classes)	Low
search_and_replace	Search + replace with dry-run preview	Medium

AST & Structure Tools

Tool	Description	Token Cost
ast_structure	File outline (functions, classes, imports)	~200 tokens
ast_query	Tree-sitter query for precise structure	Low

Reference & Relationship Tools

Tool	Description	Token Cost
search_imports	Dependency graph (what imports what)	Low
search_references	Find all usages of a function/variable	Medium
find_tests	Find tests for a function or uncovered code	Low

Git Tools

Tool	Description	Token Cost
git_blame	Who wrote each line	Low
git_history	Structured commit history	Medium
git_conflicts	Find merge conflicts	Low
git_branches	List branches	Low
git_status	Working tree status	Low

Quality Tools

Tool	Description	Token Cost
lint_code	Run ruff linter	Low
lint_fix	Auto-fix lint issues	Low
lint_format	Format code with ruff	Low

Semantic Search (Optional)

Tool	Description	Token Cost
semantic_index	Build/update semantic index	N/A
semantic_search	Search by meaning with embeddings	Low
semantic_stats	Index statistics	Low

Analysis Tools

Tool	Description	Token Cost
codebase_summary	Project overview (languages, files, modules)	Low
code_metrics	File sizes, line counts, complexity	Low
codebase_diff	Git changes, history, statistics	Medium
search_docs	Search documentation and comments	Medium
find_similar	Find similar code blocks	Medium

File Navigation Tools

Tool	Description	Token Cost
find_files	Glob pattern file discovery	Low
list_files	Directory listing	Low
read_file	Read file content with line ranges	Variable

Token Efficiency

The ast_structure tool is the key win — instead of reading a full file (~5000 tokens), you get a structural outline (~200 tokens) showing functions, classes, methods, and imports with line numbers.

Operation	Traditional	MCP Codebase Searcher	Savings
Understand file structure	read_file (500 lines)	ast_structure	95%
Find function definition	grep + read	search_definitions	80%
Find all usages	grep + filter	search_references	70%
Check test coverage	manual search	find_tests	90%

Workspace Root Detection

The server auto-detects the workspace root using this priority:

1. MCP_WORKSPACE_ROOT env var (set by MCP client config)
2. WORKSPACE_ROOT env var
3. Current working directory (when the client spawns the server from the project dir)

No configuration file is needed. If auto-detection fails, pass absolute paths to tools.

Transport Configuration

The server supports three transport protocols:

Transport	Flag	Use Case
STDIO	--transport stdio	Claude Desktop, Cursor, local tools (default)
SSE	--transport sse	Web clients, Antigravity
Streamable HTTP	--transport streamable-http	OpenCode, modern MCP clients

CLI flags:

mcp-searcher-server --transport sse --host 127.0.0.1 --port 8000

Environment variables:

MCP_TRANSPORT=sse MCP_HOST=127.0.0.1 MCP_PORT=8000 mcp-searcher-server

CLI Usage

The mcp-searcher CLI provides direct terminal access without an MCP client:

# Search for a function
mcp-searcher search "def my_function" /path/to/project

# Regex search with file filter
mcp-searcher search "class \w+:" src --regex --file-pattern "*.py"

# Case-sensitive search with limited results
mcp-searcher search "TODO" . --case-sensitive --max-results 10

# JSON output
mcp-searcher search "import" src --output-format json --output-file results.json

CLI Options:

• --no-cache — Disable caching for this run
• --clear-cache — Clear all cached data
• --cache-dir DIR — Custom cache directory
• --cache-expiry DAYS — Cache expiry (default: 7)
• --cache-size-limit MB — Cache size limit (default: 100)
• --file-pattern GLOB — Filter by file type (e.g., *.py)
• --max-results N — Limit number of results
• --output-format FORMAT — console, json, or md

Semantic Search Setup

Semantic search provides meaning-based code discovery (e.g., "find the authentication handler" finds auth code regardless of naming).

Install

pip install mcp_beacon[semantic]

This installs:

• sentence-transformers — nomic-embed-text-v1.5 model (~200MB)
• chromadb — Persistent vector database

Usage

1. Build the index (first time or after code changes):

   semantic_index(paths=["/path/to/project"])
   

2. Search by meaning:

   semantic_search(query="authentication middleware")
   semantic_search(query="error handling", language="python")
   

3. Check index stats:

   semantic_stats()
   

How It Works

• Uses nomic-embed-text-v1.5 (256 dimensions) for embeddings
• Stores embeddings in ChromaDB (persistent at ~/.cache/mcp_beaconer/chroma/)
• Incremental indexing — only re-embeds changed files (SHA256 tracking)
• Task prefixes — search_document: for code, search_query: for queries

Language Support

Core Tools (regex-based)

All languages with file extensions: Python, TypeScript, JavaScript, C#, Rust, Go, Java, Kotlin, Ruby, PHP, Swift, C/C++, and more.

AST Tools (tree-sitter)

Language	Package	Status
Python	tree-sitter-python	✅ Full
TypeScript	tree-sitter-typescript	✅ Full
JavaScript	tree-sitter-javascript	✅ Full
C#	tree-sitter-c-sharp	✅ Full
Rust	tree-sitter-rust	✅ Full
Go	tree-sitter-go	✅ Full
Java	tree-sitter-java	✅ Full

Linting (ruff)

Python, TypeScript, JavaScript

Caching

Search results are cached using SQLite (diskcache) for faster repeated queries.

• Default location: ~/.cache/mcp_beaconer
• Default expiry: 7 days
• Default size limit: 100 MB

Uninstallation

Remove the package

pip uninstall mcp_beacon

To also remove all optional dependencies:

pip uninstall mcp_beacon sentence-transformers chromadb tree-sitter gitpython ruff einops

Remove cached data

# Search cache (SQLite)
rm -rf ~/.cache/mcp_beaconer

# Semantic search index (ChromaDB embeddings)
rm -rf ~/.cache/mcp_beaconer/chroma

Remove the embeddings model

The nomic-embed-text-v1.5 model is stored in Hugging Face's cache:

# Remove the model (~200MB)
rm -rf ~/.cache/huggingface/hub/models--nomic-ai--nomic-embed-text-v1.5
rm -rf ~/.cache/huggingface/hub/models--nomic-ai--nomic-bert-2048

Or remove the entire Hugging Face cache (⚠️ removes ALL downloaded models):

rm -rf ~/.cache/huggingface

Remove tree-sitter language packages

pip uninstall tree-sitter-python tree-sitter-typescript tree-sitter-javascript \
              tree-sitter-c-sharp tree-sitter-rust tree-sitter-go tree-sitter-java

Full cleanup

# Remove package + dependencies
pip uninstall mcp_beacon sentence-transformers chromadb tree-sitter \
              gitpython ruff einops tree-sitter-python tree-sitter-typescript \
              tree-sitter-javascript tree-sitter-c-sharp tree-sitter-rust \
              tree-sitter-go tree-sitter-java

# Remove all caches
rm -rf ~/.cache/mcp_beaconer
rm -rf ~/.cache/huggingface

Managing Embeddings and Metadata

mcp_beacon generates several types of persistent data. Here's how to manage them for clean test runs.

Data Locations

Data	Location	Purpose
ChromaDB embeddings	~/.cache/mcp_beaconer/chroma/<hash>/	Semantic search vector index
Search result cache	~/.cache/mcp_beaconer/	SQLite diskcache (7-day TTL, 100MB limit)
Log file	~/.mcp_searcher.log	MCP server logs (5MB rotating)
HuggingFace model	~/.cache/huggingface/hub/models--nomic-ai--nomic-embed-text-v1.5/	Cached embedding model

The <hash> in the ChromaDB path is an MD5 of your workspace root path, so each project gets its own isolated index.

Per-Project Index Management

The semantic index is per-project (keyed by workspace path hash). To reset a specific project's index:

# List all project indexes
ls ~/.cache/mcp_beaconer/chroma/

# Each directory name is md5(workspace_path)[:12]
# Delete a specific project's index
rm -rf ~/.cache/mcp_beaconer/chroma/<hash-for-your-project>

Or programmatically:

from semantic_tools import get_index_path
import shutil

index_path = get_index_path("/path/to/your/project")
shutil.rmtree(index_path, ignore_errors=True)

Running Clean Tests

Tests are self-isolated and don't touch your real cache:

• Each test creates a temporary directory
• Tests call reset_cache() to clear workspace root caching
• tearDown removes the temp directory
• CacheManager tests use custom temp dirs, never touching ~/.cache/mcp_beaconer

# Run tests (already isolated)
python -m pytest tests/

CLI Cache Management

# Clear search cache via CLI
python -m mcp_searcher --clear-cache

# Disable caching for a single run
python -m mcp_searcher --no-cache "query"

Environment Variables for Configuration

Variable	Default	Purpose
MCP_SEMANTIC_MODEL	nomic-ai/nomic-embed-text-v1.5	Embedding model
MCP_SEMANTIC_DIMENSIONS	256	Embedding dimensions
MCP_SEMANTIC_CHUNK_SIZE	50	Lines per chunk
MCP_SEMANTIC_CHUNK_OVERLAP	10	Overlap between chunks
MCP_LOG_FILE	~/.mcp_searcher.log	Log file location
MCP_WORKSPACE_ROOT	auto-detect	Override workspace root

To use a lighter model for faster testing:

export MCP_SEMANTIC_MODEL="all-MiniLM-L6-v2"
export MCP_SEMANTIC_DIMENSIONS=384

Project Structure

src/
├── mcp_beacon.py  # MCP server, 30+ tool definitions
├── mcp_search.py           # Core regex/text search engine + AST patterns
├── file_scanner.py         # Directory walker with exclusion rules
├── cache_manager.py        # SQLite-backed disk caching
├── workspace.py            # Workspace root auto-detection
├── mcp_searcher.py         # CLI entry point
├── output_generator.py     # Console/JSON/Markdown output formatting
├── ast_tools.py            # Tree-sitter AST parsing (multi-language)
├── git_tools.py            # GitPython integration (blame, history)
├── lint_tools.py           # Ruff linting integration
└── semantic_tools.py       # Sentence-transformers + ChromaDB

tests/
├── test_mcp_server.py      # MCP tool tests
├── test_workspace.py       # Workspace detection tests
├── test_mcp_search.py      # Search engine tests
├── test_file_scanner.py    # File scanner tests
├── test_cache_manager.py   # Cache tests
├── test_mcp_searcher.py    # CLI tests
└── test_output_generator.py # Output format tests

Dependencies

Core

mcp[cli]>=1.0.0
diskcache
uvicorn
tree-sitter>=0.21.0
gitpython>=3.1.0
ruff>=0.1.0

Optional (Semantic)

sentence-transformers>=2.0.0
chromadb>=0.4.0

Optional (LSP)

python-lsp-server[all]>=1.7.0

Running Tests

python -m unittest discover -s tests

Building

pip install build
python -m build

License

MIT License — see LICENSE.