Content
# Acemcp Node.js Implementation
[](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)
- [User Guide](#-user-guide)
- [MCP Client Configuration](#configure-in-the-mcp-client)
- [Tool Description](#-tool-description)
- [Web Management Interface](#-web-management-interface)
- [WSL Support](#-complete-guide-to-wsl-path-support)
- [API Documentation](#-api-documentation)
- [Example Scenarios](#-usage-scenario-examples)
- [Development Guide](#-development)
- [Troubleshooting](#-troubleshooting)
- [Compatibility](#-compatibility-with-python-versions)
- [Contributing](#-contributing)
- [License](#-license)
---
## 📖 Introduction
**Acemcp** is a high-performance MCP (Model Context Protocol) server designed to provide **codebase indexing** and **semantic search** capabilities for AI assistants (such as Claude, GPT, etc.). With Acemcp, AI assistants can:
- 🔍 Quickly search and understand large codebases
- 📊 Retrieve precise code snippets with line numbers
- 🤖 Automatically incrementally update the index
- 🌐 Manage and debug through a 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** | Full support for Windows, Linux, macOS, WSL |
| **Multi-Encoding** | Automatically detects UTF-8, GBK, GB2312, Latin-1 |
| **AI Friendly** | Returns formatted code snippets, including file paths and line numbers |
## ⭐ Core Features
<table>
<tr>
<td width="50%">
### 🚀 Performance Optimization
- ✅ **Incremental Indexing** - Only index new or modified files
- ✅ **Batch Upload** - Supports batch operations and automatic retries
- ✅ **Intelligent Splitting** - Large files are automatically split into multiple chunks
- ✅ **Caching Mechanism** - SHA-256 hash to avoid duplicate uploads
### 🛠 Developer Friendly
- ✅ **TypeScript** - Full type support
- ✅ **Web Interface** - Real-time logs, configuration management, tool debugging
- ✅ **.gitignore Support** - Automatically exclude irrelevant files
- ✅ **Detailed Logging** - Configurable log levels and rotation
</td>
</tr>
<tr>
<td width="50%">
### 🌍 Compatibility
- ✅ **Cross-platform Path** - Unified handling of Windows/Unix paths
- ✅ **Full WSL Support** - Automatic conversion of UNC paths and /mnt
- ✅ **Multi-encoding Support** - UTF-8, GBK, GB2312, Latin-1
- ✅ **Python Version Compatibility** - Shared configuration and data formats
### 🎯 MCP Integration
- ✅ **Standard MCP Protocol** - Complete SDK implementation
- ✅ **search_context Tool** - Semantic search 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 install locally to the project
npm install acemcp-node
```
### Method 2: Install from Source
```bash
# Clone the Repository
git clone https://github.com/yeuxuan/Ace-Mcp-Node.git
cd Ace-Mcp-Node
# Install Dependencies
npm install
# Compile TypeScript
```bash
npm run build
```
### First Run
```bash
```
# Start the Server (Configuration file will be created for the first time)
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. Installation from Source Code
```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
When running for the first time, the program will automatically create a configuration file in the `~/.acemcp/` directory:
#### Configuration File Location
```
~/.acemcp/
├── settings.toml # Main configuration file
├── data/
│ └── projects.json # Project index data
└── log/
└── acemcp.log # Log file
```
#### Detailed Explanation of settings.toml Configuration
```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 number of lines per blob
# === File Type Configuration ===
# Supported Indexable 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 Mode ===
# 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 artifacts
"dist", "build", "target", "out",
# IDE configurations
".idea", ".vscode", ".vs",
# System files
".DS_Store", "Thumbs.db",
# Compiled files
"*.pyc", "*.pyo", "*.pyd", "*.so", "*.dll"
]
#### Command Line Argument Override
```bash
# Temporarily Use Different API Configuration
npm start -- --base-url https://custom-api.com --token custom-token
# Custom Batch Size
npm start -- --batch-size 20
# Start the Web Interface on a Specified Port
npm start -- --web-port 3000
# Combined Usage
```bash
npm start -- --base-url https://api.com --token abc123 --web-port 8080
```
## 📘 User Guide
### Startup Method
#### 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 Guide to WSL Path Support
Acemcp-Node provides **full 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 | Use Case |
|-----------|-----------------|------------------------|----------|
| **Windows Local** | `C:\Users\username\project` | `C:/Users/username/project` | Projects on Windows |
| **Inside WSL** | `/home/user/project` | `/home/user/project` | Within the WSL file system |
| **WSL Accessing Windows** | `/mnt/c/Users/username/project` | `C:/Users/username/project` | Accessing Windows files in WSL ⭐ |
| **Windows Accessing WSL** | `\\wsl$\Ubuntu\home\user\project` | `/home/user/project` | Accessing WSL files from Windows ⭐ |
### Usage Example
#### Windows Environment
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "C:/Users/username/myproject",
"query": "authentication logic"
}
}
```
#### Accessing Windows Projects from WSL Environment
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "/mnt/c/Users/username/myproject",
"query": "database connection"
}
}
```
#### Accessing WSL Projects from Windows
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "\\\\wsl$\\Ubuntu\\home\\user\\myproject",
"query": "API routes"
}
}
```
### Automatic Handling Features
- ✅ **Path Normalization** - Uniformly use forward slashes `/`
- ✅ **Trailing Slash Removal** - Automatically remove trailing `/` or `\` from paths
- ✅ **UNC Path Conversion** - Automatically recognize and convert `\\wsl$\` format
- ✅ **/mnt Conversion** - Automatically convert `/mnt/c/` to `C:/`
### Troubleshooting
If you encounter path issues, please refer to:
- 📄 [WSL Path Support Guide](WSL_PATH_GUIDE.md) - A guide specifically for the WSL environment
- 📄 [Path Troubleshooting Guide](PATH_TROUBLESHOOTING.md) - Detailed diagnostics for path issues
---
## 🔌 Configuring in the MCP Client
### Claude Desktop Configuration
Edit the 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 Packages
```json
{
"mcpServers": {
"acemcp": {
"command": "npx",
"args": ["acemcp-node"],
"env": {}
}
}
}
```
#### Method 2: Specify Local Path (Install 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 Four: 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 that support the MCP protocol (such as Zed, Cursor, etc.), the configuration method is similar. Please refer to the MCP configuration documentation for each client.
### Verification Configuration
After the configuration is complete:
1. Restart the MCP client
2. Check the 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 indexing and returning relevant code snippets.
#### Parameters
| Parameter | Type | Required | Description | Example |
|-----------|--------|----------|--------------------------------------------------|-------------------------------|
| `project_root_path` | string | ✅ | The **absolute path** of the project root directory, using forward slashes `/` | `C:/Users/username/myproject` |
| `query` | string | ✅ | Natural language search query | `"authentication middleware"` |
#### Function Flow
```
1. Receive search request
↓
2. Check project index status
↓
3. Execute 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 Example
##### Example 1: Search Authentication Logic
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "C:/Users/username/myproject",
"query": "user authentication and JWT token verification"
}
}
```
##### Example 2: Search Database Configuration
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "/home/user/backend-api",
"query": "database connection pool configuration"
}
}
```
##### Example 3: Error Handling in Search
```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 parameter | `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**: Enable the AI Assistant to 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: The AI retrieves the authentication-related code, understands the implementation, and provides review suggestions.
```
### Scenario 2: Bug Debugging
**Requirement**: Locate the error handling in the payment module
```
User: @acemcp How is the error 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 the payment error handling logic and identify potential issues
```
### Scenario 3: New Feature Development
**Requirement**: Understand the existing API routing structure
```
User: @acemcp I need to add a new API endpoint, how are the 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 routing structure and implement the new endpoint according to the existing pattern
```
### Scenario 4: Document Generation
**Requirement**: Generate documentation for utility functions
```
User: @acemcp Please help me generate documentation for the 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 going to deprecate legacyApi, find all the 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 calling points and plan the refactoring strategy
```
## 🌐 Web Management Interface
### Start 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 running status, number of indexed items, configuration information | Monitor server health |
| **⚙️ 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** | Simulates MCP tool calls, tests search queries | Development and testing |
| **🌍 Bilingual Support** | Switch between Chinese/English interface | 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
- Export logs
#### 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 returned results.
### Security Recommendations
⚠️ **Important**: The web interface is **only bound to localhost** and is not accessible from the external network.
For remote access:
1. Use an SSH tunnel: `ssh -L 8080:localhost:8080 user@server`
2. Configure a reverse proxy (Nginx/Caddy) and add authentication
3. **Do not** expose it directly to the public network
---
## 📁 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 # 📝 Logging system singleton
│ │ # - File log rotation
│ │ # - Console output
│ │ # - WebSocket broadcast integration
│ │
│ ├── index/ # 📊 Index management module
│ │ └── manager.ts # - Incremental indexing logic
│ │ # - File collection and splitting
│ │ # - .gitignore parsing
│ │ # - SHA-256 hash calculation
│ │ # - Batch upload
│ │
│ ├── tools/ # 🛠 MCP tool implementations
│ │ └── searchContext.ts # - search_context tool
│ │ # - Parameter validation
│ │ # - Search API calls
│ │
│ ├── 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 routes
│ │ # - 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 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 index metadata
└── log/
├── acemcp.log # Current log
├── acemcp.log.1 # Rotated log
└── ... # Keep the most recent 10
```
## 🔄 Compatibility with Python Version
Acemcp-Node is **fully compatible** with [Acemcp-Python](https://github.com/yeuxuan/Ace-Mcp-Python) and allows for seamless switching.
| Compatibility Item | Description | Location |
|--------------------|-------------|----------|
| **Configuration File** | Shares the same `settings.toml` | `~/.acemcp/settings.toml` |
| **Project Data** | Shares project index metadata | `~/.acemcp/data/projects.json` |
| **API Interface** | Calls the same indexing and search APIs | `BASE_URL` configuration |
| **Hash Algorithm** | Uses the same SHA-256 to compute `blob_name` | Incremental indexing |
| **File Format** | TOML configuration, JSON data | Universal format |
### Switch Version
```bash
```
# Switching 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 Index Data Automatic Sharing, No Migration Required
```
### Differences Explanation
| Feature | Python Version | Node.js Version |
|---------|----------------|------------------|
| **Runtime** | Python 3.10+ | Node.js 18.0+ |
| **Performance** | Good | Slightly faster (V8 engine) |
| **Memory Usage** | Moderate | 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 the 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 Reload)
npm run dev
# 4. Or start the development mode with a 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 reload | Development debugging |
| `npm start` | Run the 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 Standards
#### 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 name: PascalCase
class IndexManager {}
// Function: camelCase
function normalizePath() {}
// Constant: UPPER_SNAKE_CASE
const USER_CONFIG_DIR = '~/.acemcp';
// Interface: PascalCase + 'I' prefix (optional)
interface IConfig {}
```
#### Import Specification
```typescript
// ✅ Correct: ESM must include the .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 | `logger.exception('Error in tool', error)` |
#### Log Configuration
- **File Rotation** - Maximum single file size 5MB
- **Retention Count** - Most recent 10 log files
- **Console** - INFO level and above (non-stdio mode)
- **File** - DEBUG level and above
- **WebSocket** - Real-time broadcast to the web interface
### Adding a New Tool
```typescript
// 1. Create the 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 the 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
### Quick Reference for Common Issues
| Issue | Symptoms | Solutions |
|-------|----------|-----------|
| **Path does not exist** | `Project root path does not exist` | [Path Issues](#路径问题) |
| **API connection failed** | `Failed to connect to API` | [Connection Issues](#连接问题) |
| **Encoding error** | `UnsupportedEncoding` | [Encoding Issues](#编码问题) |
| **Port occupied** | `EADDRINUSE` | [Port Issues](#web-界面无法访问) |
| **Permission error** | `EACCES` | [Permission Issues](#权限问题) |
| **Upload failed** | Batch upload failed | [Upload Failure Handling](UPLOAD_FAILURE_HANDLING.md) |
| **Log file too large** | Logs taking up 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 Exists**
```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**
- Accessing WSL from Windows: `\\wsl$\Ubuntu\home\user\project` → Automatic conversion
- Accessing Windows from WSL: `/mnt/c/Users/username/project` → Automatic conversion
**Detailed Guides**:
- 📄 [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
```
#### Solution
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. **Temporarily 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.
#### Manually Specify Encoding (Not Supported Yet)
If you need support for other encodings, please submit an [Issue](https://github.com/yeuxuan/Ace-Mcp-Node/issues).
### Unable to Access Web Interface
#### Symptoms
```
Error: listen EADDRINUSE: address already in use :::8080
```
#### Solutions
1. **Check Port Occupation**
```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
```
#### Solution
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 Failure
#### 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 is 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
```
### Get Help
If the above methods do not resolve the issue:
1. **Check the 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 the reproduction steps
3. **Community Discussion**
- Join the [Discussions](https://github.com/yeuxuan/Ace-Mcp-Node/discussions)
---
## 🤝 Contribution
We welcome all forms of contribution!
### 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. Development and Testing
npm install
npm run dev
# Make modifications...
npm run build
npm test
# 4. Submit Changes
git add .
git commit -m "feat: add my feature"
# 5. Push and Create PR
```bash
git push origin feature/my-feature
gh pr create
```
### Code Standards
- Follow TypeScript strict mode
- Use ESLint and Prettier (if configured)
- Add appropriate comments and type definitions
- Maintain backward compatibility
### Commit Specification
Use [Conventional Commits](https://www.conventionalcommits.org/)：
```
feat: New feature
fix: Bug fix
docs: Documentation update
style: Code formatting
refactor: Refactoring
test: Testing related
chore: Build/tool related
```
## 📧 Contact Information
- **Author**: yihua
- **Email**: 487735913@qq.com
- **GitHub**: [@yeuxuan](https://github.com/yeuxuan)
- **Project Homepage**: https://github.com/yeuxuan/Ace-Mcp-Node
---
## 🙏 Acknowledgments
- Based on the design and implementation of [Acemcp-Python](https://github.com/yeuxuan/Ace-Mcp-Python)
- Thanks to the [Model Context Protocol](https://github.com/modelcontextprotocol) team
- Thanks to all contributors and users
## 🔗 Related 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 is helpful to you, please give it a Star! ⭐**
Made with ❤️ by [yihua](https://github.com/yeuxuan)
</div>
