Metadata-Version: 2.4
Name: mcp_beacon
Version: 0.4.3
Summary: A fast, token-efficient MCP server for codebase search. AST parsing, semantic search, linting, git integration. Multi-language support.
Author-email: Wilber Turcios <wilberturcios123@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/WilTurcios/mcp-beacon
Project-URL: Bug Tracker, https://github.com/WilTurcios/mcp-beacon/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: diskcache
Requires-Dist: uvicorn
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: ruff>=0.1.0
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.0.0; extra == "semantic"
Requires-Dist: chromadb>=0.4.0; extra == "semantic"
Provides-Extra: lsp
Requires-Dist: python-lsp-server[all]>=1.7.0; extra == "lsp"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.0.0; extra == "all"
Requires-Dist: chromadb>=0.4.0; extra == "all"
Requires-Dist: python-lsp-server[all]>=1.7.0; extra == "all"
Dynamic: license-file

# 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](https://github.com/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

```bash
pip install mcp_beacon
```

### Optional Extras

```bash
# 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):

```bash
# 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:**

```bash
# 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):**

```bash
# 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`:
```json
{
  "mcp": {
    "codebase-searcher": {
      "type": "local",
      "command": ["python", "-m", "mcp_beacon"],
      "enabled": true
    }
  }
}
```

**Remote (Streamable HTTP)** — `opencode.jsonc`:
```json
{
  "mcp": {
    "codebase-searcher": {
      "type": "remote",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

### Claude Desktop

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

### Antigravity / Web Clients (SSE)

Start the server:
```bash
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:

```json
{
  "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`):

```markdown
<!-- 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:
```bash
mcp-searcher-server --transport sse --host 127.0.0.1 --port 8000
```

Environment variables:
```bash
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:

```bash
# 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

```bash
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

```bash
pip uninstall mcp_beacon
```

To also remove all optional dependencies:

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

### Remove cached data

```bash
# 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:

```bash
# 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):

```bash
rm -rf ~/.cache/huggingface
```

### Remove tree-sitter language packages

```bash
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

```bash
# 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
```

## 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

```bash
python -m unittest discover -s tests
```

## Building

```bash
pip install build
python -m build
```

## License

MIT License — see [LICENSE](./LICENSE).
