Ace-Mcp-Node

# Acemcp Node.js 实现 [](https://www.npmjs.com/package/acemcp-node) [](https://www.npmjs.com/package/acemcp-node) [](LICENSE) [](https://nodejs.org) [](https://www.typescriptlang.org/) <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 客户端配置](#在-mcp-客户端中配置) - [工具说明](#-工具说明) - [Web 管理界面](#-web-管理界面) - [WSL 支持](#-wsl-路径支持完全指南) - [API 文档](#-api-文档) - [示例场景](#-使用场景示例) - [开发指南](#-开发) - [故障排除](#-故障排除) - [兼容性](#-与-python-版本的兼容性) - [贡献](#-贡献) - [许可证](#-许可证) --- ## 📖 简介 **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 安装（推荐） ```bash # 全局安装 npm install -g acemcp-node # 或本地安装到项目 npm install acemcp-node ``` ### 方式二：从源码安装 ```bash # 克隆仓库 git clone https://github.com/yeuxuan/Ace-Mcp-Node.git cd Ace-Mcp-Node # 安装依赖 npm install # 编译 TypeScript npm run build ``` ### 首次运行 ```bash # 启动服务器（首次会创建配置文件） 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 客户端） ```bash npm install -g acemcp-node # 验证安装 node -e "console.log(require('acemcp-node/package.json').version)" ``` #### 2. NPM 本地安装（用于项目集成） ```bash # 创建项目目录 mkdir my-mcp-project && cd my-mcp-project # 初始化 package.json npm init -y # 安装 acemcp-node npm install acemcp-node # 运行 npx acemcp-node ``` #### 3. 从源码开发安装 ```bash 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 配置详解 ```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" ] ``` #### 命令行参数覆盖 ```bash # 临时使用不同的 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） ```bash npm start ``` 此模式用于 MCP 客户端集成，通过标准输入/输出通信。 #### 2. Web 管理模式 ```bash npm start -- --web-port 8080 ``` 访问 http://localhost:80