Skip to content
Back to search

Ace-Mcp-Node

Acemcp 是一个高性能的 MCP (Model Context Protocol) 服务器,专为 AI 助手(如 Claude、GPT 等)提供代码库索引和语义搜索能力。通过 Acemcp,AI 助手可以: 🔍 快速搜索和理解大型代码库 📊 获取带行号的精确代码片段 🤖 自动增量更新索引 🌐 通过 Web 界面管理和调试

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yeuxuan--ace-mcp-node/badge.svg)](/listings/yeuxuan--ace-mcp-node)

HTML

<a href="/listings/yeuxuan--ace-mcp-node"><img src="/api/listings/yeuxuan--ace-mcp-node/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

系统要求

- **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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,357 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Acemcp Node.js 实现
  2. [![npm version](https://img.shields.io/npm/v/acemcp-node.svg)](https://www.npmjs.com/package/acemcp-node)
  3. [![npm downloads](https://img.shields.io/npm/dm/acemcp-node.svg)](https://www.npmjs.com/package/acemcp-node)
  4. [![License](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)
  5. [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
  6. [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
  7. <img src="https://img.shields.io/badge/MCP-Model%20Context%20Protocol-orange" alt="MCP">
  8. <img src="https://img.shields.io/badge/AI-Ready-success" alt="AI Ready">
  9. ## 📑 目录
  10. - [简介](#-简介)
  11. - [核心特性](#-核心特性)
  12. - [快速开始](#-快速开始)
  13. - [安装](#-安装)
  14. - [配置](#-配置)
  15. - [使用指南](#-使用指南)
  16. - [MCP 客户端配置](#在-mcp-客户端中配置)
  17. - [工具说明](#-工具说明)
  18. - [Web 管理界面](#-web-管理界面)
  19. - [WSL 支持](#-wsl-路径支持完全指南)
  20. - [API 文档](#-api-文档)
  21. - [示例场景](#-使用场景示例)
  22. - [开发指南](#-开发)
  23. - [故障排除](#-故障排除)
  24. - [兼容性](#-与-python-版本的兼容性)
  25. - [贡献](#-贡献)
  26. - [许可证](#-许可证)
  27. ---
  28. ## 📖 简介
  29. **Acemcp** 是一个高性能的 MCP (Model Context Protocol) 服务器,专为 AI 助手(如 Claude、GPT 等)提供**代码库索引**和**语义搜索**能力。通过 Acemcp,AI 助手可以:
  30. - 🔍 快速搜索和理解大型代码库
  31. - 📊 获取带行号的精确代码片段
  32. - 🤖 自动增量更新索引
  33. - 🌐 通过 Web 界面管理和调试
  34. **为什么选择 Acemcp?**
  35. | 特点 | 说明 |
  36. |------|------|
  37. | **零配置启动** | 首次运行自动生成配置 |
  38. | **增量索引** | 只处理变更文件,快速高效 |
  39. | **跨平台** | Windows、Linux、macOS、WSL 全支持 |
  40. | **多编码** | 自动检测 UTF-8、GBK、GB2312、Latin-1 |
  41. | **AI 友好** | 返回格式化的代码片段,含文件路径和行号 |
  42. ---
  43. ## ⭐ 核心特性
  44. <table>
  45. <tr>
  46. <td width="50%">
  47. ### 🚀 性能优化
  48. - ✅ **增量索引** - 仅索引新文件或修改的文件
  49. - ✅ **批量上传** - 支持批量操作和自动重试
  50. - ✅ **智能分割** - 大文件自动分割为多个块
  51. - ✅ **缓存机制** - SHA-256 哈希避免重复上传
  52. </td>
  53. <td width="50%">
  54. ### 🛠 开发友好
  55. - ✅ **TypeScript** - 完整类型支持
  56. - ✅ **Web 界面** - 实时日志、配置管理、工具调试
  57. - ✅ **.gitignore 支持** - 自动排除无关文件
  58. - ✅ **详细日志** - 可配置的日志级别和轮转
  59. </td>
  60. </tr>
  61. <tr>
  62. <td width="50%">
  63. ### 🌍 兼容性
  64. - ✅ **跨平台路径** - 统一处理 Windows/Unix 路径
  65. - ✅ **WSL 完整支持** - UNC 路径、/mnt 自动转换
  66. - ✅ **多编码支持** - UTF-8, GBK, GB2312, Latin-1
  67. - ✅ **Python 版本兼容** - 共享配置和数据格式
  68. </td>
  69. <td width="50%">
  70. ### 🎯 MCP 集成
  71. - ✅ **标准 MCP 协议** - 完整实现 SDK
  72. - ✅ **search_context 工具** - 语义搜索代码片段
  73. - ✅ **stdio 传输** - 标准输入输出通信
  74. - ✅ **灵活配置** - 命令行参数 + 配置文件
  75. </td>
  76. </tr>
  77. </table>
  78. ---
  79. ## 🚀 快速开始
  80. ### 方式一:通过 NPM 安装(推荐)
  81. ```bash
  82. # 全局安装
  83. npm install -g acemcp-node
  84. # 或本地安装到项目
  85. npm install acemcp-node
  86. ```
  87. ### 方式二:从源码安装
  88. ```bash
  89. # 克隆仓库
  90. git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
  91. cd Ace-Mcp-Node
  92. # 安装依赖
  93. npm install
  94. # 编译 TypeScript
  95. npm run build
  96. ```
  97. ### 首次运行
  98. ```bash
  99. # 启动服务器(首次会创建配置文件)
  100. npm start
  101. # 或启动带 Web 界面
  102. npm start -- --web-port 8080
  103. ```
  104. 访问 http://localhost:8080 查看 Web 管理界面!
  105. ---
  106. ## 📦 安装
  107. ### 系统要求
  108. - **Node.js** >= 18.0.0
  109. - **npm** >= 8.0.0(或 yarn、pnpm)
  110. - **操作系统**:Windows 10+、Linux、macOS、WSL 2
  111. ### 详细安装步骤
  112. #### 1. NPM 全局安装(推荐用于 MCP 客户端)
  113. ```bash
  114. npm install -g acemcp-node
  115. # 验证安装
  116. node -e "console.log(require('acemcp-node/package.json').version)"
  117. ```
  118. #### 2. NPM 本地安装(用于项目集成)
  119. ```bash
  120. # 创建项目目录
  121. mkdir my-mcp-project && cd my-mcp-project
  122. # 初始化 package.json
  123. npm init -y
  124. # 安装 acemcp-node
  125. npm install acemcp-node
  126. # 运行
  127. npx acemcp-node
  128. ```
  129. #### 3. 从源码开发安装
  130. ```bash
  131. git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
  132. cd Ace-Mcp-Node
  133. npm install
  134. npm run build
  135. # 开发模式(自动重载)
  136. npm run dev
  137. ```
  138. ---
  139. ### 配置文件
  140. 首次运行时,程序会在 `~/.acemcp/` 目录下自动创建配置文件:
  141. #### 配置文件位置
  142. ```
  143. ~/.acemcp/
  144. ├── settings.toml # 主配置文件
  145. ├── data/
  146. │ └── projects.json # 项目索引数据
  147. └── log/
  148. └── acemcp.log # 日志文件
  149. ```
  150. #### settings.toml 配置详解
  151. ```toml
  152. # ~/.acemcp/settings.toml
  153. # === API 配置 ===
  154. BASE_URL = "https://api.example.com" # 索引服务器地址
  155. TOKEN = "your-token-here" # 访问令牌
  156. # === 索引配置 ===
  157. BATCH_SIZE = 10 # 批量上传数量(1-50)
  158. MAX_LINES_PER_BLOB = 800 # 单个代码块最大行数
  159. # === 文件类型配置 ===
  160. # 支持索引的文本文件扩展名
  161. TEXT_EXTENSIONS = [
  162. # 编程语言
  163. ".py", ".js", ".ts", ".jsx", ".tsx",
  164. ".java", ".go", ".rs", ".cpp", ".c",
  165. ".h", ".hpp", ".cs", ".rb", ".php",
  166. ".swift", ".kt", ".scala", ".clj",
  167. # 配置和数据
  168. ".md", ".txt", ".json", ".yaml", ".yml",
  169. ".toml", ".xml", ".ini", ".conf",
  170. # Web 相关
  171. ".html", ".css", ".scss", ".sass", ".less",
  172. # 脚本
  173. ".sql", ".sh", ".bash", ".ps1", ".bat"
  174. ]
  175. # === 排除模式 ===
  176. # 不会被索引的目录和文件模式
  177. EXCLUDE_PATTERNS = [
  178. # 虚拟环境
  179. ".venv", "venv", ".env", "env",
  180. "node_modules",
  181. # 版本控制
  182. ".git", ".svn", ".hg",
  183. # Python 缓存
  184. "__pycache__", ".pytest_cache", ".mypy_cache",
  185. ".tox", ".eggs", "*.egg-info",
  186. # 构建产物
  187. "dist", "build", "target", "out",
  188. # IDE 配置
  189. ".idea", ".vscode", ".vs",
  190. # 系统文件
  191. ".DS_Store", "Thumbs.db",
  192. # 编译文件
  193. "*.pyc", "*.pyo", "*.pyd", "*.so", "*.dll"
  194. ]
  195. ```
  196. #### 命令行参数覆盖
  197. ```bash
  198. # 临时使用不同的 API 配置
  199. npm start -- --base-url https://custom-api.com --token custom-token
  200. # 自定义批次大小
  201. npm start -- --batch-size 20
  202. # 启动 Web 界面在指定端口
  203. npm start -- --web-port 3000
  204. # 组合使用
  205. npm start -- --base-url https://api.com --token abc123 --web-port 8080
  206. ```
  207. ---
  208. ## 📘 使用指南
  209. ### 启动方式
  210. #### 1. 标准 MCP 模式(stdio)
  211. ```bash
  212. npm start
  213. ```
  214. 此模式用于 MCP 客户端集成,通过标准输入/输出通信。
  215. #### 2. Web 管理模式
  216. ```bash
  217. npm start -- --web-port 8080
  218. ```
  219. 访问 http://localhost:8080 使用图形界面:
  220. - 📊 查看服务器状态
  221. - ⚙️ 编辑配置文件
  222. - 📝 实时日志查看
  223. - 🛠 工具调试测试
  224. #### 3. 开发模式
  225. ```bash
  226. npm run dev # 标准模式 + 热重载
  227. npm run dev -- --web-port 8080 # Web 模式 + 热重载
  228. ```
  229. ---
  230. ## 🔧 WSL 路径支持完全指南
  231. Acemcp-Node 对 WSL (Windows Subsystem for Linux) 提供**完整的路径支持**,无需手动转换路径格式。
  232. ### 支持的路径格式
  233. | 路径类型 | 原始格式 | 自动转换后 | 使用场景 |
  234. |---------|---------|-----------|---------|
  235. | **Windows 本地** | `C:\Users\username\project` | `C:/Users/username/project` | Windows 上的项目 |
  236. | **WSL 内部** | `/home/user/project` | `/home/user/project` | WSL 文件系统内 |
  237. | **WSL 访问 Windows** | `/mnt/c/Users/username/project` | `C:/Users/username/project` | WSL 中访问 Windows 文件 ⭐ |
  238. | **Windows 访问 WSL** | `\\wsl$\Ubuntu\home\user\project` | `/home/user/project` | Windows 访问 WSL 文件 ⭐ |
  239. ### 使用示例
  240. #### Windows 环境
  241. ```json
  242. {
  243. "tool": "search_context",
  244. "arguments": {
  245. "project_root_path": "C:/Users/username/myproject",
  246. "query": "authentication logic"
  247. }
  248. }
  249. ```
  250. #### WSL 环境访问 Windows 项目
  251. ```json
  252. {
  253. "tool": "search_context",
  254. "arguments": {
  255. "project_root_path": "/mnt/c/Users/username/myproject",
  256. "query": "database connection"
  257. }
  258. }
  259. ```
  260. #### Windows 访问 WSL 项目
  261. ```json
  262. {
  263. "tool": "search_context",
  264. "arguments": {
  265. "project_root_path": "\\\\wsl$\\Ubuntu\\home\\user\\myproject",
  266. "query": "API routes"
  267. }
  268. }
  269. ```
  270. ### 自动处理特性
  271. - ✅ **路径规范化** - 统一使用正斜杠 `/`
  272. - ✅ **末尾斜杠移除** - 自动移除路径末尾的 `/` 或 `\`
  273. - ✅ **UNC 路径转换** - 自动识别并转换 `\\wsl$\` 格式
  274. - ✅ **/mnt 转换** - 自动将 `/mnt/c/` 转为 `C:/`
  275. ### 故障排除
  276. 如果遇到路径问题,请参考:
  277. - 📄 [WSL 路径支持指南](WSL_PATH_GUIDE.md) - WSL 环境专用指南
  278. - 📄 [路径故障排查指南](PATH_TROUBLESHOOTING.md) - 详细的路径问题诊断
  279. ---
  280. ## 🔌 在 MCP 客户端中配置
  281. ### Claude Desktop 配置
  282. 编辑 Claude Desktop 配置文件:
  283. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  284. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  285. **Linux**: `~/.config/Claude/claude_desktop_config.json`
  286. #### 方式一:使用全局安装的包
  287. ```json
  288. {
  289. "mcpServers": {
  290. "acemcp": {
  291. "command": "npx",
  292. "args": ["acemcp-node"],
  293. "env": {}
  294. }
  295. }
  296. }
  297. ```
  298. #### 方式二:指定本地路径(从源码安装)
  299. ```json
  300. {
  301. "mcpServers": {
  302. "acemcp": {
  303. "command": "node",
  304. "args": ["D:/projects/Ace-Mcp-Node/dist/index.js"],
  305. "env": {}
  306. }
  307. }
  308. }
  309. ```
  310. #### 方式三:带 Web 界面
  311. ```json
  312. {
  313. "mcpServers": {
  314. "acemcp": {
  315. "command": "node",
  316. "args": [
  317. "D:/projects/Ace-Mcp-Node/dist/index.js",
  318. "--web-port",
  319. "8080"
  320. ],
  321. "env": {}
  322. }
  323. }
  324. }
  325. ```
  326. #### 方式四:自定义 API 配置
  327. ```json
  328. {
  329. "mcpServers": {
  330. "acemcp": {
  331. "command": "node",
  332. "args": [
  333. "D:/projects/Ace-Mcp-Node/dist/index.js",
  334. "--base-url",
  335. "https://your-api.com",
  336. "--token",
  337. "your-token-here"
  338. ],
  339. "env": {}
  340. }
  341. }
  342. }
  343. ```
  344. #### WSL 环境特殊配置
  345. ```json
  346. {
  347. "mcpServers": {
  348. "acemcp": {
  349. "command": "node",
  350. "args": ["\\\\wsl$\\Ubuntu\\home\\user\\Ace-Mcp-Node\\dist\\index.js"],
  351. "env": {}
  352. }
  353. }
  354. }
  355. ```
  356. ### 其他 MCP 客户端
  357. 对于支持 MCP 协议的其他客户端(如 Zed、Cursor 等),配置方式类似,请参考各客户端的 MCP 配置文档。
  358. ### 验证配置
  359. 配置完成后:
  360. 1. 重启 MCP 客户端
  361. 2. 检查日志文件:`~/.acemcp/log/acemcp.log`
  362. 3. 如果启用了 Web 界面,访问 http://localhost:8080
  363. ---
  364. ## 📚 API 文档
  365. ### `search_context` 工具
  366. 在项目代码库中执行**语义搜索**,自动进行增量索引并返回相关代码片段。
  367. #### 参数
  368. | 参数 | 类型 | 必需 | 说明 | 示例 |
  369. |------|------|------|------|------|
  370. | `project_root_path` | string | ✅ | 项目根目录的**绝对路径**,使用正斜杠 `/` | `C:/Users/username/myproject` |
  371. | `query` | string | ✅ | 自然语言搜索查询 | `"authentication middleware"` |
  372. #### 功能流程
  373. ```
  374. 1. 接收搜索请求
  375. ↓
  376. 2. 检查项目索引状态
  377. ↓
  378. 3. 执行增量索引(仅新增/修改文件)
  379. ├─ 收集文件(遵循 .gitignore)
  380. ├─ 分割大文件
  381. ├─ 计算 SHA-256 哈希
  382. └─ 批量上传到服务器
  383. ↓
  384. 4. 执行语义搜索
  385. ↓
  386. 5. 返回格式化结果(文件路径 + 行号 + 代码片段)
  387. ```
  388. #### 返回格式
  389. ```typescript
  390. interface SearchResult {
  391. type: 'text';
  392. text: string; // 格式化的搜索结果
  393. }
  394. ```
  395. **返回示例**:
  396. ```
  397. Found 3 relevant code snippets:
  398. ────────────────────────────────────────
  399. File: src/auth/middleware.ts (Lines 15-28)
  400. export function authMiddleware(req: Request, res: Response, next: NextFunction) {
  401. const token = req.headers.authorization?.split(' ')[1];
  402. if (!token) {
  403. return res.status(401).json({ error: 'No token provided' });
  404. }
  405. try {
  406. const decoded = jwt.verify(token, process.env.JWT_SECRET);
  407. req.user = decoded;
  408. next();
  409. } catch (error) {
  410. res.status(403).json({ error: 'Invalid token' });
  411. }
  412. }
  413. ────────────────────────────────────────
  414. File: src/auth/login.ts (Lines 42-56)
  415. ...
  416. ```
  417. #### 使用示例
  418. ##### 示例 1:搜索认证逻辑
  419. ```json
  420. {
  421. "tool": "search_context",
  422. "arguments": {
  423. "project_root_path": "C:/Users/username/myproject",
  424. "query": "user authentication and JWT token verification"
  425. }
  426. }
  427. ```
  428. ##### 示例 2:搜索数据库配置
  429. ```json
  430. {
  431. "tool": "search_context",
  432. "arguments": {
  433. "project_root_path": "/home/user/backend-api",
  434. "query": "database connection pool configuration"
  435. }
  436. }
  437. ```
  438. ##### 示例 3:搜索错误处理
  439. ```json
  440. {
  441. "tool": "search_context",
  442. "arguments": {
  443. "project_root_path": "D:/projects/react-app",
  444. "query": "error boundary and exception handling in React components"
  445. }
  446. }
  447. ```
  448. #### 错误处理
  449. | 错误类型 | 返回信息 | 解决方案 |
  450. |---------|---------|---------|
  451. | 路径不存在 | `Error: Project root path does not exist` | 检查路径拼写和权限 |
  452. | 缺少参数 | `Error: project_root_path is required` | 提供所有必需参数 |
  453. | API 连接失败 | `Error: Failed to connect to API` | 检查 BASE_URL 和 TOKEN 配置 |
  454. | 索引失败 | `Error: Failed to index project` | 查看日志文件诊断 |
  455. ---
  456. ## 💡 使用场景示例
  457. ### 场景 1:AI 助手代码审查
  458. **需求**:让 AI 助手理解项目的认证机制
  459. ```
  460. 用户:@acemcp 我的项目中是如何实现用户认证的?
  461. AI 助手调用:
  462. {
  463. "tool": "search_context",
  464. "arguments": {
  465. "project_root_path": "C:/projects/my-saas-app",
  466. "query": "user authentication login signup middleware"
  467. }
  468. }
  469. 结果:AI 获取认证相关代码,理解实现方式,提供审查建议
  470. ```
  471. ### 场景 2:Bug 调试
  472. **需求**:定位支付模块的错误处理
  473. ```
  474. 用户:@acemcp 支付失败时的错误是如何处理的?
  475. AI 助手调用:
  476. {
  477. "tool": "search_context",
  478. "arguments": {
  479. "project_root_path": "D:/ecommerce-backend",
  480. "query": "payment error handling failure rollback"
  481. }
  482. }
  483. 结果:快速定位支付错误处理逻辑,发现潜在问题
  484. ```
  485. ### 场景 3:新功能开发
  486. **需求**:了解现有 API 路由结构
  487. ```
  488. 用户:@acemcp 我需要添加一个新的 API 端点,现有的路由是怎么组织的?
  489. AI 助手调用:
  490. {
  491. "tool": "search_context",
  492. "arguments": {
  493. "project_root_path": "/home/dev/api-server",
  494. "query": "API routes endpoints definition express router"
  495. }
  496. }
  497. 结果:理解路由结构,按照现有模式实现新端点
  498. ```
  499. ### 场景 4:文档生成
  500. **需求**:为工具函数生成文档
  501. ```
  502. 用户:@acemcp 帮我为 utils 目录下的工具函数生成文档
  503. AI 助手调用:
  504. {
  505. "tool": "search_context",
  506. "arguments": {
  507. "project_root_path": "C:/company/shared-utils",
  508. "query": "utility helper functions in utils directory"
  509. }
  510. }
  511. 结果:获取所有工具函数,自动生成 JSDoc/TSDoc 文档
  512. ```
  513. ### 场景 5:代码重构
  514. **需求**:找到所有使用旧 API 的地方
  515. ```
  516. 用户:@acemcp 我们要废弃 legacyApi,找到所有调用它的地方
  517. AI 助手调用:
  518. {
  519. "tool": "search_context",
  520. "arguments": {
  521. "project_root_path": "D:/legacy-app",
  522. "query": "legacyApi function calls usage"
  523. }
  524. }
  525. 结果:列出所有调用点,规划重构策略
  526. ```
  527. ---
  528. ## 🌐 Web 管理界面
  529. ### 启动 Web 界面
  530. ```bash
  531. # 标准端口 8080
  532. npm start -- --web-port 8080
  533. # 自定义端口
  534. npm start -- --web-port 3000
  535. ```
  536. 访问:http://localhost:8080
  537. ### 功能特性
  538. | 功能模块 | 说明 | 用途 |
  539. |---------|------|------|
  540. | **📊 服务器状态** | 实时显示运行状态、索引项目数、配置信息 | 监控服务器健康状况 |
  541. | **⚙️ 配置管理** | 在线编辑 `settings.toml`,保存后立即生效 | 无需手动编辑配置文件 |
  542. | **📝 实时日志** | WebSocket 推送实时日志,支持过滤和搜索 | 调试和问题诊断 |
  543. | **🛠 工具调试** | 模拟 MCP 工具调用,测试搜索查询 | 开发和测试 |
  544. | **🌍 双语支持** | 中文/英文界面切换 | 国际化支持 |
  545. ### 界面预览
  546. #### 服务器状态面板
  547. ```
  548. ┌─────────────────────────────────────┐
  549. │ 🟢 MCP Server Status │
  550. │ │
  551. │ Status: Running │
  552. │ Indexed Projects: 5 │
  553. │ Port: 8080 │
  554. │ Base URL: https://api... │
  555. └─────────────────────────────────────┘
  556. ```
  557. #### 配置编辑器
  558. - 语法高亮 TOML 编辑器
  559. - 实时验证
  560. - 一键保存和应用
  561. #### 实时日志查看器
  562. - 彩色日志级别标识(DEBUG/INFO/WARNING/ERROR)
  563. - 自动滚动
  564. - 日志搜索和过滤
  565. - 导出日志
  566. #### 工具调试面板
  567. ```json
  568. {
  569. "tool": "search_context",
  570. "arguments": {
  571. "project_root_path": "C:/your/project",
  572. "query": "your search query"
  573. }
  574. }
  575. ```
  576. 点击"测试工具"按钮,查看返回结果。
  577. ### 安全建议
  578. ⚠️ **重要**:Web 界面**仅绑定 localhost**,不对外网开放。
  579. 如需远程访问:
  580. 1. 使用 SSH 隧道:`ssh -L 8080:localhost:8080 user@server`
  581. 2. 配置反向代理(Nginx/Caddy)并添加认证
  582. 3. **不要**直接暴露在公网
  583. ---
  584. ## 📁 项目结构
  585. ```
  586. Ace-Mcp-Node/
  587. ├── src/ # TypeScript 源代码
  588. │ ├── index.ts # 🚪 MCP 服务器入口点
  589. │ │ # - 初始化 MCP 服务器
  590. │ │ # - 注册工具
  591. │ │ # - 处理命令行参数
  592. │ │
  593. │ ├── config.ts # ⚙️ 配置管理单例
  594. │ │ # - 加载 settings.toml
  595. │ │ # - 生成默认配置
  596. │ │ # - 提供配置访问接口
  597. │ │
  598. │ ├── logger.ts # 📝 日志系统单例
  599. │ │ # - 文件日志轮转
  600. │ │ # - 控制台输出
  601. │ │ # - WebSocket 广播集成
  602. │ │
  603. │ ├── index/ # 📊 索引管理模块
  604. │ │ └── manager.ts # - 增量索引逻辑
  605. │ │ # - 文件收集和分割
  606. │ │ # - .gitignore 解析
  607. │ │ # - SHA-256 哈希计算
  608. │ │ # - 批量上传
  609. │ │
  610. │ ├── tools/ # 🛠 MCP 工具实现
  611. │ │ └── searchContext.ts # - search_context 工具
  612. │ │ # - 参数验证
  613. │ │ # - 搜索 API 调用
  614. │ │
  615. │ ├── utils/ # 🔧 工具函数
  616. │ │ ├── pathUtils.ts # - 路径规范化
  617. │ │ │ # - WSL 路径转换
  618. │ │ │ # - UNC 路径处理
  619. │ │ └── detailedLogger.ts # - 详细日志格式化
  620. │ │
  621. │ └── web/ # 🌐 Web 管理界面
  622. │ ├── app.ts # - Express 应用
  623. │ │ # - API 路由
  624. │ │ # - WebSocket 服务器
  625. │ ├── logBroadcaster.ts # - 日志广播器
  626. │ └── templates/
  627. │ └── index.html # - 单页应用界面
  628. │
  629. ├── dist/ # 📦 编译输出(发布到 NPM)
  630. │ ├── *.js # - 编译后的 JavaScript
  631. │ ├── *.d.ts # - TypeScript 类型定义
  632. │ ├── *.js.map # - Source Maps
  633. │ └── web/templates/ # - Web 界面资源
  634. │
  635. ├── node_modules/ # 依赖包(不发布)
  636. │
  637. ├── package.json # 📋 NPM 包配置
  638. ├── tsconfig.json # 📋 TypeScript 编译配置
  639. ├── LICENSE # 📄 ISC 许可证
  640. ├── README.md # 📖 本文档
  641. │
  642. └── docs/ # 📚 额外文档
  643. ├── PATH_TROUBLESHOOTING.md # - 路径问题排查
  644. ├── WSL_PATH_GUIDE.md # - WSL 路径指南
  645. └── USAGE_GUIDE.md # - 详细使用指南
  646. ```
  647. ### 用户数据目录
  648. ```
  649. ~/.acemcp/ # 用户配置和数据
  650. ├── settings.toml # 主配置文件
  651. ├── data/
  652. │ └── projects.json # 项目索引元数据
  653. └── log/
  654. ├── acemcp.log # 当前日志
  655. ├── acemcp.log.1 # 轮转日志
  656. └── ... # 保留最近 10 个
  657. ```
  658. ---
  659. ## 🔄 与 Python 版本的兼容性
  660. Acemcp-Node 与 [Acemcp-Python](https://github.com/yeuxuan/Ace-Mcp-Python) **完全兼容**,可以无缝切换。
  661. | 兼容项 | 说明 | 位置 |
  662. |--------|------|------|
  663. | **配置文件** | 共享同一个 `settings.toml` | `~/.acemcp/settings.toml` |
  664. | **项目数据** | 共享项目索引元数据 | `~/.acemcp/data/projects.json` |
  665. | **API 接口** | 调用相同的索引和搜索 API | `BASE_URL` 配置 |
  666. | **哈希算法** | 使用相同的 SHA-256 计算 `blob_name` | 增量索引 |
  667. | **文件格式** | TOML 配置、JSON 数据 | 通用格式 |
  668. ### 切换版本
  669. ```bash
  670. # 从 Python 版本切换到 Node.js 版本
  671. # 1. 停止 Python 版本
  672. pkill -f acemcp
  673. # 2. 启动 Node.js 版本(使用相同配置)
  674. npm start
  675. # 配置文件和索引数据自动共享,无需迁移
  676. ```
  677. ### 差异说明
  678. | 特性 | Python 版本 | Node.js 版本 |
  679. |------|------------|-------------|
  680. | **运行时** | Python 3.10+ | Node.js 18.0+ |
  681. | **性能** | 良好 | 略快(V8 引擎) |
  682. | **内存占用** | 中等 | 略低 |
  683. | **依赖管理** | pip/uv | npm/yarn/pnpm |
  684. | **类型安全** | Type hints | TypeScript 严格模式 |
  685. | **Web 界面** | ✅ | ✅ |
  686. | **WSL 支持** | ✅ | ✅ |
  687. ---
  688. ## 🛠 开发
  689. ### 开发环境设置
  690. ```bash
  691. # 1. 克隆仓库
  692. git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
  693. cd Ace-Mcp-Node
  694. # 2. 安装依赖
  695. npm install
  696. # 3. 启动开发模式(热重载)
  697. npm run dev
  698. # 4. 或启动带 Web 界面的开发模式
  699. npm run dev -- --web-port 8080
  700. ```
  701. ### NPM Scripts
  702. | 命令 | 说明 | 用途 |
  703. |------|------|------|
  704. | `npm run build` | 编译 TypeScript → `dist/` | 生产构建 |
  705. | `npm run dev` | 开发模式 + 热重载 | 开发调试 |
  706. | `npm start` | 运行编译后的代码 | 生产运行 |
  707. | `npm start:web` | 启动带 Web 界面(8080) | Web 管理 |
  708. | `npm test` | 运行测试脚本 | 测试 |
  709. | `npm run copy-templates` | 复制 Web 模板 | 构建步骤 |
  710. ### 代码规范
  711. #### TypeScript 配置
  712. - **严格模式** - 启用所有严格类型检查
  713. - **ES2022 目标** - 现代 JavaScript 特性
  714. - **ESM 模块** - 使用 ES 模块系统
  715. - **Source Maps** - 调试支持
  716. #### 命名约定
  717. ```typescript
  718. // 类名:PascalCase
  719. class IndexManager {}
  720. // 函数:camelCase
  721. function normalizePath() {}
  722. // 常量:UPPER_SNAKE_CASE
  723. const USER_CONFIG_DIR = '~/.acemcp';
  724. // 接口:PascalCase + 'I' 前缀(可选)
  725. interface IConfig {}
  726. ```
  727. #### 导入规范
  728. ```typescript
  729. // ✅ 正确:ESM 必须包含 .js 扩展名
  730. import { getConfig } from './config.js';
  731. import { IndexManager } from './index/manager.js';
  732. // ❌ 错误:缺少扩展名
  733. import { getConfig } from './config';
  734. ```
  735. ### 日志系统
  736. 日志文件位置:`~/.acemcp/log/acemcp.log`
  737. #### 日志级别
  738. | 级别 | 用途 | 示例 |
  739. |------|------|------|
  740. | **DEBUG** | 详细调试信息 | `logger.debug('File hash calculated')` |
  741. | **INFO** | 重要操作记录 | `logger.info('Project indexed successfully')` |
  742. | **WARNING** | 非致命警告 | `logger.warning('File encoding fallback')` |
  743. | **ERROR** | 错误信息 | `logger.error('API request failed')` |
  744. | **EXCEPTION** | 异常堆栈 | `logger.exception('Error in tool', error)` |
  745. #### 日志配置
  746. - **文件轮转** - 单文件最大 5MB
  747. - **保留数量** - 最近 10 个日志文件
  748. - **控制台** - INFO 级别及以上(非 stdio 模式)
  749. - **文件** - DEBUG 级别及以上
  750. - **WebSocket** - 实时广播到 Web 界面
  751. ### 添加新工具
  752. ```typescript
  753. // 1. 创建工具文件:src/tools/myTool.ts
  754. export async function myTool(args: { param1: string }): Promise<{ type: 'text'; text: string }> {
  755. try {
  756. // 参数验证
  757. if (!args.param1) {
  758. return { type: 'text', text: 'Error: param1 is required' };
  759. }
  760. // 业务逻辑
  761. const result = await doSomething(args.param1);
  762. return { type: 'text', text: result };
  763. } catch (error: any) {
  764. logger.exception('Error in myTool', error);
  765. return { type: 'text', text: `Error: ${error.message}` };
  766. }
  767. }
  768. // 2. 在 src/index.ts 中注册
  769. server.setRequestHandler(CallToolRequestSchema, async (request) => {
  770. if (request.params.name === 'my_tool') {
  771. return await myTool(request.params.arguments);
  772. }
  773. // ...
  774. });
  775. // 3. 添加到工具列表
  776. server.setRequestHandler(ListToolsRequestSchema, async () => ({
  777. tools: [
  778. {
  779. name: 'my_tool',
  780. description: 'My custom tool',
  781. inputSchema: {
  782. type: 'object',
  783. properties: {
  784. param1: { type: 'string', description: 'Parameter 1' }
  785. },
  786. required: ['param1']
  787. }
  788. },
  789. // ...
  790. ]
  791. }));
  792. ```
  793. ---
  794. ## 🐛 故障排除
  795. ### 常见问题速查
  796. | 问题 | 症状 | 解决方案 |
  797. |------|------|---------|
  798. | **路径不存在** | `Project root path does not exist` | [路径问题](#路径问题) |
  799. | **API 连接失败** | `Failed to connect to API` | [连接问题](#连接问题) |
  800. | **编码错误** | `UnsupportedEncoding` | [编码问题](#编码问题) |
  801. | **端口占用** | `EADDRINUSE` | [端口问题](#web-界面无法访问) |
  802. | **权限错误** | `EACCES` | [权限问题](#权限问题) |
  803. | **上传失败** | 批次上传失败 | [上传失败处理](UPLOAD_FAILURE_HANDLING.md) |
  804. | **日志文件过大** | 日志占用空间过多 | [日志轮转配置](LOG_ROTATION_CONFIG.md) |
  805. | **WSL 路径** | 路径转换失败 | [WSL 指南](WSL_PATH_GUIDE.md) |
  806. ### 路径问题
  807. #### 症状
  808. ```
  809. Error: Project root path does not exist: /invalid/path
  810. ```
  811. #### 诊断步骤
  812. 1. **检查路径格式**
  813. ```bash
  814. # ✅ 正确格式(使用正斜杠)
  815. C:/Users/username/project
  816. # ❌ 错误格式(使用反斜杠)
  817. C:\Users\username\project
  818. # ❌ 错误格式(末尾有斜杠)
  819. C:/Users/username/project/
  820. ```
  821. 2. **验证路径存在**
  822. ```bash
  823. # Windows
  824. dir "C:\Users\username\project"
  825. # Linux/macOS
  826. ls -la /home/user/project
  827. # WSL
  828. ls -la /mnt/c/Users/username/project
  829. ```
  830. 3. **使用绝对路径**
  831. ```json
  832. {
  833. "project_root_path": "C:/Users/username/myproject" // ✅ 绝对路径
  834. }
  835. ```
  836. 4. **WSL 特殊情况**
  837. - Windows 访问 WSL: `\\wsl$\Ubuntu\home\user\project` → 自动转换
  838. - WSL 访问 Windows: `/mnt/c/Users/username/project` → 自动转换
  839. **详细指南**:
  840. - 📄 [路径故障排查指南](PATH_TROUBLESHOOTING.md)
  841. - 📄 [WSL 路径支持指南](WSL_PATH_GUIDE.md)
  842. ### 连接问题
  843. #### 症状
  844. ```
  845. Error: Failed to connect to API: https://api.example.com
  846. ```
  847. #### 解决方案
  848. 1. **检查配置文件**
  849. ```bash
  850. cat ~/.acemcp/settings.toml
  851. ```
  852. 2. **验证 API 可达性**
  853. ```bash
  854. curl -H "Authorization: Bearer YOUR_TOKEN" https://your-api.com/health
  855. ```
  856. 3. **检查网络代理**
  857. ```bash
  858. echo $HTTP_PROXY
  859. echo $HTTPS_PROXY
  860. ```
  861. 4. **临时覆盖配置**
  862. ```bash
  863. npm start -- --base-url https://your-api.com --token your-token
  864. ```
  865. ### 编码问题
  866. #### 症状
  867. ```
  868. Warning: Failed to read file with UTF-8, trying alternative encodings
  869. ```
  870. #### 说明
  871. Acemcp-Node **自动处理**多种编码:
  872. 1. UTF-8(默认)
  873. 2. GBK(简体中文)
  874. 3. GB2312(简体中文)
  875. 4. Latin-1(西欧语言)
  876. 如果所有编码都失败,文件将被跳过并记录警告。
  877. #### 手动指定编码(暂不支持)
  878. 如需支持其他编码,请提交 [Issue](https://github.com/yeuxuan/Ace-Mcp-Node/issues)。
  879. ### Web 界面无法访问
  880. #### 症状
  881. ```
  882. Error: listen EADDRINUSE: address already in use :::8080
  883. ```
  884. #### 解决方案
  885. 1. **检查端口占用**
  886. ```bash
  887. # Windows
  888. netstat -ano | findstr :8080
  889. taskkill /PID <PID> /F
  890. # Linux/macOS
  891. lsof -i :8080
  892. kill -9 <PID>
  893. ```
  894. 2. **使用其他端口**
  895. ```bash
  896. npm start -- --web-port 3000
  897. ```
  898. 3. **检查防火墙**
  899. ```bash
  900. # Windows 防火墙
  901. netsh advfirewall firewall show rule name=all | findstr 8080
  902. # Linux 防火墙
  903. sudo ufw status
  904. sudo ufw allow 8080
  905. ```
  906. ### 权限问题
  907. #### 症状
  908. ```
  909. Error: EACCES: permission denied
  910. ```
  911. #### 解决方案
  912. 1. **检查目录权限**
  913. ```bash
  914. # Linux/macOS
  915. ls -la ~/.acemcp
  916. chmod 755 ~/.acemcp
  917. chmod 644 ~/.acemcp/settings.toml
  918. # Windows(以管理员身份运行)
  919. icacls "%USERPROFILE%\.acemcp" /grant %USERNAME%:F
  920. ```
  921. 2. **避免使用 sudo**
  922. ```bash
  923. # ❌ 不推荐
  924. sudo npm install -g acemcp-node
  925. # ✅ 推荐
  926. npm config set prefix ~/.npm-global
  927. export PATH=~/.npm-global/bin:$PATH
  928. npm install -g acemcp-node
  929. ```
  930. ### 索引失败
  931. #### 症状
  932. ```
  933. Error: Failed to index project: timeout
  934. ```
  935. #### 解决方案
  936. 1. **检查项目大小**
  937. ```bash
  938. du -sh /path/to/project
  939. ```
  940. 2. **增加批次大小**(settings.toml)
  941. ```toml
  942. BATCH_SIZE = 20 # 默认 10,可增加到 50
  943. ```
  944. 3. **检查网络稳定性**
  945. ```bash
  946. ping api.example.com
  947. ```
  948. 4. **查看详细日志**
  949. ```bash
  950. tail -f ~/.acemcp/log/acemcp.log
  951. ```
  952. ### 获取帮助
  953. 如果以上方法都无法解决问题:
  954. 1. **查看日志**
  955. ```bash
  956. cat ~/.acemcp/log/acemcp.log
  957. ```
  958. 2. **提交 Issue**
  959. - 访问 [GitHub Issues](https://github.com/yeuxuan/Ace-Mcp-Node/issues)
  960. - 提供错误信息和日志片段
  961. - 描述复现步骤
  962. 3. **社区讨论**
  963. - 参与 [Discussions](https://github.com/yeuxuan/Ace-Mcp-Node/discussions)
  964. ---
  965. ## 🤝 贡献
  966. 我们欢迎所有形式的贡献!
  967. ### 贡献方式
  968. - 🐛 **报告 Bug** - 提交 [Issue](https://github.com/yeuxuan/Ace-Mcp-Node/issues)
  969. - 💡 **建议功能** - 在 [Discussions](https://github.com/yeuxuan/Ace-Mcp-Node/discussions) 中讨论
  970. - 📖 **改进文档** - 修正错误或添加示例
  971. - 🔧 **提交代码** - Fork 并创建 Pull Request
  972. ### 开发流程
  973. ```bash
  974. # 1. Fork 仓库
  975. gh repo fork yeuxuan/Ace-Mcp-Node --clone
  976. # 2. 创建特性分支
  977. cd Ace-Mcp-Node
  978. git checkout -b feature/my-feature
  979. # 3. 开发和测试
  980. npm install
  981. npm run dev
  982. # 进行修改...
  983. npm run build
  984. npm test
  985. # 4. 提交变更
  986. git add .
  987. git commit -m "feat: add my feature"
  988. # 5. 推送并创建 PR
  989. git push origin feature/my-feature
  990. gh pr create
  991. ```
  992. ### 代码规范
  993. - 遵循 TypeScript 严格模式
  994. - 使用 ESLint 和 Prettier(如有配置)
  995. - 添加适当的注释和类型定义
  996. - 保持向后兼容性
  997. ### Commit 规范
  998. 使用 [Conventional Commits](https://www.conventionalcommits.org/):
  999. ```
  1000. feat: 新功能
  1001. fix: Bug 修复
  1002. docs: 文档更新
  1003. style: 代码格式
  1004. refactor: 重构
  1005. test: 测试相关
  1006. chore: 构建/工具相关
  1007. ```
  1008. ---
  1009. ## 📧 联系方式
  1010. - **作者**: yihua
  1011. - **Email**: 487735913@qq.com
  1012. - **GitHub**: [@yeuxuan](https://github.com/yeuxuan)
  1013. - **项目主页**: https://github.com/yeuxuan/Ace-Mcp-Node
  1014. ---
  1015. ## 🙏 致谢
  1016. - 基于 [Acemcp-Python](https://github.com/yeuxuan/Ace-Mcp-Python) 的设计和实现
  1017. - 感谢 [Model Context Protocol](https://github.com/modelcontextprotocol) 团队
  1018. - 感谢所有贡献者和使用者
  1019. ---
  1020. ## 🔗 相关资源
  1021. - **MCP 官方文档**: https://modelcontextprotocol.io/
  1022. - **Python 版本**: https://github.com/yeuxuan/Ace-Mcp-Python
  1023. - **NPM 包**: https://www.npmjs.com/package/acemcp-node
  1024. - **问题追踪**: https://github.com/yeuxuan/Ace-Mcp-Node/issues
  1025. - **更新日志**: [CHANGELOG.md](CHANGELOG.md)
  1026. ---
  1027. <div align="center">
  1028. **⭐ 如果这个项目对你有帮助,请给它一个 Star! ⭐**
  1029. Made with ❤️ by [yihua](https://github.com/yeuxuan)
  1030. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.