MantisBT MCP Server
Integra el rastreador de errores MantisBT en Claude y otros clientes MCP a través de la API REST. Lee y gestiona incidencias, notas, archivos adjuntos, etiquetas, relaciones y monitores, con búsqueda semántica opcional sin conexión en todas las incidencias.
Ver en codeberg.orgPrueba este MCPPatrocinado
Documentación
Servidor MCP para la API REST de MantisBT: lee y gestiona incidencias del rastreador de errores directamente desde Claude Code y otros clientes compatibles con MCP.
Servidor MCP de MantisBT
Español · Deutsch
Un servidor de Protocolo de Contexto de Modelo (MCP) que integra la API REST de MantisBT en Claude Code y otros clientes compatibles con MCP. Lee, crea y actualiza incidencias directamente desde tu editor.
Requisitos
- Node.js ≥ 22
- Instalación de MantisBT con la API REST habilitada (versión 2.23+)
- Token de API de MantisBT (crear en Mi Cuenta → Tokens de API)
Instalación
Vía npx (recomendado):
Añade a ~/.claude/claude_desktop_config.json (Claude Desktop) o a tu 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"
}
}
}
}
Compilación 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"
}
}
}
}
Configuración
Variables de entorno
| Variable | Obligatoria | Valor por defecto | Descripción |
|---|---|---|---|
MANTIS_BASE_URL | ✅ | – | URL base de tu instalación de MantisBT. Se aceptan tanto https://your-mantis.example.com como https://your-mantis.example.com/api/rest: el sufijo /api/rest se normaliza automáticamente. |
MANTIS_API_KEY | ✅ | – | Token de API para autenticación |
MANTIS_USE_INDEX_PHP | – | auto | Establécelo en true cuando la reescritura de URL no esté disponible: las solicitudes REST usarán entonces /api/rest/index.php/ en lugar de /api/rest/. Se detecta automáticamente cuando MANTIS_BASE_URL termina en /api/rest/index.php; un valor explícito siempre tiene prioridad. Consulta el recetario. |
MANTIS_CACHE_DIR | – | ~/.cache/mantisbt-mcp | Directorio para la caché de metadatos |
MANTIS_CACHE_TTL | – | 3600 | Duración de la caché en segundos |
TRANSPORT | – | stdio | Modo de transporte: stdio o http |
PORT | – | 3000 | Puerto para el modo HTTP |
MCP_HTTP_HOST | – | 127.0.0.1 | Dirección de enlace para el modo HTTP. Cambiado de 0.0.0.0 a 127.0.0.1: el servidor ahora escucha solo en localhost por defecto. Establécelo en 0.0.0.0 para Docker o acceso remoto. |
MCP_HTTP_TOKEN | ✅ (modo HTTP) | – | Token Bearer para el endpoint /mcp (Authorization: Bearer <token>). Obligatorio cuando TRANSPORT=http: el servidor se niega a iniciarse en modo HTTP sin él, de modo que las herramientas nunca quedan expuestas sin autenticación. Se ignora en modo stdio. El endpoint /health siempre es público. |
MANTIS_SEARCH_ENABLED | – | false | Establécelo en true para habilitar la búsqueda semántica |
MANTIS_SEARCH_BACKEND | – | vectra | Backend del almacén vectorial: vectra (JS puro) o sqlite-vec (requiere instalación manual) |
MANTIS_SEARCH_DIR | – | {MANTIS_CACHE_DIR}/search | Directorio para el índice de búsqueda |
MANTIS_SEARCH_MODEL | – | Xenova/paraphrase-multilingual-MiniLM-L12-v2 | Nombre del modelo de incrustación (se descarga una vez en el primer uso, ~80 MB) |
MANTIS_SEARCH_THREADS | – | 1 | Número de hilos intra-op de ONNX para el modelo de incrustación. El valor por defecto es 1 para evitar la saturación de la CPU en máquinas multinúcleo y WSL. Auméntalo solo si la velocidad de reconstrucción del índice importa y el host está dedicado a esta carga de trabajo. |
MANTIS_UPLOAD_DIR | – | – | Restringe el upload_file de file_path a archivos dentro de este directorio (el recorrido de rutas mediante ../ está bloqueado). En modo stdio, file_path no tiene restricciones salvo que se establezca esto. En modo HTTP, file_path lee del sistema de archivos del servidor, por lo que está deshabilitado salvo que se establezca esta variable: los clientes HTTP deben subir mediante el parámetro content (Base64) en su lugar. |
Herramientas disponibles
Incidencias
| Herramienta | Descripción |
|---|---|
get_issue | Recupera un problema por su ID numérico; select opcional para proyección de campos y reducir el tamaño de la respuesta |
get_issues | Recupera múltiples problemas por ID en una sola llamada (1–50 IDs); los IDs faltantes o inaccesibles devuelven null en su posición en lugar de fallar la llamada |
list_issues | Filtra problemas por proyecto, estado, autor y más; select opcional para proyección de campos y status para filtrado de estado en el cliente — los nombres de estado canónicos en inglés (p. ej. "new", "resolved") se comparan por ID, lo que hace que el filtro sea independiente del idioma en instalaciones localizadas |
create_issue | Crea un nuevo problema; severity y priority deben ser nombres canónicos en inglés (p. ej. minor, major, normal, high) — llama a get_issue_enums para ver todos los valores válidos y sus etiquetas localizadas; el parámetro opcional handler acepta un nombre de usuario como alternativa a handler_id (resuelto contra los miembros del proyecto); custom_fields opcional para establecer valores de campos personalizados |
update_issue | Actualiza un problema existente; los campos de enumeración (status, priority, severity, resolution, reproducibility) aceptan nombres canónicos en inglés, nombres localizados o IDs numéricos — el servidor resuelve los nombres a IDs automáticamente; admite custom_fields y un parámetro opcional note que añade una nota en la misma llamada (p. ej. el motivo de un cambio de estado) |
delete_issue | Elimina un problema |
Notas
| Herramienta | Descripción |
|---|---|
list_notes | Lista todas las notas de un problema |
add_note | Añade una nota a un problema |
delete_note | Elimina una nota |
Adjuntos
| Herramienta | Descripción |
|---|---|
list_issue_files | Lista los adjuntos de un problema |
upload_file | Sube un archivo a un problema — preferido: file_path local (el servidor lo lee y codifica automáticamente); alternativa: content codificado en Base64 + filename (usar solo cuando file_path no esté disponible) |
Relaciones
| Herramienta | Descripción |
|---|---|
add_relationship | Crea una relación entre dos problemas; el parámetro opcional type_name acepta un nombre de cadena (p. ej. "related_to", "duplicate_of") como alternativa al type_id numérico |
remove_relationship | Elimina una relación de un problema (usa el id del objeto de relación, no el tipo) |
Monitores
| Herramienta | Descripción |
|---|---|
add_monitor | Añade un usuario como monitor de un problema |
remove_monitor | Elimina un usuario como monitor de un problema |
Etiquetas
| Herramienta | Descripción |
|---|---|
list_tags | Lista todas las etiquetas disponibles; recurre a la caché de metadatos cuando GET /tags devuelve 404 (ejecuta sync_metadata primero para poblarla) |
attach_tags | Adjunta etiquetas a un problema |
detach_tag | Elimina una etiqueta de un problema |
Proyectos
| Herramienta | Descripción |
|---|---|
list_projects | Lista todos los proyectos accesibles; devuelve datos de proyecto normalizados (coherentes con la caché de sync_metadata) |
get_project_versions | Obtiene las versiones de un proyecto; los booleanos opcionales obsolete y inherit incluyen versiones obsoletas o heredadas del padre; cada versión incluye un campo timestamp (fecha de versión); consulta create_version, update_version, release_version, delete_version para modificar versiones |
create_version | Crea una nueva versión en un proyecto; devuelve el objeto de versión creado (id, nombre, descripción, publicada, obsoleta, marca de tiempo); requiere manage_project_threshold (predeterminado: manager) |
update_version | Actualiza una versión existente; solo se cambian los campos que pases (se requiere al menos uno); renombrar reescribe version/target_version/fixed_in_version en todos los problemas que la referencian; requiere manage_project_threshold (predeterminado: manager) |
release_version | Marca una versión como publicada y establece su fecha (predeterminado: ahora); opcionalmente crea una versión de seguimiento en el mismo paso mediante next_version; requiere manage_project_threshold (predeterminado: manager) |
delete_version | Elimina permanentemente una versión — irreversible, MantisBT limpia version/target_version/fixed_in_version en todos los problemas que la referencian; prefiere update_version con obsolete=true como alternativa no destructiva; requiere manage_project_threshold (predeterminado: manager) |
get_project_categories | Obtiene las categorías de un proyecto |
get_project_users | Obtiene los usuarios de un proyecto |
find_project_member | Busca miembros del proyecto por nombre, nombre real o correo electrónico (coincidencia de subcadena sin distinción de mayúsculas); query y limit opcionales (predeterminado 10, máximo 100); prioriza la caché |
Búsqueda semántica (opcional)
En lugar de la coincidencia exacta de palabras clave, la búsqueda semántica comprende el significado detrás de una consulta. Pregunta en lenguaje natural — el motor de búsqueda encuentra problemas conceptualmente relacionados incluso cuando la redacción no coincide:
- "el inicio de sesión falla después de restablecer la contraseña" — encuentra problemas sobre casos límite de autenticación
- "problemas de rendimiento en la página de pago" — muestra informes relacionados independientemente de la terminología exacta utilizada
- "entradas duplicadas en la lista de facturas" — captura problemas descritos como "se muestra dos veces", "registros dobles", etc.
El modelo de incrustación (~80 MB) se ejecuta completamente sin conexión — sin clave de OpenAI, sin API externa. Se descarga una vez al primer inicio y se almacena en caché localmente. Los problemas se indexan incrementalmente en cada inicio del servidor (solo se reindexan los problemas nuevos y actualizados).
Actívalo con MANTIS_SEARCH_ENABLED=true.
| Herramienta | Descripción |
|---|---|
search_issues | Búsqueda en lenguaje natural sobre todos los problemas indexados — devuelve los N mejores resultados con puntuación de similitud coseno; select opcional (nombres de campos separados por comas) enriquece cada resultado con los campos de problema solicitados; highlight opcional (booleano, predeterminado false) añade un campo highlights por resultado con extractos coincidentes por palabras clave de summary y description (los términos coincidentes se muestran en **bold**) |
rebuild_search_index | Construye o actualiza el índice de búsqueda; full: true lo limpia y reconstruye desde cero |
get_search_index_status | Devuelve el nivel de llenado actual del índice de búsqueda: cuántos problemas están indexados vs. el total, y la marca de tiempo de la última sincronización |
¿Qué backend elegir?
vectra (predeterminado) | sqlite-vec | |
|---|---|---|
| Dependencias | Ninguna (JS puro) | Requiere herramientas de compilación nativas |
| Instalación | Incluido | npm install sqlite-vec better-sqlite3 |
| Mejor para | Hasta ~10,000 problemas | 10,000+ problemas |
| Rendimiento | Suficientemente rápido para la mayoría de configuraciones | Más rápido para corpus grandes |
Comienza con vectra. Cambia a sqlite-vec si los tiempos de indexación o consulta se vuelven notablemente lentos.
npm install sqlite-vec better-sqlite3
# then set MANTIS_SEARCH_BACKEND=sqlite-vec
Metadatos y sistema
| Herramienta | Descripción |
|---|---|
get_issue_fields | Devuelve todos los nombres de campos válidos para el parámetro select de list_issues |
get_metadata | Recupera un resumen de metadatos compacto: recuentos de proyectos/etiquetas y recuentos de usuarios/versiones/categorías por proyecto; usa get_metadata_full para matrices completas |
get_metadata_full | Devuelve la caché de metadatos sin procesar completa como JSON minimizado (todos los proyectos con campos completos, usuarios/versiones/categorías por proyecto, todas las etiquetas) |
sync_metadata | Actualiza la caché de metadatos |
list_filters | Lista los filtros guardados |
get_current_user | Recupera tu propio perfil de usuario |
list_languages | Lista los idiomas disponibles |
get_config | Muestra la configuración del servidor (URL base, TTL de caché) |
get_issue_enums | Devuelve pares válidos de ID/nombre para todos los campos de enumeración de problemas (severidad, estado, prioridad, resolución, reproducibilidad) — usa antes de create_issue / update_issue para consultar valores correctos; en instalaciones localizadas, cada entrada puede incluir un canonical_name con el nombre de API estándar en inglés |
get_mantis_version | Obtiene la versión de MantisBT y verifica actualizaciones |
get_mcp_version | Devuelve la versión de esta instancia de mantisbt-mcp-server |
Recursos disponibles
Los recursos MCP son datos de solo lectura direccionables por URI que los clientes pueden obtener directamente sin llamar a una herramienta. Son el tercer primitivo de MCP junto con Herramientas y Prompts. Ten en cuenta que el soporte de Recursos está menos implementado en los clientes MCP que las Herramientas — consulta la documentación de tu cliente.
| URI del recurso | Descripción |
|---|---|
mantis://me | Perfil del usuario de API autenticado (obtención en vivo) |
mantis://projects | Todos los proyectos MantisBT accesibles como lista compacta (respaldado por caché, actualizado mediante sync_metadata) |
mantis://projects/{id} | Vista de proyecto combinada: campos del proyecto + usuarios + versiones + categorías en una sola llamada; prioriza la caché, con soporte de lista para enumerar todos los URI de proyecto disponibles |
mantis://enums | Valores válidos para todos los campos de enumeración de problemas: severidad, prioridad, estado, resolución, reproducibilidad (obtención en vivo) |
Prompts disponibles
Las plantillas de prompt MCP son iniciadores de conversación que instruyen al LLM para recopilar entrada estructurada y luego llamar a la herramienta adecuada. No son herramientas en sí mismas — inician un flujo de trabajo guiado.
| Prompt | Argumentos requeridos | Argumentos opcionales | Descripción |
|---|---|---|---|
create-bug-report | project_id, category, summary, description | steps_to_reproduce, expected, actual, environment | Guía a través de un informe de error estructurado y llama a create_issue |
create-feature-request | project_id, category, summary, description | use_case | Guía a través de una solicitud de funcionalidad y llama a create_issue |
summarize-issue | issue_id | – | Obtiene un problema mediante get_issue y devuelve un resumen conciso |
project-status | project_id | – | Lista problemas mediante list_issues y genera un informe de estado agrupado por severidad |
Modo HTTP
Para uso como servidor independiente (p. ej. en configuraciones remotas). MCP_HTTP_TOKEN es obligatorio en modo HTTP — el servidor se niega a iniciar sin él:
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 solicitud /mcp debe enviar Authorization: Bearer <token>. Por HTTP, upload_file de file_path está deshabilitado a menos que MANTIS_UPLOAD_DIR esté configurado — usa el parámetro content (Base64) en su lugar.
Verificación de salud: GET http://localhost:3456/health (siempre público, sin token requerido)
Documentación
- Libro de recetas — recetas orientadas a herramientas con ejemplos de parámetros listos para copiar y pegar para todas las herramientas registradas
- Ejemplos de uso — ejemplos de prompts en lenguaje natural para casos de uso cotidianos (no se requieren nombres de herramientas)
Desarrollo
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
Licencia
MIT – consulta LICENCIA
Contribuciones
¡Las contribuciones son bienvenidas! Por favor, lee CONTRIBUTING.md. Repositorio: codeberg.org/dpesch/mantisbt-mcp-server