Metadata-Version: 2.4
Name: code-search-mcp
Version: 0.5.3
Summary: MCP server for indexing code repositories with SQLite
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"

# Code Search MCP

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

## 概述

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

### 核心功能

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

## 快速开始

### 安装

```bash
pip install code-search-mcp
```

### 使用 MCP 客户端

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

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

### 基本使用

```python
from code_search_mcp import CodeIndexServer

server = CodeIndexServer()
```

## MCP 工具

本服务提供 8 个 MCP 工具：

### 1. index_repository

索引整个代码仓库。

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

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

**返回**:
```python
{
  "success": true,
  "stats": {
    "files_indexed": 150,
    "symbols": 1200,
    "content_blocks": 5000,
    "elapsed_seconds": 2.5
  }
}
```

### 2. find_files

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

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

### 3. find_symbols

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

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

### 4. find_content

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

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

### 5. get_structure

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

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

**参数**:
- `file_path` (必填): 文件路径

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

### 6. get_stats

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

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

**返回**:
```python
{
  "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

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

```python
{
  "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

**返回**:
```python
{
  "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

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

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

**返回**:
```python
{
  "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},
    ...
  }
}
```

## 支持的语言

- 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 工具：

```bash
# 索引代码仓库
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
```

## 开发

### 运行测试

```bash
pytest tests/ -v
```

### 代码检查

```bash
ruff check code_search_mcp/
```

## 文档

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

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

### Skills

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

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

## 许可证

MIT
