@rocklerson/mcp-ace

v0.1.3

Published

4 months ago

MCP server for codebase indexing and semantic search (TypeScript implementation)

0High
0Medium
0Low

rocklerson

mcp code-indexing semantic-search ai augment-context-engine

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

配置

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

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

必需配置

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": "用户认证相关的代码"
}

工作原理

增量索引流程

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

语义搜索流程

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

开发

# 安装依赖
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: 检查以下几点：

项目路径是否正确
项目中是否包含支持的文本文件类型
排除模式是否过滤了相关文件
API token 是否有效

Q: 上传失败或超时

A: 系统内置重试机制（最多 3 次），如果仍然失败：

检查网络连接
验证 API 端点是否可访问
尝试减小批次大小: --batch-size 5

技术栈

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

与 Python 版本的对比

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

许可证

Apache-2.0

贡献

欢迎提交 Issue 和 Pull Request！