Acemcp

🚀 Acemcp

An MCP server for codebase indexing and semantic search.

简体中文 | English

🚀 Quick Start

📦 Installation

As a Tool (Recommended)

# Install to the system
uv tool install acemcp

# Or run temporarily (no installation required)
uvx acemcp

For Development

# Clone the repository
git clone https://github.com/qy527145/acemcp.git
cd acemcp

# Install dependencies
uv sync

# Run the server
uv run acemcp

⚙️ Configuration

The configuration file will be automatically created at ~/.acemcp/settings.toml on the first run, containing default values.

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

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 uploaded per batch (Default: 10)
• MAX_LINES_PER_BLOB: 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 via:

• Command-line arguments (highest priority): --base-url, --token
• Web management interface (update user configuration file)
• Environment variables (use the ACEMCP_ prefix)

MCP Configuration

Add the following to your MCP client configuration (e.g., Claude Desktop):

Basic Configuration

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

Enable Web Management Interface

To enable the Web management interface, add the --web-port argument:

{
  "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 with intelligent reconnection
  • Exponential backoff reconnection strategy (1s → 1.5s → 2.25s ... max 30s)
  • Up to 10 reconnection attempts to prevent infinite loop
  • Automatic reconnection on network failure
  • Reduce log noise (WebSocket connection records 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

💻 Usage Examples

search_context

Search for relevant code context based on a query. This tool automatically performs incremental indexing before searching to ensure 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 the project - just search, and the tool will handle indexing automatically
• Always Up-to-date: Search results reflect the current state of the codebase
• Multi-encoding Support: Automatically detect and handle multiple file encodings (UTF-8, GBK, GB2312, Latin-1)
• .gitignore Integration: Automatically follow .gitignore patterns when indexing the project

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

Return Content:

• Formatted text snippets from files matching your query
• File path and line number for each snippet
• Context around the relevant code section
• Multiple results sorted by relevance

Query Examples:

1. Find Configuration Code:

{
  "project_root_path": "C:/Users/username/projects/myproject",
  "query": "Log configuration settings initialization logger"
}

Returns: Code related to log settings, logger initialization, and configuration

2. Find Authentication Logic:

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

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

{
  "project_root_path": "C:/Users/username/projects/myproject",
  "query": "Error handling exception try catch"
}

Returns: Error handling patterns, exception handlers, try-catch blocks

5. Find API Endpoints:

{
  "project_root_path": "C:/Users/username/projects/myproject",
  "query": "API endpoint route HTTP handler"
}

Returns: API route definitions, HTTP handlers, endpoint implementations

Tips for Better Results:

• Use multiple relevant keywords (e.g., "Log configuration settings" instead of just "Log")
• Include specific technical terms you're looking for
• Describe the functionality rather than exact variable names
• If the first query doesn't return what you need, try different wording

Indexing Features:

• Incremental Indexing: Only upload new or modified files, skip unchanged files
• Hash-based Deduplication: Identify files by SHA-256 hash of path + content
• Automatic Retry: Automatically retry network requests up to 3 times with exponential backoff (1s, 2s, 4s)
• Batch Resilience: If batch upload fails after retries, the tool continues with the next batch
• File Splitting: Automatically split large files into multiple chunks (Default: 800 lines per chunk)
• Exclusion Patterns: Automatically skip virtual environments, node_modules, .git, build artifacts, etc.
• Multi-encoding Support: Automatically detect file encoding (UTF-8, GBK, GB2312, Latin-1) and fallback to UTF-8 error handling on failure
• .gitignore Integration: Automatically load and follow .gitignore patterns from the project root directory, combined with configured exclusion patterns

Search Features:

• Automatic Retry: Automatically retry search requests up to 3 times with exponential backoff (2s, 4s, 8s)
• Graceful Degradation: If search fails after all retries, return a clear error message
• Timeout Handling: Use a 60-second timeout to handle long-running searches
• Empty Result Handling: If no relevant code is found, return a useful message

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/filenames or paths.

Note: If a .gitignore file exists in the project root directory, its patterns will be automatically loaded and combined with the configured exclusion patterns. .gitignore patterns follow Git's standard wildmatch syntax.

🔧 Technical Details

Multi-encoding File Support

Acemcp automatically detects and handles files with different character encodings, suitable for international projects:

• Automatic Detection: Try multiple encodings in order: UTF-8 → GBK → GB2312 → Latin-1
• Fallback Handling: If all encodings fail, use UTF-8 error handling to prevent crashes
• Logging: Log the successfully used encoding for each file (DEBUG level)
• No Configuration Required: Works out of the box, supporting most common encodings

This is particularly 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 follows your project's .gitignore file:

• Automatic Loading: Read .gitignore from the project root directory if it exists
• Standard Syntax: Support Git's standard wildmatch patterns
• Combined Filtering: Work together with the configured EXCLUDE_PATTERNS
• Directory Handling: Correctly handle directory patterns with trailing slashes
• No Configuration Required: Just place .gitignore in the project root directory

.gitignore Pattern Examples:

# Dependencies
node_modules/
vendor/

# Build output
dist/
build/
*.pyc

# IDE files
.vscode/
.idea/

# Environment files
.env
.env.local

All these patterns will be automatically followed during indexing and combined with the default exclusion patterns.

📚 Documentation

Usage Methods

1. Start the MCP server (automatically started by the MCP client)
2. Use the search_context tool 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!
   • Files are automatically handled regardless of encoding
   • Automatically follow .gitignore patterns

Data Storage

• Configuration: ~/.acemcp/settings.toml
• Indexed Projects: ~/.acemcp/data/projects.json (fixed location)
• Log Files: ~/.acemcp/log/acemcp.log (automatically rotated)
• Projects are identified by their absolute paths (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, including module, function, and line number)
• Automatic Rotation: Log files are automatically rotated when they reach 5MB
• Retention Policy: Keep up to 10 log files
• 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...

The log file is automatically created on the first run, no manual configuration 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 Verification: One-click detection of API Key validity
• 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)
• Intelligent WebSocket reconnection with exponential backoff

📄 Recent Updates

Version 0.2.1

Improvements:

• 🔧 Optimized the prompt description of the search_context tool
• 🔧 Adjusted the description text of tool parameters

Version 0.2.0

Bug Fixes:

• 🐛 Fixed the issue where acemcp failed to start due to encoding errors when a .env file existed in the project

Dependency Updates:

• ⬆️ Upgraded the versions of third-party dependency packages

Version 0.1.9

New Features:

• Automatically check if the web-port is occupied. If occupied, reuse the web panel

Improvements:

• Fixed Antigravity compatibility errors

Version 0.1.8

New Features:

• ✨ Token Verification Function: Added an API Key detection button to the Web management interface
  • Added a "Detect Key" button in the configuration section to instantly verify the validity of the token
  • Supports token verification in both view and edit modes
  • Provides clear verification result feedback (success/failure messages)
  • Helps users quickly diagnose API configuration issues

Technical Details:

• Added the /api/validate-token API endpoint
• Verify token validity by sending a test request to the API
• Comprehensive error handling: 401 Unauthorized, 403 Forbidden, timeout, connection errors, etc.
• Supports both English and Chinese interfaces

Version 0.1.7

Improvements:

• 🔧 Optimized Interface Requests: https://github.com/qy527145/acemcp/pull/6
• 🔧 Compatible with Proxy Environments: Added the httpx[socks] extension dependency to fix bugs in proxy environments

Version 0.1.5

New Features:

• ✨ Optimized Logging System: Redirected FastAPI/Uvicorn logs to loguru to prevent contamination of the MCP stdio protocol
• ✨ Tool Debugging Interface: Added a tool list and debugging function to the Web management interface

Improvements:

• 🔧 Controlled Log Output: Removed console log output, only outputting to files to avoid interfering with the stdio protocol
• 🔧 Intercepted Standard Library Logs: Used InterceptHandler to intercept all standard library logs
• 🔧 Enhanced Web API: Added the /api/tools endpoint to list available tools

Technical Details:

• Implemented the 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 detect and handle multiple file encodings (UTF-8, GBK, GB2312, Latin-1)
• ✨ .gitignore Integration: Automatically load and follow .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:

• 🔧 Optimized WebSocket: Intelligent reconnection with exponential backoff (1s → max 30s)
• 🔧 Reduced Log Noise: WebSocket connections are now logged at DEBUG level instead of INFO
• 🔧 Improved Connection Stability: Up to 10 reconnection attempts to prevent infinite loop
• 🔧 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