---
name: code-search
description: This skill should be used when the user asks to "index code", "search files", "find symbols", "search code content", "get code structure", "analyze repository", "query logs", "benchmark code search", "code search performance", or needs to perform high-performance code repository indexing and search operations via MCP. Use for code exploration, codebase analysis, code navigation, and code understanding tasks.
version: 2.1.0
---

# Code Search MCP - 完整使用指南

## 概述

Code Search MCP 是一个高性能的代码仓库索引和搜索 MCP 服务器，专为 AI 助手设计。

### 核心性能指标 (实测验证)

| 指标 | 实测数值 | 说明 |
|------|----------|------|
| 100 文件全量索引 | ~0.38s | 首次索引 |
| 100 文件增量索引 | ~0.001s | 无变更时 |
| 搜索延迟 | ~0.2ms | 单次搜索 |
| 内存占用 | < 50MB | 运行时 |

### 核心能力

1. **智能索引**: 增量索引，仅处理变更文件
2. **多语言支持**: 15+ 编程语言
3. **FTS5 全文搜索**: SQLite 内置高性能全文搜索
4. **符号解析**: 函数、类、方法、变量
5. **可观测性**: 完整的调用日志和性能统计

---

## 触发条件

### 索引操作
- "索引代码仓库" / "index repository"
- "重建索引" / "rebuild index"
- "更新索引" / "update index"

### 搜索操作
- "搜索文件" / "find files"
- "查找符号" / "find symbols" / "search function"
- "搜索代码" / "search code" / "find in code"

### 分析操作
- "获取文件结构" / "get file structure"
- "代码分析" / "code analysis"
- "代码统计" / "code statistics"

---

## 核心原则：渐进式获取

**不要一次性获取所有信息**，按需获取：

```
Level 1: 快速定位（50 tokens）
  → 符号位置、文件路径、签名

Level 2: 上下文补充（200 tokens）
  → 周围代码（context）

Level 3: 完整代码（按需）
  → 完整源代码
```

**规则**：
- 先返回 Level 1，AI 需要更多时再获取 Level 2
- 除非明确需要，否则不获取完整源代码
- 利用返回的 `context` 字段，大多数情况足够

---

## 工具选择决策树

```
用户请求内容分析：
│
├── "搜索 xxx" （不确定用什么）
│   └── smart_search （推荐，自动选择）
│
├── "文件在哪里" / "找配置文件" / "找测试文件"
│   └── find_files
│
├── "函数/类在哪里定义" / "找到 xxx 函数" / "xxx 在哪"
│   └── find_symbols
│       └── 如果需要更多上下文 → get_structure
│
├── "这段代码在哪里被使用" / "搜索所有用 xxx 的地方"
│   └── find_content
│
├── "这个文件讲什么" / "获取文件结构"
│   └── get_structure
│
├── "代码库情况如何" / "有多少文件"
│   └── get_stats
│
└── "搜索无结果" / "不知道搜什么"
    └── get_suggestions
```

---

## MCP 工具详解

本服务提供 **10 个 MCP 工具**：

### 1. index_repository

索引代码仓库，支持增量模式。

**参数:**
```python
{
    "repo_path": "/path/to/repo",   # 必填：仓库路径
    "force_rebuild": False           # 可选：是否全量重建
}
```

**返回:**
```python
{
    "success": True,
    "stats": {
        "files_indexed": 150,
        "files_skipped": 50,
        "files_deleted": 5,
        "symbols": 1200,
        "content_blocks": 5000,
        "elapsed_seconds": 0.32
    },
    "is_incremental": True
}
```

**最佳实践:**
- 首次使用 `force_rebuild=True`
- 后续使用 `force_rebuild=False` 增量更新
- 100 文件通常 < 1 秒完成

---

### 2. find_files

按文件名或路径搜索。

**参数:**
```python
{
    "query": "test",                    # 搜索关键词
    "extensions": [".py", ".js"],      # 扩展名过滤
    "limit": 20
}
```

**返回:**
```python
{
    "results": [
        {
            "path": "/src/utils/test_helper.py",
            "name": "test_helper.py",
            "type": "file",
            "size": 1234,
            "modified": "2024-01-01T00:00:00"
        }
    ],
    "search_metadata": {
        "indexed_files": 150,
        "total_matches": 5,
        "search_time_ms": 0.2
    }
}
```

**使用场景:**
```python
# 找所有测试文件
find_files: query="test", extensions=[".test.py", "_test.py"]

# 找配置文件
find_files: query="config", extensions=[".json", ".yaml", ".toml"]
```

---

### 3. smart_search 🤖

**智能搜索推荐工具！** 自动处理索引检查和搜索策略选择。

**参数:**
```python
{
    "repo_path": "/path/to/repo",    # 可选：代码仓库路径
    "query": "handleClick",          # 必填：搜索关键词
    "search_type": "auto",          # auto | content | symbol | file
    "limit": 20
}
```

**特点:**
- 自动检测是否需要索引，未索引时自动索引
- 自动选择最优搜索策略
- 避免无效调用

**使用示例:**
```python
# 自动模式（推荐）
smart_search: query="handleClick"

# 指定搜索类型
smart_search: query="User", search_type="symbol"
smart_search: query="config", search_type="file"
```

**最佳实践：**
- 首选 smart_search，它会自动处理复杂情况
- 只有需要精细控制时才使用具体工具

---

### 4. find_symbols

搜索代码符号。**这是最常用的工具**。

**参数:**
```python
{
    "query": "calculate",              # 搜索关键词
    "kind": "function",               # function | class | method | variable | all
    "file": "*.py",                  # 文件过滤
    "limit": 20
}
```

**返回:**
```python
{
    "symbols": [
        {
            "name": "calculate_total",
            "kind": "function",
            "file_path": "/src/utils.py",
            "file_name": "utils.py",
            "line": 42,
            "line_number": 42,
            "signature": "def calculate_total(items: List) -> int",
            "context": {
                "before": ["def helper():", "    ..."],
                "after": ["    return result", "def another():"]
            }
        }
    ],
    "search_metadata": {
        "indexed_files": 150,
        "total_matches": 1,
        "search_time_ms": 0.2
    }
}
```

**高级用法:**
```python
# 搜索所有类
find_symbols: query="", kind="class"

# 搜索特定文件的函数
find_symbols: query="", kind="function", file="**/utils/*.py"

# 模糊搜索
find_symbols: query="handle"
```

---

### 5. find_content

全文搜索代码内容。

**参数:**
```python
{
    "query": "def.*main",      # 搜索内容
    "regex": True,             # 是否正则
    "file_pattern": "*.py",    # 文件过滤
    "context_lines": 3,        # 上下文行数（默认3）
    "limit": 20
}
```

**搜索模式:**

| 模式 | 示例 | 说明 |
|------|------|------|
| 精确搜索 | `"TODO"` | 查找 TODO 注释 |
| 通配符 | `"*error*"` | 包含 error 的行 |
| 正则 | `"def\s+\w+\("` | 函数定义 |
| 多条件 | `"import.*requests"` | 特定 import |

**返回:**
```python
{
    "results": [
        {
            "file_path": "/src/main.py",
            "line": 10,
            "content": "def main():",
            "context": {
                "before": ["import sys", ""],
                "after": ["    pass", ""]
            }
        }
    ],
    "search_metadata": {
        "indexed_files": 150,
        "total_matches": 5,
        "search_time_ms": 0.5
    }
}
```

---

### 6. get_structure

获取文件结构。

**参数:**
```python
{
    "file_path": "/path/to/file.py"
}
```

**返回:**
```python
{
    "path": "/src/utils.py",
    "language": "python",
    "symbols": [
        {"name": "MyClass", "kind": "class", "line": 10},
        {"name": "my_method", "kind": "method", "line": 15},
        {"name": "helper", "kind": "function", "line": 30}
    ]
}
```

---

### 7. get_stats

索引统计。

**返回:**
```python
{
    "stats": {
        "files": 150,
        "symbols": 1200,
        "content_blocks": 5000,
        "indexed_repos": ["/path/to/repo1", "/path/to/repo2"],
        "languages": {"python": 50, "javascript": 30}
    }
}
```

---

### 8. get_logs

调用日志查询。

**参数:**
```python
{
    "tool_name": "find_files",     # 可选过滤
    "success": False,              # 错误日志
    "start_time": "2024-01-01T00:00:00",
    "limit": 10,                   # 默认 10
    "format": "json"               # json | markdown
}
```

---

### 9. get_call_stats

调用统计。

**返回:**
```python
{
    "call_stats": {
        "total_calls": 1000,
        "success_count": 980,
        "error_count": 20,
        "success_rate": 98.0,
        "avg_duration_ms": 12.5,
        "by_tool": [
            {
                "tool_name": "find_files",
                "count": 500,
                "avg_duration": 8.2,
                "max_duration": 50.0
            }
        ]
    }
}
```

---

### 10. get_suggestions

获取智能搜索建议。

**参数:**
```python
{
    "query": "fetch",     # 必填：当前搜索词
    "limit": 10           # 可选：返回建议数量
}
```

**返回:**
```python
{
    "suggestions": {
        "query": "fetch",
        "pattern_suggestions": [
            {"pattern": "fetch", "keywords": ["fetch", "axios", "request", "http"]}
        ],
        "related_searches": ["axios", "request", "http"],
        "symbol_suggestions": [
            {"name": "fetchData", "kind": "function"},
            {"name": "ApiHandler", "kind": "class"}
        ]
    }
}
```

**代码模式关联:**
| 模式 | 关联关键词 |
|------|------------|
| fetch | fetch, axios, request, http, get, post |
| api | api, endpoint, route, controller, handler |
| async | async, await, promise, then, coroutine |
| error | error, exception, throw, catch, raise |
| test | test, spec, mock, describe, it, expect |

---

## 高效工作流

### 场景 0: 快速搜索（推荐）

```
# 首选 smart_search，一键搞定
smart_search: query="handleClick"

# 自动处理：
# 1. 检查是否已索引
# 2. 未索引则自动索引
# 3. 自动选择搜索策略
# 4. 返回优化结果
```

### 场景 1: 理解新代码库

```
1. get_stats
   → 了解代码库规模

2. find_files: query="", extensions=[".py"]
   → 列出主要文件类型

3. find_symbols: query="", kind="class", limit=20
   → 找到核心类

4. get_structure: file_path="核心文件"
   → 理解文件结构
```

### 场景 2: 定位并理解函数

```
1. find_symbols: query="函数名"
   → 定位函数位置（已包含 context）

2. 大多数情况这就够了！
   → 利用返回的 signature 和 context

3. 如果需要更多：
   get_structure: file_path="文件路径"
   → 获取完整上下文
```

### 场景 3: 搜索使用位置

```
1. find_content: query="关键词"
   → 找到所有使用位置

2. 查看每条的 context
   → 了解使用场景

3. 如果需要看完整代码：
   按需调用 Read 工具
```

---

## 错误处理

### 常见错误与解决

| 错误码 | 原因 | 解决策略 |
|--------|------|----------|
| NOT_INDEXED | 未索引 | 调用 index_repository |
| NO_RESULTS | 无结果 | 尝试更短关键词，使用 get_suggestions |
| EXECUTION_ERROR | 执行错误 | 检查参数，查看错误信息 |

### 搜索无结果时

```python
# ❌ 错误做法：直接放弃
"没有找到结果"

# ✅ 正确做法：利用 suggestion
{
    "error": {
        "code": "NO_RESULTS",
        "suggestion": "Try shorter keywords like 'handle' or 'auth'",
        "example": "find_symbols: query='handle', kind='function'"
    }
}

# AI 应该：
1. 读取 suggestion 字段
2. 按照建议调整搜索
3. 重新尝试
# 而不是直接告诉用户"找不到"
```

---

## 协作指南

### Code Search MCP + Read 工具

```
MCP 负责定位 → Read 负责读取内容

1. find_symbols: 找到函数位置
2. 如果 context 不够：
3. Read: 读取完整源代码
```

### Code Search MCP + Edit 工具

```
MCP 负责理解 → Edit 负责修改

1. find_symbols: 找到目标函数
2. get_structure: 理解文件结构
3. Read: 读取完整代码
4. Edit: 进行修改
```

---

## 性能优化

### 1. 增量索引优先

```python
# ✅ 始终使用增量
index_repository: repo_path, force_rebuild=false
```

### 2. 合理限制结果

```python
# ✅ 合理限制
find_files: query="test", limit=20
find_content: query="pattern", limit=50
```

### 3. 利用元数据

```python
# 返回结果包含 metadata
{
    "search_metadata": {
        "indexed_files": 150,
        "total_matches": 5,
        "search_time_ms": 0.2
    }
}

# 利用这些信息：
# - indexed_files: 确认搜索范围
# - search_time_ms: 性能监控
# - total_matches: 判断是否需要调整
```

---

## 支持的语言

| 语言 | 扩展名 | 符号支持 |
|------|--------|----------|
| Python | .py | 函数、类、方法 |
| JavaScript | .js, .jsx | 函数、类 |
| TypeScript | .ts, .tsx | 函数、类、接口 |
| Go | .go | 函数、结构体 |
| Rust | .rs | 函数、结构体 impl |
| Java | .java | 类、方法 |
| C/C++ | .c, .cpp, .h | 函数、类 |
| Ruby | .rb | 方法、类 |
| PHP | .php | 函数、类 |
| Swift | .swift | 函数、类 |
| Kotlin | .kt | 函数、类 |
| Scala | .scala | 函数、类 |
| Vue | .vue | 函数、组件 |
| Svelte | .svelte | 函数、组件 |

---

## 故障排查

### 索引失败
```python
# 检查日志
get_logs: success=False, limit=20

# 常见原因:
# - 路径不存在
# - 权限不足
# - 文件编码问题
```

### 搜索无结果
```python
# 1. 确认已索引
get_stats: {}

# 2. 扩大搜索范围
find_content: query="keyword"

# 3. 使用 get_suggestions 获取建议
get_suggestions: query="原关键词"
```

---

## 快速参考表

| 用户意图 | 首选工具 | 备选工具 |
|----------|----------|----------|
| **智能搜索（推荐）** | smart_search | - |
| 找文件 | find_files | - |
| 找定义 | find_symbols | find_content |
| 搜内容 | find_content | - |
| 理解结构 | get_structure | - |
| 了解规模 | get_stats | - |
| 搜索无结果 | get_suggestions | - |
| 性能监控 | get_call_stats | get_logs |

---

**核心原则**：渐进式获取、按需加载。优先返回位置和签名（Level 1），需要更多时再获取上下文（Level 2），只有必要时才读取完整代码（Level 3）。
