STARWARCLOUD STARWAR.AI
返回市场
王牌-MCP节点

王牌-MCP节点

作者：yeuxuan161 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

技术文档摘要

Acemcp Node.js 实现

npm 版本 npm 下载次数 许可证 Node.js TypeScript <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">

📑 目录

📖 简介

Acemcp 是一个高性能的 MCP（模型上下文协议）服务器，专门设计用于像 Claude、GPT 等 AI 助手，并且具有代码库索引和语义搜索的能力。通过 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
  • ✅ 可搜索文本工具 - 语义搜索代码片段
  • ✅ STDio 传输 - 标准输入输出通信
  • ✅ 灵活配置 - 命令行参数+配置文件
</td> </tr> </table>

🚀 快速开始

方法 1：通过 NPM 安装（推荐）

# 全局安装
npm install -g acemcp-node

# 或者本地安装到项目
npm install acemcp-node

方法 2：从源代码安装

# 克隆仓库
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 模式 + 热重载

🔧 完整指南支持 WSI 路径

Acemcp Node 提供了对 Windows Subsystem for Linux (WSL) 的完整路径支持，无需手动转换路径格式。

支持的路径格式

路径类型原始格式自动转换使用场景
Windows 本地C:\Users\username\projectC:/Users/username/projectWindows 上的项目
WSI 内部/home/user/project/home/user/projectWSI 文件系统内
通过 WSL 访问 Windows/mnt/c/Users/username/projectC:/Users/username/project在 WSL 中访问 Windows 文件 ⭐
Windows 访问 WSL\\wsl$\Ubuntu\home\user\project/home/user/projectWindows 访问 WSA 文件 ⭐

使用示例

Windows 环境

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "C:/Users/username/myproject",
    "query": "authentication logic"
  }
}

在 WSI 环境中访问 Windows 项目

{
  "tool": "search_context",
  "arguments": {
    "project_root_path": "/mnt/c/Users/username/myproject",
    "query": "database connection"
  }
}

Windows 访问 WSA 项目

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

方法 1：使用全局安装的包

{
  "mcpServers": {
    "acemcp": {
      "command": "npx",
      "args": ["acemcp-node"],
      "env": {}
    }
  }
}

方法 2：指定本地路径（从源代码安装）

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

方法 3：带有 Web 界面

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

方法 4：自定义 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": {}
    }
  }
}

WSI 环境的特殊配置

{
  "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_pathstring