Mantis MCP Server

🚀 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/