MCP Ace

MCP-ACE

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

特性

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

安装

前置要求

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

从 npm 安装

npm install -g @rocklerson/mcp-ace

从源码安装

# 克隆仓库
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:

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

环境变量

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 服务器运行

# 使用命令行参数
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

{
  "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, 必需): 搜索查询（自然语言）

示例:

{
  "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. 结果返回 - 返回格式化的代码片段（包含文件路径和行号）

开发

# 安装依赖
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 版本的对比

许可证

Apache-2.0

贡献

欢迎提交 Issue 和 Pull Request！

相关链接

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