Mantis MCP Server

Um servidor MCP para integração com o sistema Mantis Bug Tracker.

Documentação

Mantis MCP Server

O Mantis MCP Server é um serviço baseado no Model Context Protocol (MCP) para integração com o sistema Mantis Bug Tracker. Ele fornece uma série de ferramentas que permitem aos usuários consultar e analisar dados no sistema Mantis por meio do protocolo MCP.

Funcionalidades

Gerenciamento de problemas
- Obter lista de problemas (suporta múltiplos filtros)
- Consultar detalhes do problema por ID
Gerenciamento de usuários
- Consultar usuário por nome
- Obter lista de todos os usuários
Gerenciamento de projetos
- Obter lista de projetos
Análise estatística
- Estatísticas de problemas (suporta análise multidimensional)
- Estatísticas de atribuição (analisa a atribuição de problemas)
Otimização de desempenho
- Seleção de campos (reduz a quantidade de dados retornados)
- Paginação (controla a quantidade retornada por vez)
- Compressão automática de dados (compressão automática para grandes volumes de dados)
Tratamento completo de erros e registro de logs

Instalação

Instalação via Smithery

Para instalar a Integração do Mantis Bug Tracker para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @kfnzero/mantis-mcp-server --client claude

Instalação Manual

npm install mantis-mcp-server

Configuração

Crie o arquivo .env na raiz do projeto:

# 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

Como obter a chave da API do MantisBT

Faça login na sua conta MantisBT
Clique no nome de usuário no canto superior direito e selecione "Minha conta"
Alterne para a aba "Token de API"
Clique no botão "Criar novo token"
Digite o nome do token (por exemplo: MCP Server)
Copie o token de API gerado e cole-o na configuração MANTIS_API_KEY do arquivo .env

Configuração do MCP

Instalação global

Primeiro, é necessário instalar o mantis-mcp-server globalmente:

npm install -g mantis-mcp-server

Configuração no Windows

No sistema Windows, edite o arquivo %USERPROFILE%\.cursor\mcp.json (geralmente em C:\Users\你的用戶名\.cursor\mcp.json) e adicione a seguinte configuração:

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

Configuração no macOS/Linux

No sistema macOS ou Linux, edite o arquivo ~/.cursor/mcp.json e adicione a seguinte configuração:

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

Observação: no macOS/Linux, usamos npx para executar a versão mais recente do mantis-mcp-server, garantindo que você sempre use a versão mais atual, sem necessidade de instalação global.

Descrição das variáveis de ambiente

MANTIS_API_URL: URL da sua API Mantis
MANTIS_API_KEY: Chave da sua API Mantis
NODE_ENV: Ambiente de execução, recomendado definir como "production"
LOG_LEVEL: Nível de log, valores possíveis: error, warn, info, debug

Verificando a configuração

Após a configuração, você pode:

Recarregar o MCP do Cursor
Abrir a paleta de comandos (Windows: Ctrl+Shift+P, Mac: Cmd+Shift+P)

Configuração no Cursor

Adicione a seguinte configuração em .vscode/mcp.json:

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

Adicione a seguinte configuração em .vscode/launch.json para depuração:

{
  "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"
    }
  ]
}

Descrição das ferramentas da API

1. Obter lista de problemas (get_issues)

Obtém a lista de problemas do Mantis, podendo filtrar por múltiplas condições.

Parâmetros:

projectId (opcional): ID do projeto
statusId (opcional): ID do status
handlerId (opcional): ID do responsável
reporterId (opcional): ID do relator
search (opcional): Palavra-chave de busca
pageSize (opcional, padrão 20): Tamanho da página
page (opcional, padrão 0): Posição inicial da paginação, começando em 1
select (opcional): Campos a serem retornados, por exemplo: ['id', 'summary', 'description']. Pode ser usado para reduzir a quantidade de dados retornados

2. Obter detalhes do problema (get_issue_by_id)

Obtém os detalhes de um problema do Mantis por ID.

Parâmetros:

issueId: ID do problema

3. Consultar usuário (get_user)

Consulta um usuário do Mantis pelo nome.

Parâmetros:

username: Nome do usuário

4. Obter lista de projetos (get_projects)

Obtém a lista de projetos do Mantis.

Parâmetros: Nenhum

5. Obter estatísticas de problemas (get_issue_statistics)

Obtém dados estatísticos de problemas do Mantis, analisando por diferentes dimensões.

Parâmetros:

projectId (opcional): ID do projeto
groupBy: Agrupamento, valores possíveis: 'status', 'priority', 'severity', 'handler', 'reporter'
period (padrão 'all'): Período de tempo, valores possíveis: 'all', 'today', 'week', 'month'

6. Obter estatísticas de atribuição (get_assignment_statistics)

Obtém dados estatísticos de atribuição de problemas do Mantis, analisando a atribuição de problemas entre diferentes usuários.

Parâmetros:

projectId (opcional): ID do projeto
includeUnassigned (padrão true): Se deve incluir problemas não atribuídos
statusFilter (opcional): Filtro de status, calcula apenas problemas com status específico

7. Obter todos os usuários (get_users)

Obtém a lista de todos os usuários usando força bruta.

Parâmetros: Nenhum

Estrutura do código

Funções de alta ordem

O serviço usa a função de alta ordem withMantisConfigured para lidar com a lógica de verificação compartilhada, garantindo:

Verificação da configuração da API Mantis
Tratamento uniforme de erros
Formato de resposta padronizado
Registro automático de logs

Tratamento de erros

O mecanismo completo de tratamento de erros inclui:

Tratamento de erros da API Mantis (incluindo códigos de status HTTP)
Tratamento de erros genéricos
Respostas de erro estruturadas
Logs de erro detalhados

Desenvolvimento

# 安裝依賴
npm install

# 構建
npm run build

# 開發模式（監視變更）
npm run watch

# 運行
npm start

Logs

Se o log em arquivo estiver habilitado (ENABLE_FILE_LOGGING=true), os arquivos de log serão salvos em:

logs/mantis-mcp-server-combined.log: Logs de todos os níveis
logs/mantis-mcp-server-error.log: Apenas logs de nível de erro

O tamanho máximo do arquivo de log é 5MB, com retenção máxima de 5 arquivos históricos.

Licença

MIT

Referência

@https://documenter.getpostman.com/view/29959/7Lt6zkP#c0c24256-341e-4649-95cb-ad7bdc179399

Publicação

npm login --registry=https://registry.npmjs.org/ npm run build npm publish --access public --registry=https://registry.npmjs.org/

Atualização de versão

npm version patch # Versão de correção 0.0.x npm version minor # Versão secundária 0.x.0 npm version major # Versão principal x.0.0

Republicação

npm publish