ACE MCP

Name: ACE MCP
Author: qy527145

作者：qy527145542 星标更新：2025-11-19

安装使用来源：spider==github.com

项目介绍

【技术文档摘要】：

简体中文 | English

Acemcp

用于代码库索引和语义搜索的MCP服务器。

安装

作为工具进行安装（推荐）

# 安装到系统
uv tool install acemcp

# 或临时运行（无需安装）
uvx acemcp

开发与安装

# 克隆仓库
git clone https://github.com/qy527145/acemcp.git
cd acemcp

# 安装依赖
uv sync

# 运行
uv run acemcp

配置

首次运行时会自动创建配置文件 ~/.acemcp/settings.toml，包括默认值。

编辑 ~/.acemcp/settings.toml 配置：

BATCH_SIZE = 10
MAX_LINES_PER_BLOB = 800
BASE_URL = "https://your-api-endpoint.com"
TOKEN = "your-bearer-token-here"
TEXT_EXTENSIONS = [".py", ".js", ".ts", ...]
EXCLUDE_PATTERNS = [".venv", "node_modules", ".git", "__pycache__", "*.pyc", ...]

配置选项：

BATCH_SIZE 每批上传的文件数量（默认：10）
MAX_LINES_PER_BLOB 在分割大文件之前的最大行数（默认：800）
BASE_URL API端点URL
TOKEN 认证令牌
TEXT_EXTENSIONS 要索引的文件扩展名列表
EXCLUDE_PATTERNS 要排除的模式列表（支持通配符如 *.pyc）

您还可以通过以下方法进行配置：

命令行参数（最高优先级）：--base-url、--token
Web管理界面（更新用户资料）
环境变量（使用）ACEMCP_ 前缀）

MCP配置

在您的MCP客户端配置中添加以下内容（例如Claude Desktop）：

基本配置

{
  "mcpServers": {
    "acemcp": {
      "command": "uvx",
      "args": [
        "acemcp"
      ]
    }
  }
}

可用的命令行参数：

--base-url：覆盖BASE-URL配置
--token：覆盖TOKEN配置
--web-port：在指定端口启用Web管理界面（例如8080）

启用Web管理界面配置

要启用Web管理界面，请添加 --web-port 参数

{
  "mcpServers": {
    "acemcp": {
      "command": "uvx",
      "args": [
        "acemcp",
        "--web-port",
        "8888"
      ]
    }
  }
}

然后访问管理界面：http://localhost:8888

Web管理功能：

配置管理：查看和编辑服务器配置（BASE-URL、TOKEN、BATCHSIZE、MAX_LINE、PER-BLOB、TEX、EXENSIONS）
实时日志：通过WebSocket连接实时监控服务器日志，并具有智能重连功能
- 指数退避重连策略（1秒 → 1.5秒 → 2.25秒... 最大30秒）
- 最多10次重连尝试以防止无限循环
- 网络故障时自动重连
- 减少日志噪音（WebSocket连接记录在DEBUG级别）
工具调试器：直接从Web界面测试和调试MCP工具
- 测试 search_context 工具，输入项目路径和查询
- 查看格式化的结果和错误消息

工具

search_context

根据查询搜索相关的代码上下文。此工具在搜索前自动执行增量索引，确保结果始终是最新的。它在您的代码库中执行语义搜索，并返回一个格式化的文本片段，显示相关代码的位置。

核心功能：

自动增量索引：每次搜索前，工具仅自动索引新或修改过的文件，跳过未修改的文件以提高效率
无需手动索引：您不需要手动索引项——只需搜索，工具会自动处理索引
始终保持最新：搜索结果反映代码库的当前状态
多种编码支持：自动检测和处理多种文件编码（UTF-8、GBK、GB2312、Latin-1）
.gitignore集成：索引项时自动遵循 .gitignore 模式

参数

project_root_path（字符串）：项目的根目录绝对路径
- 重要：即使在Windows上也使用正斜杠（/）作为路径分隔符
- Windows 示例：C:/Users/username/projects/myproject
- Linux/Mac 示例：/home/username/projects/myproject
query（字符串）：用于查找相关代码上下文的自然语言搜索查询
- 使用与您正在寻找的内容相关的描述性关键词
- 工具执行语义匹配，而不仅仅是关键词搜索
- 返回带有文件路径和行号的代码片段

返回内容：

匹配您查询的文件中的格式化文本片段
每个片段的文件路径和行号
相关代码部分周围的上下文
按相关性排序的多个结果

查询示例：

搜索配置代码：

{
  "project_root_path": "C:/Users/username/projects/myproject",
  "query": "日志配置 设置 初始化 logger"
}

返回：与日志设置、logger初始化和配置相关的代码

搜索身份验证逻辑：

{
  "project_root_path": "C:/Users/username/projects/myproject",
  "query": "用户认证 登录 密码验证"
}

返回：身份验证处理器、登录函数、密码验证代码

搜索数据库代码：

{
  "project_root_path": "C:/Users/username/projects/myproject",
  "query": "数据库连接池 初始化"
}

返回：数据库连接设置、连接池配置、初始化代码

搜索错误处理：

{
  "project_root_path": "C:/Users/username/projects/myproject",
  "query": "错误处理 异常 try catch"
}

返回：错误处理模式、异常处理器、try catch块

搜索API端点：

{
  "project_root_path": "C:/Users/username/projects/myproject",
  "query": "API 端点 路由 HTTP 处理器"
}

返回：API路由定义、HTTP处理器、端点实现

获得更好结果的提示：

使用多个相关关键词（例如“日志配置设置”而不是仅仅“日志”）
包含您正在寻找的具体技术术语
描述功能而不是确切的变量名
如果第一次查询没有返回您需要的内容，请尝试不同的措辞

索引特性：

增量索引：仅上传新或修改过的文件，跳过未修改的文件
基于哈希的去重：通过路径+内容的SHA-256哈希识别文件
自动重试：网络请求最多可自动重试3次，使用指数退避（1秒、2秒、4秒）
批量弹性：如果重试后批量上传失败，工具将继续处理下一批
文件拆分：大文件将自动拆分为多个块（默认：每块800行）
排除模式：自动跳过虚拟环境、node_modules、.git、构建产品等
多种编码支持：自动检测文件编码（UTF-8、GBK、GB2312、Latin-1），并在失败时回退到UTF-8错误处理
.gitignore集成：从项目根目录自动加载并遵守 .gitignore 模式，结合配置的排除模式

搜索特性：

自动重试：搜索请求最多可自动重试3次，使用指数退避（2秒、4秒、8秒）
优雅降级：如果所有重试后搜索失败，则返回清晰的错误消息
超时处理：使用60秒超时来处理长时间运行的搜索
空结果处理：如果没有找到相关代码，则返回有用的消息

默认排除模式：

.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, .Python,
pip-log.txt, pip-delete-this-directory.txt, .coverage, htmlcov,
.gradle, target, bin, obj

模式支持通配符（*、?），并匹配目录/文件名或路径。

注意：如果项目根目录存在 .gitignore 文件，其模式将自动加载并与配置的排除模式结合使用。.gitignore 的模式遵循Git的标准通配符语法。

高级功能

多种编码文件支持

Acemcp自动检测并处理不同字符编码的文件，适用于国际项目：

自动检测：按顺序尝试多种编码：UTF-8 → GBK → GB2312 → Latin-1
回退处理：如果所有编码都失败，则使用UTF-8错误处理以防止崩溃
日志记录：记录每个文件成功使用的编码（DEBUG级别）
无需配置：开箱即用，支持大多数常见编码

这特别适用于以下情况：

混合编码文件的项目（例如UTF-8源代码+GBK文档）
使用非UTF-8编码的旧代码库
国际团队拥有不同语言的文件

.gitignore集成

Acemcp自动遵守您的项目需求 .gitignore 文件：

自动加载：如果存在，则从项目根目录读取 .gitignore
标准语法：支持Git的标准通配符模式
组合过滤：与配置 EXCLUDE_PATTERNS 结合工作
目录处理：正确处理带有尾随斜杠的目录模式
无需配置：只需将其放置在项目的根目录 .gitignore

.gitignore 模式示例：

# 依赖
node_modules/
vendor/

# 构建输出
dist/
build/
*.pyc

# IDE 文件
.vscode/
.idea/

# 环境文件
.env
.env.local

所有这些模式将在索引期间自动遵循，并与默认排除模式结合使用。

使用说明

启动MCP服务器（由MCP客户端自动启动）
使用 search_context 搜索代码上下文
- 工具会在搜索前自动索引您的项目
- 增量索引确保只上传新/修改过的文件
- 不需要手动索引步骤！
- 无论编码如何，文件都会被自动处理
- 自动遵守 .gitignore 模式

数据存储

配置：~/.acemcp/settings.toml
已索引项目：~/.acemcp/data/projects.json（固定位置）
日志文件：~/.acemcp/log/acemcp.log（自动轮换）
项目通过其绝对路径识别（使用正斜杠标准化）

日志记录

应用程序自动记录日志到 ~/.acemcp/log/acemcp.log，具有以下特点：

控制台输出：INFO级别及以上（彩色输出）
文件输出：DEBUG级别及以上（详细格式，包括模块、函数和行号）
自动轮换：当达到5MB时自动轮换日志文件
保留策略：保留最多10个日志文件
压缩：旋转的日志文件自动压缩为 .zip 格式
线程安全：日志记录对并发操作是线程安全的

日志格式：

2025-11-06 13:51:25 | INFO     | acemcp.server:main:103 - 正在启动 acemcp MCP 服务器...

日志文件在首次运行时自动创建，无需手动配置。

Web管理界面

Web管理界面提供：

实时服务器状态监控
实时日志流通过WebSocket
配置管理：查看和编辑服务器配置
令牌验证：一键检测API密钥的有效性
项目统计：已索引项的数量
工具调试器：直接从Web界面测试和调试MCP工具

要启用Web界面，请使用 --web-port 参数。

功能：

实时日志显示并自动滚动
服务器状态和指标
配置概览和编辑
使用Tailwind CSS的响应式设计
无需构建步骤（使用CDN资源）
具有指数退避的智能WebSocket重连