Kfnzero Mantis MCP Server

🚀 Mantis 項目 Cobra 服務文檔

Cobra 服務是 Mantis 項目的重要組成部分，它提供了一系列 API 接口，用於與 Mantis 系統進行交互，如獲取問題列表、問題詳情、用戶信息等。同時，具備完善的配置、錯誤處理和日誌記錄機制，方便開發和維護。

🚀 快速開始

環境準備

在開始使用 Cobra 服務之前，需要進行環境配置。可以通過環境變量或配置文件兩種方式進行配置。

環境變量配置

通過設置以下環境變量來配置服務：

• 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"
}

啟動服務

完成配置後，按照以下步驟啟動服務：

# 安裝依賴
npm install

# 構建
npm run build

# 啟動服務
npm start

✨ 主要特性

高階函數處理

服務使用 withMantisConfigured 高階函數來處理通用的檢查邏輯，確保：

• Mantis API 配置檢查
• 統一的錯誤處理
• 標準化的響應格式
• 自動的日誌記錄

完善的錯誤處理

完善的錯誤處理機制包括：

• Mantis API 錯誤處理（包含 HTTP 狀態碼）
• 通用錯誤處理
• 結構化的錯誤響應
• 資源使用情況的詳細日誌

📦 安裝指南

打包

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);

💻 使用示例

基礎用法

以下是使用 Cobra 服務 API 接口的基礎示例：

// 獲取問題列表
const { get_issues } = require('mantis-cobra-service');

const params = {
  projectId: 1,
  statusId: 2,
  pageSize: 10,
  page: 1
};

get_issues(params)
 .then(issues => {
    console.log(issues);
  })
 .catch(error => {
    console.error(error);
  });

高級用法

根據不同的業務需求，可以組合使用多個 API 接口，實現更復雜的功能。例如，先獲取項目列表，再根據項目 ID 獲取該項目下的問題列表：

const { get_projects, get_issues } = require('mantis-cobra-service');

// 獲取項目列表
get_projects()
 .then(projects => {
    const projectId = projects[0].id;

    // 根據項目 ID 獲取問題列表
    const params = {
      projectId: projectId,
      pageSize: 10,
      page: 1
    };

    return get_issues(params);
  })
 .then(issues => {
    console.log(issues);
  })
 .catch(error => {
    console.error(error);
  });

📚 詳細文檔

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)

暴力方式獲取所有用戶列表。 參數： 無

🔧 技術細節

代碼結構

Cobra 服務的代碼結構清晰，主要圍繞 API 接口的實現和相關工具函數的封裝。通過模塊化的設計，提高了代碼的可維護性和可擴展性。

日誌記錄

日誌輸出格式如下：

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"

📄 許可證

文檔中未提及許可證相關信息。

附錄

環境變量列表

常見問題

1. 如何處理認證失敗？

   • 檢查用戶名和密碼是否正確。
   • 確保環境變量或配置文件中的憑據無誤。

2. 無法連接到 API？

   • 檢查網絡連接。
   • 確認 API 服務是否正常運行。