金大哥 - kfnzero_mantis-mcp-server MCP 详情

article

README

🚀 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 接口，支持多种参数过滤和分页查询，满足不同场景的需求。

📄 附录

环境变量列表

| 环境变量名称 | 描述 | 必填 | |--------------|------|------| | MANTIS_API_BASE_URL | Mantis API 的基础 URL | 是 | | MANTIS_USER | 访问 API 的用户名 | 是 | | MANTIS_PASSWORD | 对应用户的密码 | 是 |

kfnzero_mantis-mcp-server