Acemcp

Acemcp

Provides code repository indexing and semantic search capabilities, allowing natural language queries to find relevant code snippets with automatic incremental indexing and multi-language support.

Category
访问服务器

README

Acemcp Node.js 实现

🚀 强大的 MCP 服务器，为 AI 助手提供代码库索引和语义搜索能力

npm version npm downloads License Node.js TypeScript

<p align="center"> <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"> </p>

📑 目录

📖 简介

Acemcp 是一个高性能的 MCP (Model Context Protocol) 服务器，专为 AI 助手（如 Claude、GPT 等）提供代码库索引和语义搜索能力。通过 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
  • ✅ search_context 工具 - 语义搜索代码片段
  • ✅ stdio 传输 - 标准输入输出通信
  • ✅ 灵活配置 - 命令行参数 + 配置文件

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

🚀 快速开始

方式一：通过 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 本地 C:\Users\username\project C:/Users/username/project Windows 上的项目
WSL 内部 /home/user/project /home/user/project WSL 文件系统内
WSL 访问 Windows /mnt/c/Users/username/project C:/Users/username/project WSL 中访问 Windows 文件 ⭐
Windows 访问 WSL \\wsl$\Ubuntu\home\user\project /home/user/project Windows 访问 WSL 文件 ⭐

使用示例

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:/

故障排除

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

🔌 在 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 工具

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

参数

参数 类型 必需 说明 示例
project_root_path string ✅ 项目根目录的绝对路径，使用正斜杠 / C:/Users/username/myproject
query string ✅ 自然语言搜索查询 "authentication middleware"

功能流程

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"
  }
}

错误处理

错误类型 返回信息 解决方案
路径不存在 Error: Project root path does not exist 检查路径拼写和权限
缺少参数 Error: project_root_path is required 提供所有必需参数
API 连接失败 Error: Failed to connect to API 检查 BASE_URL 和 TOKEN 配置
索引失败 Error: Failed to index project 查看日志文件诊断

💡 使用场景示例

场景 1：AI 助手代码审查

需求：让 AI 助手理解项目的认证机制

用户：@acemcp 我的项目中是如何实现用户认证的？

AI 助手调用：
{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "C:/projects/my-saas-app",
    "query": "user authentication login signup middleware"
  }
}

结果：AI 获取认证相关代码，理解实现方式，提供审查建议

场景 2：Bug 调试

需求：定位支付模块的错误处理

用户：@acemcp 支付失败时的错误是如何处理的？

AI 助手调用：
{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "D:/ecommerce-backend",
    "query": "payment error handling failure rollback"
  }
}

结果：快速定位支付错误处理逻辑，发现潜在问题

场景 3：新功能开发

需求：了解现有 API 路由结构

用户：@acemcp 我需要添加一个新的 API 端点，现有的路由是怎么组织的？

AI 助手调用：
{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "/home/dev/api-server",
    "query": "API routes endpoints definition express router"
  }
}

结果：理解路由结构，按照现有模式实现新端点

场景 4：文档生成

需求：为工具函数生成文档

用户：@acemcp 帮我为 utils 目录下的工具函数生成文档

AI 助手调用：
{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "C:/company/shared-utils",
    "query": "utility helper functions in utils directory"
  }
}

结果：获取所有工具函数，自动生成 JSDoc/TSDoc 文档

场景 5：代码重构

需求：找到所有使用旧 API 的地方

用户：@acemcp 我们要废弃 legacyApi，找到所有调用它的地方

AI 助手调用：
{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "D:/legacy-app",
    "query": "legacyApi function calls usage"
  }
}

结果：列出所有调用点，规划重构策略

🌐 Web 管理界面

启动 Web 界面

# 标准端口 8080
npm start -- --web-port 8080

# 自定义端口
npm start -- --web-port 3000

访问：http://localhost:8080

功能特性

功能模块 说明 用途
📊 服务器状态 实时显示运行状态、索引项目数、配置信息 监控服务器健康状况
⚙️ 配置管理 在线编辑 settings.toml，保存后立即生效 无需手动编辑配置文件
📝 实时日志 WebSocket 推送实时日志，支持过滤和搜索 调试和问题诊断
🛠 工具调试 模拟 MCP 工具调用，测试搜索查询 开发和测试
🌍 双语支持 中文/英文界面切换 国际化支持

界面预览

服务器状态面板

┌─────────────────────────────────────┐
│ 🟢 MCP Server Status                │
│                                     │
│ Status:          Running            │
│ Indexed Projects: 5                 │
│ Port:            8080               │
│ Base URL:        https://api...     │
└─────────────────────────────────────┘

配置编辑器

  • 语法高亮 TOML 编辑器
  • 实时验证
  • 一键保存和应用

实时日志查看器

  • 彩色日志级别标识（DEBUG/INFO/WARNING/ERROR）
  • 自动滚动
  • 日志搜索和过滤
  • 导出日志

工具调试面板

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "C:/your/project",
    "query": "your search query"
  }
}

点击"测试工具"按钮，查看返回结果。

安全建议

⚠️ 重要：Web 界面仅绑定 localhost，不对外网开放。

如需远程访问：

  1. 使用 SSH 隧道：ssh -L 8080:localhost:8080 user@server
  2. 配置反向代理（Nginx/Caddy）并添加认证
  3. 不要直接暴露在公网

📁 项目结构

Ace-Mcp-Node/
├── src/                          # TypeScript 源代码
│   ├── index.ts                  # 🚪 MCP 服务器入口点
│   │                             #    - 初始化 MCP 服务器
│   │                             #    - 注册工具
│   │                             #    - 处理命令行参数
│   │
│   ├── config.ts                 # ⚙️ 配置管理单例
│   │                             #    - 加载 settings.toml
│   │                             #    - 生成默认配置
│   │                             #    - 提供配置访问接口
│   │
│   ├── logger.ts                 # 📝 日志系统单例
│   │                             #    - 文件日志轮转
│   │                             #    - 控制台输出
│   │                             #    - WebSocket 广播集成
│   │
│   ├── index/                    # 📊 索引管理模块
│   │   └── manager.ts            #    - 增量索引逻辑
│   │                             #    - 文件收集和分割
│   │                             #    - .gitignore 解析
│   │                             #    - SHA-256 哈希计算
│   │                             #    - 批量上传
│   │
│   ├── tools/                    # 🛠 MCP 工具实现
│   │   └── searchContext.ts     #    - search_context 工具
│   │                             #    - 参数验证
│   │                             #    - 搜索 API 调用
│   │
│   ├── utils/                    # 🔧 工具函数
│   │   ├── pathUtils.ts          #    - 路径规范化
│   │   │                         #    - WSL 路径转换
│   │   │                         #    - UNC 路径处理
│   │   └── detailedLogger.ts     #    - 详细日志格式化
│   │
│   └── web/                      # 🌐 Web 管理界面
│       ├── app.ts                #    - Express 应用
│       │                         #    - API 路由
│       │                         #    - WebSocket 服务器
│       ├── logBroadcaster.ts     #    - 日志广播器
│       └── templates/
│           └── index.html        #    - 单页应用界面
│
├── dist/                         # 📦 编译输出（发布到 NPM）
│   ├── *.js                      #    - 编译后的 JavaScript
│   ├── *.d.ts                    #    - TypeScript 类型定义
│   ├── *.js.map                  #    - Source Maps
│   └── web/templates/            #    - Web 界面资源
│
├── node_modules/                 # 依赖包（不发布）
│
├── package.json                  # 📋 NPM 包配置
├── tsconfig.json                 # 📋 TypeScript 编译配置
├── LICENSE                       # 📄 ISC 许可证
├── README.md                     # 📖 本文档
│
└── docs/                         # 📚 额外文档
    ├── PATH_TROUBLESHOOTING.md   #    - 路径问题排查
    ├── WSL_PATH_GUIDE.md         #    - WSL 路径指南
    └── USAGE_GUIDE.md            #    - 详细使用指南

用户数据目录

~/.acemcp/                        # 用户配置和数据
├── settings.toml                 # 主配置文件
├── data/
│   └── projects.json             # 项目索引元数据
└── log/
    ├── acemcp.log                # 当前日志
    ├── acemcp.log.1              # 轮转日志
    └── ...                       # 保留最近 10 个

🔄 与 Python 版本的兼容性

Acemcp-Node 与 Acemcp-Python 完全兼容，可以无缝切换。

兼容项 说明 位置
配置文件 共享同一个 settings.toml ~/.acemcp/settings.toml
项目数据 共享项目索引元数据 ~/.acemcp/data/projects.json
API 接口 调用相同的索引和搜索 API BASE_URL 配置
哈希算法 使用相同的 SHA-256 计算 blob_name 增量索引
文件格式 TOML 配置、JSON 数据 通用格式

切换版本

# 从 Python 版本切换到 Node.js 版本
# 1. 停止 Python 版本
pkill -f acemcp

# 2. 启动 Node.js 版本（使用相同配置）
npm start

# 配置文件和索引数据自动共享，无需迁移

差异说明

特性 Python 版本 Node.js 版本
运行时 Python 3.10+ Node.js 18.0+
性能 良好 略快（V8 引擎）
内存占用 中等 略低
依赖管理 pip/uv npm/yarn/pnpm
类型安全 Type hints TypeScript 严格模式
Web 界面 ✅ ✅
WSL 支持 ✅ ✅

🛠 开发

开发环境设置

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

# 2. 安装依赖
npm install

# 3. 启动开发模式（热重载）
npm run dev

# 4. 或启动带 Web 界面的开发模式
npm run dev -- --web-port 8080

NPM Scripts

命令 说明 用途
npm run build 编译 TypeScript → dist/ 生产构建
npm run dev 开发模式 + 热重载 开发调试
npm start 运行编译后的代码 生产运行
npm start:web 启动带 Web 界面（8080） Web 管理
npm test 运行测试脚本 测试
npm run copy-templates 复制 Web 模板 构建步骤

代码规范

TypeScript 配置

  • 严格模式 - 启用所有严格类型检查
  • ES2022 目标 - 现代 JavaScript 特性
  • ESM 模块 - 使用 ES 模块系统
  • Source Maps - 调试支持

命名约定

// 类名：PascalCase
class IndexManager {}

// 函数：camelCase
function normalizePath() {}

// 常量：UPPER_SNAKE_CASE
const USER_CONFIG_DIR = '~/.acemcp';

// 接口：PascalCase + 'I' 前缀（可选）
interface IConfig {}

导入规范

// ✅ 正确：ESM 必须包含 .js 扩展名
import { getConfig } from './config.js';
import { IndexManager } from './index/manager.js';

// ❌ 错误：缺少扩展名
import { getConfig } from './config';

日志系统

日志文件位置：~/.acemcp/log/acemcp.log

日志级别

级别 用途 示例
DEBUG 详细调试信息 logger.debug('File hash calculated')
INFO 重要操作记录 logger.info('Project indexed successfully')
WARNING 非致命警告 logger.warning('File encoding fallback')
ERROR 错误信息 logger.error('API request failed')
EXCEPTION 异常堆栈 logger.exception('Error in tool', error)

日志配置

  • 文件轮转 - 单文件最大 5MB
  • 保留数量 - 最近 10 个日志文件
  • 控制台 - INFO 级别及以上（非 stdio 模式）
  • 文件 - DEBUG 级别及以上
  • WebSocket - 实时广播到 Web 界面

添加新工具

// 1. 创建工具文件：src/tools/myTool.ts
export async function myTool(args: { param1: string }): Promise<{ type: 'text'; text: string }> {
  try {
    // 参数验证
    if (!args.param1) {
      return { type: 'text', text: 'Error: param1 is required' };
    }
    
    // 业务逻辑
    const result = await doSomething(args.param1);
    
    return { type: 'text', text: result };
  } catch (error: any) {
    logger.exception('Error in myTool', error);
    return { type: 'text', text: `Error: ${error.message}` };
  }
}

// 2. 在 src/index.ts 中注册
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'my_tool') {
    return await myTool(request.params.arguments);
  }
  // ...
});

// 3. 添加到工具列表
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'my_tool',
      description: 'My custom tool',
      inputSchema: {
        type: 'object',
        properties: {
          param1: { type: 'string', description: 'Parameter 1' }
        },
        required: ['param1']
      }
    },
    // ...
  ]
}));

🐛 故障排除

常见问题速查

问题 症状 解决方案
路径不存在 Project root path does not exist 路径问题
API 连接失败 Failed to connect to API 连接问题
编码错误 UnsupportedEncoding 编码问题
端口占用 EADDRINUSE 端口问题
权限错误 EACCES 权限问题
WSL 路径 路径转换失败 WSL 指南

路径问题

症状

Error: Project root path does not exist: /invalid/path

诊断步骤

  1. 检查路径格式

    # ✅ 正确格式（使用正斜杠）
C:/Users/username/project

# ❌ 错误格式（使用反斜杠）
C:\Users\username\project

# ❌ 错误格式（末尾有斜杠）
C:/Users/username/project/

  2. 验证路径存在

    # Windows
dir "C:\Users\username\project"

# Linux/macOS
ls -la /home/user/project

# WSL
ls -la /mnt/c/Users/username/project

  3. 使用绝对路径

    {
  "project_root_path": "C:/Users/username/myproject"  // ✅ 绝对路径
}

  4. WSL 特殊情况

    • Windows 访问 WSL: \\wsl$\Ubuntu\home\user\project → 自动转换
    • WSL 访问 Windows: /mnt/c/Users/username/project → 自动转换

详细指南：

连接问题

症状

Error: Failed to connect to API: https://api.example.com

解决方案

  1. 检查配置文件

    cat ~/.acemcp/settings.toml

  2. 验证 API 可达性

    curl -H "Authorization: Bearer YOUR_TOKEN" https://your-api.com/health

  3. 检查网络代理

    echo $HTTP_PROXY
echo $HTTPS_PROXY

  4. 临时覆盖配置

    npm start -- --base-url https://your-api.com --token your-token

编码问题

症状

Warning: Failed to read file with UTF-8, trying alternative encodings

说明

Acemcp-Node 自动处理多种编码：

  1. UTF-8（默认）
  2. GBK（简体中文）
  3. GB2312（简体中文）
  4. Latin-1（西欧语言）

如果所有编码都失败，文件将被跳过并记录警告。

手动指定编码（暂不支持）

如需支持其他编码，请提交 Issue。

Web 界面无法访问

症状

Error: listen EADDRINUSE: address already in use :::8080

解决方案

  1. 检查端口占用

    # Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F

# Linux/macOS
lsof -i :8080
kill -9 <PID>

  2. 使用其他端口

    npm start -- --web-port 3000

  3. 检查防火墙

    # Windows 防火墙
netsh advfirewall firewall show rule name=all | findstr 8080

# Linux 防火墙
sudo ufw status
sudo ufw allow 8080

权限问题

症状

Error: EACCES: permission denied

解决方案

  1. 检查目录权限

    # Linux/macOS
ls -la ~/.acemcp
chmod 755 ~/.acemcp
chmod 644 ~/.acemcp/settings.toml

# Windows（以管理员身份运行）
icacls "%USERPROFILE%\.acemcp" /grant %USERNAME%:F

  2. 避免使用 sudo

    # ❌ 不推荐
sudo npm install -g acemcp-node

# ✅ 推荐
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g acemcp-node

索引失败

症状

Error: Failed to index project: timeout

解决方案

  1. 检查项目大小

    du -sh /path/to/project

  2. 增加批次大小（settings.toml）

    BATCH_SIZE = 20  # 默认 10，可增加到 50

  3. 检查网络稳定性

    ping api.example.com

  4. 查看详细日志

    tail -f ~/.acemcp/log/acemcp.log

获取帮助

如果以上方法都无法解决问题：

  1. 查看日志

    cat ~/.acemcp/log/acemcp.log

  2. 提交 Issue

    • 访问 GitHub Issues
    • 提供错误信息和日志片段
    • 描述复现步骤

  3. 社区讨论

🤝 贡献

我们欢迎所有形式的贡献！

贡献方式

  • 🐛 报告 Bug - 提交 Issue
  • 💡 建议功能 - 在 Discussions 中讨论
  • 📖 改进文档 - 修正错误或添加示例
  • 🔧 提交代码 - Fork 并创建 Pull Request

开发流程

# 1. Fork 仓库
gh repo fork yeuxuan/Ace-Mcp-Node --clone

# 2. 创建特性分支
cd Ace-Mcp-Node
git checkout -b feature/my-feature

# 3. 开发和测试
npm install
npm run dev
# 进行修改...
npm run build
npm test

# 4. 提交变更
git add .
git commit -m "feat: add my feature"

# 5. 推送并创建 PR
git push origin feature/my-feature
gh pr create

代码规范

  • 遵循 TypeScript 严格模式
  • 使用 ESLint 和 Prettier（如有配置）
  • 添加适当的注释和类型定义
  • 保持向后兼容性

Commit 规范

使用 Conventional Commits：

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试相关
chore: 构建/工具相关

📧 联系方式

  • 作者: yihua
  • Email: 487735913@qq.com
  • GitHub: @yeuxuan
  • 项目主页: https://github.com/yeuxuan/Ace-Mcp-Node

🙏 致谢

🔗 相关资源

  • MCP 官方文档: https://modelcontextprotocol.io/
  • Python 版本: https://github.com/yeuxuan/Ace-Mcp-Python
  • NPM 包: https://www.npmjs.com/package/acemcp-node
  • 问题追踪: https://github.com/yeuxuan/Ace-Mcp-Node/issues
  • 更新日志: CHANGELOG.md

<div align="center">

⭐ 如果这个项目对你有帮助，请给它一个 Star！ ⭐

Made with ❤️ by wmymz

</div>

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选