Kfnzero Mantis MCP Server

🚀 Mantis 项目 Cobra 服务文档

本项目为 Mantis 项目的 Cobra 服务，提供了一系列与 Mantis API 交互的接口，可用于获取问题列表、详情、用户信息等，同时具备完善的配置、错误处理和日志记录机制。

🚀 快速开始

安装依赖

# 安装依赖
npm install

构建项目

# 构建
npm run build

启动服务

# 启动服务
npm start

✨ 主要特性

• 灵活配置：支持通过环境变量和 config.json 文件进行服务配置。
• 高阶函数处理：使用 withMantisConfigured 高阶函数处理通用检查逻辑。
• 完善的错误处理：包含 Mantis API 错误处理、通用错误处理和结构化错误响应。
• 丰富的 API 接口：提供获取问题列表、详情、用户信息、项目列表等多种接口。
• 详细的日志记录：记录服务运行和错误信息。

📦 安装指南

打包

npm run build && npm pack

安装

npm install mantis-cobra-service-0.1.0.tgz

配置示例

const withMantisConfigured = require('mantis-cobra-service');

const config = {
  apiUrl: 'https://your-mantis-url.com',
  username: 'admin',
  password: 'secret'
};

withMantisConfigured(config);

💻 使用示例

基础用法

以下是使用 get_issues 接口获取问题列表的示例：

// 假设已经完成配置
const { get_issues } = require('mantis-cobra-service');

// 调用接口
get_issues({
  projectId: 1,
  statusId: 2,
  pageSize: 10,
  page: 1
}).then((issues) => {
  console.log(issues);
}).catch((error) => {
  console.error(error);
});

高级用法

使用 get_issue_statistics 接口进行问题统计分析：

// 假设已经完成配置
const { get_issue_statistics } = require('mantis-cobra-service');

// 调用接口
get_issue_statistics({
  projectId: 1,
  groupBy: 'status',
  period: 'week'
}).then((statistics) => {
  console.log(statistics);
}).catch((error) => {
  console.error(error);
});

📚 详细文档

配置

环境变量配置

通过设置以下环境变量来配置服务：

• MANTIS_API_BASE_URL：Mantis API 的基础 URL（必填）
• MANTIS_USER：访问 Mantis API 的用户名（必填）
• MANTIS_PASSWORD：对应用户的密码（必填）
• PORT（默认值: 3000）：服务运行的端口
• ENV（可选，默认: production）：环境模式，支持 development 和 production

配置文件

也可以通过 config.json 文件进行配置：

{
  "mantis": {
    "apiUrl": "https://your-mantis-url.com",
    "username": "admin",
    "password": "secret"
  },
  "port": 3000,
  "env": "development"
}

高阶函数

服务使用 withMantisConfigured 高阶函数来处理通用的检查逻辑，确保：

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

错误处理

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

• Mantis API 错误处理（包含 HTTP 状态码）
• 通用错误处理
• 结构化的错误响应
• 资源使用情况的详细日志

代码结构

API 工具说明

服务提供了以下 API 接口：

1. 获取问题列表 (get_issues)

获取 Mantis 问题列表，可以根据多个条件进行过滤。 参数：

• projectId（可选）：项目 ID
• statusId（可选）：状态 ID
• handlerId（可选）：处理人 ID
• reporterId（可选）：报告者 ID
• search（可选）：搜索关键字
• pageSize（可选，默认 20）：页面大小
• page（可选，默认 0）：分页起始位置，从 1 开始
• select（可选）：返回的数据字段，例如：['id', 'summary', 'description']。可以用于减少返回数据量

2. 获取问题详情 (get_issue_by_id)

根据 ID 获取 Mantis 问题详情。 参数：

• issueId：问题 ID

3. 查询用户 (get_user)

根据用户名查询 Mantis 用户。 参数：

• username：用户名

4. 获取项目列表 (get_projects)

获取 Mantis 项目列表。 参数：无

5. 获取问题统计 (get_issue_statistics)

获取 Mantis 问题统计数据，可以根据不同维度进行分析。 参数：

• projectId（可选）：项目 ID
• groupBy：分组依据，可选值: 'status', 'priority', 'severity', 'handler', 'reporter'
• period（默认 'all'）：时间范围，可选值: 'all', 'today', 'week', 'month'

6. 获取分派统计 (get_assignment_statistics)

获取 Mantis 问题分派统计数据，分析不同用户的分派情况。 参数：

• projectId（可选）：项目 ID
• includeUnassigned（默认 true）：是否包含未分派的问题
• statusFilter（可选）：状态过滤器，只计算特定状态的问题

7. 获取所有用户 (get_users)

暴力方式获取所有用户列表。 参数：无

日志记录

日志输出格式如下：

time=2023-10-26T15:34:12.879Z level=INFO message="启动服务" port=3000 env=development
time=2023-10-26T15:34:13.000Z level=ERROR message="无法连接到 Mantis API" error="connection timeout"

🔧 技术细节

高阶函数 withMantisConfigured

该高阶函数封装了通用的检查逻辑，包括 Mantis API 配置检查、错误处理、响应格式标准化和日志记录，提高了代码的复用性和可维护性。

错误处理机制

通过捕获不同类型的错误，对 Mantis API 错误和通用错误进行分类处理，返回结构化的错误响应，并记录详细的日志，方便问题排查和定位。

API 接口设计

采用 RESTful 风格设计 API 接口，支持多种参数过滤和分页查询，满足不同场景的需求。

📄 附录

环境变量列表

常见问题

如何处理认证失败？

• 检查用户名和密码是否正确。
• 确保环境变量或配置文件中的凭据无误。

无法连接到 API？

• 检查网络连接。
• 确认 API 服务是否正常运行。