MantisBT MCP Server
Integra o rastreador de bugs MantisBT no Claude e outros clientes MCP via API REST. Leia e gerencie issues, notas, anexos de arquivos, tags, relacionamentos e monitores — com pesquisa semântica offline opcional em todas as issues.
Ver em codeberg.orgExperimente este MCPPatrocinado
Documentação
Servidor MCP para a API REST do MantisBT – leia e gerencie issues do rastreador de bugs diretamente do Claude Code e de outros clientes compatíveis com MCP.
MantisBT MCP Server
Inglês · Alemão
Um servidor Model Context Protocol (MCP) que integra a API REST do MantisBT ao Claude Code e a outros clientes compatíveis com MCP. Leia, crie e atualize issues diretamente do seu editor.
Requisitos
- Node.js ≥ 22
- Instalação do MantisBT com API REST habilitada (versão 2.23+)
- Token de API do MantisBT (crie em Minha Conta → Tokens de API)
Instalação
Via npx (recomendado):
Adicione ao ~/.claude/claude_desktop_config.json (Claude Desktop) ou ao seu claude_desktop_config.json local (Claude Code):
{
"mcpServers": {
"mantisbt": {
"command": "npx",
"args": ["-y", "@dpesch/mantisbt-mcp-server"],
"env": {
"MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
"MANTIS_API_KEY": "your-api-token"
}
}
}
}
Build local:
git clone https://codeberg.org/dpesch/mantisbt-mcp-server
cd mantisbt-mcp-server
npm run init
npm run build
{
"mcpServers": {
"mantisbt": {
"command": "node",
"args": ["/path/to/mantisbt-mcp-server/dist/index.js"],
"env": {
"MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
"MANTIS_API_KEY": "your-api-token"
}
}
}
}
Configuração
Variáveis de ambiente
| Variável | Obrigatória | Padrão | Descrição |
|---|---|---|---|
MANTIS_BASE_URL | ✅ | – | URL base da sua instalação do MantisBT. Tanto https://your-mantis.example.com quanto https://your-mantis.example.com/api/rest são aceitos — o sufixo /api/rest é normalizado automaticamente. |
MANTIS_API_KEY | ✅ | – | Token de API para autenticação |
MANTIS_USE_INDEX_PHP | – | auto | Defina como true quando a reescrita de URL não estiver disponível — as solicitações REST usarão /api/rest/index.php/ em vez de /api/rest/. Detectado automaticamente quando MANTIS_BASE_URL termina com /api/rest/index.php; um valor explícito sempre tem prioridade. Consulte o cookbook. |
MANTIS_CACHE_DIR | – | ~/.cache/mantisbt-mcp | Diretório para o cache de metadados |
MANTIS_CACHE_TTL | – | 3600 | Tempo de vida do cache em segundos |
TRANSPORT | – | stdio | Modo de transporte: stdio ou http |
PORT | – | 3000 | Porta para o modo HTTP |
MCP_HTTP_HOST | – | 127.0.0.1 | Endereço de bind para o modo HTTP. Alterado de 0.0.0.0 para 127.0.0.1 — o servidor agora escuta apenas em localhost por padrão. Defina como 0.0.0.0 para Docker ou acesso remoto. |
MCP_HTTP_TOKEN | ✅ (modo HTTP) | – | Token Bearer para o endpoint /mcp (Authorization: Bearer <token>). Obrigatório quando TRANSPORT=http — o servidor se recusa a iniciar no modo HTTP sem ele, para que as ferramentas nunca sejam expostas sem autenticação. Ignorado no modo stdio. O endpoint /health é sempre público. |
MANTIS_SEARCH_ENABLED | – | false | Defina como true para habilitar a busca semântica |
MANTIS_SEARCH_BACKEND | – | vectra | Backend do armazenamento vetorial: vectra (JS puro) ou sqlite-vec (requer instalação manual) |
MANTIS_SEARCH_DIR | – | {MANTIS_CACHE_DIR}/search | Diretório para o índice de busca |
MANTIS_SEARCH_MODEL | – | Xenova/paraphrase-multilingual-MiniLM-L12-v2 | Nome do modelo de embeddings (baixado uma vez no primeiro uso, ~80 MB) |
MANTIS_SEARCH_THREADS | – | 1 | Número de threads intra-op ONNX para o modelo de embeddings. O padrão é 1 para evitar saturação da CPU em máquinas com múltiplos núcleos e WSL. Aumente apenas se a velocidade de reconstrução do índice for importante e o host for dedicado a essa carga de trabalho. |
MANTIS_UPLOAD_DIR | – | – | Restringir o upload_file do file_path a arquivos dentro deste diretório (traversal de caminho via ../ é bloqueado). No modo stdio, file_path não tem restrições, a menos que isso seja definido. No modo HTTP, file_path lê do sistema de arquivos do servidor, portanto é desabilitado a menos que esta variável seja definida — clientes HTTP devem enviar via o parâmetro content (Base64) em vez disso. |
Ferramentas disponíveis
Issues
| Ferramenta | Descrição |
|---|---|
get_issue | Recupera um problema pelo seu ID numérico; select opcional para projeção de campos, reduzindo o tamanho da resposta |
get_issues | Recupera múltiplos problemas por ID em uma única chamada (1–50 IDs); problemas ausentes ou inacessíveis retornam null em sua posição, em vez de falhar a chamada |
list_issues | Filtra problemas por projeto, status, autor e mais; select opcional para projeção de campos e status para filtragem de status no lado do cliente — nomes canônicos de status em inglês (ex.: "new", "resolved") são correspondidos por ID, tornando o filtro independente do idioma em instalações localizadas |
create_issue | Cria um novo problema; severity e priority devem ser nomes canônicos em inglês (ex.: minor, major, normal, high) — chame get_issue_enums para ver todos os valores válidos e seus rótulos localizados; o parâmetro opcional handler aceita um nome de usuário como alternativa a handler_id (resolvido entre os membros do projeto); custom_fields opcional para definir valores de campos personalizados |
update_issue | Atualiza um problema existente; campos de enumeração (status, priority, severity, resolution, reproducibility) aceitam nomes canônicos em inglês, nomes localizados ou IDs numéricos — o servidor resolve nomes para IDs automaticamente; suporta custom_fields e um parâmetro opcional note que adiciona uma nota na mesma chamada (ex.: o motivo de uma mudança de status) |
delete_issue | Exclui um problema |
Notas
| Ferramenta | Descrição |
|---|---|
list_notes | Lista todas as notas de um problema |
add_note | Adiciona uma nota a um problema |
delete_note | Exclui uma nota |
Anexos
| Ferramenta | Descrição |
|---|---|
list_issue_files | Lista anexos de um problema |
upload_file | Envia um arquivo para um problema — preferido: file_path local (o servidor lê e codifica automaticamente); alternativa: content codificado em Base64 + filename (use apenas quando file_path não estiver disponível) |
Relacionamentos
| Ferramenta | Descrição |
|---|---|
add_relationship | Cria um relacionamento entre dois problemas; o parâmetro opcional type_name aceita um nome de string (ex.: "related_to", "duplicate_of") como alternativa ao type_id numérico |
remove_relationship | Remove um relacionamento de um problema (use o id do objeto de relacionamento, não o tipo) |
Monitores
| Ferramenta | Descrição |
|---|---|
add_monitor | Adiciona um usuário como monitor de um problema |
remove_monitor | Remove um usuário como monitor de um problema |
Tags
| Ferramenta | Descrição |
|---|---|
list_tags | Lista todas as tags disponíveis; usa o cache de metadados como fallback quando GET /tags retorna 404 (execute sync_metadata primeiro para popular) |
attach_tags | Anexa tags a um problema |
detach_tag | Remove uma tag de um problema |
Projetos
| Ferramenta | Descrição |
|---|---|
list_projects | Lista todos os projetos acessíveis; retorna dados normalizados do projeto (consistentes com o cache sync_metadata) |
get_project_versions | Obtém versões de um projeto; os booleanos opcionais obsolete e inherit incluem versões obsoletas ou herdadas do projeto pai; cada versão inclui um campo timestamp (data da versão); veja create_version, update_version, release_version, delete_version para modificar versões |
create_version | Cria uma nova versão em um projeto; retorna o objeto da versão criada (id, nome, descrição, lançada, obsoleta, timestamp); requer manage_project_threshold (padrão: gerente) |
update_version | Atualiza uma versão existente; apenas os campos passados são alterados (pelo menos um é obrigatório); renomear reescreve version/target_version/fixed_in_version em todos os problemas referenciados; requer manage_project_threshold (padrão: gerente) |
release_version | Marca uma versão como lançada e define sua data (padrão: agora); opcionalmente cria uma versão de acompanhamento na mesma etapa via next_version; requer manage_project_threshold (padrão: gerente) |
delete_version | Exclui permanentemente uma versão — irreversível, o MantisBT limpa version/target_version/fixed_in_version em todos os problemas referenciados; prefira update_version com obsolete=true como alternativa não destrutiva; requer manage_project_threshold (padrão: gerente) |
get_project_categories | Obtém categorias de um projeto |
get_project_users | Obtém usuários de um projeto |
find_project_member | Busca membros do projeto por nome, nome real ou e-mail (correspondência de substring sem diferenciar maiúsculas/minúsculas); query e limit opcionais (padrão 10, máximo 100); prioriza o cache |
Busca semântica (opcional)
Em vez de correspondência exata de palavras-chave, a busca semântica entende o significado por trás de uma consulta. Pergunte em linguagem natural — o mecanismo de busca encontra problemas conceitualmente relacionados mesmo quando a redação não corresponde:
- "o login falha após redefinir a senha" — encontra problemas sobre casos extremos de autenticação
- "problemas de desempenho na página de checkout" — traz relatórios relacionados independentemente da terminologia exata usada
- "entradas duplicadas na lista de faturas" — captura problemas descritos como "exibido duas vezes", "registros duplicados", etc.
O modelo de incorporação (~80 MB) roda inteiramente offline — sem chave OpenAI, sem API externa. Ele é baixado uma vez na primeira inicialização e armazenado em cache localmente. Os problemas são indexados incrementalmente a cada inicialização do servidor (apenas problemas novos e atualizados são reindexados).
Ative com MANTIS_SEARCH_ENABLED=true.
| Ferramenta | Descrição |
|---|---|
search_issues | Busca em linguagem natural sobre todos os problemas indexados — retorna os N principais resultados com pontuação de similaridade de cosseno; select opcional (nomes de campos separados por vírgula) enriquece cada resultado com os campos solicitados do problema; highlight opcional (booleano, padrão false) adiciona um campo highlights por resultado com trechos correspondentes por palavras-chave de summary e description (termos correspondentes exibidos em **bold**) |
rebuild_search_index | Constrói ou atualiza o índice de busca; full: true limpa e reconstrói do zero |
get_search_index_status | Retorna o nível atual de preenchimento do índice de busca: quantos problemas estão indexados vs. o total, e o timestamp da última sincronização |
Qual backend escolher?
vectra (padrão) | sqlite-vec | |
|---|---|---|
| Dependências | Nenhuma (JS puro) | Requer ferramentas de build nativas |
| Instalação | Incluído | npm install sqlite-vec better-sqlite3 |
| Melhor para | Até ~10.000 problemas | 10.000+ problemas |
| Desempenho | Rápido o suficiente para a maioria das configurações | Mais rápido para grandes corpora |
Comece com vectra. Mude para sqlite-vec se os tempos de indexação ou consulta ficarem visivelmente lentos.
npm install sqlite-vec better-sqlite3
# then set MANTIS_SEARCH_BACKEND=sqlite-vec
Metadados e sistema
| Ferramenta | Descrição |
|---|---|
get_issue_fields | Retorna todos os nomes de campos válidos para o parâmetro select de list_issues |
get_metadata | Recupera um resumo compacto de metadados: contagens de projetos/tags e contagens de usuários/versões/categorias por projeto; use get_metadata_full para arrays completos |
get_metadata_full | Retorna o cache completo de metadados brutos como JSON minificado (todos os projetos com campos completos, usuários/versões/categorias por projeto, todas as tags) |
sync_metadata | Atualiza o cache de metadados |
list_filters | Lista filtros salvos |
get_current_user | Recupera seu próprio perfil de usuário |
list_languages | Lista idiomas disponíveis |
get_config | Mostra a configuração do servidor (URL base, TTL do cache) |
get_issue_enums | Retorna pares válidos de ID/nome para todos os campos de enumeração de problemas (severidade, status, prioridade, resolução, reprodutibilidade) — use antes de create_issue / update_issue para consultar valores corretos; em instalações localizadas, cada entrada pode incluir um canonical_name com o nome padrão da API em inglês |
get_mantis_version | Obtém a versão do MantisBT e verifica atualizações |
get_mcp_version | Retorna a versão desta instância do mantisbt-mcp-server |
Recursos disponíveis
Recursos MCP são dados somente leitura endereçáveis por URI que os clientes podem buscar diretamente sem chamar uma ferramenta. Eles são a terceira primitiva MCP, junto com Ferramentas e Prompts. Observe que o suporte a Recursos é menos amplamente implementado em clientes MCP do que Ferramentas — consulte a documentação do seu cliente.
| URI do recurso | Descrição |
|---|---|
mantis://me | Perfil do usuário da API autenticado (busca ao vivo) |
mantis://projects | Todos os projetos MantisBT acessíveis como uma lista compacta (com suporte a cache, atualizada via sync_metadata) |
mantis://projects/{id} | Visão combinada do projeto: campos do projeto + usuários + versões + categorias em uma única chamada; prioriza o cache; suporte a lista para enumerar todos os URIs de projeto disponíveis |
mantis://enums | Valores válidos para todos os campos de enumeração de problemas: severidade, prioridade, status, resolução, reprodutibilidade (busca ao vivo) |
Prompts disponíveis
Modelos de prompt MCP são iniciadores de conversa que instruem o LLM a coletar entrada estruturada e então chamar a ferramenta apropriada. Eles não são ferramentas em si — iniciam um fluxo de trabalho guiado.
| Prompt | Argumentos obrigatórios | Argumentos opcionais | Descrição |
|---|---|---|---|
create-bug-report | project_id, category, summary, description | steps_to_reproduce, expected, actual, environment | Guia por um relatório de bug estruturado e chama create_issue |
create-feature-request | project_id, category, summary, description | use_case | Guia por uma solicitação de recurso e chama create_issue |
summarize-issue | issue_id | – | Busca um problema via get_issue e retorna um resumo conciso |
project-status | project_id | – | Lista problemas via list_issues e gera um relatório de status agrupado por severidade |
Modo HTTP
Para uso como servidor autônomo (ex.: em configurações remotas). MCP_HTTP_TOKEN é obrigatório no modo HTTP — o servidor se recusa a iniciar sem ele:
MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
TRANSPORT=http PORT=3456 node dist/index.js
# With explicit bind address (required for Docker/remote):
# MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
# TRANSPORT=http PORT=3456 MCP_HTTP_HOST=0.0.0.0 node dist/index.js
Cada requisição /mcp deve enviar Authorization: Bearer <token>. Via HTTP, o file_path de upload_file é desabilitado a menos que MANTIS_UPLOAD_DIR esteja definido — use o parâmetro content (Base64) em vez disso.
Verificação de saúde: GET http://localhost:3456/health (sempre público, sem token necessário)
Documentação
- Cookbook — receitas orientadas a ferramentas com exemplos de parâmetros prontos para copiar e colar para todas as ferramentas registradas
- Exemplos de Uso — exemplos de prompts em linguagem natural para casos de uso do dia a dia (sem necessidade de nomes de ferramentas)
Desenvolvimento
npm run init # First-time setup: install deps, git hooks, typecheck
npm run build # Compile TypeScript → dist/
npm run typecheck # Type check without output
npm run dev # Watch mode for development
npm test # Run tests (vitest)
npm run test:watch # Run tests in watch mode
npm run test:coverage # Coverage report
Licença
MIT – veja LICENSE
Contribuindo
Contribuições são bem-vindas! Por favor, leia CONTRIBUTING.md. Repositório: codeberg.org/dpesch/mantisbt-mcp-server