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-with-python-version)
- [Contributing](#contributing)
- [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
- 📊 Obtain precise code snippets with line numbers
- 🤖 Automatically incrementally update indexes
- 🌐 Manage and debug through the web interface
**Why Choose Acemcp?**
| Feature | Description |
|------|------|
| **Zero-configuration startup** | Automatically generates configuration on first run |
| **Incremental indexing** | Only processes changed files, fast and efficient |
| **Cross-platform** | Supports Windows, Linux, macOS, WSL |
| **Multi-encoding** | Automatically detects 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 indexes new or modified files
- ✅ **Batch Upload** - Supports batch operations and automatic retries
- ✅ **Intelligent Splitting** - Large files automatically split 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 excludes irrelevant files
- ✅ **Detailed Logs** - Configurable log levels and rotation
</td>
</tr>
<tr>
<td width="50%">
### 🌍 Compatibility
- ✅ **Cross-platform Paths** - Unified handling of Windows/Unix paths
- ✅ **Complete WSL Support** - UNC paths, /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/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. Install from Source
```bash
git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
cd Ace-Mcp-Node
npm install
npm run build
# Development mode (auto-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 size (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"
]
# === Exclusion Patterns ===
# Directories and file 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",
# Compiled 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 specified port
npm start -- --web-port 3000
# Combine usage
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
```
Visit 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 Guide to WSL Path Support
Acemcp-Node provides **complete path support** for WSL (Windows Subsystem for Linux), eliminating 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` | Within WSL file system |
| **WSL Access to Windows** | `/mnt/c/Users/username/project` | `C:/Users/username/project` | WSL accessing Windows files ⭐ |
| **Windows Access to 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** - Automatically removes trailing `/` or `\`
- ✅ **UNC Path Conversion** - Automatically recognizes and converts `\\wsl$\` format
- ✅ **/mnt Conversion** - Automatically converts `/mnt/c/` to `C:/`
### Troubleshooting
If path issues are encountered, refer to:
- 📄 [WSL Path Support Guide](WSL_PATH_GUIDE.md) - WSL environment-specific guide
- 📄 [Path Troubleshooting Guide](PATH_TROUBLESHOOTING.md) - Detailed path issue 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: Using 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": {}
}
}
}
```
#### WSL Environment Special Configuration
```json
{
"mcpServers": {
"acemcp": {
"command": "node",
"args": ["\\\\wsl$\\Ubuntu\\home\\user\\Ace-Mcp-Node\\dist\\index.js"],
"env": {}
}
}
}
```
### Other MCP Clients
For other MCP protocol-supported clients (like Zed, Cursor, etc.), the configuration method is similar. Please refer to each client's MCP configuration documentation.
### Verify Configuration
After configuration:
1. Restart MCP client
2. Check log file: `~/.acemcp/log/acemcp.log`
3. If web interface is enabled, visit http://localhost:8080
---
## API Documentation
### `search_context` Tool
Performs **semantic search** in the project codebase, automatically incrementally indexing and returning relevant code snippets.
#### Parameters
| Parameter | Type | Required | Description | Example |
|------|------|------|------|------|
| `project_root_path` | string | ✅ | **Absolute path** to 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)
├─ Split large files
├─ Calculate SHA-256 hash
└─ Batch upload to server
↓
4. Perform semantic search
↓
5. Return formatted results (file path + line number + code snippet)
```
#### Return Format
```typescript
interface SearchResult {
type: 'text';
text: string; // Formatted search result
}
```
**Return Example**:
```
Found 3 relevant code snippets:
────────────────────────────────────────
File: src/auth/middleware.ts (Lines 15-28)
export function authMiddleware(req: Request, res: Response, next: NextFunction) {
const token = req.headers.authorization?.split(' ')[1];
if (!token) {
return res.status(401).json({ error: 'No token provided' });
}
try {
const decoded = jwt.verify(token, process.env.JWT_SECRET);
req.user = decoded;
next();
} catch (error) {
res.status(403).json({ error: 'Invalid token' });
}
}
────────────────────────────────────────
File: src/auth/login.ts (Lines 42-56)
...
```
#### Usage Examples
##### Example 1: Searching for Authentication 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": "search_context",
"arguments": {
"project_root_path": "/home/user/backend-api",
"query": "database connection pool configuration"
}
}
```
##### Example 3: Searching for Error Handling
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "D:/projects/react-app",
"query": "error boundary and exception handling in React components"
}
}
```
#### Error Handling
| Error Type | Return Message | Solution |
|---------|---------|---------|
| Path does not exist | `Error: Project root path does not exist` | Check path spelling and permissions |
| Missing parameters | `Error: project_root_path is required` | Provide all required parameters |
| API connection failed | `Error: Failed to connect to API` | Check BASE_URL and TOKEN configuration |
| Indexing failed | `Error: Failed to index project` | Check log files for diagnosis |
---
## 💡 Use Case Examples
### 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 the implementation, and provides review suggestions.
```
### Scenario 2: Bug Debugging
**Requirement**: Locate the error handling for the payment module.
```
User: @acemcp How are errors handled when payment fails?
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 the existing API route structure.
```
User: @acemcp I need to add a new API endpoint. How are existing routes organized?
AI Assistant Call:
{
"tool": "search_context",
"arguments": {
"project_root_path": "/home/dev/api-server",
"query": "API routes endpoints definition express router"
}
}
Result: Understand the route structure and implement new endpoints following the existing pattern.
```
### Scenario 4: Documentation Generation
**Requirement**: Generate documentation for utility functions.
```
User: @acemcp Help me generate documentation for utility functions in the utils directory.
AI Assistant Call:
{
"tool": "search_context",
"arguments": {
"project_root_path": "C:/company/shared-utils",
"query": "utility helper functions in utils directory"
}
}
Result: Retrieve all utility functions and automatically generate JSDoc/TSDoc documentation.
```
### Scenario 5: Code Refactoring
**Requirement**: Find all places using the old API.
```
User: @acemcp We are deprecating legacyApi. Find all places that call it.
AI Assistant Call:
{
"tool": "search_context",
"arguments": {
"project_root_path": "D:/legacy-app",
"query": "legacyApi function calls usage"
}
}
Result: List all call points and plan refactoring strategy.
```
---
## 🌐 Web Management Interface
### Starting the Web Interface
```bash
# Standard port 8080
npm start -- --web-port 8080
# Custom port
npm start -- --web-port 3000
```
Access: http://localhost:8080
### Features
| Feature Module | Description | Purpose |
|---------|------|------|
| **📊 Server Status** | Displays real-time status, indexed projects, and configuration | Monitor server health |
| **⚙️ Configuration Management** | Online editing of `settings.toml`, takes effect immediately | No need for manual configuration file editing |
| **📝 Real-time Logs** | WebSocket pushes real-time logs, supports filtering and search | Debugging and issue diagnosis |
| **🛠 Tool Debugging** | Simulate MCP tool calls, test search queries | Development and testing |
| **🌍 Bilingual Support** | Chinese/English interface switching | Internationalization support |
### Interface Preview
#### Server Status Panel
```
┌─────────────────────────────────────┐
│ 🟢 MCP Server Status │
│ │
│ Status: Running │
│ Indexed Projects: 5 │
│ Port: 8080 │
│ Base URL: https://api... │
└─────────────────────────────────────┘
```
#### Configuration Editor
- Syntax highlighting TOML editor
- Real-time validation
- One-click save and apply
#### Real-time Log Viewer
- Color-coded log level indicators (DEBUG/INFO/WARNING/ERROR)
- Auto-scrolling
- Log search and filtering
- Log export
#### Tool Debugging Panel
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "C:/your/project",
"query": "your search query"
}
}
```
Click the "Test Tool" button to view the return result.
### Security Recommendations
⚠️ **Important**: The Web interface is **only bound to localhost** and not open to the Internet.
For remote access:
1. Use SSH tunnel: `ssh -L 8080:localhost:8080 user@server`
2. Configure reverse proxy (Nginx/Caddy) and add authentication
3. **Do not** expose directly to the public Internet
---
## 📁 Project Structure
```
Ace-Mcp-Node/
├── src/ # TypeScript source code
│ ├── index.ts # 🚪 MCP server entry point
│ │ # - Initialize MCP server
│ │ # - Register tools
│ │ # - Handle command-line arguments
│ │
│ ├── config.ts # ⚙️ Configuration management singleton
│ │ # - Load settings.toml
│ │ # - Generate default configuration
│ │ # - Provide configuration access interface
│ │
│ ├── logger.ts # 📝 Log system singleton
│ │ # - File log rotation
│ │ # - Console output
│ │ # - WebSocket broadcast integration
│ │
│ ├── index/ # 📊 Index management module
│ │ └── manager.ts # - Incremental indexing logic
│ │ # - File collection and segmentation
│ │ # - .gitignore parsing
│ │ # - SHA-256 hash calculation
│ │ # - Batch upload
│ │
│ ├── tools/ # 🛠 MCP tool implementation
│ │ └── searchContext.ts # - search_context tool
│ │ # - Parameter validation
│ │ # - Search API call
│ │
│ ├── utils/ # 🔧 Utility functions
│ │ ├── pathUtils.ts # - Path normalization
│ │ │ # - WSL path conversion
│ │ │ # - UNC path handling
│ │ └── detailedLogger.ts # - Detailed log formatting
│ │
│ └── web/ # 🌐 Web management interface
│ ├── app.ts # - Express application
│ │ # - 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 and indexing data are automatically shared, no need for migration
```
### 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
### Development Environment Setup
```bash
# 1. Clone repository
git clone https://github.com/yeuxuan/Ace-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 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** - Maximum file size: 5MB
- **Retention** - Recent 10 log files
- **Console** - INFO level and above (non-stdio mode)
- **File** - DEBUG level and above
- **WebSocket** - Real-time broadcasting to the 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 validation
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 Quick Check
| Issue | Symptoms | Solutions |
|------|------|---------|
| **Path Does Not Exist** | `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 file occupies 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 will be logged.
#### Manual Encoding Specification (not supported)
If you need 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 Another 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 messages and log snippets
- Describe reproduction steps
3. **Community Discussion**
- Participate in [Discussions](https://github.com/yeuxuan/Ace-Mcp-Node/discussions)
---
## 🤝 Contributing
We welcome all forms of contributions!
### Ways to Contribute
- 🐛 **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 Workflow
```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/tooling-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>
