Acemcp Node.js 实现

📑 目录

简介
核心特性
快速开始
安装
配置
使用指南
WSL 支持
API 文档
示例场景
开发指南
故障排除
兼容性
贡献
许可证

📖 简介

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

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

为什么选择 Acemcp？

特点	说明
零配置启动	首次运行自动生成配置
增量索引	只处理变更文件，快速高效
跨平台	Windows、Linux、macOS、WSL 全支持
多编码	自动检测 UTF-8、GBK、GB2312、Latin-1
AI 友好	返回格式化的代码片段，含文件路径和行号

⭐ 核心特性

🚀 性能优化

✅ 增量索引 - 仅索引新文件或修改的文件
✅ 批量上传 - 支持批量操作和自动重试
✅ 智能分割 - 大文件自动分割为多个块
✅ 缓存机制 - 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 本地	`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:/

故障排除

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

📄 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 配置文档。

验证配置

配置完成后：

重启 MCP 客户端
检查日志文件：~/.acemcp/log/acemcp.log
如果启用了 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，不对外网开放。

如需远程访问：

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

📁 项目结构

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

诊断步骤

检查路径格式

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

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

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

验证路径存在

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

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

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

使用绝对路径

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

WSL 特殊情况
- Windows 访问 WSL: \\wsl$\Ubuntu\home\user\project → 自动转换
- WSL 访问 Windows: /mnt/c/Users/username/project → 自动转换

详细指南：

📄 路径故障排查指南
📄 WSL 路径支持指南

连接问题

症状

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

解决方案

检查配置文件
```
cat ~/.acemcp/settings.toml
```

验证 API 可达性

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

检查网络代理
```
echo $HTTP_PROXY
echo $HTTPS_PROXY
```

临时覆盖配置

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

编码问题

症状

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

说明

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

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

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

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

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

Web 界面无法访问

症状

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

解决方案

检查端口占用

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

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

使用其他端口
```
npm start -- --web-port 3000
```

检查防火墙

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

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

权限问题

症状

Error: EACCES: permission denied

解决方案

检查目录权限

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

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

避免使用 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

解决方案

检查项目大小
```
du -sh /path/to/project
```

增加批次大小（settings.toml）

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

检查网络稳定性
```
ping api.example.com
```
查看详细日志
```
tail -f ~/.acemcp/log/acemcp.log
```

获取帮助

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

查看日志
```
cat ~/.acemcp/log/acemcp.log
```
提交 Issue
- 访问 GitHub Issues
- 提供错误信息和日志片段
- 描述复现步骤
社区讨论
- 参与 Discussions

🤝 贡献

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

贡献方式

🐛 报告 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

🙏 致谢

基于 Acemcp-Python 的设计和实现
感谢 Model Context Protocol 团队
感谢所有贡献者和使用者

🔗 相关资源

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

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

Made with ❤️ by yihua

Acemcp Node.js 实现

📖 简介

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

为什么选择 Acemcp？

特点	说明
零配置启动	首次运行自动生成配置
增量索引	只处理变更文件，快速高效
跨平台	Windows、Linux、macOS、WSL 全支持
多编码	自动检测 UTF-8、GBK、GB2312、Latin-1
AI 友好	返回格式化的代码片段，含文件路径和行号

⭐ 核心特性

🚀 性能优化

✅ 增量索引 - 仅索引新文件或修改的文件
✅ 批量上传 - 支持批量操作和自动重试
✅ 智能分割 - 大文件自动分割为多个块
✅ 缓存机制 - 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 本地	`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:/

故障排除

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

📄 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 配置文档。

验证配置

配置完成后：

重启 MCP 客户端
检查日志文件：~/.acemcp/log/acemcp.log
如果启用了 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，不对外网开放。

如需远程访问：

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

📁 项目结构

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

诊断步骤

检查路径格式

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

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

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

验证路径存在

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

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

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

使用绝对路径

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

WSL 特殊情况
- Windows 访问 WSL: \\wsl$\Ubuntu\home\user\project → 自动转换
- WSL 访问 Windows: /mnt/c/Users/username/project → 自动转换

详细指南：

📄 路径故障排查指南
📄 WSL 路径支持指南

连接问题

症状

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

解决方案

检查配置文件
```
cat ~/.acemcp/settings.toml
```

验证 API 可达性

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

检查网络代理
```
echo $HTTP_PROXY
echo $HTTPS_PROXY
```

临时覆盖配置

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

编码问题

症状

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

说明

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

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

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

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

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

Web 界面无法访问

症状

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

解决方案

检查端口占用

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

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

使用其他端口
```
npm start -- --web-port 3000
```

检查防火墙

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

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

权限问题

症状

Error: EACCES: permission denied

解决方案

检查目录权限

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

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

避免使用 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

解决方案

检查项目大小
```
du -sh /path/to/project
```

增加批次大小（settings.toml）

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

检查网络稳定性
```
ping api.example.com
```
查看详细日志
```
tail -f ~/.acemcp/log/acemcp.log
```

获取帮助

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

查看日志
```
cat ~/.acemcp/log/acemcp.log
```
提交 Issue
- 访问 GitHub Issues
- 提供错误信息和日志片段
- 描述复现步骤
社区讨论
- 参与 Discussions

🤝 贡献

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

贡献方式

🐛 报告 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

🙏 致谢

基于 Acemcp-Python 的设计和实现
感谢 Model Context Protocol 团队
感谢所有贡献者和使用者

🔗 相关资源

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

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

Made with ❤️ by yihua