Content
# Tool List
[](https://www.npmjs.com/package/acemcp-node)
[](https://www.npmjs.com/package/acemcp-node)
[](LICENSE)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
<img src="https://img.shields.io/badge/MCP-Model%20Context%20Protocol-orange" alt="MCP">
<img src="https://img.shields.io/badge/AI-Ready-success" alt="AI Ready">
## 📑 Table of Contents
- [Introduction](#introduction)
- [Core Features](#core-features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage Guide](#usage-guide)
- [MCP Client Configuration](#mcp-client-configuration)
- [Tool Description](#tool-description)
- [Web Management Interface](#web-management-interface)
- [WSL Support](#wsl-support)
- [API Documentation](#api-documentation)
- [Example Scenarios](#example-scenarios)
- [Development Guide](#development-guide)
- [Troubleshooting](#troubleshooting)
- [Compatibility](#compatibility)
- [Contribute](#contribute)
- [License](#license)
---
## 📖 Introduction
**Acemcp** is a high-performance MCP (Model Context Protocol) server, designed for AI assistants (such as Claude, GPT, etc.) to provide **codebase indexing** and **semantic search** capabilities. With Acemcp, AI assistants can:
- 🔍 Quickly search and understand large codebases
- 📊 Retrieve precise code snippets with line numbers
- 🤖 Automatically update indexes incrementally
- 🌐 Manage and debug through the web interface
**Why Choose Acemcp?**
| Feature | Description |
|------|------|
| **Zero-configuration startup** | Automatic configuration generation on first run |
| **Incremental indexing** | Only process changed files, fast and efficient |
| **Cross-platform** | Full support for Windows, Linux, macOS, WSL |
| **Multi-encoding** | Automatic detection of UTF-8, GBK, GB2312, Latin-1 |
| **AI-friendly** | Returns formatted code snippets with file paths and line numbers |
---
## ⭐ Core Features
<table>
<tr>
<td width="50%">
### 🚀 Performance Optimization
- ✅ **Incremental Indexing** - Only index new or modified files
- ✅ **Batch Upload** - Support batch operations and automatic retries
- ✅ **Intelligent Segmentation** - Large files automatically segmented into multiple blocks
- ✅ **Cache Mechanism** - SHA-256 hash avoids duplicate uploads
</td>
<td width="50%">
### 🛠 Development Friendly
- ✅ **TypeScript** - Complete type support
- ✅ **Web Interface** - Real-time logs, configuration management, tool debugging
- ✅ **.gitignore Support** - Automatically exclude irrelevant files
- ✅ **Detailed Logs** - Configurable log levels and rotation
</td>
</tr>
<tr>
<td width="50%">
### 🌍 Compatibility
- ✅ **Cross-platform Path** - Unified handling of Windows/Unix paths
- ✅ **Complete WSL Support** - UNC path, /mnt automatic conversion
- ✅ **Multi-encoding Support** - UTF-8, GBK, GB2312, Latin-1
- ✅ **Python Version Compatibility** - Shared configuration and data format
</td>
<td width="50%">
### 🎯 MCP Integration
- ✅ **Standard MCP Protocol** - Complete implementation of SDK
- ✅ **search_context Tool** - Semantic search for code snippets
- ✅ **stdio Transmission** - Standard input and output communication
- ✅ **Flexible Configuration** - Command-line parameters + configuration files
</td>
</tr>
</table>
---
## 🚀 Quick Start
### Method 1: Install via NPM (Recommended)
```bash
# Global installation
npm install -g acemcp-node
# Or local installation to project
npm install acemcp-node
```
### Method 2: Install from Source
```bash
# Clone repository
git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
cd Ace-Mcp-Node
# Install dependencies
npm install
# Compile TypeScript
npm run build
```
### First Run
```bash
# Start server (will create configuration file on first run)
npm start
# Or start with web interface
npm start -- --web-port 8080
```
Visit http://localhost:8080 to view the web management interface!
---
## 📦 Installation
### System Requirements
- **Node.js** >= 18.0.0
- **npm** >= 8.0.0 (or yarn, pnpm)
- **Operating System**: Windows 10+, Linux, macOS, WSL 2
### Detailed Installation Steps
#### 1. NPM Global Installation (Recommended for MCP Client)
```bash
npm install -g acemcp-node
# Verify installation
node -e "console.log(require('acemcp-node/package.json').version)"
```
#### 2. NPM Local Installation (for project integration)
```bash
# Create project directory
mkdir my-mcp-project && cd my-mcp-project
# Initialize package.json
npm init -y
# Install acemcp-node
npm install acemcp-node
# Run
npx acemcp-node
```
#### 3. Development Installation from Source
```bash
git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
cd Ace-Mcp-Node
npm install
npm run build
# Development mode (automatic reload)
npm run dev
```
---
### Configuration File
The program will automatically create a configuration file in the `~/.acemcp/` directory on the first run:
#### Configuration File Location
```
~/.acemcp/
├── settings.toml # Main configuration file
├── data/
│ └── projects.json # Project index data
└── log/
└── acemcp.log # Log file
```
#### settings.toml Configuration Details
```toml
# ~/.acemcp/settings.toml
# === API Configuration ===
BASE_URL = "https://api.example.com" # Index server address
TOKEN = "your-token-here" # Access token
# === Index Configuration ===
BATCH_SIZE = 10 # Batch upload quantity (1-50)
MAX_LINES_PER_BLOB = 800 # Maximum lines per code block
# === File Type Configuration ===
# Supported text file extensions
TEXT_EXTENSIONS = [
# Programming languages
".py", ".js", ".ts", ".jsx", ".tsx",
".java", ".go", ".rs", ".cpp", ".c",
".h", ".hpp", ".cs", ".rb", ".php",
".swift", ".kt", ".scala", ".clj",
# Configuration and data
".md", ".txt", ".json", ".yaml", ".yml",
".toml", ".xml", ".ini", ".conf",
# Web related
".html", ".css", ".scss", ".sass", ".less",
# Scripts
".sql", ".sh", ".bash", ".ps1", ".bat"
]
# === Exclude Patterns ===
# Patterns that will not be indexed
EXCLUDE_PATTERNS = [
# Virtual environments
".venv", "venv", ".env", "env",
"node_modules",
# Version control
".git", ".svn", ".hg",
# Python cache
"__pycache__", ".pytest_cache", ".mypy_cache",
".tox", ".eggs", "*.egg-info",
# Build products
"dist", "build", "target", "out",
# IDE configuration
".idea", ".vscode", ".vs",
# System files
".DS_Store", "Thumbs.db",
# Compilation files
"*.pyc", "*.pyo", "*.pyd", "*.so", "*.dll"
]
```
#### Command-line Parameter Override
```bash
# Temporarily use a different API configuration
npm start -- --base-url https://custom-api.com --token custom-token
# Custom batch size
npm start -- --batch-size 20
# Start web interface on a specified port
npm start -- --web-port 3000
# Combined use
npm start -- --base-url https://api.com --token abc123 --web-port 8080
```
---
## 📘 Usage Guide
### Startup Methods
#### 1. Standard MCP Mode (stdio)
```bash
npm start
```
This mode is used for MCP client integration, communicating through standard input/output.
#### 2. Web Management Mode
```bash
npm start -- --web-port 8080
```
Access http://localhost:8080 to use the graphical interface:
- 📊 View server status
- ⚙️ Edit configuration files
- 📝 Real-time log viewing
- 🛠 Tool debugging and testing
#### 3. Development Mode
```bash
npm run dev # Standard mode + hot reload
npm run dev -- --web-port 8080 # Web mode + hot reload
```
---
## 🔧 Complete WSL Path Support Guide
Acemcp-Node provides **complete path support** for WSL (Windows Subsystem for Linux), without the need for manual path format conversion.
### Supported Path Formats
| Path Type | Original Format | Automatically Converted | Usage Scenario |
|---------|---------|-----------|---------|
| **Windows Local** | `C:\Users\username\project` | `C:/Users/username/project` | Projects on Windows |
| **WSL Internal** | `/home/user/project` | `/home/user/project` | File system within WSL |
| **WSL Accessing Windows** | `/mnt/c/Users/username/project` | `C:/Users/username/project` | WSL accessing Windows files ⭐ |
| **Windows Accessing WSL** | `\\wsl$\Ubuntu\home\user\project` | `/home/user/project` | Windows accessing WSL files ⭐ |
### Usage Examples
#### Windows Environment
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "C:/Users/username/myproject",
"query": "authentication logic"
}
}
```
#### WSL Environment Accessing Windows Project
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "/mnt/c/Users/username/myproject",
"query": "database connection"
}
}
```
#### Windows Accessing WSL Project
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "\\\\wsl$\\Ubuntu\\home\\user\\myproject",
"query": "API routes"
}
}
```
### Automatic Handling Features
- ✅ **Path Normalization** - Unified use of forward slashes `/`
- ✅ **Trailing Slash Removal** - Automatic removal of trailing `/` or `\`
- ✅ **UNC Path Conversion** - Automatic recognition and conversion of `\\wsl$\` format
- ✅ **/mnt Conversion** - Automatic conversion of `/mnt/c/` to `C:/`
### Troubleshooting
If encountering path issues, refer to:
- 📄 [WSL Path Support Guide](WSL_PATH_GUIDE.md) - Special guide for WSL environment
- 📄 [Path Troubleshooting Guide](PATH_TROUBLESHOOTING.md) - Detailed path problem diagnosis
---
## 🔌 MCP Client Configuration
### Claude Desktop Configuration
Edit Claude Desktop configuration file:
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
#### Method 1: Use Globally Installed Package
```json
{
"mcpServers": {
"acemcp": {
"command": "npx",
"args": ["acemcp-node"],
"env": {}
}
}
}
```
#### Method 2: Specify Local Path (Installed from Source)
```json
{
"mcpServers": {
"acemcp": {
"command": "node",
"args": ["D:/projects/Ace-Mcp-Node/dist/index.js"],
"env": {}
}
}
}
```
#### Method 3: With Web Interface
```json
{
"mcpServers": {
"acemcp": {
"command": "node",
"args": [
"D:/projects/Ace-Mcp-Node/dist/index.js",
"--web-port",
"8080"
],
"env": {}
}
}
}
```
#### Method 4: Custom API Configuration
```json
{
"mcpServers": {
"acemcp": {
"command": "node",
"args": [
"D:/projects/Ace-Mcp-Node/dist/index.js",
"--base-url",
"https://your-api.com",
"--token",
"your-token-here"
],
"env": {}
}
}
}
```
#### Special Configuration for WSL Environment
```json
{
"mcpServers": {
"acemcp": {
"command": "node",
"args": ["\\\\wsl$\\Ubuntu\\home\\user\\Ace-Mcp-Node\\dist\\index.js"],
"env": {}
}
}
}
```
### Other MCP Clients
For other clients supporting MCP protocol (such as Zed, Cursor, etc.), the configuration method is similar. Please refer to the MCP configuration documentation for each client.
### Verification
After configuration:
1. Restart MCP client
2. Check log file: `~/.acemcp/log/acemcp.log`
3. If the web interface is enabled, visit http://localhost:8080
---
## 📚 API Documentation
### `search_context` Tool
Perform **semantic search** in the project codebase, automatically incrementally index and return relevant code snippets.
#### Parameters
| Parameter | Type | Required | Description | Example |
|------|------|------|------|------|
| `project_root_path` | string | ✅ | **Absolute path** of project root directory, using forward slashes `/` | `C:/Users/username/myproject` |
| `query` | string | ✅ | Natural language search query | `"authentication middleware"` |
#### Functional Process
```
1. Receive search request
↓
2. Check project index status
↓
3. Perform incremental indexing (only new/modified files)
├─ Collect files (follow .gitignore)
├─ Segment large files
├─ Calculate SHA-256 hash
└─ Batch upload to server
↓
4. Perform semantic search
↓
5. Return formatted results (file path + line number + code snippet)
```
Response Format
```typescript
interface {
type: ' text: string; //
}
```
**Response Example**:
```
Found 3 snippets:
────────────────────────────────────────
/auth/middleware.ts (Lines 15-28)
authMiddleware(req: Request, res: Response, next: Next const token = req.headers.authorization?.split(' ')[
if (!token) {
return res.status(json({ error: 'No token provided' });
}
{
const decoded =(token, process.env.JWT req.user = decoded;
next();
} catch (error) {
res.status(403).json({ error: token' });
}
}
────────────────────────────────────────
File: src/auth (Lines 42-...
```
#### Usage Examples Example 1: Searching Logic
```json
{
"tool": "search_context",
"arguments": {
project_root_path": "C:/Users/username/myproject "query": "user authentication and JWT token verification"
```
##### Example 2: Searching for Database Configuration
```json "tool": "",
"arguments": "project_root_path":/user/backend-api",
": "database connection pool }
}
```
##### Example 3: Searching for Error```json
{
": "search_context",
arguments": {
"project_root_path": "D:/projects",
"query": boundary and exception handling components"
}
}
Error Handling
| Error Type | Return Message | Solution---------|---------|---------|
| Not Exist | ` Project root path does not | Check path spelling |
| Missing Parameters | `Error: project_root_path is required` | Provide all required parameters Connection Failed | ` Failed to connect to API` | Check BASE_URL and TOKEN configuration |
| Indexing Failed | `Error: Failed to index project` | Check log files for diagnostics |
---
## 💡 Usage Scenarios
### Scenario 1: AI Assistant Code Review
**Requirement**: Let the AI assistant understand the project's authentication mechanism
```
User: @acemcp How is user authentication implemented in my project?
AI Assistant Call:
{
"tool": "search_context",
"arguments": {
"project_root_path": "C:/projects/my-saas-app",
"query": "user authentication login signup middleware"
}
}
Result: AI retrieves authentication-related code, understands implementation, and provides review suggestions
```
### Scenario 2: Bug Debugging
**Requirement**: Locate error handling in the payment module
```
User: @acemcp How is error handling done for payment failures?
AI Assistant Call:
{
"tool": "search_context",
"arguments": {
"project_root_path": "D:/ecommerce-backend",
"query": "payment error handling failure rollback"
}
}
Result: Quickly locate payment error handling logic and discover potential issues
```
### Scenario 3: New Feature Development
**Requirement**: Understand existing structure
```
User: @acemcp I need to new API endpoint. How routes organized?
AI Assistant{
"tool":_context",
"arguments": {
"project_root "/home/dev/api-server "query": "API definition express router"
Result: Understand route structure new endpoints in the
```
### Scenario Documentation Generation
**Requirement**: for utility functions
: @acemcp generate documentation for utility functions utils directory
AI{
"toolsearch_context",
" {
"project_root "C:/company/shared "query": functions in utils directory"
}
}
Result: Retrieve functions and automatically generate JSDoc documentation
5:actoring
**Requirement**: usages of the old APIUser: @acem are deprecating. Find all places that
AI Assistant Call:
{
"tool": "search "arguments": "project_root_path"::/legacy-app",
"legacyApi function"
}
}
all call points and strategy
```
---
## Management Interface
### Web Interface
```bash
# Standard port 808npm start -- --web0
# Custom port
npm start -- -- 3000
```
Access: http://localhost:### Features
| Feature Description | Purpose |
------|
| ** Status** |-time running status, indexed and configuration information | Monitor |
| **⚙️ Configuration Management** | Online editing of `settings.toml`, takes effect immediately after saving | No need to manually edit configuration files |
| **📝 Real-time Logs** | WebSocket pushes real-time logs, supports filtering and searching | Debugging and issue diagnosis |
| **🛠 Tool Debugging** | tool calls, queries | Development and testing **🌍 B** | Chinese/English Internationalization support |
###
#### Server Status┌──────────────────────────────────── 🟢 Status │
││ Status: Running│ Indexed Projects: 5 │
│ Port: 8080 │
│: https:// │
└─────────────────────────────────────┘
```
#### Configuration Editor
- Syntax highlighting TOML editor
- Real-time validation
-click save and apply Real-time Log Viewer
-coded log levels (DEBUG/INFO/WARNING/ERROR)
- Auto-scrolling
- and filtering
- Log export
#### Tool Debugging Panel
```json
{
": "search_context",
arguments": {
"project_root_path": "C/project",
"query search query"
}
```
Click the "Test Tool" button to view the response.
### Security Recommendations
**: The Web interface is **bound to localhost not exposed to the public remote access:
Use SSH tunnel: `ssh 8080:localhost:8080 user@server`
2. Configure reverse proxy (Nginx/Caddy add authentication
3. **** expose directly public internet
---
## Project Structure
```
-Node/
├── # TypeScript
│ ├── index 🚪 MCP point
│ │ # - Initialize MCP│ │ # - Register tools
│ # - Handle
│ ├── config.ts ️ Configuration management│ │ # settings.toml
│ # - Generate default configuration
│ # - Provide configuration
│ │
├── logger.ts # Logging system singleton
│ # - File log rotation
│ │ # - Console output
│ │ # - WebSocket broadcast integration
│ │
│ ├── index/ # 📊 Indexing management module
│ │ └── manager.ts # - Incremental indexing logic
│ # collection and splitting
│ │ # -ignore parsing
│ # - SHA hash calculation
│ # - Batch │
│ / # tool implementations
│ │ └── searchContext - search
│ │ Parameter validation
│ # - Search API calls
│ ├── utils/ 🔧 Utility functions
│ ├── path # - Path│ │ - W conversion
│ │ # - handling
│ │ └── detailedLogger.ts - Detailed log formatting │
│ └── # 🌐
│ ├── app.ts # -
│ │ - API routing
│ │ # - WebSocket server
│ ├── logBroadcaster.ts - Log broadcaster └── templates/
│ └── index.html # - Single-page application interface
│
├── dist/ # 📦 Compiled output (published to NPM)
│ ├── *.js # - Compiled JavaScript
│ ├── *.d.ts # - TypeScript type definitions
│ ├── *.js.map # - Source Maps
│ └── web/templates/ # - Web interface resources
│
├── node_modules/ # Dependencies (not published)
│
├── package.json # 📋 NPM package configuration
├── tsconfig.json # 📋 TypeScript compilation configuration
├── LICENSE # 📄 ISC license
├── README.md # 📖 This document
│
└── docs/ # 📚 Additional documentation
├── PATH_TROUBLESHOOTING.md # - Path issue troubleshooting
├── WSL_PATH_GUIDE.md # - WSL path guide
└── USAGE_GUIDE.md # - Detailed usage guide
```
### User Data Directory
```
~/.acemcp/ # User configuration and data
├── settings.toml # Main configuration file
├── data/
│ └── projects.json # Project indexing metadata
└── log/
├── acemcp.log # Current log
├── acemcp.log.1 # Rotated log
└── ... # Keep the last 10 logs
```
---
## 🔄 Compatibility with Python Version
Acemcp-Node is **fully compatible** with [Acemcp-Python](https://github.com/yeuxuan/Ace-Mcp-Python) and can be seamlessly switched.
| Compatibility Item | Description | Location |
|--------|------|------|
| **Configuration File** | Shares the same `settings.toml` | `~/.acemcp/settings.toml` |
| **Project Data** | Shares project indexing metadata | `~/.acemcp/data/projects.json` |
| **API Interface** | Calls the same indexing and search API | `BASE_URL` configuration |
| **Hash Algorithm** | Uses the same SHA-256 calculation for `blob_name` | Incremental indexing |
| **File Format** | TOML configuration, JSON data | Common format |
### Switching Versions
```bash
# Switch from Python version to Node.js version
# 1. Stop Python version
pkill -f acemcp
# 2. Start Node.js version (using the same configuration)
npm start
# Configuration files and indexing data are automatically shared, no migration needed
```
### Differences
| Feature | Python Version | Node.js Version |
|------|------------|-------------|
| **Runtime** | Python 3.10+ | Node.js 18.0+ |
| **Performance** | Good | Slightly faster (V8 engine) |
| **Memory Usage** | Medium | Slightly lower |
| **Dependency Management** | pip/uv | npm/yarn/pnpm |
| **Type Safety** | Type hints | TypeScript strict mode |
| **Web Interface** | ✅ | ✅ |
| **WSL Support** | ✅ | ✅ |
---
## 🛠 Development
### Setting Up Development Environment
```bash
# 1. Clone repository
git clone https:///yeuxce-Mcp-Node.git
cd Ace-Mcp-Node
# 2. Install dependencies
npm install
# 3. Start development mode (hot reloading)
npm run dev
# 4. Or start development mode with web interface
npm run dev -- --web-port 8080
```
### NPM Scripts
| Command | Description | Purpose |
|------|------|------|
| `npm run build` | Compile TypeScript → `dist/` | Production build |
| `npm run dev` | Development mode + hot reloading | Development debugging |
| `npm start` | Run compiled code | Production run |
| `npm start:web` | Start with web interface (8080) | Web management |
| `npm test` | Run test scripts | Testing |
| `npm run copy-templates` | Copy web templates | Build step |
### Code Style
#### TypeScript Configuration
- **Strict Mode** - Enable all strict type checks
- **ES2022 Target** - Modern JavaScript features
- **ESM Modules** - Use ES module system
- **Source Maps** - Debugging support
#### Naming Conventions
```typescript
// Class names: PascalCase
class IndexManager {}
// Functions: camelCase
function normalizePath() {}
// Constants: UPPER_SNAKE_CASE
const USER_CONFIG_DIR = '~/.acemcp';
// Interfaces: PascalCase + 'I' prefix (optional)
interface IConfig {}
```
# Import Specifications
```typescript
// ✅ Correct: ESM must include .js extension
import { getConfig } from './config.js';
import { IndexManager } from './index/manager.js';
// ❌ Incorrect: Missing extension
import { getConfig } from './config';
```
## Logging System
Log file location: `~/.acemcp/log/acemcp.log`
### Log Levels
| Level | Purpose | Example |
|------|------|------|
| **DEBUG** | Detailed debugging information | `logger.debug('File hash calculated')` |
| **INFO** | Important operation records | `logger.info('Project indexed successfully')` |
| **WARNING** | Non-fatal warnings | `logger.warning('File encoding fallback')` |
| **ERROR** | Error messages | `logger.error('API request failed')` |
| **EXCEPTION** | Exception stack traces | `logger.exception('Error in tool', error)` |
### Log Configuration
- **File Rotation** - Single file maximum 5MB
- **Retention Count** - Recent 10 log files
- **Console** - INFO level and above (non-stdio mode)
- **File** - DEBUG level and above
- **WebSocket** - Real-time broadcasting to Web interface
## Adding New Tools
```typescript
// 1. Create a tool file: src/tools/myTool.ts
export async function myTool(args: { param1: string }): Promise<{ type: 'text'; text: string }> {
try {
// Parameter verification
if (!args.param1) {
return { type: 'text', text: 'Error: param1 is required' };
}
// Business logic
const result = await doSomething(args.param1);
return { type: 'text', text: result };
} catch (error: any) {
logger.exception('Error in myTool', error);
return { type: 'text', text: `Error: ${error.message}` };
}
}
// 2. Register in src/index.ts
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === 'my_tool') {
return await myTool(request.params.arguments);
}
// ...
});
// 3. Add to tool list
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'my_tool',
description: 'My custom tool',
inputSchema: {
type: 'object',
properties: {
param1: { type: 'string', description: 'Parameter 1' }
},
required: ['param1']
}
},
// ...
]
}));
```
---
## 🐛 Troubleshooting
### Common Issues
| Issue | Symptoms | Solutions |
|------|------|---------|
| **Path Not Found** | `Project root path does not exist` | [Path Issues](#path-issues) |
| **API Connection Failed** | `Failed to connect to API` | [Connection Issues](#connection-issues) |
| **Encoding Error** | `UnsupportedEncoding` | [Encoding Issues](#encoding-issues) |
| **Port Occupied** | `EADDRINUSE` | [Web Interface Unavailable](#web-interface-unavailable) |
| **Permission Error** | `EACCES` | [Permission Issues](#permission-issues) |
| **Upload Failed** | Batch upload failed | [Upload Failure Handling](UPLOAD_FAILURE_HANDLING.md) |
| **Large Log File** | Log occupying too much space | [Log Rotation Configuration](LOG_ROTATION_CONFIG.md) |
| **WSL Path** | Path conversion failed | [WSL Guide](WSL_PATH_GUIDE.md) |
### Path Issues
#### Symptoms
```
Error: Project root path does not exist: /invalid/path
```
#### Diagnostic Steps
1. **Check Path Format**
```bash
# ✅ Correct format (using forward slashes)
C:/Users/username/project
# ❌ Incorrect format (using backslashes)
C:\Users\username\project
# ❌ Incorrect format (trailing slash)
C:/Users/username/project/
```
2. **Verify Path Existence**
```bash
# Windows
dir "C:\Users\username\project"
# Linux/macOS
ls -la /home/user/project
# WSL
ls -la /mnt/c/Users/username/project
```
3. **Use Absolute Path**
```json
{
"project_root_path": "C:/Users/username/myproject" // ✅ Absolute path
}
```
4. **WSL Special Cases**
- Windows accessing WSL: `\\wsl$\Ubuntu\home\user\project` → Automatic conversion
- WSL accessing Windows: `/mnt/c/Users/username/project` → Automatic conversion
**Detailed Guide**:
- 📄 [Path Troubleshooting Guide](PATH_TROUBLESHOOTING.md)
- 📄 [WSL Path Support Guide](WSL_PATH_GUIDE.md)
### Connection Issues
#### Symptoms
```
Error: Failed to connect to API: https://api.example.com
```
#### Solutions
1. **Check Configuration File**
```bash
cat ~/.acemcp/settings.toml
```
2. **Verify API Accessibility**
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://your-api.com/health
```
3. **Check Network Proxy**
```bash
echo $HTTP_PROXY
echo $HTTPS_PROXY
```
4. **Temporary Override Configuration**
```bash
npm start -- --base-url https://your-api.com --token your-token
```
### Encoding Issues
#### Symptoms
```
Warning: Failed to read file with UTF-8, trying alternative encodings
```
#### Description
Acemcp-Node **automatically handles** multiple encodings:
1. UTF-8 (default)
2. GBK (Simplified Chinese)
3. GB2312 (Simplified Chinese)
4. Latin-1 (Western European languages)
If all encodings fail, the file will be skipped and a warning logged.
#### Manual Encoding Specification (not supported)
To support other encodings, please submit an [Issue](https://github.com/yeuxuan/Ace-Mcp-Node/issues).
### Web Interface Unavailable
#### Symptoms
```
Error: listen EADDRINUSE: address already in use :::8080
```
#### Solutions
1. **Check Port Occupancy**
```bash
# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F
# Linux/macOS
lsof -i :8080
kill -9 <PID>
```
2. **Use Alternative Port**
```bash
npm start -- --web-port 3000
```
3. **Check Firewall**
```bash
# Windows Firewall
netsh advfirewall firewall show rule name=all | findstr 8080
# Linux Firewall
sudo ufw status
sudo ufw allow 8080
```
### Permission Issues
#### Symptoms
```
Error: EACCES: permission denied
```
#### Solutions
1. **Check Directory Permissions**
```bash
# Linux/macOS
ls -la ~/.acemcp
chmod 755 ~/.acemcp
chmod 644 ~/.acemcp/settings.toml
# Windows (run as administrator)
icacls "%USERPROFILE%\.acemcp" /grant %USERNAME%:F
```
2. **Avoid Using sudo**
```bash
# ❌ Not recommended
sudo npm install -g acemcp-node
# ✅ Recommended
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g acemcp-node
```
### Indexing Failed
#### Symptoms
```
Error: Failed to index project: timeout
```
#### Solutions
1. **Check Project Size**
```bash
du -sh /path/to/project
```
2. **Increase Batch Size** (settings.toml)
```toml
BATCH_SIZE = 20 # Default 10, can be increased to 50
```
3. **Check Network Stability**
```bash
ping api.example.com
```
4. **View Detailed Logs**
```bash
tail -f ~/.acemcp/log/acemcp.log
```
### Getting Help
If none of the above solutions work:
1. **View Logs**
```bash
cat ~/.acemcp/log/acemcp.log
```
2. **Submit an Issue**
- Visit [GitHub Issues](https://github.com/yeuxuan/Ace-Mcp-Node/issues)
- Provide error information and log snippets
- Describe reproduction steps
3. **Community Discussion**
- Participate in [Discussions](https://github.com/yeuxuan/Ace-Mcp-Node/discussions)
---
## 🤝 Contributions
We welcome all forms of contributions!
### Contribution Methods
- 🐛 **Report Bugs** - Submit an [Issue](https://github.com/yeuxuan/Ace-Mcp-Node/issues)
- 💡 **Suggest Features** - Discuss in [Discussions](https://github.com/yeuxuan/Ace-Mcp-Node/discussions)
- 📖 **Improve Documentation** - Correct errors or add examples
- 🔧 **Submit Code** - Fork and create a Pull Request
### Development Process
```bash
# 1. Fork the repository
gh repo fork yeuxuan/Ace-Mcp-Node --clone
# 2. Create a feature branch
cd Ace-Mcp-Node
git checkout -b feature/my-feature
# 3. Develop and test
npm install
npm run dev
# Make changes...
npm run build
npm test
# 4. Commit changes
git add .
git commit -m "feat: add my feature"
# 5. Push and create a PR
git push origin feature/my-feature
gh pr create
```
### Code Style
- Follow TypeScript strict mode
- Use ESLint and Prettier (if configured)
- Add proper comments and type definitions
- Maintain backward compatibility
### Commit Style
Use [Conventional Commits](https://www.conventionalcommits.org/):
```
feat: New feature
fix: Bug fix
docs: Documentation update
style: Code formatting
refactor: Refactoring
test: Test-related
chore: Build/tool-related
```
---
## 📧 Contact
- **Author**: yihua
- **Email**: 487735913@qq.com
- **GitHub**: [@yeuxuan](https://github.com/yeuxuan)
- **Project Homepage**: https://github.com/yeuxuan/Ace-Mcp-Node
---
## 🙏 Acknowledgements
- Based on [Acemcp-Python](https://github.com/yeuxuan/Ace-Mcp-Python) design and implementation
- Thanks to the [Model Context Protocol](https://github.com/modelcontextprotocol) team
- Thanks to all contributors and users
---
## 🔗 Resources
- **MCP Official Documentation**: https://modelcontextprotocol.io/
- **Python Version**: https://github.com/yeuxuan/Ace-Mcp-Python
- **NPM Package**: https://www.npmjs.com/package/acemcp-node
- **Issue Tracker**: https://github.com/yeuxuan/Ace-Mcp-Node/issues
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
---
<div align="center">
**⭐ If this project helps you, give it a Star! ⭐**
Made with ❤️ by [yihua](https://github.com/yeuxuan)
</div>
