侦察兵
通过模型上下文协议（MCP）为人工智能工具提供语义代码搜索索引器。
⚡ 想快速开始吗？ 看 QUICKSTART.md 获取5分钟的设置指南。
文档
- QUICKSTART.md -5分钟后开始跑步
- README.md （此文件）-概述和参考
- docs/CONFIGURATION.md -配置选项
- docs/TROUBLESHOOTING.md -常见问题和解决方案
- docs/ARCHITECTURE.md -系统架构和内部
- 测试.md -测试指南
- 贡献.md -如何做出贡献
- 代理人。医学博士 -AI编码代理说明
适用于AI编码代理
如果你是一个从事这个项目的人工智能代理，请阅读 代理人。医学博士 第一。它包含使用Beads问题跟踪在会话中系统地管理任务的说明。
概述
Scout为任何兼容MCP的LLM（Claude等）提供智能代码搜索功能。它使用语义嵌入对存储库进行索引，实现自然语言代码搜索、符号查找和跨存储库依赖性分析。
特性
- 语义搜索：自然语言查询按含义查找相关代码，而不仅仅是关键字
- 多语言支持：Python、JavaScript、TypeScript、Ruby、Go
- 交叉回购分析：检测依赖关系并建议缺少的存储库
- 增量更新：仅在需要时跟踪git提交和重新索引
- MCP集成：适用于任何兼容MCP的LLM客户端
- 堆栈管理：仓库集合的持久配置
安装
快速入门： 大多数用户应该使用自动设置脚本。仅当自动脚本失败或需要自定义配置时，才使用手动设置。
先决条件
Python 3.10或更高版本 -检查您的版本：
python3 --version如果你需要安装或升级Python：
- macOS:
brew install python@3.11或从以下网址下载https://python.org/downloads/ - Ubuntu/Debian:
sudo apt install python3.11 python3.11-venv - 视窗：从下载https://python.org/downloads/
自动设置（推荐）
- 克隆存储库：
git clone https://github.com/gkatechis/Scout.git
cd Scout- 运行安装脚本：
./setup.sh此脚本将：
- 在以下位置创建虚拟环境
./venv - 安装所有依赖项
- 生成
.mcp.json具有正确路径的配置 - 为方便起见，可以选择添加shell别名
环境变量为 可选的 -setup.sh配置了合理的默认值。有关高级配置（自定义数据库路径等），请参阅 配置.md.
Manual Setup (Click to expand)
仅在以下情况下使用此方法：
- 自动设置脚本失败
- 您需要自定义Python版本或依赖关系管理
- 您正在将Scout集成到现有项目中
步骤：
- 克隆存储库：
git clone https://github.com/gkatechis/Scout.git
cd Scout- 创建并激活虚拟环境：
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项：
pip install -e .- 创建配置目录：
mkdir -p ~/.scout- 配置MCP集成（适用于Claude Code或其他MCP客户端）：
cp .mcp.json.example .mcp.json
# Edit .mcp.json and update paths to your installation directory- （可选）如果需要，配置环境变量：
看 docs/CONFIGURATION.md 用于高级配置选项。
快速开始
1.激活虚拟环境
在使用任何命令之前，请激活虚拟环境：
source venv/bin/activate每次打开新终端时，您都需要激活venv。
2.交互式设置
最简单的开始方法：
scout init此向导将：
- 验证您的安装
- 添加您的第一个存储库
- 运行演示搜索
- 解释接下来的步骤
3.添加存储库
# 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-name4.与MCP客户端一起使用
配置后 .mcp.json，当您使用像Claude Code这样的MCP客户端时，MCP服务器会自动启动。
CLI命令参考
# Getting started
scout init # Interactive setup wizard
scout check # Verify installation
# Repository management
scout add
# Add local repository
scout add # 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 # Auto-reindex on git pull有关任何命令的详细帮助：
scout --help
scout --helpMCP工具参考
MCP服务器公开了13个按功能组织的工具：
人工智能问答（推荐）
answer_question -询问有关代码库的问题并获得答案
- 返回AI代理的相关代码片段+文件引用+分析提示
- 示例：“身份验证是如何工作的？”→ Agent分析代码并对其进行解释
- 最适合： 终端用户询问有关代码库的问题
搜索工具
semantic_search -自然语言代码搜索
- 返回包含元数据（文件、行、相关性分数）的代码段列表
- 示例：“身份验证逻辑”→ 返回10个相关代码片段
find_definition -查找符号的定义位置
- 示例：“authenticate_user”→ 显示函数的定义位置
find_references -查找符号的所有用法
- 示例：“authenticate_user”→ 显示对此函数的所有调用
find_related_code -查找与架构相关的文件
- 示例：给定“auth/login.py”→ 查找其他与身份验证相关的文件
库管理
add_repo_to_stack-将新存储库添加到索引remove_repo-从堆栈中删除存储库list_repos-列出所有索引存储库get_repo_stats-获取详细的存储库统计信息reindex_repo-强制重新索引存储库
交叉回购分析
get_cross_repo_dependencies-查找存储库之间的依赖关系suggest_missing_repos-建议添加存储库get_stack_status-获取总体堆栈状态
配置
配置存储在 ~/.scout/stack.json 并跟踪所有索引存储库及其元数据。
有关包括环境变量、自定义数据库位置和高级功能在内的详细配置选项，请参阅 docs/CONFIGURATION.md.
故障排除
有关常见问题和解决方案，请参阅 docs/TROUBLESHOOTING.md.
快速提示：
- 启用调试日志记录：
scout --debug - 检查安装：
scout check - 查看日志：
~/.scout/logs/scout.log
建筑
有关内部架构、组件和索引管道的详细信息，请参阅 docs/ARCHITECTURE.md.
测试
# Activate virtual environment first
source venv/bin/activate
# Run all tests
pytest tests/ -v
# Run specific test file
pytest tests/test_embeddings.py -v看 测试.md 获取完整的测试指南。
贡献
我们欢迎捐款！请看 贡献.md 用于：
- 开发设置
- 代码风格指南（黑色、flake8、isort）
- 测试要求
- 拉取请求流程
- CI/CD管道信息
许可证
\[在此处添加您的许可证\]
支持
- 文档：请参阅本README顶部列出的文档
- 问题：通过以下方式报告错误或请求功能