#!/usr/bin/env python3
"""
CCA-F P5: Custom MCP server using the official Python SDK (FastMCP).

Transport: stdio (default) — used by Claude Code via .mcp.json
Auth: MCP_API_KEY environment variable
"""

from __future__ import annotations

import os
from typing import Any

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("cca-f-tools")

# In-memory fixtures for exam scenario drills (no external API required)
_TICKETS: dict[str, dict[str, str]] = {
    "TCK-1001": {
        "status": "open",
        "subject": "Billing discrepancy",
        "customer": "acme-corp",
    },
    "TCK-1002": {
        "status": "resolved",
        "subject": "Password reset",
        "customer": "user-42",
    },
}

_DOCS: list[dict[str, str]] = [
    {
        "id": "KB-001",
        "title": "Refund policy",
        "snippet": "Refunds within 30 days with receipt.",
    },
    {
        "id": "KB-002",
        "title": "MCP transport guide",
        "snippet": "Use stdio for local Claude Code; HTTP/SSE for remote shared servers.",
    },
    {
        "id": "KB-003",
        "title": "Escalation criteria",
        "snippet": "Escalate when confidence below 0.7 or customer requests human agent.",
    },
]


def _require_api_key(provided: str | None) -> None:
    expected = os.environ.get("MCP_API_KEY", "")
    if not expected:
        raise PermissionError("MCP_API_KEY not configured on server")
    if not provided or provided != expected:
        raise PermissionError("Invalid or missing api_key")


@mcp.tool()
def health_check(api_key: str) -> dict[str, str]:
    """
    Verify server is running and API key authentication works.
    Call this before other tools to confirm connectivity.

    Args:
        api_key: Must match MCP_API_KEY environment variable on the server.
    """
    _require_api_key(api_key)
    return {"status": "ok", "server": "cca-f-tools", "transport": "stdio"}


@mcp.tool()
def lookup_ticket(ticket_id: str, api_key: str) -> dict[str, Any]:
    """
    Look up a customer support ticket by ID.
    Use for order/account support scenarios. Returns structured ticket data.

    Args:
        ticket_id: Ticket identifier e.g. TCK-1001
        api_key: Must match MCP_API_KEY environment variable on the server.
    """
    _require_api_key(api_key)
    ticket = _TICKETS.get(ticket_id.upper())
    if not ticket:
        return {
            "found": False,
            "ticket_id": ticket_id,
            "error": "Ticket not found",
        }
    return {"found": True, "ticket_id": ticket_id.upper(), **ticket}


@mcp.tool()
def search_docs(query: str, api_key: str, limit: int = 3) -> dict[str, Any]:
    """
    Search the knowledge base for support and architecture documentation.
    Returns top matching snippets for RAG-style grounding.

    Args:
        query: Search terms
        api_key: Must match MCP_API_KEY environment variable on the server.
        limit: Maximum results (1-5)
    """
    _require_api_key(api_key)
    limit = max(1, min(5, limit))
    q = query.lower()
    matches = [
        doc
        for doc in _DOCS
        if q in doc["title"].lower() or q in doc["snippet"].lower()
    ]
    if not matches:
        matches = _DOCS[:limit]
    return {"query": query, "results": matches[:limit], "count": len(matches[:limit])}


@mcp.tool()
def create_escalation(
    ticket_id: str,
    reason: str,
    priority: str,
    api_key: str,
) -> dict[str, str]:
    """
    Escalate a support ticket to a human specialist.
    Use when automated resolution fails or customer requests escalation.

    Args:
        ticket_id: Existing ticket ID
        reason: Structured escalation reason (specific, not vague)
        priority: One of low, normal, high
        api_key: Must match MCP_API_KEY environment variable on the server.
    """
    _require_api_key(api_key)
    if priority not in {"low", "normal", "high"}:
        raise ValueError("priority must be low, normal, or high")
    if len(reason.strip()) < 10:
        raise ValueError("reason must be at least 10 characters — be specific")
    return {
        "escalation_id": f"ESC-{ticket_id}",
        "ticket_id": ticket_id,
        "priority": priority,
        "status": "queued_for_human",
    }


if __name__ == "__main__":
    mcp.run()