mcp-beacon 0.4.0__tar.gz

mcp_beacon-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Wilber Turcios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_beacon-0.4.0/PKG-INFO

@@ -0,0 +1,510 @@
+Metadata-Version: 2.4
+Name: mcp-beacon
+Version: 0.4.0
+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_codebase_searcher-0.4.0-py3-none-any.whl
+
+# Install with semantic extras (edit the .whl name if needed)
+pip install "dist/mcp_codebase_searcher-0.4.0-py3-none-any.whl[semantic]"
+
+# Install with all extras
+pip install "dist/mcp_codebase_searcher-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_codebase_searcher-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_codebase_search"],
+      "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_codebase_search"]
+    }
+  }
+}
+```
+
+### 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_codebase_search"],
+  "env": {
+    "MCP_WORKSPACE_ROOT": "/path/to/your/project"
+  }
+}
+```
+
+## 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_codebase_searcher/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_codebase_searcher`
+- **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_codebase_searcher
+
+# Semantic search index (ChromaDB embeddings)
+rm -rf ~/.cache/mcp_codebase_searcher/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_codebase_searcher
+rm -rf ~/.cache/huggingface
+```
+
+## Project Structure
+
+```
+src/
+├── mcp_codebase_search.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).