🚀 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 # 错误处理工具
日志
如果启用了文件日志记录 (ENABLE_FILE_LOGGING=true)，日志文件将保存在：
logs/mantis-mcp-server-combined.log：所有级别的日志logs/mantis-mcp-server-error.log：仅错误级别的日志
日志文件大小上限为 5MB，最多保留 5 个历史文件。
命令行工具
安装 CLI
npm install -g mantis-mcp-cli
使用 CLI
mantis-mcp --version # 查看版本号
mantis-mcp help # 显示帮助信息
🔧 技术细节
API 工具说明
getIssues
获取问题列表。
参数
projectId(number)：项目 IDpageIndex(number)：当前页码，默认为 1pageSize(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 // 错误信息
}
📄 许可证
MIT License
参考
@ https://documentazione.it-mantis.com/zh-CN/
贡献指南
欢迎 Fork 和 Pull Request！
⚠️ 重要提示
- 所有 API 调用都需要有效的认证令牌。
- 更新和删除操作需要额外的权限验证。
- 请确保服务器时间与 Mantis 时间同步，以避免时钟偏移问题。