技术文档摘要

Acemcp Node.js 实现

<img src="https://img.shields.io/badge/MCP-Model%20Context%20Protocol-orange" alt="MCP"> <img src="https://img.shields.io/badge/AI-Ready-success" alt="AI Ready">

📑 目录

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

---

📖 简介

Acemcp 是一个高性能的 MCP（模型上下文协议）服务器，专门设计用于像 Claude、GPT 等 AI 助手，并且具有代码库索引和语义搜索的能力。通过 Acemcp，AI 助手可以：

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

为什么选择 Acemcp？

特性	描述
零配置启动	第一次运行时自动生成配置
增量索引	只处理更改过的文件，快速高效
跨平台	支持 Windows、Linux、macOS 和 WSL
多编码支持	自动检测 UTF-8、GBK、GB2312、Latin-1
AI 友好	返回格式化的代码片段，包括文件路径和行号

---

⭐ 核心功能

<table> <tr> <td width="50%">

🚀 性能优化

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

</td> <td width="50%">

🛠 开发友好

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

</td> </tr> <tr> <td width="50%">

🌍 兼容性

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

</td> <td width="50%">

🎯 MCP 集成

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

</td> </tr> </table>

---

🚀 快速开始

方法 1：通过 NPM 安装（推荐）

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

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

方法 2：从源代码安装

# 克隆仓库
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 模式 + 热重载

---

🔧 完整指南支持 WSI 路径

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

支持的路径格式

路径类型	原始格式	自动转换	使用场景
Windows 本地	C:\Users\username\project	C:/Users/username/project	Windows 上的项目
WSI 内部	/home/user/project	/home/user/project	WSI 文件系统内
通过 WSL 访问 Windows	/mnt/c/Users/username/project	C:/Users/username/project	在 WSL 中访问 Windows 文件 ⭐
Windows 访问 WSL	\\wsl$\Ubuntu\home\user\project	/home/user/project	Windows 访问 WSA 文件 ⭐

使用示例

Windows 环境

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

在 WSI 环境中访问 Windows 项目

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

Windows 访问 WSA 项目

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

自动处理功能

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

故障排除

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

• 📄 WSI 路径支持指南 - 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

方法 1：使用全局安装的包

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

方法 2：指定本地路径（从源代码安装）

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

方法 3：带有 Web 界面

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

方法 4：自定义 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": {}
    }
  }
}

WSI 环境的特殊配置

{
  "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 工具

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

参数

参数	类型	必填	描述	示例
project_root_path	string