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:

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:

2. Run the setup script:

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.

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:

2. Create and activate a virtual environment:

3. Install dependencies:

4. Create configuration directory:

5. Configure MCP integration (for Claude Code or other MCP clients):

6. (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:

You'll need to activate the venv each time you open a new terminal.

2. Interactive Setup

The easiest way to get started:

This wizard will:

• Verify your installation

• Add your first repository

• Run a demo search

• Explain next steps

3. Add Repositories

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

For detailed help on any command:

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.

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

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