Mantis MCP Server

Mantis MCP Server 是一个基于 Model Context Protocol (MCP) 的服务，用于与 Mantis Bug Tracker 系统进行集成。它提供了一系列工具，允许用户通过 MCP 协议查询和分析 Mantis 系统中的数据。

功能

• 问题管理
  • 获取问题列表（支持多种过滤条件）
  • 根据 ID 查询问题详情
• 用户管理
  • 根据用户名查询用户
  • 获取所有用户列表
• 项目管理
  • 获取项目列表
• 统计分析
  • 问题统计（支持多维度分析）
  • 分派统计（分析问题分派情况）
• 性能优化
  • 字段选择（减少返回数据量）
  • 分页处理（控制每次返回数量）
  • 自动数据压缩（大量数据时自动压缩）
• 完整的错误处理和日志记录

安装

npm install mantis-mcp-server

配置

1. 在项目根目录创建 .env 文件：

# 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：

npm install -g mantis-mcp-server

Windows 配置

在 Windows 系统中，编辑 %USERPROFILE%\.cursor\mcp.json（通常在 C:\Users\你的用户名\.cursor\mcp.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，添加以下配置：

{
  "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 中添加以下配置：

{
  "servers": {
    "mantis-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

1. 在 .vscode/launch.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 状态码）
• 通用错误处理
• 结构化的错误响应
• 详细的错误日志

开发

# 安裝依賴
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
npm run build
npm publish --access public

更新版本号

npm version patch  # 修复版本 0.0.x
npm version minor  # 次要版本 0.x.0
npm version major  # 主要版本 x.0.0

重新发布

npm publish