Scout
Semantic code search indexer for AI tools via the Model Context Protocol (MCP).
⚡ Want to get started quickly? See QUICKSTART.md for a 5-minute setup guide.
Documentation
- QUICKSTART.md - Get running in 5 minutes
- README.md (this file) - Overview and reference
- docs/CONFIGURATION.md - Configuration options
- docs/TROUBLESHOOTING.md - Common issues and solutions
- docs/ARCHITECTURE.md - System architecture and internals
- TESTING.md - Testing guide
- CONTRIBUTING.md - How to contribute
- 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 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:
python3 --version
If you need to install or upgrade Python:
- macOS:
brew install python@3.11or 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)
- Clone the repository:
git clone https://github.com/gkatechis/Scout.git
cd Scout
- Run the setup script:
./setup.sh
This script will:
- Create a virtual environment at
./venv - Install all dependencies
- Generate
.mcp.jsonconfiguration 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.
Manual Setup (Click to expand)
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:
- Clone the repository:
git clone https://github.com/gkatechis/Scout.git
cd Scout
- Create and activate a virtual environment:
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -e .
- Create configuration directory:
mkdir -p ~/.scout
- Configure MCP integration (for Claude Code or other MCP clients):
cp .mcp.json.example .mcp.json
# Edit .mcp.json and update paths to your installation directory
- (Optional) Configure environment variables if needed: See docs/CONFIGURATION.md for advanced configuration options.
Quick Start
1. Activate Virtual Environment
Before using any commands, activate the virtual environment:
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:
scout init
This wizard will:
- Verify your installation
- Add your first repository
- Run a demo search
- Explain next steps
3. Add Repositories
# 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
# 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:
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 indexremove_repo- Remove a repository from the stacklist_repos- List all indexed repositoriesget_repo_stats- Get detailed repository statisticsreindex_repo- Force reindex a repository
Cross-Repo Analysis
get_cross_repo_dependencies- Find dependencies between repositoriessuggest_missing_repos- Suggest repositories to addget_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.
Troubleshooting
For common issues and solutions, see 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.
Testing
# 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 for the complete testing guide.
Contributing
We welcome contributions! Please see 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