Acemcp

# Acemcp MCP server for codebase indexing and semantic search. ## Installation ```bash uv add mcp httpx fastapi "uvicorn[standard]" toml websockets uv sync ``` ## Configuration The configuration file is automatically created at `~/.acemcp/settings.toml` on first run with 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 to upload per batch (default: 10) - `MAX_LINES_PER_BLOB`: Maximum lines per blob 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 from indexing (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** with `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 BASE_URL configuration - `--token`: Override TOKEN configuration - `--web-port`: Enable web management interface on specified port (e.g., 8080) ### Configuration with 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 at `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 connection - **Tool Debugger**: Test and debug MCP tools directly from the web interface - Test `index_code` tool with any project path - Test `search_context` tool with project path and query - View formatted results and error messages ## Tools ### search_context Search 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** across your codebase and returns formatted text snippets showing where relevant code is located. **Key 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 your codebase **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 **What it 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 ranked by relevance **Query Examples:** 1. **Finding configuration code:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "查找所有调用 get_model 的地方" } ``` Returns: Code related to logging setup, logger initialization, and configuration 2. **Finding authentication logic:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "user authentication login password validation" } ``` Returns: Authentication handlers, login functions, password validation code 3. **Finding database code:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "database connection pool initialization" } ``` Returns: Database connection setup, pool configuration, initialization code 4. **Finding error handling:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "error handling exception try catch" } ``` Returns: Error handling patterns, exception handlers, try-catch blocks 5. **Finding API endpoints:** ```json { "project_root_path": "C:/Users/username/projects/myproject", "query": "API endpoint routes HTTP handlers" } ``` Returns: API route definitions, HTTP handlers, endpoint implementations **Tips for better results:** - Use multiple related keywords (e.g., "logging configuration setup" instead of just "logging") - Include technical terms specific to what you're looking for - Describe the functionality rather than exact variable names - Try different phrasings if the first query doesn't return what you need **Indexing Features:** - **Incremental Indexing**: Only new or modified files are uploaded, unchanged files are skipped - **Hash-based Deduplication**: Files are identified by SHA-256 hash of path + content - **Automatic Retry**: Network requests are automatically retried up to 3 times with exponential backoff (1s, 2s, 4s) - **Batch Resilience**: If a batch upload fails after retries, the tool continues with the next batch - **File Splitting**: Large files are automatically split into multiple blobs (default: 800 lines per blob) - **Exclude Patterns**: Automatically skips virtual environments, node_modules, .git, build artifacts, etc. **Search Features:** - **Automatic Retry**: Search requests are automatically retried up to 3 times with exponential backoff (2s, 4s, 8s) - **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 Exclude 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 against directory/file names or paths. ## Usage 1. Start the MCP server (automatically started by 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 step required! ## Data Storage - **Configuration**: `~/.acemcp/settings.toml` - **Indexed projects**: `~/.acemcp/data/projects.json` (fixed location) - **Log files**: `~/.acemcp/log/acemcp.log` (with 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 rotated when they reach 5MB - **Retention**: Maximum of 10 log files are kept - **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 files are automatically created on first run and require no manual configuration. ## Web Management Interface The web management interface provides: - **Real-time server status** monitoring - **Live log streaming** via WebSocket - **Configuration viewing** (current settings) - **Project statistics** (number of indexed projects) To enable the web interface, use the `--web-port` argument when starting the server. **Features:** - Real-time log display with auto-scroll - Server status and metrics - Configuration overview - Responsive design with Tailwind CSS - No build step required (uses CDN resources)