Code Search MCP

基于 SQLite 的代码仓库索引 MCP 服务器

概述

Code Search MCP 是一个 MCP（Model Context Protocol）服务器，用于对代码仓库建立索引并提供强大的搜索能力。它使用 SQLite 存储索引数据，支持全文搜索（FTS5）、符号搜索和结构分析。

核心功能

• 代码索引: 自动扫描代码仓库，提取文件、符号（函数、类、方法）和代码内容
• 全文搜索: 基于 SQLite FTS5 的高速全文搜索
• 符号搜索: 按名称搜索函数、类、方法等符号
• 可观测性: 内置日志系统，记录所有工具调用和性能指标

快速开始

安装

pip install code-search-mcp

使用 MCP 客户端

配置你的 MCP 客户端（如 Claude Code）：

{
  "mcpServers": {
    "code-search": {
      "command": "python",
      "args": ["-m", "code_search_mcp"]
    }
  }
}

基本使用

from code_search_mcp import CodeIndexServer

server = CodeIndexServer()

MCP 工具

本服务提供 15 个 MCP 工具：

1. index_repository

索引整个代码仓库。

{
  "name": "index_repository",
  "arguments": {
    "repo_path": "/path/to/repo",
    "force_rebuild": false
  }
}

参数:

• repo_path (必填): 代码仓库路径
• force_rebuild (可选): 是否强制重建索引，默认 false

返回:

{
  "success": true,
  "stats": {
    "files_indexed": 150,
    "symbols": 1200,
    "content_blocks": 5000,
    "elapsed_seconds": 2.5
  }
}

2. find_files

按文件名或路径搜索文件。

{
  "name": "find_files",
  "arguments": {
    "query": "test",
    "extensions": [".py", ".js"],
    "limit": 20
  }
}

3. find_symbols

搜索代码符号（函数、类、方法等）。

{
  "name": "find_symbols",
  "arguments": {
    "query": "calculate",
    "kind": "function",
    "limit": 20
  }
}

4. find_content

在代码内容中进行全文搜索。

{
  "name": "find_content",
  "arguments": {
    "query": "def.*main",
    "regex": true,
    "file_pattern": "*.py",
    "limit": 20
  }
}

5. get_structure

获取单个文件的结构信息，包括顶层符号（函数、类、变量等）。

{
  "name": "get_structure",
  "arguments": {
    "file_path": "/path/to/file.py"
  }
}

参数:

• file_path (必填): 文件路径

返回:

{
  "structure": {
    "file_path": "/path/to/file.py",
    "functions": [{"name": "main", "line": 10, "doc": "主函数"}],
    "classes": [{"name": "Config", "line": 20, "doc": "配置类"}],
    "imports": [...]
  }
}

6. get_stats

获取索引统计信息，包括已索引的文件数、符号数、内容块数等。

{
  "name": "get_stats",
  "arguments": {}
}

返回:

{
  "stats": {
    "total_files": 150,
    "total_symbols": 1200,
    "total_content_blocks": 5000,
    "indexed_repos": ["/path/to/repo1", "/path/to/repo2"],
    "languages": {"python": 50, "javascript": 30, "typescript": 20}
  }
}

7. get_logs

查询工具调用日志，用于可观测性和调试。

{
  "name": "get_logs",
  "arguments": {
    "tool_name": "find_files",
    "start_time": "2024-01-01T00:00:00",
    "end_time": "2024-01-02T00:00:00",
    "success": true,
    "limit": 100
  }
}

参数:

• tool_name (可选): 按工具名称过滤
• start_time (可选): 开始时间 (ISO 格式)
• end_time (可选): 结束时间 (ISO 格式)
• success (可选): 是否成功
• limit (可选): 返回条数限制，默认 100

返回:

{
  "logs": [
    {
      "id": 1,
      "tool_name": "find_files",
      "arguments": {"query": "test", "limit": 20},
      "result": {...},
      "success": true,
      "elapsed_ms": 15,
      "timestamp": "2024-01-01T12:00:00"
    }
  ]
}

8. get_call_stats

获取工具调用统计信息，包括调用次数、平均耗时、成功率等。

{
  "name": "get_call_stats",
  "arguments": {}
}

返回:

{
  "call_stats": {
    "index_repository": {"calls": 10, "avg_ms": 2500, "success_rate": 1.0},
    "find_files": {"calls": 50, "avg_ms": 12, "success_rate": 0.98},
    "find_symbols": {"calls": 30, "avg_ms": 18, "success_rate": 1.0},
    "find_content": {"calls": 100, "avg_ms": 25, "success_rate": 0.95},
    ...
  }
}

9. smart_search

🤖 智能搜索 - 推荐的搜索方式！

推荐使用此工具代替其他搜索工具，因为它能自动判断是否需要索引，并自动选择最优搜索策略。

{
  "name": "smart_search",
  "arguments": {
    "query": "handleClick",
    "search_type": "auto"
  }
}

参数:

• query (必填): 搜索关键词
• repo_path (可选): 代码仓库路径（如果未索引会自动索引）
• search_type (可选): 搜索类型，默认为 "auto"
  • auto: 自动选择（推荐）
  • content: 全文搜索
  • symbol: 符号搜索
  • file: 文件搜索

10. get_suggestions

获取智能搜索建议。当你不确定搜索什么时，可以使用此工具。

{
  "name": "get_suggestions",
  "arguments": {
    "query": "search"
  }
}

11. get_dependencies

获取文件的依赖关系（导入的模块）。

{
  "name": "get_dependencies",
  "arguments": {
    "file_path": "/path/to/file.py"
  }
}

12. get_dependents

获取依赖此文件的文件（反向依赖）。

{
  "name": "get_dependents",
  "arguments": {
    "file_path": "/path/to/file.py"
  }
}

13. get_memory

获取当前会话记忆（已查看的文件和结论）。

{
  "name": "get_memory",
  "arguments": {}
}

14. clear_memory

清除会话记忆。

{
  "name": "clear_memory",
  "arguments": {}
}

15. remember_file

记住文件分析结果。

{
  "name": "remember_file",
  "arguments": {
    "file_path": "/path/to/file.py",
    "summary": "文件主要功能...",
    "conclusions": ["结论1", "结论2"]
  }
}

支持的语言

• Python (.py)
• JavaScript (.js, .jsx)
• TypeScript (.ts, .tsx)
• Go (.go)
• Rust (.rs)
• Java (.java)
• C/C++ (.c, .cpp, .h, .hpp)
• Ruby (.rb)
• PHP (.php)
• Swift (.swift)
• Kotlin (.kt)
• Scala (.scala)
• Vue (.vue)
• Svelte (.svelte)

CLI 命令

安装后可以使用 CLI 工具：

# 索引代码仓库
code-search index /path/to/repo

# 重建索引
code-search rebuild /path/to/repo

# 综合搜索
code-search search "query"

# 搜索文件
code-search files "query"

# 搜索符号
code-search symbols "query"

# 搜索内容
code-search content "query"

# 查看日志
code-search logs

# 查看统计
code-search stats

# 查看状态
code-search status

# 清理数据
code-search clean --all

开发

运行测试

pytest tests/ -v

代码检查

ruff check code_search_mcp/

文档

详细文档请参阅 docs/ 目录：

文档	说明
docs/README.md	文档中心首页
docs/入门指南.md	快速安装和基础使用
docs/教程.md	从入门到高级的完整教程
docs/架构设计.md	系统架构、技术实现
docs/产品设计.md	产品定位、核心功能、路线图

Skills

Skills 目录包含 AI 助手使用的技能模块：

• skills/code-search/ - 代码搜索技能（SKILL.md + examples + reference）
• skills/code-review-assistant/ - 代码审查技能

许可证

MIT