Acemcp Node.js 实现

📑 目录

• 简介
• 核心特性
• 快速开始
• 安装
• 配置
• 使用指南
  • MCP 客户端配置
  • 工具说明
  • Web 管理界面
• WSL 支持
• API 文档
• 示例场景
• 开发指南
• 故障排除
• 兼容性
• 贡献
• 许可证

📖 简介

Acemcp 是一个高性能的 MCP (Model Context Protocol) 服务器，专为 AI 助手（如 Claude、GPT 等）提供代码库索引和语义搜索能力。通过 Acemcp，AI 助手可以：

• 🔍 快速搜索和理解大型代码库
• 📊 获取带行号的精确代码片段
• 🤖 自动增量更新索引
• 🌐 通过 Web 界面管理和调试

为什么选择 Acemcp？

⭐ 核心特性

🚀 性能优化

• ✅ 增量索引 - 仅索引新文件或修改的文件
• ✅ 批量上传 - 支持批量操作和自动重试
• ✅ 智能分割 - 大文件自动分割为多个块
• ✅ 缓存机制 - SHA-256 哈希避免重复上传

🛠 开发友好

• ✅ TypeScript - 完整类型支持
• ✅ Web 界面 - 实时日志、配置管理、工具调试
• ✅ .gitignore 支持 - 自动排除无关文件
• ✅ 详细日志 - 可配置的日志级别和轮转

🌍 兼容性

• ✅ 跨平台路径 - 统一处理 Windows/Unix 路径
• ✅ WSL 完整支持 - UNC 路径、/mnt 自动转换
• ✅ 多编码支持 - UTF-8, GBK, GB2312, Latin-1
• ✅ Python 版本兼容 - 共享配置和数据格式

🎯 MCP 集成

• ✅ 标准 MCP 协议 - 完整实现 SDK
• ✅ search_context 工具 - 语义搜索代码片段
• ✅ stdio 传输 - 标准输入输出通信
• ✅ 灵活配置 - 命令行参数 + 配置文件

🚀 快速开始

方式一：通过 NPM 安装（推荐）

# 全局安装
npm install -g acemcp-node

# 或本地安装到项目
npm install acemcp-node

方式二：从源码安装

# 克隆仓库
git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
cd Ace-Mcp-Node

# 安装依赖
npm install

# 编译 TypeScript
npm run build

首次运行

# 启动服务器（首次会创建配置文件）
npm start

# 或启动带 Web 界面
npm start -- --web-port 8080

访问 http://localhost:8080 查看 Web 管理界面！

📦 安装

系统要求

• Node.js >= 18.0.0
• npm >= 8.0.0（或 yarn、pnpm）
• 操作系统：Windows 10+、Linux、macOS、WSL 2

详细安装步骤

1. NPM 全局安装（推荐用于 MCP 客户端）

npm install -g acemcp-node

# 验证安装
node -e "console.log(require('acemcp-node/package.json').version)"

2. NPM 本地安装（用于项目集成）

# 创建项目目录
mkdir my-mcp-project && cd my-mcp-project

# 初始化 package.json
npm init -y

# 安装 acemcp-node
npm install acemcp-node

# 运行
npx acemcp-node

3. 从源码开发安装

git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
cd Ace-Mcp-Node
npm install
npm run build

# 开发模式（自动重载）
npm run dev

配置文件

首次运行时，程序会在 ~/.acemcp/ 目录下自动创建配置文件：

配置文件位置

~/.acemcp/
├── settings.toml     # 主配置文件
├── data/
│   └── projects.json # 项目索引数据
└── log/
    └── acemcp.log    # 日志文件

settings.toml 配置详解

# ~/.acemcp/settings.toml

# === API 配置 ===
BASE_URL = "https://api.example.com"  # 索引服务器地址
TOKEN = "your-token-here"              # 访问令牌

# === 索引配置 ===
BATCH_SIZE = 10                        # 批量上传数量（1-50）
MAX_LINES_PER_BLOB = 800               # 单个代码块最大行数

# === 文件类型配置 ===
# 支持索引的文本文件扩展名
TEXT_EXTENSIONS = [
  # 编程语言
  ".py", ".js", ".ts", ".jsx", ".tsx",
  ".java", ".go", ".rs", ".cpp", ".c",
  ".h", ".hpp", ".cs", ".rb", ".php",
  ".swift", ".kt", ".scala", ".clj",
  
  # 配置和数据
  ".md", ".txt", ".json", ".yaml", ".yml",
  ".toml", ".xml", ".ini", ".conf",
  
  # Web 相关
  ".html", ".css", ".scss", ".sass", ".less",
  
  # 脚本
  ".sql", ".sh", ".bash", ".ps1", ".bat"
]

# === 排除模式 ===
# 不会被索引的目录和文件模式
EXCLUDE_PATTERNS = [
  # 虚拟环境
  ".venv", "venv", ".env", "env",
  "node_modules",
  
  # 版本控制
  ".git", ".svn", ".hg",
  
  # Python 缓存
  "__pycache__", ".pytest_cache", ".mypy_cache",
  ".tox", ".eggs", "*.egg-info",
  
  # 构建产物
  "dist", "build", "target", "out",
  
  # IDE 配置
  ".idea", ".vscode", ".vs",
  
  # 系统文件
  ".DS_Store", "Thumbs.db",
  
  # 编译文件
  "*.pyc", "*.pyo", "*.pyd", "*.so", "*.dll"
]

命令行参数覆盖

# 临时使用不同的 API 配置
npm start -- --base-url https://custom-api.com --token custom-token

# 自定义批次大小
npm start -- --batch-size 20

# 启动 Web 界面在指定端口
npm start -- --web-port 3000

# 组合使用
npm start -- --base-url https://api.com --token abc123 --web-port 8080

📘 使用指南

启动方式

1. 标准 MCP 模式（stdio）

npm start

此模式用于 MCP 客户端集成，通过标准输入/输出通信。

2. Web 管理模式

npm start -- --web-port 8080

访问 http://localhost:8080 使用图形界面：

• 📊 查看服务器状态
• ⚙️ 编辑配置文件
• 📝 实时日志查看
• 🛠 工具调试测试

3. 开发模式

npm run dev                    # 标准模式 + 热重载
npm run dev -- --web-port 8080 # Web 模式 + 热重载

🔧 WSL 路径支持完全指南

Acemcp-Node 对 WSL (Windows Subsystem for Linux) 提供完整的路径支持，无需手动转换路径格式。

支持的路径格式

使用示例

Windows 环境

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "C:/Users/username/myproject",
    "query": "authentication logic"
  }
}

WSL 环境访问 Windows 项目

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "/mnt/c/Users/username/myproject",
    "query": "database connection"
  }
}

Windows 访问 WSL 项目

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "\\\\wsl$\\Ubuntu\\home\\user\\myproject",
    "query": "API routes"
  }
}

自动处理特性

• ✅ 路径规范化 - 统一使用正斜杠 /
• ✅ 末尾斜杠移除 - 自动移除路径末尾的 / 或 \
• ✅ UNC 路径转换 - 自动识别并转换 \\wsl$\ 格式
• ✅ /mnt 转换 - 自动将 /mnt/c/ 转为 C:/

故障排除

如果遇到路径问题，请参考：

• 📄 WSL 路径支持指南 - WSL 环境专用指南
• 📄 路径故障排查指南 - 详细的路径问题诊断

🔌 在 MCP 客户端中配置

Claude Desktop 配置

编辑 Claude Desktop 配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

方式一：使用全局安装的包

{
  "mcpServers": {
    "acemcp": {
      "command": "npx",
      "args": ["acemcp-node"],
      "env": {}
    }
  }
}

方式二：指定本地路径（从源码安装）

{
  "mcpServers": {
    "acemcp": {
      "command": "node",
      "args": ["D:/projects/Ace-Mcp-Node/dist/index.js"],
      "env": {}
    }
  }
}

方式三：带 Web 界面

{
  "mcpServers": {
    "acemcp": {
      "command": "node",
      "args": [
        "D:/projects/Ace-Mcp-Node/dist/index.js",
        "--web-port",
        "8080"
      ],
      "env": {}
    }
  }
}

方式四：自定义 API 配置

{
  "mcpServers": {
    "acemcp": {
      "command": "node",
      "args": [
        "D:/projects/Ace-Mcp-Node/dist/index.js",
        "--base-url",
        "https://your-api.com",
        "--token",
        "your-token-here"
      ],
      "env": {}
    }
  }
}

WSL 环境特殊配置

{
  "mcpServers": {
    "acemcp": {
      "command": "node",
      "args": ["\\\\wsl$\\Ubuntu\\home\\user\\Ace-Mcp-Node\\dist\\index.js"],
      "env": {}
    }
  }
}

其他 MCP 客户端

对于支持 MCP 协议的其他客户端（如 Zed、Cursor 等），配置方式类似，请参考各客户端的 MCP 配置文档。

验证配置

配置完成后：

1. 重启 MCP 客户端
2. 检查日志文件：~/.acemcp/log/acemcp.log
3. 如果启用了 Web 界面，访问 http://localhost:8080

📚 API 文档

search_context 工具

在项目代码库中执行语义搜索，自动进行增量索引并返回相关代码片段。

参数

功能流程

1. 接收搜索请求
   ↓
2. 检查项目索引状态
   ↓
3. 执行增量索引（仅新增/修改文件）
   ├─ 收集文件（遵循 .gitignore）
   ├─ 分割大文件
   ├─ 计算 SHA-256 哈希
   └─ 批量上传到服务器
   ↓
4. 执行语义搜索
   ↓
5. 返回格式化结果（文件路径 + 行号 + 代码片段）

返回格式

interface SearchResult {
  type: 'text';
  text: string; // 格式化的搜索结果
}

返回示例：

Found 3 relevant code snippets:

────────────────────────────────────────

File: src/auth/middleware.ts (Lines 15-28)

export function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (error) {
    res.status(403).json({ error: 'Invalid token' });
  }
}

────────────────────────────────────────

File: src/auth/login.ts (Lines 42-56)
...

使用示例

示例 1：搜索认证逻辑

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "C:/Users/username/myproject",
    "query": "user authentication and JWT token verification"
  }
}

示例 2：搜索数据库配置

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "/home/user/backend-api",
    "query": "database connection pool configuration"
  }
}

示例 3：搜索错误处理

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "D:/projects/react-app",
    "query": "error boundary and exception handling in React components"
  }
}

错误处理

| 错误类型 |