README.md•7.92 kB
# Mantis MCP Server
[](https://smithery.ai/server/@kfnzero/mantis-mcp-server)
Mantis MCP Server 是一個基於 Model Context Protocol (MCP) 的服務，用於與 Mantis Bug Tracker 系統進行集成。它提供了一系列工具，允許用戶通過 MCP 協議查詢和分析 Mantis 系統中的數據。
<a href="https://glama.ai/mcp/servers/@kfnzero/mantis-mcp-server">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@kfnzero/mantis-mcp-server/badge" alt="Mantis Server MCP server" />
</a>
## 功能
- 問題管理
- 獲取問題列表（支持多種過濾條件）
- 根據 ID 查詢問題詳情
- 用戶管理
- 根據用戶名稱查詢用戶
- 獲取所有用戶列表
- 專案管理
- 獲取專案列表
- 統計分析
- 問題統計（支持多維度分析）
- 分派統計（分析問題分派情況）
- 效能優化
- 欄位選擇（減少回傳資料量）
- 分頁處理（控制每次返回數量）
- 自動資料壓縮（大量資料時自動壓縮）
- 完整的錯誤處理和日誌記錄
## 安裝
### Installing via Smithery
To install Mantis Bug Tracker Integration for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@kfnzero/mantis-mcp-server):
```bash
npx -y @smithery/cli install @kfnzero/mantis-mcp-server --client claude
```
### Manual Installation
```bash
npm install mantis-mcp-server
```
## 配置
1. 在專案根目錄建立 `.env` 文件：
```bash
# Mantis API 配置
MANTIS_API_URL=https://your-mantis-instance.com/api/rest
MANTIS_API_KEY=your_api_key_here
# 應用配置
NODE_ENV=development # development, production, test
LOG_LEVEL=info # error, warn, info, debug
# 快取配置
CACHE_ENABLED=true
CACHE_TTL_SECONDS=300 # 5分鐘
# 日誌配置
LOG_DIR=logs
ENABLE_FILE_LOGGING=false
```
### MantisBT API Key 獲取方式
1. 登入您的 MantisBT 帳戶
2. 點擊右上角的用戶名稱，選擇「我的帳戶」
3. 切換到「API 令牌」標籤
4. 點擊「創建新令牌」按鈕
5. 輸入令牌名稱（例如：MCP Server）
6. 複製生成的 API 令牌，並將其貼入 `.env` 文件的 `MANTIS_API_KEY` 設置中
## MCP 配置
### 全域安裝
首先，需要全域安裝 mantis-mcp-server：
```bash
npm install -g mantis-mcp-server
```
### Windows 配置
在 Windows 系統中，編輯 `%USERPROFILE%\.cursor\mcp.json`（通常在 `C:\Users\你的用戶名\.cursor\mcp.json`），添加以下配置：
```json
{
"mcpServers": {
"mantis-mcp-server": {
"type": "stdio",
"command": "cmd",
"args": [
"/c",
"node",
"%APPDATA%\\npm\\node_modules\\mantis-mcp-server\\dist\\index.js"
],
"env": {
"MANTIS_API_URL": "YOUR_MANTIS_API_URL",
"MANTIS_API_KEY": "YOUR_MANTIS_API_KEY",
"NODE_ENV": "production",
"LOG_LEVEL": "info"
}
}
}
}
```
### macOS/Linux 配置
在 macOS 或 Linux 系統中，編輯 `~/.cursor/mcp.json`，添加以下配置：
```json
{
"mcpServers": {
"mantis-mcp-server": {
"command": "npx",
"args": [
"-y",
"mantis-mcp-server@latest",
],
"env": {
"MANTIS_API_URL": "YOUR_MANTIS_API_URL",
"MANTIS_API_KEY": "YOUR_MANTIS_API_KEY",
"NODE_ENV": "production",
"LOG_LEVEL": "info"
}
}
}
}
```
> 注意：在 macOS/Linux 中，我們使用 npx 來運行最新版本的 mantis-mcp-server，這樣可以確保始終使用最新版本，不需要全域安裝。
### 環境變數說明
- `MANTIS_API_URL`: 您的 Mantis API URL
- `MANTIS_API_KEY`: 您的 Mantis API 金鑰
- `NODE_ENV`: 執行環境，建議設置為 "production"
- `LOG_LEVEL`: 日誌級別，可選值：error、warn、info、debug
### 驗證配置
配置完成後，您可以：
1. 重新載入 Cursor MCP
2. 開啟命令面板（Windows: Ctrl+Shift+P, Mac: Cmd+Shift+P）
## 在 Cursor 中設定
1. 在 `.vscode/mcp.json` 中添加以下配置：
```json
{
"servers": {
"mantis-mcp-server": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"]
}
}
}
```
2. 在 `.vscode/launch.json` 中添加以下配置用於除錯：
```json
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug MCP Server",
"skipFiles": ["<node_internals>/**"],
"outFiles": ["${workspaceFolder}/dist/**/*.js"],
"runtimeExecutable": "npx",
"runtimeArgs": [
"-y",
"@modelcontextprotocol/inspector",
"node",
"dist/index.js"
],
"console": "integratedTerminal",
"preLaunchTask": "npm: watch",
"serverReadyAction": {
"action": "openExternally",
"pattern": "running at (https?://\\S+)",
"uriFormat": "%s?timeout=60000"
},
"envFile": "${workspaceFolder}/.env"
}
]
}
```
## 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)
用暴力法獲取所有用戶列表。
**參數：** 無
## 代碼結構
### 高階函數
服務使用 `withMantisConfigured` 高階函數來處理共用的檢查邏輯，確保：
- Mantis API 配置檢查
- 統一的錯誤處理
- 標準化的回應格式
- 自動的日誌記錄
### 錯誤處理
完整的錯誤處理機制包括：
- Mantis API 錯誤處理（包含 HTTP 狀態碼）
- 通用錯誤處理
- 結構化的錯誤響應
- 詳細的錯誤日誌
## 開發
```bash
# 安裝依賴
npm install
# 構建
npm run build
# 開發模式（監視變更）
npm run watch
# 運行
npm start
```
## 日誌
如果啟用了檔案日誌（`ENABLE_FILE_LOGGING=true`），日誌文件將保存在：
- `logs/mantis-mcp-server-combined.log`: 所有級別的日誌
- `logs/mantis-mcp-server-error.log`: 僅錯誤級別的日誌
日誌文件大小上限為 5MB，最多保留 5 個歷史文件。
## 許可證
MIT
## 參考
@https://documenter.getpostman.com/view/29959/7Lt6zkP#c0c24256-341e-4649-95cb-ad7bdc179399
# 發布
npm login --registry=https://registry.npmjs.org/
npm run build
npm publish --access public --registry=https://registry.npmjs.org/
# 更新版本號
npm version patch # 修復版本 0.0.x
npm version minor # 次要版本 0.x.0
npm version major # 主要版本 x.0.0
# 重新發布
npm publish