Content
[](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
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Sequential Thinking
A structured MCP server for dynamic problem-solving and reflective thinking.
git
A Model Context Protocol server for Git automation and interaction.