Acemcp

MCP server for codebase indexing and semantic search.

Installation

Configuration

The configuration file is automatically created at ~/.acemcp/settings.toml on first run with default values.

Edit ~/.acemcp/settings.toml to configure:

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

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:

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:

   { "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:

   { "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:

   { "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:

   { "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:

   { "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:

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:

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)