acemcp

[](https://mseep.ai/app/qy527145-acemcp) Simplified Chinese | [English](./README_EN.md) # Acemcp The MCP (Model Control Protocol) server for codebase 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 ### Installation as a Tool (Recommended) ```bash # Install to System uv tool install acemcp # Or run temporarily (no installation required) 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 will be automatically created at `~/.acemcp/settings.toml` during the first run, containing default values. Edit `~/.acemcp/settings.toml` for configuration: ```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`: The number of files to upload per batch (default: 10) - `MAX_LINES_PER_BLOB`: The maximum number of 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 it in the following ways: - **Command Line Arguments** (highest priority): `--base-url`, `--token` - **Web Management Interface** (updates user configuration file) - **Environment Variables** (using the `ACEMCP_` prefix) ## MCP Configuration Add the following content to your MCP client configuration (for example, Claude Desktop): ### Basic Configuration ```json { "mcpServers": { "acemcp": { "command": "uvx", "args": [ "acemcp" ] } } } ``` **Available Command Line Parameters:** - `--base-url`: Override BASE_URL configuration - `--token`: Override TOKEN configuration - `--web-port`: Enable the Web management interface on the specified port (e.g., 8080) ### Configuration to Enable the Web Management Interface To enable the Web management interface, add the `--web-port` parameter: ```json { "mcpServers": { "acemcp": { "command": "uvx", "args": [ "acemcp", "--web-port", "8888" ] } } } ``` Then access the management interface at: `http://localhost:8888` **Web Management Features:** - **Configuration Management**: View and edit server configurations (BASE_URL, TOKEN, BATCH_SIZE, MAX_LINES_PER_BLOB, TEXT_EXTENSIONS) - **Real-time Logs**: Monitor server logs in real-time via WebSocket connection, with intelligent reconnection features - Exponential backoff reconnection strategy (1 second → 1.5 seconds → 2.25 seconds ... up to 30 seconds) - Up to 10 reconnection attempts to prevent infinite loops - Automatic reconnection during network failures - Reduce log noise (WebSocket connection logs at DEBUG level) - **Tool Debugger**: Test and debug MCP tools directly from the Web interface - Test the `search_context` tool by entering the project path and query - View formatted results and error messages ## Tools ### search_context Search for relevant code context based on queries. This tool automatically performs **incremental indexing** before each search, ensuring that results are always up to date. It executes **semantic search** within your codebase and returns formatted text snippets that show the location of relevant code. **Core Features:** - **Automatic Incremental Indexing**: The tool automatically indexes only new or modified files before each search, skipping unchanged files for efficiency. - **No Manual Indexing Required**: You do not need to manually index the project - just search, and the tool will handle the indexing automatically. - **Always Up-to-Date**: Search results reflect the current state of the codebase. - **Multi-Encoding Support**: Automatically detects and handles various file encodings (UTF-8, GBK, GB2312, Latin-1). - **.gitignore Integration**: Automatically adheres to `.gitignore` patterns when indexing the project. **Parameters:** - `project_root_path` (string): The 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): A natural language search query used to find relevant code context. - Use descriptive keywords related to what you are looking for. - The tool performs semantic matching, not just keyword searching. - Returns code snippets with file paths and line numbers. **Return Content:** - 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": "日志配置 设置 初始化 logger" } ``` Returns: Code related to log settings, logger initialization, and configuration. 2. **Find Authentication Logic:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "用户认证 登录 密码验证" } ``` Returns: Authentication handlers, login functions, password validation code. 3. **Find Database Code:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "数据库连接池 初始化" } ``` Returns: Database connection setup, connection pool configuration, initialization code. 4. **Find Error Handling:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "错误处理 异常 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 端点 路由 HTTP 处理器" } ``` Returns: API route definitions, HTTP handlers, endpoint implementations. **Tips for Better Results:** - Use multiple related keywords (e.g., "日志配置设置" instead of just "日志"). - Include specific technical terms you are looking for. - Describe functionality rather than exact variable names. - If the first query does not 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 Retry**: Network requests automatically retry up to 3 times with exponential backoff (1s, 2s, 4s). - **Batch Resilience**: If a batch upload fails after retries, the tool continues processing the next batch. - **File Splitting**: Large files are automatically split 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 on failure. - **.gitignore Integration**: Automatically loads and adheres to `.gitignore` patterns from the project root, used in conjunction with configured exclusion patterns. **Search Features:** - **Automatic Retry**: Search requests automatically retry up to 3 times with exponential backoff (2s, 4s, 8s). - **Graceful Degradation**: If all retries fail, returns a clear error message. - **Timeout Handling**: Uses a 60-second timeout to handle long-running searches. - **Empty Result Handling**: Returns useful messages 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 directory, its patterns will be automatically loaded and used in conjunction 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 internationalization projects: - **Automatic Detection**: Attempts multiple encodings in order: UTF-8 → GBK → GB2312 → Latin-1 - **Fallback Handling**: If all encodings fail, uses UTF-8 error handling to prevent crashes - **Logging**: Records the encoding successfully used for each file (DEBUG level) - **No Configuration Needed**: Works out of the box, supporting most common encodings This is particularly useful for the following scenarios: - 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 adheres to 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 in conjunction with configured `EXCLUDE_PATTERNS` - **Directory Handling**: Correctly processes directory patterns with trailing slashes - **No Configuration Needed**: Simply place `.gitignore` in the project root **`.gitignore` Pattern Example:** ```gitignore # Dependencies node_modules/ vendor/ # Build Output dist/ build/ *.pyc # IDE Files .vscode/ .idea/ # Environment Files .env .env.local ``` All of these patterns will be automatically respected during indexing and will be combined with the default exclusion patterns. ``` ## Usage 1. Start the MCP Server (automatically started by the MCP Client) 2. Use `search_context` to search the code context - The tool automatically indexes your project before searching - Incremental indexing ensures that only new or modified files are uploaded - No manual indexing steps required! - Files are automatically processed regardless of coding style - Automatically adheres to `.gitignore` patterns ## Data Storage - **Configuration**: `~/.acemcp/settings.toml` - **Indexed Projects**: `~/.acemcp/data/projects.json` (fixed location) - **Log File**: `~/.acemcp/log/acemcp.log` (automatically rotated) - Projects are identified by their absolute paths (normalized using 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, including 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 Safety**: Logging is thread-safe for concurrent operations **Log Format:** ``` 2025-11-06 13:51:25 | INFO | acemcp.server:main:103 - Starting acemcp MCP server... ``` Log files are automatically created on the first run, with no manual configuration required. ## Web Management Interface The Web Management Interface provides: - **Real-time server status** monitoring - **Real-time log stream** via WebSocket - **Configuration management**: view and edit server configuration - **Token validation**: one-click check if 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` parameter when starting the server. **Features:** - Real-time log display with auto-scrolling - Server status and metrics - Configuration overview and editing - Responsive design using Tailwind CSS - No build steps required (uses CDN resources) - Intelligent WebSocket reconnection with exponential backoff ## Recent Updates ### Version 0.2.1 **Improvements:** - 🔧 Optimized the prompt description for the `search_context` tool - 🔧 Adjusted the explanatory text for the tool parameters ### Version 0.2.0 **Bug Fixes:** - 🐛 Fixed the issue where acemcp failed to start due to encoding errors when a `.env` file exists in the project. **Dependency Updates:** - ⬆️ Upgraded the versions of third-party dependencies. ### Version 0.1.9 **New Features:** - Automatically determine if the web-port is occupied; if so, it will reuse the web panel. **Improvements:** - [Fix Antigravity compatibility issue](https://github.com/qy527145/acemcp/pull/12) ### Version 0.1.8 **New Features:** - ✨ **Token Verification Functionality**: Added API Key check button in the web management interface - Added "Check Key" button in the configuration section to instantly verify if the token is valid - Supports token verification in both view mode and edit mode - Provides clear feedback on verification results (success/failure messages) - Helps users quickly diagnose API configuration issues **Technical Details:** - New `/api/validate-token` API endpoint - Validates token validity by sending test requests to the API - Comprehensive error handling: 401 Unauthorized, 403 Forbidden, timeout, connection errors, etc. - Supports both Chinese and English interfaces ### Version 0.1.7 **Improvements:** - 🔧 **Interface request optimization**: https://github.com/qy527145/acemcp/pull/6 - 🔧 **Compatibility with proxy environments**: Added httpx[socks] extension dependency to resolve bugs occurring in proxy environments. ### Version 0.1.5 **New Features:** - ✨ **Log System Optimization**: Redirect FastAPI/Uvicorn logs to loguru to prevent pollution of MCP stdio protocol - ✨ **Tool Debugging Interface**: Added tool list and debugging functionality to the web management interface **Improvements:** - 🔧 **Log Output Control**: Removed console log output, only outputting to file to avoid interference with stdio protocol - 🔧 **Standard Library Log Interception**: Used `InterceptHandler` to intercept all standard library logs - 🔧 **Web API Enhancement**: Added `/api/tools` endpoint to list available tools **Technical Details:** - Implemented `InterceptHandler` class to intercept standard library logging - Configured uvicorn to use `log_config=None` to disable default logging - All logs are uniformly output to `~/.acemcp/log/acemcp.log` ### Version 0.1.4 **New Features:** - ✨ **Multi-encoding Support**: Automatically detects and handles various file encodings (UTF-8, GBK, GB2312, Latin-1) - ✨ **.gitignore Integration**: Automatically loads and adheres to `.gitignore` patterns from the project root directory - ✨ **Improved Tool Response Format**: Changed from a list-based format to a dictionary-based format for better client compatibility **Improvements:** - 🔧 **WebSocket Optimization**: Intelligent reconnection with exponential backoff (1 second → maximum 30 seconds) - 🔧 **Reduced Log Noise**: WebSocket connections are now logged at the DEBUG level instead of INFO - 🔧 **Connection Stability**: Up to 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 connection/disconnection loops - 🐛 Fixed encoding errors when reading non-UTF-8 encoded files - 🐛 Improved handling of .gitignore patterns with directory matching