Content
# MCP-Zentao
An advanced API integration package for Zentao project management system, providing complete encapsulation of task management, bug tracking and other functions, specifically designed for Cursor IDE.
## Installation
```bash
npm install @bigtian/mcp-zentao -g
```
## Usage
### First Use (Configure Zentao Information)
When using for the first time, you need to provide Zentao configuration information:
```bash
zentao '{"config":{"url":"https://your-zentao-url","username":"your-username","password":"your-password","apiVersion":"v1"},"name":"John Doe","age":25,"skills":["Programming","Design"]}'
```
The configuration information will be saved in the `.zentao/config.json` file under the user's directory, and there is no need to provide it again for subsequent use.
### Subsequent Use
After configuration, you only need to provide task-related information:
```bash
zentao '{"name":"John Doe","age":25,"skills":["Programming","Design"]}'
```
### Update Configuration
If you need to update Zentao configuration information, you only need to provide the `config` parameter again:
```bash
zentao '{"config":{"url":"https://new-zentao-url","username":"new-username","password":"new-password","apiVersion":"v1"},"name":"John Doe","age":25,"skills":["Programming","Design"]}'
```
## Configuration File Location
The configuration file is saved in the `.zentao/config.json` file under the user's directory:
- Windows: `C:\Users\YourUsername\.zentao\config.json`
- macOS/Linux: `~/.zentao/config.json`
## Features
- Support for persistent storage of configuration information
- Automatic management of Zentao API authentication information
- Provide task creation, update, completion and other functions
- Support bug tracking and processing
- Complete type definition support
## Precautions
- The configuration file contains sensitive information, please ensure that the file permissions are set correctly
- It is recommended to update the password regularly to ensure security
- If you encounter problems, you can delete the configuration file and reconfigure
## License
MIT
## Characteristics
- Complete Zentao API encapsulation
- Simple and easy-to-use interface design
- Type safety (TypeScript support)
- Complete error handling
- Automated authentication management
## Differences from Other Projects
Unlike general database operation tools (such as `mcp-mysql-server`), this project focuses on providing:
1. Zentao system-specific business functions
2. High-level API abstraction
3. Complete Zentao workflow support
4. Out-of-the-box Zentao integration solution
## Local Development
1. Clone the repository
```bash
git clone https://github.com/bigtian/mcp-zentao.git
cd mcp-zentao
```
2. Install dependencies
```bash
npm install
```
3. Run tests
```bash
npm test
```
4. Build the project
```bash
npm run build
```
## Docker Usage
### Use docker-compose (Recommended)
1. Copy environment variable template and modify configuration
```bash
cp .env.example .env
# Edit .env file and fill in your Zentao system configuration
```
2. Start service
```bash
docker-compose up -d
```
3. View logs
```bash
docker-compose logs -f
```
### Manual Use Docker
1. Build image
```bash
docker build -t mcp-zentao .
```
2. Run container
```bash
docker run -d \
--name mcp-zentao \
-p 3000:3000 \
-e ZENTAO_URL=your-zentao-url \
-e ZENTAO_USERNAME=your-username \
-e ZENTAO_PASSWORD=your-password \
-e ZENTAO_API_VERSION=v1 \
-v $(pwd)/logs:/app/logs \
mcp-zentao
```
### Configure in Cursor IDE
Add the following configuration to the configuration file of Cursor IDE:
```json
{
"mcpServers": {
"zentao": {
"url": "http://localhost:3000"
}
}
}
```
## Basic Usage
```typescript
import { ZentaoAPI } from '@bigtian/mcp-zentao';
// Create API instance
const api = new ZentaoAPI({
url: 'https://your-zentao-url', // Your Zentao system URL
username: 'your-username', // Username
password: 'your-password', // Password
apiVersion: 'v1' // API version, default is v1
});
// Get my task list
async function getMyTasks() {
try {
const tasks = await api.getMyTasks();
console.log('My tasks:', tasks);
} catch (error) {
console.error('Failed to get tasks:', error);
}
}
// Get my bug list
async function getMyBugs() {
try {
const bugs = await api.getMyBugs();
console.log('My bugs:', bugs);
} catch (error) {
console.error('Failed to get bugs:', error);
}
}
// Complete task
async function finishTask(taskId: number) {
try {
await api.finishTask(taskId);
console.log('Task completed');
} catch (error) {
console.error('Failed to complete task:', error);
}
}
// Resolve bug
async function resolveBug(bugId: number) {
try {
await api.resolveBug(bugId, {
resolution: 'fixed',
resolvedBuild: 'trunk',
comment: 'Issue resolved'
});
console.log('Bug resolved');
} catch (error) {
console.error('Failed to resolve bug:', error);
}
}
```
## API Documentation
### ZentaoAPI Class
#### Constructor
```typescript
constructor(config: {
url: string; // Zentao system URL
username: string; // Username
password: string; // Password
apiVersion?: string; // API version, default is v1
})
```
#### Methods
1. `getMyTasks(): Promise<Task[]>`
- Get the task list of the current user
- Return: Promise<Task[]>
2. `getMyBugs(): Promise<Bug[]>`
- Get the bug list of the current user
- Return: Promise<Bug[]>
3. `finishTask(taskId: number): Promise<void>`
- Complete the task with the specified ID
- Parameter: taskId - Task ID
- Return: Promise<void>
4. `resolveBug(bugId: number, resolution: BugResolution): Promise<void>`
- Resolve the bug with the specified ID
- Parameter:
- bugId - Bug ID
- resolution - Bug resolution
- Return: Promise<void>
### Type Definitions
```typescript
interface Task {
id: number;
name: string;
status: string;
pri: number;
// ... Other task properties
}
interface Bug {
id: number;
title: string;
status: string;
severity: number;
// ... Other bug properties
}
interface BugResolution {
resolution: string; // Resolution type
resolvedBuild?: string; // Resolved version
duplicateBug?: number; // Duplicate bug ID
comment?: string; // Remark
}
```
## Precautions
1. Ensure that the correct Zentao system URL and API version are provided
2. The username and password need to have corresponding API access permissions
3. All API calls are asynchronous and need to be processed using async/await or Promise
4. Error handling is recommended to use try/catch for capture
## Development Environment
- Node.js >= 14.0.0
- TypeScript >= 4.0.0
## Contribution
Welcome to submit issues and pull requests!
