MCP-Zentao

Una integración de API para el sistema de gestión de proyectos Zent

Documentación

MCP-Zentao

Paquete de integración de API de alto nivel para el sistema de gestión de proyectos Zentao, que proporciona una encapsulación completa de funciones como gestión de tareas y seguimiento de errores, diseñado como extensión MCP para Cursor IDE.

Instalación

npm install @bigtian/mcp-zentao -g

Uso

Primer uso (configuración de la información de Zentao)

En el primer uso, es necesario proporcionar la información de configuración de Zentao:

zentao '{"config":{"url":"https://your-zentao-url","username":"your-username","password":"your-password","apiVersion":"v1"},"name":"张三","age":25,"skills":["编程","设计"]}'

La información de configuración se guarda en el archivo .zentao/config.json en el directorio del usuario, y no es necesario volver a proporcionarla en usos posteriores.

Uso posterior

Una vez completada la configuración, solo es necesario proporcionar la información relacionada con las tareas:

zentao '{"name":"张三","age":25,"skills":["编程","设计"]}'

Actualizar configuración

Si necesita actualizar la información de configuración de Zentao, solo tiene que volver a proporcionar el parámetro config:

zentao '{"config":{"url":"https://new-zentao-url","username":"new-username","password":"new-password","apiVersion":"v1"},"name":"张三","age":25,"skills":["编程","设计"]}'

Ubicación del archivo de configuración

El archivo de configuración se guarda en el archivo .zentao/config.json en el directorio del usuario:

Windows: C:\Users\你的用户名\.zentao\config.json
macOS/Linux: ~/.zentao/config.json

Características

Almacenamiento persistente de la información de configuración
Gestión automática de la información de autenticación de la API de Zentao
Funciones de creación, actualización y finalización de tareas
Seguimiento y gestión de errores (bugs)
Soporte completo de definiciones de tipos

Notas

El archivo de configuración contiene información sensible; asegúrese de que los permisos del archivo estén configurados correctamente
Se recomienda actualizar la contraseña periódicamente para garantizar la seguridad
Si encuentra problemas, puede eliminar el archivo de configuración y volver a configurarlo

Licencia

MIT

Características destacadas

Encapsulación completa de la API de Zentao
Diseño de interfaz simple y fácil de usar
Seguridad de tipos (soporte de TypeScript)
Manejo de errores completo
Gestión de autenticación automatizada

Diferencias con otros proyectos

A diferencia de las herramientas genéricas de operación de bases de datos (como mcp-mysql-server), este proyecto se centra en proporcionar:

Funciones de negocio específicas del sistema Zentao
Abstracción de API de alto nivel
Soporte completo del flujo de trabajo de Zentao
Solución de integración de Zentao lista para usar

Desarrollo local

Clonar el repositorio

git clone https://github.com/bigtian/mcp-zentao.git
cd mcp-zentao

Instalar dependencias

npm install

Ejecutar pruebas

npm test

Compilar el proyecto

npm run build

Uso con Docker

Uso con docker-compose (recomendado)

Copiar la plantilla de variables de entorno y modificar la configuración

cp .env.example .env
# 编辑 .env 文件，填入你的禅道系统配置

Iniciar el servicio

docker-compose up -d

Ver los registros

docker-compose logs -f

Uso manual de Docker

Construir la imagen

docker build -t mcp-zentao .

Ejecutar el contenedor

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

Configuración en Cursor IDE

Agregue la siguiente configuración en el archivo de configuración de Cursor IDE:

{
  "mcpServers": {
    "zentao": {
      "url": "http://localhost:3000"
    }
  }
}

Uso básico

import { ZentaoAPI } from '@bigtian/mcp-zentao';

// 创建API实例
const api = new ZentaoAPI({
    url: 'https://your-zentao-url',  // 你的禅道系统URL
    username: 'your-username',        // 用户名
    password: 'your-password',        // 密码
    apiVersion: 'v1'                 // API版本，默认为v1
});

// 获取我的任务列表
async function getMyTasks() {
    try {
        const tasks = await api.getMyTasks();
        console.log('我的任务:', tasks);
    } catch (error) {
        console.error('获取任务失败:', error);
    }
}

// 获取我的Bug列表
async function getMyBugs() {
    try {
        const bugs = await api.getMyBugs();
        console.log('我的Bug:', bugs);
    } catch (error) {
        console.error('获取Bug失败:', error);
    }
}

// 完成任务
async function finishTask(taskId: number) {
    try {
        await api.finishTask(taskId);
        console.log('任务已完成');
    } catch (error) {
        console.error('完成任务失败:', error);
    }
}

// 解决Bug
async function resolveBug(bugId: number) {
    try {
        await api.resolveBug(bugId, {
            resolution: 'fixed',
            resolvedBuild: 'trunk',
            comment: '问题已修复'
        });
        console.log('Bug已解决');
    } catch (error) {
        console.error('解决Bug失败:', error);
    }
}

Documentación de la API

Clase ZentaoAPI

Constructor

constructor(config: {
    url: string;          // 禅道系统URL
    username: string;     // 用户名
    password: string;     // 密码
    apiVersion?: string;  // API版本，默认为v1
})

Métodos

getMyTasks(): Promise<Task[]>
- Obtener la lista de tareas del usuario actual
- Devuelve: Promise<Task[]>
getMyBugs(): Promise<Bug[]>
- Obtener la lista de errores (bugs) del usuario actual
- Devuelve: Promise<Bug[]>
finishTask(taskId: number): Promise<void>
- Completar la tarea con el ID especificado
- Parámetros: taskId - ID de la tarea
- Devuelve: Promise
resolveBug(bugId: number, resolution: BugResolution): Promise<void>
- Resolver el error (bug) con el ID especificado
- Parámetros:
  - bugId - ID del error (bug)
  - resolution - Solución del error (bug)
- Devuelve: Promise

Definiciones de tipos

interface Task {
    id: number;
    name: string;
    status: string;
    pri: number;
    // ... 其他任务属性
}

interface Bug {
    id: number;
    title: string;
    status: string;
    severity: number;
    // ... 其他Bug属性
}

interface BugResolution {
    resolution: string;      // 解决方案类型
    resolvedBuild?: string; // 解决版本
    duplicateBug?: number;  // 重复Bug ID
    comment?: string;       // 备注
}

Notas

Asegúrese de proporcionar la URL correcta del sistema Zentao y la versión de la API
El nombre de usuario y la contraseña deben tener los permisos de acceso a la API correspondientes
Todas las llamadas a la API son asíncronas; deben manejarse con async/await o Promise
Se recomienda capturar los errores con try/catch

Entorno de desarrollo

Node.js >= 14.0.0
TypeScript >= 4.0.0

Contribuciones

¡Bienvenidos a enviar Issues y Pull Requests!