Acemcp

Acemcp is an MCP server that indexes a codebase and enables semantic search across that code. It helps you quickly locate relevant code fragments, understand project structure, and continuously keep search results up to date as your repository evolves.

How to use

Start the MCP server via an MCP client. You run the server locally as a stdio process, and you can enable a Web management interface for real-time monitoring and configuration.

How to install

# Prerequisites: ensure you have a working Node-like runtime tooling environment
# You will be using a standard MCP client to run the server locally

Option 1: Install as a tool (recommended). Run the server directly on your system or use a temporary run.

uv tool install acemcp

# Or run temporarily without installation
uvx acemcp

Option 2: Development installation. Clone the project, install dependencies, and start the server.

git clone https://github.com/qy527145/acemcp.git
cd acemcp

# Install dependencies for development
uv sync

# Run the server locally
uv run acemcp

Additional configuration and server setup

On first run, a configuration file is created at ~/.acemcp/settings.toml. You can edit this file to tailor how indexing and searching work for your environment.

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", ...]

Web management interface

You can enable a Web management interface to view and adjust configuration, monitor logs, and test MCP tools from your browser.

{
  "mcpServers": {
    "acemcp": {
      "command": "uvx",
      "args": [
        "acemcp"
      ]
    }
  }
}

Start the Web management interface (optional)

To start the Web UI on a specific port, enable the web interface by adding the port number to the command line arguments.

{
  "mcpServers": {
    "acemcp": {
      "command": "uvx",
      "args": [
        "acemcp",
        "--web-port",
        "8888"
      ]
    }
  }
}

Accessing the Web UI

Open your browser at http://localhost:8888 to view configuration, live logs, and tool debugging features.

Data storage and logging

Configuration, indexed project data, and logs are stored under your home directory. You can review and manage these files to keep your environment organized and auditable.

Configuration: ~/.acemcp/settings.toml
Indexed projects: ~/.acemcp/data/projects.json
Logs: ~/.acemcp/log/acemcp.log

Tools and features you can use

The server provides a set of MCP tools to help you work with your codebase. You can test and debug these tools from the Web UI or the MCP client.

Core capabilities include incremental indexing before each search, semantic code context retrieval, multi-encoding support, automatic respect for .gitignore patterns, and robust WebSocket-based log streaming with retry logic.

Logging and updates

Logs are written to file with rotation and archival. The system also logs important events to the console at INFO level and more detailed traces at DEBUG level.

Notes on usage

The MCP server is designed to be run by an MCP client and to work with local or remote endpoints as configured. You can adjust batch sizes, memory usage, and filtering patterns to suit large codebases and complex projects.

Available tools

search_context

Automates incremental indexing before each semantic search, keeping results current and relevant.

web_console

Web-based console for managing configuration, viewing real-time logs, and testing MCP tools.

tool_debugger

Directly test and debug MCP tools from the Web UI to verify behavior and outputs.

token_validator

Validate API tokens from the Web UI to ensure proper authentication against the configured endpoint.