acemcp

[](https://mseep.ai/app/qy527145-acemcp) [English](./README_EN.md) # Acemcp MCP Server for code base indexing and semantic search. <a href="https://glama.ai/mcp/servers/@qy527145/acemcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@qy527145/acemcp/badge" alt="Acemcp MCP server" /> </a> ## Installation ### Install as a tool (Recommended) ```bash # Install to system uv tool install acemcp # Or run temporarily (without installation) uvx acemcp ``` ### Development Installation ```bash # Clone the repository git clone https://github.com/qy527145/acemcp.git cd acemcp # Install dependencies uv sync # Run uv run acemcp ``` ## Configuration The configuration file is automatically created on the first run at `~/.acemcp/settings.toml`, containing default values. Edit `~/.acemcp/settings.toml` to configure: ```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", ...] ``` **Configuration Options:** - `BATCH_SIZE`: Number of files per batch to upload (default: 10) - `MAX_LINES_PER_BLOB`: Maximum lines before splitting large files (default: 800) - `BASE_URL`: API endpoint URL - `TOKEN`: Authentication token - `TEXT_EXTENSIONS`: List of file extensions to index - `EXCLUDE_PATTERNS`: List of patterns to exclude (supports wildcards like `*.pyc`) You can also configure via: - **Command-line arguments** (highest priority): `--base-url`, `--token` - **Web Management Interface** (updates user config file) - **Environment variables** (using the `ACEMCP_` prefix) ## MCP Configuration Add the following to your MCP client configuration (e.g., Claude Desktop): ### Basic Configuration ```json { "mcpServers": { "acemcp": { "command": "uvx", "args": [ "acemcp" ] } } } ``` **Available command-line arguments:** - `--base-url`: Override the BASE_URL configuration - `--token`: Override the TOKEN configuration - `--web-port`: Enable the web management interface on the specified port (e.g., 8080) ### Configuration to Enable Web Management Interface To enable the web management interface, add the `--web-port` argument: ```json { "mcpServers": { "acemcp": { "command": "uvx", "args": [ "acemcp", "--web-port", "8888" ] } } } ``` Then access the management interface: `http://localhost:8888` **Web Management Features:** - **Configuration Management**: View and edit server configuration (BASE_URL, TOKEN, BATCH_SIZE, MAX_LINES_PER_BLOB, TEXT_EXTENSIONS) - **Real-time Logs**: Monitor server logs in real-time via WebSocket with smart reconnect - Exponential backoff reconnect strategy (1 second → 1.5 seconds → 2.25 seconds ... up to 30 seconds) - Maximum of 10 reconnect attempts to prevent infinite loops - Automatic reconnection on network failures - Reduced log noise (WebSocket connections logged at DEBUG level) - **Tool Debugger**: Test and debug MCP tools directly from the web interface - Test the `search_context` tool by entering a project path and query - View formatted results and error messages ## Tools ### search_context Searches for relevant code context based on a query. This tool **automatically performs incremental indexing** before searching, ensuring results are always up-to-date. It performs **semantic search** in your codebase and returns formatted text snippets showing the location of relevant code. **Core Features:** - **Automatic Incremental Indexing**: Before each search, the tool automatically indexes only new or modified files, skipping unchanged files for efficiency - **No Manual Indexing Required**: You don't need to manually index your project - just search, and the tool handles indexing automatically - **Always Up-to-Date**: Search results reflect the current state of the codebase - **Multi-Encoding Support**: Automatically detects and handles multiple file encodings (UTF-8, GBK, GB2312, Latin-1) - **.gitignore Integration**: Automatically respects `.gitignore` patterns when indexing projects **Parameters:** - `project_root_path` (string): Absolute path to the project root directory - **Important**: Use forward slashes (`/`) as path separators, even on Windows - Windows example: `C:/Users/username/projects/myproject` - Linux/Mac example: `/home/username/projects/myproject` - `query` (string): Natural language search query to find relevant code context - Use descriptive keywords related to what you're looking for - The tool performs semantic matching, not just keyword search - Returns code snippets with file paths and line numbers **Returns:** - Formatted text snippets from files that match your query - File paths and line numbers for each snippet - Context around the relevant code sections - Multiple results sorted by relevance **Query Examples:** 1. **Find configuration code:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "logging configuration settings initialize logger" } ``` Returns: Code related to logging settings, logger initialization, and configuration 2. **Find authentication logic:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "user authentication login password verification" } ``` Returns: Authentication handlers, login functions, password verification code 3. **Find database code:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "database connection pool initialization" } ``` Returns: Database connection settings, connection pool configuration, initialization code 4. **Find error handling:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "error handling exceptions try catch" } ``` Returns: Error handling patterns, exception handlers, try-catch blocks 5. **Find API endpoints:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "API endpoints routes HTTP handlers" } ``` Returns: API route definitions, HTTP handlers, endpoint implementations **Tips for Better Results:** - Use multiple relevant keywords (e.g., "logging configuration settings" instead of just "logging") - Include specific technical terms for what you're looking for - Describe functionality rather than exact variable names - If the first query doesn't return what you need, try different phrasing **Indexing Features:** - **Incremental Indexing**: Only uploads new or modified files, skipping unchanged files - **Hash-Based Deduplication**: Identifies files by SHA-256 hash of path + content - **Automatic Retries**: Retries network requests automatically up to 3 times with exponential backoff (1 second, 2 seconds, 4 seconds) - **Batch Resilience**: If a batch upload fails after retries, the tool continues processing the next batch - **File Splitting**: Automatically splits large files into multiple chunks (default: 800 lines per chunk) - **Exclusion Patterns**: Automatically skips virtual environments, node_modules, .git, build artifacts, etc. - **Multi-Encoding Support**: Automatically detects file encoding (UTF-8, GBK, GB2312, Latin-1) and falls back to UTF-8 error handling if detection fails - **.gitignore Integration**: Automatically loads and respects `.gitignore` patterns from the project root, combined with configured exclusion patterns **Search Features:** - **Automatic Retries**: Retries search requests automatically up to 3 times with exponential backoff (2 seconds, 4 seconds, 8 seconds) - **Graceful Degradation**: Returns a clear error message if the search fails after all retries - **Timeout Handling**: Uses a 60-second timeout to handle long-running searches - **Empty Result Handling**: Returns a helpful message if no relevant code is found **Default Exclusion Patterns:** ``` .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 ``` Patterns support wildcards (`*`, `?`) and match directory/file names or paths. **Note:** If a `.gitignore` file exists in the project root, its patterns are automatically loaded and combined with the configured exclusion patterns. `.gitignore` patterns follow Git's standard wildmatch syntax. ## Advanced Features ### Multi-Encoding File Support Acemcp automatically detects and handles files with different character encodings, suitable for internationalized projects: - **Automatic Detection**: Tries multiple encodings in order: UTF-8 → GBK → GB2312 → Latin-1 - **Fallback Handling**: Uses UTF-8 error handling if all encodings fail to prevent crashes - **Logging**: Logs the encoding successfully used for each file (DEBUG level) - **No Configuration**: Works out of the box, supporting most common encodings This is especially useful for: - Projects with mixed-encoding files (e.g., UTF-8 source code + GBK documentation) - Legacy codebases using non-UTF-8 encodings - International teams with files in different languages ### .gitignore Integration Acemcp automatically respects your project's `.gitignore` file: - **Automatic Loading**: Reads `.gitignore` from the project root if it exists - **Standard Syntax**: Supports Git's standard wildmatch patterns - **Combined Filtering**: Works together with configured `EXCLUDE_PATTERNS` - **Directory Handling**: Correctly handles directory patterns with trailing slashes - **No Configuration**: Just place `.gitignore` in your project root **`.gitignore` Pattern Examples:** ```gitignore # Dependencies node_modules/ vendor/ # Build output dist/ build/ *.pyc # IDE files .vscode/ .idea/ # Environment files .env .env.local ``` All these patterns are automatically respected during indexing and combined with the default exclusion patterns. ## Usage 1. Start the MCP server (automatically started by the MCP client) 2. Use `search_context` to search for code context - The tool automatically indexes your project before searching - Incremental indexing ensures only new/modified files are uploaded - No manual indexing steps required! - Files are automatically handled regardless of encoding - `.gitignore` patterns are automatically respected ## Data Storage - **Configuration**: `~/.acemcp/settings.toml` - **Indexed Projects**: `~/.acemcp/data/projects.json` (fixed location) - **Log Files**: `~/.acemcp/log/acemcp.log` (automatic rotation) - Projects are identified by their absolute path (normalized with forward slashes) ## Logging The application automatically logs to `~/.acemcp/log/acemcp.log` with the following features: - **Console Output**: INFO level and above (colored output) - **File Output**: DEBUG level and above (detailed format with module, function, and line number) - **Automatic Rotation**: Log files are automatically rotated when they reach 5MB - **Retention Policy**: Up to 10 log files are retained - **Compression**: Rotated log files are automatically compressed to `.zip` format - **Thread-Safe**: Logging is thread-safe for concurrent operations **Log Format:** ``` 2025-11-06 13:51:25 | INFO | acemcp.server:main:103 - Starting acemcp MCP server... ``` The log file is automatically created on the first run, no manual configuration is required. ## Web Management Interface The web management interface provides: - **Real-time server status** monitoring - **Real-time log streaming** via WebSocket - **Configuration management**: View and edit server configuration - **Token Validation**: One-click detection of whether the API Key is valid - **Project Statistics**: Number of indexed projects - **Tool Debugger**: Test and debug MCP tools directly from the web interface To enable the web interface, use the `--web-port` argument when starting the server. **Features:** - Real-time log display with automatic scrolling - Server status and metrics - Configuration overview and editing - Responsive design using Tailwind CSS - No build steps required (uses CDN resources) - Smart WebSocket reconnection with exponential backoff ## Recent Updates ### Version 0.2.2 **New Features:** - ✨ **Upload Exception Handling System**: A brand new intelligent exception handling mechanism - **Binary Search Positioning**: When batch upload fails, automatically use binary search to accurately locate the abnormal blob - **Abnormal Blob Storage**: Record detailed information of abnormal blobs (file path, hash, error message, timestamp) - **Intelligent Recovery**: Recover successful blobs from failed batches to maximize upload success rate - **Search Optimization**: Automatically exclude abnormal blobs during search to ensure the reliability of search results - ✨ **Enhanced Exception Logs**: Detailed recording of the file path and hash value of each blob - ✨ **Web Console Integration**: Added `/api/failed-blobs` API interface to support web console display of exception information **Technical Details:** - Implemented `_binary_search_failed_blobs()` recursive binary search algorithm with O(log n) complexity - Added `failed_blobs.json` storage file to record project abnormal blob information - The search function automatically filters abnormal blobs and provides statistical information - Complete exception handling workflow: detection → positioning → recording → exclusion ### Version 0.2.1 **Improvements:** - 🔧 Optimized the prompt description of the `search_context` tool - 🔧 Adjusted the explanatory text of the tool parameters ### Version 0.2.0 **Bug Fixes:** - 🐛 Fixed the problem that acemcp startup failed due to encoding errors when a `.env` file existed in the project **Dependency Updates:** - ⬆️ Upgrade third-party dependency package versions ### Version 0.1.9 **New Features:** - Automatically determine whether the web-port port is occupied, and reuse the web panel if it is occupied **Improvements:** - [Fix Antigravity compatibility error](https://github.com/qy527145/acemcp/pull/12) ### Version 0.1.8 **New Features:** - ✨ **Token Validation Feature**: Added API Key detection button to the Web Management Interface - Add a "Detect Key" button in the configuration section to instantly verify whether the token is valid - Support token verification in view mode and edit mode - Provide clear verification result feedback (success/failure message) - Help users quickly diagnose API configuration problems **Technical Details:** - Added `/api/validate-token` API endpoint - Verify the validity of the token by sending a test request to the API - Complete error handling: 401 Unauthorized, 403 Forbidden, timeout, connection error, etc. - Support Chinese and English interfaces ### Version 0.1.7 **Improvements:** - 🔧 **Interface Request Optimization**: https://github.com/qy527145/acemcp/pull/6 - 🔧 **Compatible with Proxy Environment**: Add httpx[socks] extension dependency to solve bugs in the proxy environment ### Version 0.1.5 **New Features:** - ✨ **Log System Optimization**: Redirect FastAPI/Uvicorn logs to loguru to prevent pollution of the MCP stdio protocol - ✨ **Tool Debugging Interface**: Added tool list and debugging functions to the Web Management Interface **Improvements:** - 🔧 **Log Output Control**: Remove console log output and only output to files to avoid interfering with the stdio protocol - 🔧 **Standard Library Log Interception**: Use `InterceptHandler` to intercept all standard library logs - 🔧 **Web API Enhancement**: Added `/api/tools` endpoint to list available tools **Technical Details:** - Implemented the `InterceptHandler` class to intercept standard library logging - Configure uvicorn to use `log_config=None` to disable default logs - All logs are uniformly output to `~/.acemcp/log/acemcp.log` ### Version 0.1.4 **New Features:** - ✨ **Multi-Encoding Support**: Automatically detects and handles multiple file encodings (UTF-8, GBK, GB2312, Latin-1) - ✨ **.gitignore Integration**: Automatically loads and respects `.gitignore` patterns from the project root - ✨ **Improved Tool Response Format**: Changed from a list-based format to a dictionary-based format for better client compatibility **Improvements:** - 🔧 **WebSocket Optimization**: Smart reconnection with exponential backoff (1 second → max 30 seconds) - 🔧 **Reduced Log Noise**: WebSocket connections are now logged at DEBUG level instead of INFO - 🔧 **Connection Stability**: Maximum of 10 reconnection attempts to prevent infinite loops - 🔧 **Better Error Handling**: Graceful fallback for files that cannot be decoded with any encoding **Bug Fixes:** - 🐛 Fixed frequent WebSocket connect/disconnect loops - 🐛 Fixed encoding errors when reading non-UTF-8 encoded files - 🐛 Improved handling of .gitignore patterns with directory matching