Acemcp Node.js 实现

MCP 服务器，用于代码库索引和语义搜索 - Node.js 实现

License Node.js TypeScript

📖 简介

Acemcp 是一个 MCP (Model Context Protocol) 服务器，提供代码库索引和语义搜索功能。此 Node.js 实现与 Python 版本完全兼容，共享相同的配置文件和数据格式。

主要特性

✅ 完整的 MCP 服务器功能 - 实现 search_context 工具
✅ 增量索引 - 仅索引新文件或修改的文件
✅ 文件分割 - 大文件自动分割为多个块
✅ .gitignore 支持 - 自动排除 .gitignore 中的文件
✅ 多编码支持 - 支持 UTF-8, GBK, GB2312, Latin-1
✅ 批量上传 - 支持批量上传和自动重试
✅ Web 管理界面 - 配置管理、实时日志、工具调试
✅ 数据兼容 - 与 Python 版本共享数据格式
✅ WSL 路径支持 - 完全支持 Windows Subsystem for Linux 路径

📦 安装

前置要求

Node.js >= 18.0.0
npm 或其他包管理器

安装步骤

# 克隆仓库 git clone https://github.com/yourusername/Ace-Mcp.git cd Ace-Mcp/Ace-Mcp-Node # 安装依赖 npm install # 编译 TypeScript npm run build

🚀 使用

配置

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

# ~/.acemcp/settings.toml BASE_URL = "https://api.example.com" TOKEN = "your-token-here" BATCH_SIZE = 10 MAX_LINES_PER_BLOB = 800 TEXT_EXTENSIONS = [ ".py", ".js", ".ts", ".jsx", ".tsx", ".java", ".go", ".rs", ".cpp", ".c", ".h", ".hpp", ".cs", ".rb", ".php", ".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".xml", ".html", ".css", ".scss", ".sql", ".sh", ".bash" ] EXCLUDE_PATTERNS = [ ".venv", "venv", ".env", "env", "node_modules", ".git", ".svn", ".hg", "__pycache__", ".pytest_cache", ".mypy_cache", ".tox", ".eggs", "*.egg-info", "dist", "build", ".idea", ".vscode", ".DS_Store", "*.pyc", "*.pyo", "*.pyd" ]

启动 MCP 服务器

# 标准模式（stdio） npm start # 或使用开发模式（带自动重载） npm run dev # 使用自定义配置 npm start -- --base-url https://your-api.com --token your-token # 启动 Web 管理界面 npm start -- --web-port 8080

WSL 路径支持

Ace-Mcp-Node 完全支持 Windows Subsystem for Linux (WSL) 路径格式：

路径类型	示例	说明
Windows 本地	`C:\Users\username\project`	自动转换为 `C:/Users/username/project`
WSL 内部	`/home/user/project`	保持不变（仅 WSL 环境）
WSL 访问 Windows	`/mnt/c/Users/username/project`	Windows 环境自动转为 `C:/Users/username/project` ⭐
Windows 访问 WSL	`\\wsl$\Ubuntu\home\user\project`	自动转换为 `/home/user/project`

使用示例:

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

注意:

路径将自动规范化为统一格式（使用正斜杠）
末尾斜杠会被自动移除
遇到路径问题请参考路径故障排查指南

在 MCP 客户端中配置

在你的 MCP 客户端配置文件中添加：

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

WSL 环境配置示例:

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

或使用 Web 管理界面：

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

🔧 工具说明

search_context

搜索项目代码库中与查询相关的代码片段。

参数：

project_root_path (string, 必需): 项目根目录的绝对路径，使用正斜杠 / 作为路径分隔符
- 示例: C:/Users/username/projects/myproject
query (string, 必需): 自然语言搜索查询
- 示例: "logging configuration setup", "user authentication login"

功能：

自动对项目进行增量索引
执行语义搜索
返回格式化的代码片段，包含文件路径和行号

使用示例：

{ "tool": "search_context", "arguments": { "project_root_path": "C:/Users/username/projects/myproject", "query": "logging configuration setup initialization" } }

🌐 Web 管理界面

启动 Web 界面：

npm start -- --web-port 8080

然后访问 http://localhost:8080

Web 界面功能

服务器状态 - 查看运行状态和已索引项目数量
配置管理 - 在线编辑和保存配置
实时日志 - 通过 WebSocket 查看实时日志
工具调试 - 调试 MCP 工具调用
双语支持 - 支持中文和英文界面

📁 项目结构

Ace-Mcp-Node/ ├── src/ │ ├── index.ts # MCP 服务器入口 │ ├── config.ts # 配置管理 │ ├── logger.ts # 日志系统 │ ├── index/ │ │ └── manager.ts # 索引管理器 │ ├── tools/ │ │ └── searchContext.ts # search_context 工具 │ └── web/ │ ├── app.ts # Express 应用 │ ├── logBroadcaster.ts # WebSocket 日志广播 │ └── templates/ │ └── index.html # Web 界面 ├── dist/ # 编译后的 JavaScript ├── package.json ├── tsconfig.json └── README.md

🔄 与 Python 版本的兼容性

Node.js 实现与 Python 版本完全兼容：

共享配置文件 - 使用相同的 ~/.acemcp/settings.toml
共享数据格式 - 使用相同的 ~/.acemcp/data/projects.json
相同的 API 接口 - 调用相同的索引和搜索 API
相同的哈希算法 - 使用相同的 SHA-256 计算 blob_name

可以在 Python 和 Node.js 版本之间无缝切换。

🛠 开发

开发模式

# 启动开发服务器（自动重载） npm run dev # 构建项目 npm run build # 启动 Web 界面（开发模式） npm run dev -- --web-port 8080

脚本说明

npm run build - 编译 TypeScript 到 dist/
npm run dev - 开发模式（使用 tsx watch）
npm start - 运行编译后的代码
npm start:web - 启动带 Web 界面的服务器

📝 日志

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

自动日志轮转（单文件最大 5MB）
保留最近 10 个日志文件
控制台输出 INFO 级别及以上
文件输出 DEBUG 级别及以上

🐛 故障排除

路径问题

如果遇到 "Project root path does not exist" 错误：

检查路径末尾是否有斜杠 - 路径末尾不应包含 / 或 \（v0.1.5+ 自动移除）
验证路径存在 - 使用 ls (Unix) 或 dir (Windows) 检查
使用绝对路径 - 避免使用相对路径
参考文档 - 查看路径故障排查指南

相关文档:

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

编码问题

如果遇到文件编码错误，程序会自动尝试多种编码（UTF-8, GBK, GB2312, Latin-1）。

连接问题

检查 BASE_URL 和 TOKEN 配置是否正确：

cat ~/.acemcp/settings.toml

Web 界面无法访问

确保指定的端口未被占用：

# Windows netstat -ano | findstr :8080 # Linux/Mac lsof -i :8080

📄 许可证

ISC License

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

Acemcp