# Code Tools MCP

一个整合了**文件阅读**和**代码搜索**功能的 MCP (Model Context Protocol) 服务工具。

## 功能概述

本 MCP 服务注册了两个工具，供支持 MCP 协议的 AI 客户端（如 Claude Desktop、Claude Code 等）调用：

### 1. `read_file` — 文件阅读

读取指定路径的文件内容，支持按行范围分页读取。

**参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_path` | string | 是 | 文件的绝对或相对路径，支持跨盘符路径（如 `D:/path/to/file`） |
| `offset` | number | 否 | 起始行号（从 1 开始），配合 `limit` 实现分页读取 |
| `limit` | number | 否 | 最大读取行数，配合 `offset` 实现分页读取 |

**示例：**
```json
{
  "file_path": "D:/projects/main.cpp",
  "offset": 100,
  "limit": 50
}
```

### 2. `search_codebase` — 代码搜索

在指定目录中递归搜索匹配正则表达式的内容，基于 grep 实现。

**参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | 是 | grep 兼容的搜索查询（支持正则表达式） |
| `directory` | string | 否 | 搜索目录，支持绝对/相对路径，默认为当前工作目录 |
| `include` | string | 否 | 文件类型过滤（如 `*.js`、`*.cpp`），对应 grep 的 `--include` |

**示例：**
```json
{
  "query": "function\\s+loadNextLevel",
  "directory": "D:/raylib/proj_1",
  "include": "*.cpp"
}
```

## 安装与配置

### 1. 安装依赖

```bash
cd D:/code-tools-mcp
npm install
```

### 2. 配置 MCP 客户端

在 Claude Desktop 或 Claude Code 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "code-tools": {
      "command": "node",
      "args": ["D:/code-tools-mcp/index.js"]
    }
  }
}
```

### 3. 启动（测试）

```bash
node D:/code-tools-mcp/index.js
```

## 项目结构

```
code-tools-mcp/
├── index.js        # MCP 服务主入口，注册 read_file 和 search_codebase 两个工具
├── package.json    # 项目配置文件
└── README.md       # 本说明文件
```

## 技术栈

- **运行时：** Node.js
- **MCP SDK：** `@modelcontextprotocol/sdk` v1.29+
- **参数校验：** Zod v4.4+
- **文件读取：** Node.js 内置 `fs/promises`
- **代码搜索：** 调用系统 `grep` 命令

## 注意事项

- `search_codebase` 依赖系统安装的 `grep` 命令，Windows 用户需确保 Git Bash 或类似环境可用
- 单次返回内容上限约为 64,000 字符，超出部分会被截断
- 文件读取默认使用 UTF-8 编码