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)
- [Usage Guide](#-usage-guide)
- [MCP Client Configuration](#configuring-in-mcp-client)
- [Tool Description](#-tool-description)
- [Web Management Interface](#-web-management-interface)
- [WSL Support](#-wsl-path-support-complete-guide)
- [API Documentation](#-api-documentation)
- [Example Scenarios](#-example-usage-scenarios)
- [Development Guide](#-development)
- [Troubleshooting](#-troubleshooting)
- [Compatibility](#-compatibility-with-python-versions)
- [Contribution](#-contribution)
- [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.). Through Acemcp, AI assistants can:
- 🔍 Quickly search and understand large codebases
- 📊 Obtain 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 indexes 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 hashing avoids duplicate uploads
</td>
<td width="50%">
### 🛠 Developer Friendly
- ✅ **TypeScript** - Full 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** - Uniformly handles Windows/Unix paths
- ✅ **Full WSL Support** - UNC paths, /mnt automatic conversion
- ✅ **Multi-Encoding Support** - UTF-8, GBK, GB2312, Latin-1
- ✅ **Python Version Compatibility** - Shared configuration and data formats
</td>
<td width="50%">
### 🎯 MCP Integration
- ✅ **Standard MCP Protocol** - Complete SDK implementation
- ✅ **search_context Tool** - Semantic search for code snippets
- ✅ **stdio Transmission** - Standard input/output communication
- ✅ **Flexible Configuration** - Command-line parameters + configuration file
</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
npm run build
```
### First Run
```bash
# Start the server (configuration file will be created on first run)
npm start
# Or start with the 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 Clients)
```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
On the first run, 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
```
#### 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 number of lines per code block
# === File Type Configuration ===
# Supported text file extensions for indexing
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 artifacts
"dist", "build", "target", "out",
# IDE configuration
".idea", ".vscode", ".vs",
# System files
".DS_Store", "Thumbs.db",
# Compiled files
"*.pyc", "*.pyo", "*.pyd", "*.so", "*.dll"
]
```
#### Command-Line Argument Overrides
```bash
# Temporarily use different API configuration
npm start -- --base-url https://custom-api.com --token custom-token
# Customize batch size
npm start -- --batch-size 20
# Start the Web interface on a specified port
npm start -- --web-port 3000
# Use in combination
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 via 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
```
---
## 🔧 WSL Path Support Complete Guide
Acemcp-Node provides **complete path support** for WSL (Windows Subsystem for Linux) without manual path format conversion.
### Supported Path Formats
| Path Type | Original Format | Automatically Converted To | Usage Scenario |
|---------|---------|-----------|---------|
| **Windows Local** | `C:\Users\username\project` | `C:/Users/username/project` | Projects on Windows |
| **WSL Internal** | `/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 from WSL ⭐ |
| **Windows Accessing WSL** | `\\wsl$\Ubuntu\home\user\project` | `/home/user/project` | Accessing WSL files from Windows ⭐ |
### 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** - Uniformly uses forward slashes `/`
- ✅ **Trailing Slash Removal** - Automatically removes trailing `/` or `\` from paths
- ✅ **UNC Path Conversion** - Automatically recognizes and converts `\\wsl$\` format
- ✅ **/mnt Conversion** - Automatically converts `/mnt/c/` to `C:/`
### Troubleshooting
If you encounter path issues, please refer to:
- 📄 [WSL Path Support Guide](WSL_PATH_GUIDE.md) - Guide specific to the WSL environment
- 📄 [Path Troubleshooting Guide](PATH_TROUBLESHOOTING.md) - Detailed diagnosis of path issues
---
## 🔌 Configuring in 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 the Globally Installed Package
```json
{
"mcpServers": {
"acemcp": {
"command": "npx",
"args": ["acemcp-node"],
"env": {}
}
}
}
```
#### Method 2: Specifying a 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 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.
### Verify Configuration
After configuration:
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
Performs a **semantic search** in the project codebase, automatically performs incremental indexing, and returns relevant code snippets.
#### Parameters
| Parameter | Type | Required | Description | Example |
|------|------|------|------|------|
| `project_root_path` | string | ✅ | **Absolute path** to the project root directory, using forward slashes `/` | `C:/Users/username/myproject` |
| `query` | string | ✅ | Natural language search query | `"authentication middleware"` |
#### Functionality Flow
```
1. Receive search request
↓
2. Check project index status
↓
3. Perform incremental indexing (only new/modified files)
├─ Collect files (following .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 results
}
```
**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 for authentication logic
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "C:/Users/username/myproject",
"query": "user authentication and JWT token verification"
}
}
```
##### Example 2: Search for database configuration
```json
{
"tool": "search_context",
"arguments": {
"project_root_path": "/home/user/backend-api",
"query": "database connection pool configuration"
}
}
```
##### Example 3: Search 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 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 |
---
## 💡 Usage Scenario 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 obtains authentication-related code, understands the implementation method, and provides review suggestions
```
### Scenario 2: Bug Debugging
**Requirement**: Locate error handling in 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 identify 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 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 route structure and implement new endpoints according to the existing pattern
```
### Scenario 4: Documentation Generation
**Requirement**: Generate documentation for utility functions
```
User: @acemcp 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: Get all utility functions and automatically generate JSDoc/TSDoc documentation
```
### Scenario 5: Code Refactoring
**Requirement**: Find all places using the old API
```
User: @acemcp We want to deprecate 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 a 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** | Real-time display of running status, number of indexed projects, and 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 problem 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
- Colored log level identification (DEBUG/INFO/WARNING/ERROR)
- Automatic 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 return result.
### Security Recommendations
⚠️ **Important**: The Web interface is **only bound to localhost** and is not open to the external network.
To access remotely:
1. Use SSH tunneling: `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 # 📝 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 processing
│ │ └── 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/ # 📦 Compilation 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 last 10
```
---
## 🔄 Compatibility with Python Version
Acemcp-Node is **fully compatible** with [Acemcp-Python](https://github.com/yeuxuan/Ace-Mcp-Python) and can be switched seamlessly.
| Compatibility Item | Description | Location |
|--------|------|------|
| **Configuration File** | Share the same `settings.toml` | `~/.acemcp/settings.toml` |
| **Project Data** | Share project index metadata | `~/.acemcp/data/projects.json` |
| **API Interface** | Call the same indexing and search API | `BASE_URL` configuration |
| **Hash Algorithm** | Use the same SHA-256 to calculate `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 file and index data are automatically shared, no migration required
```
### 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 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 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 reload | 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 checking
- **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 trace | `logger.exception('Error in tool', error)` |
#### Log Configuration
- **File Rotation** - Maximum 5MB per file
- **Retention Count** - Last 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 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 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
### Common Issues Quick Reference
| Issue | Symptom | Solution |
|------|------|---------|
| **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 in Use** | `EADDRINUSE` | [Port Issues](#web-interface-unavailable) |
| **Permission Error** | `EACCES` | [Permission Issues](#permission-issues) |
| **Upload Failed** | Batch upload failed | [Upload Failure Handling](UPLOAD_FAILURE_HANDLING.md) |
| **Log File Too Large** | Log occupies too much space | [Log Rotation Configuration](LOG_ROTATION_CONFIG.md) |
| **WSL Path** | Path conversion failed | [WSL Guide](WSL_PATH_GUIDE.md) |
### Path Issues
#### Symptom
```
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 Paths**
```json
{
"project_root_path": "C:/Users/username/myproject" // ✅ Absolute path
}
```
4. **WSL Special Cases**
- Windows accessing WSL: `\\wsl$\Ubuntu\home\user\project` → Auto-conversion
- WSL accessing Windows: `/mnt/c/Users/username/project` → Auto-conversion
**Detailed Guides**:
- 📄 [Path Troubleshooting Guide](PATH_TROUBLESHOOTING.md)
- 📄 [WSL Path Support Guide](WSL_PATH_GUIDE.md)
### Connection Issues
#### Symptom
```
Error: Failed to connect to API: https://api.example.com
```
#### Solution
1. **Check Configuration File**
```bash
cat ~/.acemcp/settings.toml
```
2. **Verify API Reachability**
```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
#### Symptom
```
Warning: Failed to read file with UTF-8, trying alternative encodings
```
#### Explanation
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)
To support other encodings, please submit an [Issue](https://github.com/yeuxuan/Ace-Mcp-Node/issues).
### Web Interface Unavailable
#### Symptom
```
Error: listen EADDRINUSE: address already in use :::8080
```
#### Solution
1. **Check Port Usage**
```bash
# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F
# Linux/macOS
lsof -i :8080
kill -9 <PID>
```
2. **Use a Different 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
#### Symptom
```
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 Failed
#### Symptom
```
Error: Failed to index project: timeout
```
#### Solution
1. **Check Project Size**
```bash
du -sh /path/to/project
```
2. **Increase Batch Size** (settings.toml)
```toml
BATCH_SIZE = 20 # Default 10, can increase 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 the above methods do not solve the problem:
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 the steps to reproduce
3. **Community Discussion**
- Participate in [Discussions](https://github.com/yeuxuan/Ace-Mcp-Node/discussions)
---
## 🤝 Contributing
We welcome contributions of all kinds!
### 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** - Fix 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 appropriate comments and type definitions
- Maintain backward compatibility
### Commit Conventions
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
---
## 🙏 Acknowledgements
- 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 Tracking**: 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>
