Acemcp

🚀 Acemcp

Acemcp 是一個用於代碼庫索引和語義搜索的 MCP 服務器，能夠幫助用戶高效地在代碼庫中查找相關代碼上下文。

簡體中文 | English

🚀 快速開始

您可以按照以下步驟快速開始使用 Acemcp：

1. 完成 Acemcp 的安裝（具體安裝方式見“📦 安裝指南”）。
2. 對 Acemcp 進行配置（具體配置方法見“🔧 配置說明”）。
3. 啟動 MCP 服務器（由 MCP 客戶端自動啟動），使用 search_context 工具搜索代碼上下文。

✨ 主要特性

• 自動增量索引：每次搜索前，工具自動僅索引新文件或修改過的文件，跳過未更改的文件以提高效率。
• 多編碼文件支持：自動檢測和處理不同字符編碼的文件，適用於國際化項目。
• .gitignore 集成：自動遵守項目的 .gitignore 文件，與配置的排除模式結合使用。
• 語義搜索：在代碼庫中執行語義搜索，返回格式化的文本片段，顯示相關代碼的位置。
• Web 管理界面：提供即時服務器狀態監控、即時日誌流、配置管理、Token 驗證、項目統計和工具調試等功能。

📦 安裝指南

作為工具安裝（推薦）

# 安裝到系統
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_ 前綴）。

💻 使用示例

基礎用法

使用 search_context 工具基於查詢搜索相關的代碼上下文：

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

此查詢將返回與日誌設置、logger 初始化和配置相關的代碼。

高級用法

您可以根據不同的查詢需求，靈活調整 project_root_path 和 query 參數，以獲取更精準的搜索結果。例如：

{
    "project_root_path": "C:/Users/username/projects/myproject",
    "query": "用戶認證 登錄 密碼驗證"
}

此查詢將返回認證處理器、登錄函數、密碼驗證代碼。

📚 詳細文檔

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、BATCH_SIZE、MAX_LINES_PER_BLOB、TEXT_EXTENSIONS）。
• 即時日誌：通過 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（字符串）：用於查找相關代碼上下文的自然語言搜索查詢。
  • 使用與您要查找的內容相關的描述性關鍵詞。
  • 工具執行語義匹配，而不僅僅是關鍵詞搜索。
  • 返回帶有文件路徑和行號的代碼片段。

返回內容

• 與您的查詢匹配的文件中的格式化文本片段。
• 每個片段的文件路徑和行號。
• 相關代碼部分周圍的上下文。
• 按相關性排序的多個結果。

獲得更好結果的技巧

• 使用多個相關關鍵詞（例如，"日誌配置設置"而不僅僅是"日誌"）。
• 包含您要查找的特定技術術語。
• 描述功能而不是確切的變量名。
• 如果第一次查詢沒有返回您需要的內容，嘗試不同的措辭。

索引特性

• 增量索引：僅上傳新文件或修改過的文件，跳過未更改的文件。
• 基於哈希的去重：通過路徑 + 內容的 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 的標準 wildmatch 語法。

高級特性

多編碼文件支持

Acemcp 自動檢測和處理不同字符編碼的文件，適用於國際化項目：

• 自動檢測：按順序嘗試多種編碼：UTF-8 → GBK → GB2312 → Latin-1。
• 回退處理：如果所有編碼都失敗，使用 UTF-8 錯誤處理以防止崩潰。
• 日誌記錄：記錄每個文件成功使用的編碼（DEBUG 級別）。
• 無需配置：開箱即用，支持大多數常見編碼。

這對以下情況特別有用：

• 混合編碼文件的項目（例如，UTF-8 源代碼 + GBK 文檔）。
• 使用非 UTF-8 編碼的遺留代碼庫。
• 具有不同語言文件的國際團隊。

.gitignore 集成

Acemcp 自動遵守您項目的 .gitignore 文件：

• 自動加載：如果存在，從項目根目錄讀取 .gitignore。
• 標準語法：支持 Git 的標準 wildmatch 模式。
• 組合過濾：與配置的 EXCLUDE_PATTERNS 一起工作。
• 目錄處理：正確處理帶有尾部斜槓的目錄模式。
• 無需配置：只需在項目根目錄放置 .gitignore。

.gitignore 模式示例：

# 依賴
node_modules/
vendor/

# 構建輸出
dist/
build/
*.pyc

# IDE 文件
.vscode/
.idea/

# 環境文件
.env
.env.local

所有這些模式在索引期間都會自動遵守，並與默認排除模式結合使用。

數據存儲

• 配置：~/.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 - Starting acemcp MCP server...

日誌文件在首次運行時自動創建，無需手動配置。

Web 管理界面

Web 管理界面提供：

• 即時服務器狀態監控。
• 即時日誌流通過 WebSocket。
• 配置管理：查看和編輯服務器配置。
• Token 驗證：一鍵檢測 API Key 是否有效。
• 項目統計：已索引項目數量。
• 工具調試器：直接從 Web 界面測試和調試 MCP 工具。

要啟用 Web 界面，在啟動服務器時使用 --web-port 參數。

功能：

• 帶自動滾動的即時日誌顯示。
• 服務器狀態和指標。
• 配置概覽和編輯。
• 使用 Tailwind CSS 的響應式設計。
• 無需構建步驟（使用 CDN 資源）。
• 具有指數退避的智能 WebSocket 重連。

最近更新

版本 0.2.1

• 🔧 優化了 search_context 工具的提示詞描述。
• 🔧 調整了工具參數的說明文字。

版本 0.2.0

• 🐛 修復了項目中存在 .env 文件時，因編碼錯誤導致 acemcp 啟動失敗的問題。
• ⬆️ 升級第三方依賴包版本。

版本 0.1.9

• 自動判斷 web-port 端口是否佔用，如果佔用會複用 web 面板。
• 修復 Antigravity 兼容性錯誤。

版本 0.1.8

• ✨ Token 驗證功能：Web 管理界面新增 API Key 檢測按鈕。
  • 在配置部分添加"檢測 Key"按鈕，可即時驗證 token 是否有效。
  • 支持在查看模式和編輯模式下驗證 token。
  • 提供清晰的驗證結果反饋（成功/失敗消息）。
  • 幫助用戶快速診斷 API 配置問題。
• 技術細節：
  • 新增 /api/validate-token API 端點。
  • 通過向 API 發送測試請求驗證 token 有效性。
  • 完善的錯誤處理：401 未授權、403 禁止訪問、超時、連接錯誤等。
  • 支持中英文界面。

版本 0.1.7

• 🔧 接口請求優化：https://github.com/qy527145/acemcp/pull/6。
• 🔧 兼容代理環境：添加 httpx[socks] 擴展依賴，解決代理環境下出錯的 bug。

版本 0.1.5

• ✨ 日誌系統優化：將 FastAPI/Uvicorn 日誌重定向到 loguru，防止汙染 MCP stdio 協議。
• ✨ 工具調試接口：Web 管理界面新增工具列表和調試功能。
• 🔧 日誌輸出控制：移除控制檯日誌輸出，僅輸出到文件，避免干擾 stdio 協議。
• 🔧 標準庫日誌攔截：使用 InterceptHandler 攔截所有標準庫日誌。
• 🔧 Web API 增強：新增 /api/tools 端點列出可用工具。
• 技術細節：
  • 實現了 InterceptHandler 類來攔截標準庫 logging。
  • 配置 uvicorn 使用 log_config=None 禁用默認日誌。
  • 所有日誌統一輸出到 ~/.acemcp/log/acemcp.log。

版本 0.1.4

• ✨ 多編碼支持：自動檢測和處理多種文件編碼（UTF-8、GBK、GB2312、Latin-1）。
• ✨ .gitignore 集成：自動從項目根目錄加載並遵守 .gitignore 模式。
• ✨ 改進的工具響應格式：從基於列表的格式改為基於字典的格式，以提高客戶端兼容性。
• 🔧 WebSocket 優化：具有指數退避的智能重連（1 秒 → 最大 30 秒）。
• 🔧 減少日誌噪音：WebSocket 連接現在記錄在 DEBUG 級別而不是 INFO。
• 🔧 連接穩定性：最多 10 次重連嘗試，防止無限循環。
• 🔧 更好的錯誤處理：對無法用任何編碼解碼的文件進行優雅回退。
• 🐛 修復了頻繁的 WebSocket 連接/斷開循環。
• 🐛 修復了讀取非 UTF-8 編碼文件時的編碼錯誤。
• 🐛 改進了對帶有目錄匹配的 .gitignore 模式的處理。