Servidor MCP de PagerDuty

Un servidor que expone la funcionalidad de la API de PagerDuty a los LLM. Este servidor está diseñado para usarse programáticamente, con entradas y salidas estructuradas.

Descripción general

El servidor MCP de PagerDuty proporciona un conjunto de herramientas para interactuar con la API de PagerDuty. Estas herramientas están diseñadas para que los LLM realicen diversas operaciones en recursos de PagerDuty, como incidentes, servicios, equipos y usuarios.

Instalación

Desde PyPI

pip install pagerduty-mcp-server

De la fuente

# Clone the repository
git clone https://github.com/wpfleger96/pagerduty-mcp-server.git
cd pagerduty-mcp-server

# Install dependencies
brew install uv
uv sync

Requisitos

Python 3.13 o superior
Clave API de PagerDuty

Configuración

El servidor MCP de PagerDuty requiere que se configure una clave API de PagerDuty en el entorno:

PAGERDUTY_API_KEY=your_api_key_here

Uso

Como extensión de ganso

{
  "type": "stdio",
  "enabled": true,
  "args": [
    "run",
    "python",
    "-m",
    "pagerduty_mcp_server"
  ],
  "commandInput": "uv run python -m pagerduty_mcp_server",
  "timeout": 300,
  "id": "pagerduty-mcp-server",
  "name": "pagerduty-mcp-server",
  "description": "pagerduty-mcp-server",
  "env_keys": [
    "PAGERDUTY_API_KEY"
  ],
  "cmd": "uv"
}

Como servidor independiente

uv run python -m pagerduty_mcp_server

Formato de respuesta

Todas las respuestas de la API siguen un formato consistente:

{
  "metadata": {
    "count": <int>,  // Number of results
    "description": "<str>"  // A short summary of the results
  },
  <resource_type>: [ // Always pluralized for consistency, even if one result is returned
    {
      ...
    },
    ...
  ],
  "error": {  // Only present if there's an error
    "message": "<str>",  // Human-readable error description
    "code": "<str>"  // Machine-readable error code
  }
}

Manejo de errores

Cuando ocurre un error, la respuesta incluirá un objeto de error con la siguiente estructura:

{
  "metadata": {
    "count": 0,
    "description": "Error occurred while processing request"
  },
  "error": {
    "message": "Invalid user ID provided",
    "code": "INVALID_USER_ID"
  }
}

Los escenarios de error más comunes incluyen:

ID de recursos no válidos (por ejemplo, user_id, team_id, service_id)
Faltan parámetros requeridos
Valores de parámetros no válidos
Errores en las solicitudes de API
Errores de procesamiento de respuesta

Validación de parámetros

Todos los parámetros de identificación deben ser identificaciones de recursos de PagerDuty válidas
Los parámetros de fecha deben ser marcas de tiempo ISO8601 válidas
Los parámetros de lista (por ejemplo, statuses , team_ids ) deben contener valores válidos
Los valores no válidos en los parámetros de lista serán ignorados
Los parámetros obligatorios no pueden ser None ni cadenas vacías
Para statuses en list_incidents , solo triggered , acknowledged y resolved son valores válidos
Para urgency en incidentes, solo valores high y low son válidos
El parámetro limit se puede utilizar para restringir la cantidad de resultados devueltos por las operaciones de lista

Limitación de velocidad y paginación

El servidor respeta los límites de velocidad de PagerDuty
El servidor gestiona automáticamente la paginación por usted
El parámetro limit se puede utilizar para controlar la cantidad de resultados devueltos por las operaciones de lista.
Si no se especifica ningún límite, el servidor devolverá hasta {pagerduty_mcp_server.utils.RESPONSE_LIMIT} resultados de forma predeterminada

Ejemplo de uso

from pagerduty_mcp_server import incidents
from pagerduty_mcp_server.utils import RESPONSE_LIMIT

# List all incidents (including resolved) for the current user's teams
incidents_list = incidents.list_incidents()

# List only active incidents
active_incidents = incidents.list_incidents(statuses=['triggered', 'acknowledged'])

# List incidents for specific services
service_incidents = incidents.list_incidents(service_ids=['SERVICE-1', 'SERVICE-2'])

# List incidents for specific teams
team_incidents = incidents.list_incidents(team_ids=['TEAM-1', 'TEAM-2'])

# List incidents within a date range
date_range_incidents = incidents.list_incidents(
    since='2024-03-01T00:00:00Z',
    until='2024-03-14T23:59:59Z'
)

# List incidents with a limit on the number of results
limited_incidents = incidents.list_incidents(limit=10)

# List incidents with the default limit
default_limit_incidents = incidents.list_incidents(limit=RESPONSE_LIMIT)

Contexto del usuario

Muchas funciones aceptan el parámetro current_user_context (valor predeterminado: True ), que filtra automáticamente los resultados según este contexto. Si current_user_context es True , no se pueden usar ciertos parámetros de filtro, ya que entrarían en conflicto con el filtrado automático:

Para todos los tipos de recursos:
- user_ids no se puede utilizar con current_user_context=True
Para incidentes:
- team_ids y service_ids no se pueden usar con current_user_context=True
Para servicios:
- team_ids no se puede utilizar con current_user_context=True
Para políticas de escalada:
- team_ids no se puede utilizar con current_user_context=True
Para guardias:
- user_ids no se puede utilizar con current_user_context=True
- schedule_ids todavía se puede usar para filtrar por horarios específicos
- La consulta mostrará las llamadas disponibles para todas las políticas de escalamiento asociadas con los equipos del usuario actual.
- Esto es útil para responder preguntas como "¿quién está actualmente de guardia en mi equipo?"
- El ID del usuario actual no se utiliza como filtro, por lo que verá todos los miembros del equipo que están de guardia.

Desarrollo

Ejecución de pruebas

Tenga en cuenta que la mayoría de las pruebas requieren una conexión real a la API de PagerDuty, por lo que deberá configurar PAGERDUTY_API_KEY en el entorno antes de ejecutar el conjunto de pruebas completo.

uv run pytest

Para ejecutar solo pruebas unitarias (es decir, pruebas que no requieren PAGERDUTY_API_KEY configurado en el entorno):

uv run pytest -m unit

Para ejecutar solo pruebas de integración:

uv run pytest -m integration

Para ejecutar únicamente pruebas del analizador:

uv run pytest -m parsers

Para ejecutar únicamente pruebas relacionadas con un submódulo específico:

uv run pytest -m <client|escalation_policies|...>

Servidor de depuración con MCP Inspector

npx @modelcontextprotocol/inspector uv run python -m pagerduty_mcp_server

Contribuciones

Lanzamientos

Este proyecto utiliza confirmaciones convencionales para lanzamientos automatizados. Los mensajes de confirmación determinan las actualizaciones de versión:

feat: → versión menor (1.0.0 → 1.1.0)
fix: → versión del parche (1.0.0 → 1.0.1)
BREAKING CHANGE: → versión principal (1.0.0 → 2.0.0)

El CHANGELOG.md, las versiones de GitHub y los paquetes de PyPI se actualizan automáticamente.

Documentación

Documentación de herramientas : información detallada sobre las herramientas disponibles, incluidos parámetros, tipos de retorno y consultas de ejemplo

Convenciones

Todas las respuestas de la API siguen el formato estándar con metadatos, lista de recursos y error opcional.
Los nombres de los recursos en las respuestas siempre se pluralizan para mantener la coherencia.
Todas las funciones que devuelven un solo elemento aún devuelven una lista con un elemento
Las respuestas de error incluyen tanto un mensaje como un código
Todas las marcas de tiempo están en formato ISO8601
Las pruebas se marcan con marcadores pytest para indicar su tipo (unidad/integración), el recurso que prueban (incidentes, equipos, etc.) y si prueban la funcionalidad de análisis (marcador "parsers").

PagerDuty MCP Server

Integrations