npm package: @rocklerson/mcp-ace
Description: MCP server for codebase indexing and semantic search (TypeScript implementation)
Author: rocklerson
Latest version: 0.1.3

# MCP-ACE

基于 TypeScript 实现的 MCP (Model Context Protocol) 服务器，用于代码库索引和语义搜索。

## 特性

- ✨ **增量索引** - 仅上传新增或修改的文件，基于 SHA-256 哈希检测变更
- 🔍 **语义搜索** - 使用自然语言查询代码库
- 🚀 **自动索引** - 搜索前自动执行增量索引，确保结果最新
- 📦 **文件分割** - 自动处理大文件（默认 800 行/片段）
- 🔁 **重试机制** - 内置指数退避重试，处理网络波动
- ⚙️ **灵活配置** - 支持配置文件、环境变量和命令行参数

## 安装

### 前置要求

- Node.js >= 18.0.0
- npm 或 yarn 或 pnpm

### 从 npm 安装

```bash
npm install -g @rocklerson/mcp-ace
```

### 从源码安装

```bash
# 克隆仓库
git clone https://github.com/rocklerson/mcp-ace.git
cd mcp-ace

# 安装依赖
npm install

# 构建项目
npm run build

# 全局链接（可选）
npm link
```

## 配置

### 配置方式（按优先级排序）

1. **命令行参数** - 最高优先级
2. **环境变量** - 前缀 `MCP_ACE_`
3. **配置文件** - `~/.mcp-ace/settings.json`
4. **默认值**

### 必需配置

- `baseUrl`: ACE API 服务器地址
- `token`: API 认证令牌

### 可选配置

- `batchSize`: 批量上传大小（默认: 10）
- `maxLinesPerBlob`: 每个 blob 最大行数（默认: 800）
- `textExtensions`: 支持的文本文件扩展名
- `excludePatterns`: 排除的文件/目录模式

### 配置文件示例

创建 `~/.mcp-ace/settings.json`:

```json
{
  "baseUrl": "https://api.augmentcode.com",
  "token": "your-api-token-here",
  "batchSize": 10,
  "maxLinesPerBlob": 800,
  "textExtensions": [".py", ".js", ".ts", ".md"],
  "excludePatterns": ["node_modules", ".git", "dist"]
}
```

### 环境变量

```bash
export MCP_ACE_BASE_URL="https://api.augmentcode.com"
export MCP_ACE_TOKEN="your-api-token-here"
export MCP_ACE_BATCH_SIZE="10"
export MCP_ACE_MAX_LINES_PER_BLOB="800"
```

## 使用方法

### 作为 MCP 服务器运行

```bash
# 使用命令行参数
mcp-ace --base-url https://api.augmentcode.com --token YOUR_TOKEN

# 使用环境变量
MCP_ACE_BASE_URL=https://api.augmentcode.com MCP_ACE_TOKEN=YOUR_TOKEN mcp-ace

# 开发模式
npm run dev -- --base-url https://api.augmentcode.com --token YOUR_TOKEN
```

### 与 Claude Desktop 集成

在 Claude Desktop 的配置文件中添加：

**macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcp-ace": {
      "command": "mcp-ace",
      "env": {
        "MCP_ACE_BASE_URL": "https://api.augmentcode.com",
        "MCP_ACE_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

### 工具使用

服务器提供以下 MCP 工具：

#### `search_context`

在代码库中搜索相关代码上下文。

**参数**:
- `project_root_path` (string, 必需): 项目根目录的绝对路径
- `query` (string, 必需): 搜索查询（自然语言）

**示例**:
```json
{
  "project_root_path": "C:/workspace/myproject",
  "query": "用户认证相关的代码"
}
```

## 工作原理

### 增量索引流程

1. **文件收集** - 递归扫描项目目录，根据扩展名和排除模式过滤
2. **哈希计算** - 对每个文件计算 SHA-256 哈希（路径 + 内容）
3. **变更检测** - 与历史索引比对，识别新增/修改的文件
4. **文件分割** - 大文件自动分割为多个片段（默认 800 行/片段）
5. **批量上传** - 仅上传变更的 blob（默认 10 个/批次）
6. **元数据保存** - 更新 `~/.mcp-ace/data/projects.json`

### 语义搜索流程

1. **自动索引** - 搜索前执行增量索引，确保数据最新
2. **加载索引** - 读取项目的所有 blob 哈希
3. **API 请求** - 发送搜索请求到 ACE API
4. **结果返回** - 返回格式化的代码片段（包含文件路径和行号）

## 开发

```bash
# 安装依赖
npm install

# 开发模式（带热重载）
npm run dev

# 构建
npm run build

# 清理构建产物
npm run clean
```

## 项目结构

```
mcp-ace/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── config.ts             # 配置管理
│   ├── manager.ts            # 索引管理器（核心逻辑）
│   ├── types.ts              # TypeScript 类型定义
│   └── tools/
│       └── search-context.ts # 搜索工具实现
├── dist/                     # 构建输出目录
├── package.json
├── tsconfig.json
└── README.md
```

## 故障排查

### 常见问题

**Q: 提示"配置错误: baseUrl 是必需的"**

A: 请通过以下任一方式配置：
- 命令行参数: `--base-url https://api.example.com`
- 环境变量: `MCP_ACE_BASE_URL=https://api.example.com`
- 配置文件: 在 `~/.mcp-ace/settings.json` 中设置

**Q: 搜索结果为空**

A: 检查以下几点：
1. 项目路径是否正确
2. 项目中是否包含支持的文本文件类型
3. 排除模式是否过滤了相关文件
4. API token 是否有效

**Q: 上传失败或超时**

A: 系统内置重试机制（最多 3 次），如果仍然失败：
1. 检查网络连接
2. 验证 API 端点是否可访问
3. 尝试减小批次大小: `--batch-size 5`

## 技术栈

- **TypeScript** - 类型安全的 JavaScript
- **@modelcontextprotocol/sdk** - MCP 协议实现
- **axios** - HTTP 客户端
- **Node.js** - 运行时环境

## 与 Python 版本的对比

| 特性 | Python 版本 | TypeScript 版本 |
|------|------------|----------------|
| 核心索引功能 | ✅ | ✅ |
| 语义搜索 | ✅ | ✅ |
| 增量索引 | ✅ | ✅ |
| 配置热加载 | ✅ | ✅ |

## 许可证

Apache-2.0

## 贡献

欢迎提交 Issue 和 Pull Request！

## 相关链接

- GitHub: https://github.com/rocklerson/mcp-ace
- npm: https://www.npmjs.com/package/@rocklerson/mcp-ace