代码搜索MCP
项目介绍
技术文档摘要
CodeSearch MCP Server
一个针对 Claude Code 的快速代码搜索和导航工具，帮助您即时找到文件、搜索代码、导航符号并理解项目。只需向 Claude 提问“查找我所有的 React 组件”、“显示最近的更改”或“查找 UserService 的定义”，即可在毫秒内获得结果。
使用 .NET 9.0 和 COA MCP 框架 2.1.8 构建，具有由 Lucene 提供支持的搜索功能，并通过 AI 进行优化响应。
🚀 功能
- ⚡ 雷霆般的快速搜索：Lucene 索引使数百万行代码的即时搜索成为可能
- 🔍 智能代码分析：自定义分析器保留了如
: ITool、[Fact]等代码模式，并增强了驼峰命名法的分词处理，支持完整的泛型类型（搜索“McpToolBase”时可找到McpToolBase<TParams, TResult>） - 📁 文件发现：基于模式的文件和目录搜索，支持模糊匹配
- 🧬 高级类型提取：从 25 种编程语言中提取类型、接口、类和方法，使用 julie-codesearch Rust 命令行工具（包括 C#、TypeScript、JavaScript、Python、Java、Rust、Go、C/C++、PHP、Ruby、Swift、Kotlin 等 13 种更专业的语言）
- 🧭 代码导航：无需编译即可进行符号搜索、查找引用和跳转到定义
- 📝 行级搜索：获取所有出现位置及其精确行号——比 grep 更快，且有结构化的 JSON 输出
- 🔄 搜索与替换：在整个代码库中批量查找/替换，带有预览模式以确保安全，支持模糊匹配以处理拼写错误和变体
- 🔧 智能重构：使用字节偏移量替换进行 AST 意识的符号重命名——比文本搜索/替换更安全
- ✏️ 手术级行编辑：插入、替换或删除特定行范围，无需读取整个文件
- ⏱️ 最近修改的文件：跟踪并查找最近修改的文件
- 🔗 调用路径追踪：层次化的调用链分析，带有语义桥接，支持跨语言追踪
- 🧠 语义搜索：使用嵌入式向量相似性搜索来查找概念上相似的代码
- 🎯 实时更新：文件监视器会在更改时自动更新索引
- 📊 AI 优化：基于置信度的结果限制，提高令牌效率
- 🏠 混合本地索引：索引存储在工作区
.coa/codesearch/indexes/中，支持多工作区
性能
- 启动时间：< 500ms
- 文本搜索：< 10ms 已索引
- 文件搜索：< 50ms
- 内存使用：< 200MB 典型
- 索引大小：约每 1000 个文件 1MB
🎯 令牌优化
- 60-85% 令牌减少：通过基于置信度的限制实现
- 渐进披露：首先提供基本结果，完整数据通过资源 URI 获取
- 智能上下文处理：包含上下文行时结果较少
- 标准化响应：所有工具均采用一致的格式
🧬 支持的语言类型提取
类型提取系统支持 25 种编程语言，使用 julie-codesearch，这是一个带有原生 tree-sitter 绑定的 Rust 命令行工具：
核心语言（10种）：
- Rust • TypeScript • JavaScript • Python • Java • C# • PHP • Ruby • Swift • Kotlin
系统语言（4种）：
- C • C++ • Go • Lua
专业语言（11种）：
- GDScript • Vue SFCs • Razor • SQL • HTML • CSS • Regex • Bash • PowerShell • Zig • Dart
特殊功能：
- Vue 单文件组件：从
<script>块中提取类型（TS/JS） - Razor/Blazor：从
@code和@functions块中提取类型 - 混合语言：处理模板系统中的嵌入代码
- 跨平台二进制文件：构建中包含预编译的 julie-codesearch 二进制文件，适用于 macOS (ARM64)、Linux (x64) 和 Windows (x64)
- 零依赖：无需手动安装 tree-sitter 库——julie-codesearch 二进制文件是独立的
📋 先决条件
- .NET 9.0 SDK 或更高版本
- 无需 tree-sitter 库——julie-codesearch 二进制文件是独立的，并包含在构建中
🚀 快速开始
从源码构建
# 克隆仓库
git clone https://github.com/anortham/coa-codesearch-mcp.git
cd coa-codesearch-mcp
# 构建项目
dotnet build -c Release
添加到 Claude Code
# macOS/Linux
claude mcp add codesearch /path/to/coa-codesearch-mcp/COA.CodeSearch.McpServer/bin/Release/net9.0/COA.CodeSearch.McpServer
# Windows
claude mcp add codesearch C:\path\to\coa-codesearch-mcp\COA.CodeSearch.McpServer\bin\Release\net9.0\COA.CodeSearch.McpServer.exe
添加后：
- 完全重启 Claude Code
- Claude 将具备强大的搜索能力——只需自然地提问！
可选：添加到 .gitignore
# CodeSearch 本地索引（可以重新生成）
.coa/
注意：NuGet 包安装将在未来的版本中提供
🌟 特殊之处
不同于基本的文件搜索，CodeSearch 理解您的代码：
- 智能模式识别：找到
async Task、[Fact]、interface IService模式，增强的驼峰命名法拆分用于泛型类型 - 上下文感知：使用 julie-codesearch 原生 tree-sitter 提取，区分 C# 类和 JavaScript 函数
- 即时结果：在数百万行代码中进行毫秒级搜索
- 模糊匹配：即使名称中有拼写错误也能找到文件
- 内容相似性：使用高级分析“查找类似此文件的文件”
- 近期活动：跟踪您最近的工作
- 多工作区支持：同时索引和搜索多个项目，完全隔离
- 本地存储：索引直接存储在工作区中，快速访问
- 代码导航：无需编译即可进行符号搜索、查找引用和跳转到定义
- 结构化行搜索：优于 grep——返回带有精确行号和上下文的 JSON
- 安全的大批量编辑：搜索/替换的预览模式防止意外更改
- 类型感知：通过 julie-codesearch 从 25 种语言中提取和索引类型，准确导航所有主要编程语言
- 精准编辑：完整的基于行的编辑套件，无需读取整个文件即可进行手术级代码修改
🛠️ 可用工具 - 现在带有智能默认值！ ✨
注意：所有工具都支持智能默认值——大多数参数都是可选的，并默认为合理的值。workspacePath 参数默认为当前工作区目录，在所有工具中均如此。
核心搜索工具
| 工具 | 目的 | 关键参数（其余均为可选） |
|---|---|---|
index_workspace | 为搜索索引文件 | workspacePath（可选，默认为当前目录） |
text_search | 使用语义/模糊/正则模式搜索文件内容 | query（必需），searchMode（可选：“auto”、“exact”、“fuzzy”、“semantic”、“regex”） |
search_files | 🆕 按模式查找文件或目录 | pattern（必需），resourceType（可选：“file”、“directory”、“both”） |
recent_files | 获取最近修改的文件 | timeFrame（可选，例如“2d”、“1w”） |
导航工具
| 工具 | 目的 | 关键参数（其余均为可选） |
|---|---|---|
symbol_search | 按名称查找类、接口、方法 | symbol（必需） |
find_references | 查找符号的所有用法 | symbol（必需） |
goto_definition | 跳转到符号定义 | symbol（必需） |
高级搜索工具
| 工具 | 目的 | 关键参数（其余均为可选） |
|---|---|---|
line_search | 获取所有出现位置及其行号 | pattern（必需） |
search_and_replace | 在文件中替换模式，带有预览和模糊匹配 | searchPattern（必需），replacePattern（可选） |
重构工具
| 工具 | 目的 | 关键参数（其余均为可选） |
|---|---|---|
smart_refactor | 使用字节偏移精度的 AST 意识的符号重命名 | operation（必需），params（必需） |
编辑工具
| 工具 | 目的 | 关键参数（其余均为可选） |
|---|---|---|
edit_lines | 🆕 统一的行编辑（插入/替换/删除） | filePath（必需），operation（必需：“insert”、“replace”、“delete”），startLine（必需） |
分析工具
| 工具 | 目的 | 关键参数（其余均为可选） |
|---|---|---|
get_symbols_overview | 从文件中提取所有符号 | filePath（必需） |
find_patterns | 检测代码模式和质量问题 | filePath（必需） |
trace_call_path | 层次化的调用链分析 | symbol（必需） |
💬 如何与 Claude Code 一起使用
安装后，只需自然地与 Claude Code 对话即可！以下是一些示例：
查找文件和代码
“查找我所有的 TypeScript 文件”
Claude 将搜索项目中的 *.ts 文件
“显示我代码库中所有的异步函数”
Claude 将搜索类似于 "async function" 和 "async Task" 的模式
“查找包含 'UserService' 的文件”
Claude 将搜索文件内容中的术语 "UserService"
“哪些文件在过去两天内被修改过？”
Claude 将显示带有时间戳的最近修改过的文件
项目理解
“查找我所有的 React 组件”
Claude 将查找 .jsx、.tsx 文件和 React 模式
“显示我所有的测试文件”
Claude 将查找文件名或路径中包含 "test"、"spec" 的文件
“查找与 UserController.cs 结构类似的文件”
Claude 将使用内容分析来查找结构上相似的文件
“在我的项目中搜索所有数据库查询”
Claude 将查找 SQL 模式、ORM 调用等
代码导航
“查找 UserService 的定义”
Claude 将直接跳转到 UserService 类的定义处
显示精确的行和列，可选上下文片段
“显示 UpdateUser 方法的所有引用”
Claude 将查找所有调用 UpdateUser 的地方
按文件分组结果，便于扫描
“搜索所有以 Controller 结尾的类”
Claude 将查找所有匹配如 UserController、OrderController 模式的类
使用 julie-codesearch 基于 tree-sitter 的提取，支持 25 种语言的准确结果
“查找 IRepository 接口的所有实现”
Claude 将定位所有实现 IRepository 接口的地方
显示继承关系和使用次数
类型和代码分析
“查找我项目中的所有类和接口”
Claude 将从 25 种语言中提取类型，包括 C#、TypeScript、Python、Java、Rust、Go、C/C++、PHP、Ruby、Swift、Kotlin 等
使用 julie-codesearch 基于 tree-sitter 的提取，达到 LSP 质量的结果
“显示我代码库中的所有函数和方法”
Claude 将解析 25 种语言并提取函数/方法定义及其签名
支持从 C# 到 Bash，再到 GDScript 等专业语言
“查找所有 Vue 组件的方法”
Claude 将解析 Vue SFC 并从 JavaScript/TypeScript 脚本块中提取方法
julie-codesearch 处理模板系统中的嵌入语言
“显示所有 Python 类及其方法”
Claude 将分析 Python 文件并提取类定义及其方法
全面支持 Python 的类层次结构和方法签名
“查找所有 Rust 结构体和实现块”
Claude 将解析 Rust 代码并提取结构体定义及其实现
julie-codesearch 提供原生 Rust tree-sitter 集成
开发工作流
“为搜索索引我的项目”
Claude 将扫描并索引您的文件，以便快速搜索
“查找所有 TODO 注释”
Claude 将搜索 TODO、FIXME、HACK 注释
“显示配置文件”
Claude 将查找 .json、.yaml、.config 文件
高级示例
“查找 Services 目录中 30 天内未修改的文件”
Claude 将使用 recent_files 并结合时间过滤器来查找陈旧代码
“在我的 C# 代码中搜索错误处理模式”
Claude 将使用 text_search 查找 try-catch 块和异常处理
“查找我项目中的所有 API 端点”
Claude 将搜索路由装饰器和端点定义
“显示导入 React 但不使用钩子的文件”
Claude 将结合多个搜索来查找导入 React 但没有使用 useState/useEffect 的文件
行级搜索示例
“显示所有包含 'Thread.Sleep' 的行”
Claude 将使用 line_search 查找所有出现位置及其精确行号
返回结构化的 JSON 而不是纯文本 grep 输出
“查找所有 console.log 语句及其行号”
Claude 将返回每个 console.log 语句及其文件路径和行号
非常适合在生产部署前清理任务
搜索和替换示例
“将所有 'var' 声明替换为 'let' 在我的 JavaScript 文件中”
Claude 将使用 search_and_replace 并首先显示预览
显示更改前的内容
“更新所有版权声明到 2025”
Claude 将查找并替换所有文件中的版权声明
支持复杂的替换模式
模糊匹配示例
“使用模糊匹配替换 getUserData() 即使有拼写错误”
Claude 将使用模糊模式，阈值为 0.7-0.8
找到：getUserData()、getUserDat()（拼写错误）、getUserData ()（空格）、getUserDatta()（双 t）
完美解决不一致代码模式的清理问题
“修复代码库中的方法名称变化”
Claude 将使用模糊搜索查找所有相似的变化
自动处理拼写错误、空格问题和小差异
智能重构示例
“将 UserService 更名为 AccountService”
Claude 将使用 smart_refactor 和 AST 意识的符号重命名
通过 SQLite 标识符表查找所有用法（LSP 质量）
使用字节偏移量替换进行精确、安全的重构
“重构 UpdateUser 方法名称为 UpdateUserAccount”
Claude 将使用符号分析查找所有引用
在精确的字节位置替换（非正则表达式）
预览模式显示应用前的确切更改
🔒 安全性和线程安全性
路径验证
PathResolutionService 实现了全面的路径验证：
- 防止目录遍历：阻止包含 ".." 序列的路径
- 路径长度验证：防止过长的路径（超过 240 字符）
- 输入净化：验证和规范化所有工作区路径
- 跨平台兼容性：处理路径分隔符和特殊文件夹
线程安全性
- 并发元数据访问：信号量锁保护工作区元数据文件
- 原子文件操作：元数据更新使用临时文件和原子替换
- 锁定管理：每个文件的锁定防止并发访问时的损坏
- 安全的文件系统操作：所有 I/O 操作包括错误处理和回退
API 安全性
- 路径解析：内部哈希目录从未通过 HTTP API 暴露
- 实际路径验证：仅返回