jira-alerts-mcp

Un servidor MCP para la API REST de Jira Service Management Operations: alertas y guardias.

Por qué existe

Las alertas no son elementos de trabajo. Viven detrás de una API distinta: /jsm/ops/api, la superficie reubicada de Opsgenie, con sus propios ámbitos, su propio formato de id y su propia semántica de escritura asíncrona. El Registry de MCP lista 30 servidores de Jira; todos hablan con elementos de trabajo. Ninguno puede decirte qué te está paginando ahora mismo.

El servidor MCP oficial de Atlassian no cubre ese hueco. atlassian/atlassian-mcp-server cubre Jira, Confluence, requests de Jira Service Management, Bitbucket, Compass y el Teamwork Graph. No tiene ninguna herramienta para alertas, horarios o guardias. Además, es un servidor alojado y cerrado; el repositorio contiene manifests y skills, no handlers, así que ese hueco solo lo puede cerrar Atlassian, no una contribución.

Los servidores MCP de Opsgenie que existen hablan con una API con fecha de caducidad. giantswarm/mcp-opsgenie, burakdirin/opsgenie-mcp-server y daviddykeuk/opsgenie-mcp llaman todos a api.opsgenie.com con una GenieKey. Opsgenie dejó de venderse el 4 de junio de 2025 y se apagará el 5 de abril de 2027, momento en el que esas API REST dejarán de responder. La funcionalidad se trasladó a Jira Service Management.

Este servidor apunta a la superficie que las reemplaza: api.atlassian.com/jsm/ops/api/{cloudId} con OAuth o un token de API de Atlassian. Busca alertas, lee sus notas y su línea de actividad, reconoce / cierra / anota / añade responders, y consulta quién está de guardia ahora y después.

Related MCP server: Jira & Confluence MCP Server

Compatibilidad

Para inquilinos de Atlassian Cloud con JSM Operations, es decir, sitios ya migrados de Opsgenie independiente o aprovisionados después de la fusión. Si tu equipo todavía accede a app.opsgenie.com y se autentica con una GenieKey, este servidor no llegará a tus datos; uno de los servidores de Opsgenie mencionados arriba sí lo hará, hasta 2027.

URL base: https://api.atlassian.com/jsm/ops/api/{cloudId}/v1

Herramientas

Deliberadamente no implementados: DELETE /v1/alerts/{id} y la creación de alertas. Eliminar alertas destruye el historial de auditoría sin posibilidad de deshacer, y la creación de alertas pertenece a la API de integración (/jsm/ops/integration/v2/alerts) con una integration key, no a un agente interactivo. Abre un issue si tienes una necesidad concreta.

Tres comportamientos de la API que las descripciones de las herramientas codifican

Estas son las cosas que rompen en silencio las integraciones ingenuas, por eso se indican en las descripciones de las herramientas, donde el modelo las leerá de verdad:

1. Las escrituras son asíncronas. Cada endpoint mutante devuelve { result, requestId, took } inmediatamente y aplica el cambio fuera de banda. Volver a leer la alerta justo después de un ack a menudo la mostrará aún sin reconocer. jsm_get_request_status es la vía de verificación correcta, y cada herramienta de escritura apunta a ella.

2. tinyId no es un id. El número corto de la interfaz de JSM (#4821) es rechazado por /v1/alerts/{id}, que solo acepta el id completo uuid-timestamp. Los alias requieren un endpoint completamente distinto (/v1/alerts/alias?alias=). Tanto las descripciones del esquema como el handler de 404 lo indican explícitamente, para que el modelo se autocorrija en lugar de reintentar la misma llamada.

3. La ventana de búsqueda tiene un tope de 20.000. offset + limit debe mantenerse por debajo. jsm_list_alerts rechaza localmente la paginación más profunda con un mensaje que le dice al modelo que acote la consulta en lugar de gastar un viaje de ida y vuelta en un 400 garantizado.

Configuración

Requiere Node ≥ 22.

git clone https://github.com/rrvrs/jira-alerts-mcp.git
cd jira-alerts-mcp
npm install
npm run build

Configuración

Copia .env.example como referencia. Ten en cuenta que el servidor no lee .env por sí mismo: un servidor MCP lo lanza su cliente, y el entorno pertenece al cliente. Usa el archivo como lista de verificación para el bloque env de tu cliente, o set -a; source .env; set +a para desarrollo local.

Las credenciales se validan al arrancar, así que una configuración incorrecta falla de inmediato con un mensaje accionable en lugar de hacerlo en la primera llamada a una herramienta.

Cómo encontrar tu cloud id. Abre https://<your-site>.atlassian.net/_edgeAuth/tenantInfo con la sesión iniciada, o llama a GET https://api.atlassian.com/oauth/token/accessible-resources con tu token.

Ámbitos requeridos. Las herramientas de lectura necesitan read:ops-alert:jira-service-management; las de escritura necesitan write:ops-alert:jira-service-management. Conceder solo el ámbito de lectura es una configuración compatible: las herramientas de escritura fallarán con un 403 que nombra el ámbito que falta.

La cuenta también necesita acceso a JSM Operations en el equipo correspondiente. Las alertas y horarios cuelgan de la página de Operations de un equipo, así que unas credenciales que no pueden ver el equipo obtendrán listas vacías en lugar de errores.

Conexión con Claude Code

claude mcp add jsm-alerts \
  --env JSM_CLOUD_ID='your-cloud-id' \
  --env JSM_EMAIL='you@example.com' \
  --env JSM_API_TOKEN="${JSM_API_TOKEN}" \
  -- node /absolute/path/to/jira-alerts-mcp/dist/index.js

Dos cosas que suelen despistar: el nombre del servidor es el primer argumento posicional, antes de cualquier flag; y en zsh ${VAR} necesita comillas. Para sesiones iniciadas desde la GUI, el token tiene que vivir en el bloque env de ~/.claude/settings.json; el entorno del shell no se hereda.

Pruebas

npm test           # offline test suite — no network, no tenant
npm run inspect    # MCP Inspector against dist/index.js — needs credentials

Para la comprobación en vivo, empieza con jsm_list_schedules. No necesita ids y confirma autenticación, ámbitos y visibilidad del equipo en una sola llamada.

Estado de verificación de endpoints

Las rutas se comprobaron contra la referencia de la API REST de JSM ops en lugar de darse por supuestas:

• Confirmados en la documentación publicada: /v1/alerts, /v1/alerts/{id}, /v1/alerts/alias, /v1/alerts/requests/{id}, /v1/alerts/{id}/acknowledge, /v1/alerts/{id}/close, /v1/alerts/{id}/responders, /v1/alerts/{id}/notes, /v1/schedules/{id}/on-calls, /v1/schedules/{id}/next-on-calls.

• Paridad con Opsgenie, merece confirmación en la primera ejecución: GET /v1/alerts/{id}/logs y los parámetros de consulta exactos para la paginación de notas/logs (order, cursor offset). JSM Operations es una reubicación de la API de Opsgenie y estos no han cambiado allí, pero el sitio de documentación se renderiza en el cliente y no se pudo leer de principio a fin.

• Envoltura de colecciones: Atlassian no es consistente sobre si las colecciones llegan bajo data o values. JsmClient.getCollection acepta ambas y normaliza, así que esto no requiere ningún cambio en ningún caso; pero si una herramienta de listado devuelve cero elementos contra datos que sabes que existen, ese normalizador es lo primero que hay que inspeccionar.

Arquitectura

src/
├── index.ts                 # transports and startup credential validation
├── server.ts                # assembles the tool domains
├── constants.ts             # API root, limits
├── types.ts                 # JSM API interfaces
├── schemas/common.ts        # Zod fragments shared across domains
├── services/
│   ├── client.ts            # auth, request, envelope normalisation, error mapping
│   └── format.ts            # markdown rendering, truncation, result envelopes
└── tools/
    ├── define.ts            # defineTool() + registerTools()
    ├── list-executor.ts     # the shared list pipeline
    ├── alerts/              # read tools — one file per tool, plus shapes.ts
    ├── actions/             # write tools, all via execute-action.ts
    └── oncall/              # schedules and on-call

Una herramienta por archivo. Un módulo de herramienta es dueño de su forma de entrada, su descripción y su handler, y de nada más: la más grande tiene ~100 líneas. server.ts concatena los arrays exportados de los tres dominios; index.ts solo sabe de transportes.

Hay tres convenciones que merece la pena conservar al ampliarlo:

• Toda herramienta de listado pasa por executeList (tools/list-executor.ts). Gestiona la obtención, la rama de resultado vacío, el truncado a 25.000 caracteres, el bloque de paginación y el conmutador de formato. En su día hubo dos bugs en copias por herramienta de esa lógica: una página vacía devolvía un resultado que el SDK rechazaba, y next_offset se saltaba registros que el truncado había descartado. Ahora hay una sola copia, a propósito.

• Toda escritura pasa por executeAction (tools/actions/execute-action.ts), para que el contrato de recibo asíncrono no pueda desviarse entre las cuatro herramientas de escritura.

• La paginación informa de lo que se entregó, no de lo que se obtuvo. count y next_offset describen los registros realmente presentes en la respuesta, y truncated avisa cuando la API devolvió más de lo que cabía.

Nota sobre inputSchema

La registerTool del SDK de TypeScript de MCP espera un raw Zod shape (un objeto plano de tipos Zod), no un z.object(...). Pasar un z.object — como muestran algunos ejemplos — falla. Las herramientas de aquí definen un shape plano y derivan su tipo de entrada con z.infer<z.ZodObject<typeof shape>>. Una consecuencia: .strict() no se puede aplicar a un shape plano, así que las claves desconocidas se eliminan en lugar de rechazarse.

Relacionado con esto, ToolResult es un type alias, no una interface: el CallToolResult del SDK lleva una firma de índice, y TypeScript solo concede una implícita a los type aliases.

Contribuciones

Consulta CONTRIBUTING.md para conocer el bucle de desarrollo, las convenciones que merece la pena conservar y cómo añadir una herramienta. Los issues y PRs no deben contener cloud ids, tokens ni datos reales de alertas.

Seguridad

Este servidor guarda credenciales de Atlassian, y el transporte HTTP no realiza autenticación propia; consulta SECURITY.md para el modelo de amenazas, notas de endurecimiento y cómo informar de una vulnerabilidad de forma privada.

Licencia

Apache-2.0