🚀 Mantis MCP 服务器

Mantis MCP 服务器是用于 Mantis 问题跟踪系统的服务器，提供了项目管理、问题处理等功能，支持配置化管理和多种操作模式，同时具备完善的错误处理机制。

🚀 快速开始

安装依赖

npm install

构建

npm run build

开发模式（监视变更）

npm run watch

运行

npm start

📦 安装指南

本地安装

npm install mantis-mcp-server --save

全局安装

npm install -g mantis-mcp-server

创建新项目

npx mantis-mcp-server init my-project
cd my-project && npm install

更新

从 npm 更新

npm update mantis-mcp-server

卸载

npm uninstall mantis-mcp-server

💻 使用示例

基础用法

创建新项目

import { createServer } from 'mantis-mcp-server'

const server = createServer({
    mantis: {
        url: 'http://your-mantis-server.com',
        username: 'admin', // Mantis 管理员账户名
        password: 'password' // Mantis 管理员密码
    },
    log: {
        level: 'info', // 日志级别：debug, info, warning, error
        dir: './logs/' // 日志文件存储目录
    }
})

server.listen(3000, () => {
    console.log('服务器已启动在 http://localhost:3000')
})

高级用法

配置

{
    "name": "mantis-mcp-server",
    "version": "1.0.0",
    "description": "Mantis 问题跟踪系统 MCP 服务器",
    "main": "dist/index.js",
    "scripts": {
        "start": "node dist/index.js",
        "build": "webpack --config webpack.config.js"
    },
    "dependencies": {
        "express": "^4.18.2",
        "axios": "^1.5.0",
        "lodash": "^4.17.15",
        "moment": "^2.29.1"
    }
}

📚 详细文档

配置文件示例

module.exports = {
    mantis: {
        url: 'http://your-mantis-server.com',
        username: 'admin', // Mantis 管理员账户名
        password: 'password' // Mantis 管理员密码
    },
    log: {
        level: 'info', // 日志级别：debug, info, warning, error
        dir: './logs/' // 日志文件存储目录
    },
    pages: {
        pageSize: 20, // 默认每页大小
        defaultPage: 1 // 默认起始页码
    }
}

高阶函数

withMantisConfigured

该高阶函数用于处理公共的验证逻辑，确保：

• Mantis API 配置检查
• 统一错误处理
• 标准化响应格式
• 自动日志记录

错误处理

完整的错误处理机制包括：

• Mantis API 错误处理（包含 HTTP 状态码）
• 通用错误处理
• 结构化错误响应
• 详细错误日志记录

代码结构

目录结构

src/
├── config/                 # 配置文件夹
│   ├── mantis.config.ts    # Mantis 服务器配置
│   └── log.config.ts      # 日志配置
├── services/               # 服务模块
│   ├── issue.service.ts    # 问题处理逻辑
│   ├── user.service.ts     # 用户处理逻辑
│   └── project.service.ts  # 项目处理逻辑
├── controllers/           # 控制器层
│   ├── issue.controller.ts # 问题接口定义
│   ├── user.controller.ts  # 用户接口定义
│   └── project.controller.ts # 项目接口定义
└── utils/                 # 工具函数
    ├── logger.ts          # 日志工具
    └── errorHandling.ts   # 错误处理工具

命令行工具

安装 CLI

npm install -g mantis-mcp-cli

使用 CLI

mantis-mcp --version # 查看版本号
mantis-mcp help # 显示帮助信息

API 工具说明

getIssues

获取问题列表。

参数

• projectId (number): 项目 ID
• pageIndex (number): 当前页码，默认为 1
• pageSize (number): 每页大小，默认为 20

返回

{
    issues: Array<Issue>, // 问题列表
    totalPages: number,   // 总页数
    totalItems: number   // 总记录数
}

getIssue

获取单个问题。

参数

• issueId (number): 问题 ID

返回

{
    id: number,       // 问题 ID
    title: string,    // 问题标题
    description: string, // 问题描述
    status: string,   // 问题状态
    priority: string, // 问题优先级
    assignee: string, // 负责人
    reporter: string  // 报告人
}

createIssue

创建新问题。

参数

{
    title: string,       // 必填，问题标题
    description: string, // 可选，问题描述
    projectId: number,   // 必填，项目 ID
    status: string,      // 可选，默认为 'new'
    priority: string,    // 可选，默认为 'normal'
    assignee: string     // 可选，默认为空
}

返回

{
    id: number         // 新创建的问题 ID
}

updateIssue

更新问题。

参数

{
    issueId: number,   // 必填，问题 ID
    title?: string,    // 可选，新标题
    description?: string, // 可选，新描述
    status?: string,   // 可选，新状态
    priority?: string, // 可选，新优先级
    assignee?: string  // 可选，新负责人
}

deleteIssue

删除问题。

参数

• issueId (number): 必填，问题 ID

错误处理

所有 API 调用返回标准的 HTTP 状态码：

• 成功：200 OK
• 创建成功：201 Created
• 更新成功：204 No Content
• 删除成功：204 No Content
• 失败：4xx 或 5xx 错误状态码

错误响应格式：

{
    code: number,     // 错误代码
    message: string   // 错误信息
}

🔧 技术细节

日志

如果启用了文件日志记录 (ENABLE_FILE_LOGGING=true)，日志文件将保存在：

• logs/mantis-mcp-server-combined.log: 所有级别的日志
• logs/mantis-mcp-server-error.log: 仅错误级别的日志

日志文件大小上限为 5MB，最多保留 5 个历史文件。

📄 许可证

MIT License

贡献指南

欢迎 Fork 和 Pull Request！

⚠️ 重要提示

1. 所有 API 调用都需要有效的认证令牌。
2. 更新和删除操作需要额外的权限验证。
3. 请确保服务器时间与 Mantis 时间同步，以避免时钟偏移问题。

参考

@ https://documentazione.it-mantis.com/zh-CN/