build_user_context

Build and validate a user's context into a structured dictionary to filter escalation policies, incidents, on-calls, services, and users in PagerDuty.

Instructions

Validate and build the current user's context into a dictionary with the following format: { "user_id": str, "team_ids": List[str], "service_ids": List[str], "escalation_policy_ids": List[str] } The MCP server tools use this user context to filter the following resources: - Escalation policies - Incidents - Oncalls - Services - Users

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/pagerduty_mcp_server/users.py:15-68 (handler)

Core implementation of build_user_context: fetches current user via _show_current_user, builds context dict with user_id, name, email, team_ids, service_ids, escalation_policy_ids using helper functions from other modules, handles errors.

def build_user_context() -> Dict[str, Any]:
    """Validate and build the current user's context. Exposed as MCP server tool.

    See the "Standard Response Format" section in `tools.md` for the complete standard response structure.

    Returns:
        See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
        The response will contain the current user's context in the format defined in the "build_user_context" section of `tools.md`.

    Raises:
        See the "Error Handling" section in `tools.md` for common error scenarios.
    """
    try:
        user = _show_current_user()
        if not user:
            raise ValueError("Failed to get current user data")

        context = {
            "user_id": str(user.get("id", "")).strip(),
            "name": user.get("name", ""),
            "email": user.get("email", ""),
            "team_ids": [],
            "service_ids": [],
            "escalation_policy_ids": [],
        }

        if not context["user_id"]:
            raise ValueError("Invalid user data: missing or empty user ID")

        team_ids = teams.fetch_team_ids(user=user)
        context["team_ids"] = [
            str(tid).strip() for tid in team_ids if tid and str(tid).strip()
        ]

        if context["team_ids"]:
            service_ids = services.fetch_service_ids(team_ids=context["team_ids"])
            context["service_ids"] = [
                str(sid).strip() for sid in service_ids if sid and str(sid).strip()
            ]

        escalation_policy_ids = escalation_policies.fetch_escalation_policy_ids(
            user_id=context["user_id"]
        )
        context["escalation_policy_ids"] = [
            str(epid).strip()
            for epid in escalation_policy_ids
            if epid and str(epid).strip()
        ]

        return context

    except Exception as e:
        utils.handle_api_error(e)

src/pagerduty_mcp_server/server.py:420-437 (registration)

Registration of the MCP tool 'build_user_context' via @mcp.tool() decorator. Includes output format documentation (acts as schema) and thin wrapper delegating to users.build_user_context().

@mcp.tool()
def build_user_context() -> Dict[str, Any]:
    """Validate and build the current user's context into a dictionary with the following format:
        {
            "user_id": str,
            "team_ids": List[str],
            "service_ids": List[str],
            "escalation_policy_ids": List[str]
        }
    The MCP server tools use this user context to filter the following resources:
        - Escalation policies
        - Incidents
        - Oncalls
        - Services
        - Users
    """
    return users.build_user_context()

PagerDuty MCP Server