MCP Indexer

# Scout Semantic code search indexer for AI tools via the Model Context Protocol (MCP). ⚡ **Want to get started quickly?** See [QUICKSTART.md](QUICKSTART.md) for a 5-minute setup guide. ## Documentation - **[QUICKSTART.md](QUICKSTART.md)** - Get running in 5 minutes - **[README.md](README.md)** (this file) - Overview and reference - **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)** - Configuration options - **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture and internals - **[TESTING.md](TESTING.md)** - Testing guide - **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute - **[AGENTS.MD](AGENTS.MD)** - Instructions for AI coding agents ## For AI Coding Agents **If you're an AI agent working on this project**, please read [AGENTS.MD](AGENTS.MD) first. It contains instructions for using Beads issue tracking to manage tasks systematically across sessions. ## Overview Scout provides intelligent code search capabilities to any MCP-compatible LLM (Claude, etc.). It indexes your repositories using semantic embeddings, enabling natural language code search, symbol lookups, and cross-repo dependency analysis. ## Features - **Semantic Search**: Natural language queries find relevant code by meaning, not just keywords - **Multi-Language Support**: Python, JavaScript, TypeScript, Ruby, Go - **Cross-Repo Analysis**: Detect dependencies and suggest missing repos - **Incremental Updates**: Track git commits and reindex only when needed - **MCP Integration**: Works with any MCP-compatible LLM client - **Stack Management**: Persistent configuration for repo collections ## Installation **Quick Start:** Most users should use the automated setup script. Use manual setup only if the automated script fails or you need custom configuration. ### Prerequisites **Python 3.10 or higher** - Check your version: ```bash python3 --version ``` If you need to install or upgrade Python: - **macOS**: `brew install python@3.11` or download from https://python.org/downloads/ - **Ubuntu/Debian**: `sudo apt install python3.11 python3.11-venv` - **Windows**: Download from https://python.org/downloads/ ### Automated Setup (Recommended) 1. Clone the repository: ```bash git clone https://github.com/gkatechis/Scout.git cd Scout ``` 2. Run the setup script: ```bash ./setup.sh ``` This script will: - Create a virtual environment at `./venv` - Install all dependencies - Generate `.mcp.json` configuration with correct paths - Optionally add shell aliases for convenience Environment variables are **optional** - setup.sh configures sensible defaults. For advanced configuration (custom database paths, etc.), see [CONFIGURATION.md](docs/CONFIGURATION.md). <details> <summary><b>Manual Setup (Click to expand)</b></summary> **Use this method only if:** - The automated setup script fails - You need custom Python version or dependency management - You're integrating Scout into an existing project **Steps:** 1. Clone the repository: ```bash git clone https://github.com/gkatechis/Scout.git cd Scout ``` 2. Create and activate a virtual environment: ```bash python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. Install dependencies: ```bash pip install -e . ``` 4. Create configuration directory: ```bash mkdir -p ~/.scout ``` 5. Configure MCP integration (for Claude Code or other MCP clients): ```bash cp .mcp.json.example .mcp.json # Edit .mcp.json and update paths to your installation directory ``` 6. (Optional) Configure environment variables if needed: See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for advanced configuration options. </details> ## Quick Start ### 1. Activate Virtual Environment **Before using any commands, activate the virtual environment:** ```bash source venv/bin/activate ``` You'll need to activate the venv each time you open a new terminal. ### 2. Interactive Setup The easiest way to get started: ```bash scout init ``` This wizard will: - Verify your installation - Add your first repository - Run a demo search - Explain next steps ### 3. Add Repositories ```bash # Add a local repository scout add /path/to/local/repo # Add from GitHub (auto-clones and indexes) scout add https://github.com/user/repo # Specify a custom name scout add https://github.com/user/repo --name my-custom-name ``` ### 4. Use with MCP Clients Once configured in `.mcp.json`, the MCP server automatically starts when you use an MCP client like Claude Code. ## CLI Commands Reference ```bash # Getting started scout init # Interactive setup wizard scout check # Verify installation # Repository management scout add <path> # Add local repository scout add <url> # Clone and add from GitHub scout status # Show stack status # Keeping repos up to date scout check-updates # Check which repos need reindexing scout reindex-changed # Reindex repos with new commits # Recovery and maintenance scout recover # Recover from interrupted indexing # Git integration scout install-hook <repo-path> # Auto-reindex on git pull ``` For detailed help on any command: ```bash scout --help scout <command> --help ``` ## MCP Tools Reference The MCP server exposes 13 tools organized by functionality: ### AI-Powered Q&A (Recommended) **`answer_question`** - Ask questions about your codebase and get answers - Returns relevant code snippets + file references + analysis prompt for the AI agent - Example: "How does authentication work?" → Agent analyzes code and explains it - **Best for:** End users asking questions about codebases ### Search Tools **`semantic_search`** - Natural language code search - Returns list of code snippets with metadata (file, lines, relevance scores) - Example: "authentication logic" → Returns 10 relevant code snippets **`find_definition`** - Find where a symbol is defined - Example: "authenticate_user" → Shows where the function is defined **`find_references`** - Find all usages of a symbol - Example: "authenticate_user" → Shows all calls to this function **`find_related_code`** - Find architecturally related files - Example: Given "auth/login.py" → Finds other auth-related files ### Repository Management - **`add_repo_to_stack`** - Add a new repository to index - **`remove_repo`** - Remove a repository from the stack - **`list_repos`** - List all indexed repositories - **`get_repo_stats`** - Get detailed repository statistics - **`reindex_repo`** - Force reindex a repository ### Cross-Repo Analysis - **`get_cross_repo_dependencies`** - Find dependencies between repositories - **`suggest_missing_repos`** - Suggest repositories to add - **`get_stack_status`** - Get overall stack status ## Configuration Configuration is stored at `~/.scout/stack.json` and tracks all indexed repositories with their metadata. For detailed configuration options including environment variables, custom database locations, and advanced features, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md). ## Troubleshooting For common issues and solutions, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md). Quick tips: - Enable debug logging: `scout --debug <command>` - Check installation: `scout check` - View logs: `~/.scout/logs/scout.log` ## Architecture For details on the internal architecture, components, and indexing pipeline, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## Testing ```bash # Activate virtual environment first source venv/bin/activate # Run all tests pytest tests/ -v # Run specific test file pytest tests/test_embeddings.py -v ``` See [TESTING.md](TESTING.md) for the complete testing guide. ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for: - Development setup - Code style guidelines (black, flake8, isort) - Testing requirements - Pull request process - CI/CD pipeline information ## License [Add your license here] ## Support - **Documentation**: See the docs listed at the top of this README - **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/gkatechis/Scout/issues)