"""`docs/handlers/elicitation.md`: every claim the page makes, proved against the real SDK."""

from typing import Literal

import pytest
from inline_snapshot import snapshot
from mcp_types import (
    ElicitCompleteNotification,
    ElicitRequestFormParams,
    ElicitRequestParams,
    ElicitRequestURLParams,
    ElicitResult,
    TextContent,
)
from pydantic import BaseModel

from docs_src.elicitation import tutorial001, tutorial002, tutorial003, tutorial004
from mcp import Client, MCPError
from mcp.client import ClientRequestContext
from mcp.server import MCPServer
from mcp.server.mcpserver import Context

# See test_index.py for why this is a per-module mark and not a conftest hook.
pytestmark = [pytest.mark.anyio, pytest.mark.filterwarnings("error::mcp.MCPDeprecationWarning")]


async def test_an_accepted_answer_resumes_the_tool() -> None:
    """tutorial001: the user's answer comes back into the same call as a validated model."""

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        return ElicitResult(action="accept", content={"accept_alternative": True, "date": "2025-12-26"})

    async with Client(tutorial001.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
        result = await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})
        assert not result.is_error
        assert result.content == [TextContent(type="text", text="Booked a table for 2 on 2025-12-26.")]


async def test_an_alternative_that_is_also_full_is_asked_about_again() -> None:
    """tutorial001: the accepted date goes back through `book_table`, so a full date is re-asked, not booked."""
    asked: list[str] = []

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        asked.append(params.message)
        date = "2025-12-25" if len(asked) == 1 else "2025-12-27"
        return ElicitResult(action="accept", content={"accept_alternative": True, "date": date})

    async with Client(tutorial001.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
        result = await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})
    assert result.content == [TextContent(type="text", text="Booked a table for 2 on 2025-12-27.")]
    assert asked == [
        "No tables for 2 on 2025-12-25. Would you like to try another date?",
        "No tables for 2 on 2025-12-25. Would you like to try another date?",
    ]


async def test_the_client_receives_the_message_and_the_generated_schema() -> None:
    """tutorial001: form mode sends your message plus a JSON Schema built from the Pydantic model."""
    received: list[ElicitRequestParams] = []

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        received.append(params)
        return ElicitResult(action="accept", content={"accept_alternative": False})

    async with Client(tutorial001.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
        await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})
    (params,) = received
    assert isinstance(params, ElicitRequestFormParams)
    assert params.message == "No tables for 2 on 2025-12-25. Would you like to try another date?"
    assert params.requested_schema == snapshot(
        {
            "properties": {
                "accept_alternative": {
                    "description": "Try another date?",
                    "title": "Accept Alternative",
                    "type": "boolean",
                },
                "date": {
                    "default": "2025-12-26",
                    "description": "Alternative date (YYYY-MM-DD)",
                    "title": "Date",
                    "type": "string",
                },
            },
            "required": ["accept_alternative"],
            "title": "AlternativeDate",
            "type": "object",
        }
    )


async def test_decline_and_cancel_are_ordinary_return_values() -> None:
    """tutorial001: a refusal is not an error; the tool sees the action and answers the model normally."""

    async def on_decline(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        return ElicitResult(action="decline")

    async def on_cancel(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        return ElicitResult(action="cancel")

    async with Client(tutorial001.mcp, mode="legacy", elicitation_callback=on_decline) as client:
        declined = await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})
    async with Client(tutorial001.mcp, mode="legacy", elicitation_callback=on_cancel) as client:
        cancelled = await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})
    assert declined.content == [TextContent(type="text", text="No booking made.")]
    assert not declined.is_error
    assert cancelled.content == [TextContent(type="text", text="No booking made.")]


async def test_a_tool_that_does_not_ask_needs_nothing_from_the_client() -> None:
    """tutorial001: the elicitation only happens on the path that needs it."""
    async with Client(tutorial001.mcp, mode="legacy") as client:
        result = await client.call_tool("book_table", {"date": "2025-12-30", "party_size": 4})
        assert result.content == [TextContent(type="text", text="Booked a table for 4 on 2025-12-30.")]


async def test_an_answer_that_does_not_match_the_schema_never_reaches_the_tool_code() -> None:
    """`!!! tip`: the client's content is validated against the model; a mismatch fails the call."""

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        return ElicitResult(action="accept", content={"accept_alternative": "maybe"})

    async with Client(tutorial001.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
        result = await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})
    assert result.is_error
    assert isinstance(result.content[0], TextContent)
    assert "does not match the requested schema" in result.content[0].text


class Address(BaseModel):
    city: str


class Applicant(BaseModel):
    name: str
    address: Address


class Seating(BaseModel):
    area: Literal["inside", "terrace"]


schema_gate_server = MCPServer("Bistro")
"""The `!!! warning` claims: what the elicitation schema gate accepts and rejects."""


@schema_gate_server.tool()
async def sign_up(ctx: Context) -> str:
    """Collect the new customer's details."""
    return str(await ctx.elicit(message="Who are you?", schema=Applicant))


@schema_gate_server.tool()
async def choose_seating(ctx: Context) -> str:
    """Ask where the party wants to sit."""
    result = await ctx.elicit(message="Where would you like to sit?", schema=Seating)
    assert result.action == "accept"
    return result.data.area


async def test_a_nested_model_is_rejected_before_anything_is_sent() -> None:
    """`!!! warning`: a non-primitive field raises `TypeError` inside `ctx.elicit`, with this exact message."""
    async with Client(schema_gate_server, mode="legacy") as client:
        result = await client.call_tool("sign_up", {})
    assert result.is_error
    assert isinstance(result.content[0], TextContent)
    assert result.content[0].text == (
        "Error executing tool sign_up: Elicitation schema field 'address' rendered as "
        "{'$ref': '#/$defs/Address'}, which is not a valid PrimitiveSchemaDefinition"
    )


async def test_a_literal_field_passes_the_gate_as_an_enum() -> None:
    """`!!! warning`: a `Literal[...]` of strings renders as a JSON Schema `enum`, which the spec allows."""
    received: list[ElicitRequestParams] = []

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        received.append(params)
        return ElicitResult(action="accept", content={"area": "terrace"})

    async with Client(schema_gate_server, mode="legacy", elicitation_callback=on_elicit) as client:
        result = await client.call_tool("choose_seating", {})
    assert result.content == [TextContent(type="text", text="terrace")]
    (params,) = received
    assert isinstance(params, ElicitRequestFormParams)
    assert params.requested_schema["properties"]["area"] == snapshot(
        {"enum": ["inside", "terrace"], "title": "Area", "type": "string"}
    )


async def test_url_mode_sends_a_url_and_gets_consent_back_not_data() -> None:
    """tutorial002: the client receives the URL and the elicitation id; only the action comes back."""
    received: list[ElicitRequestParams] = []

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        received.append(params)
        return ElicitResult(action="accept")

    async with Client(tutorial002.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
        result = await client.call_tool("pay_deposit", {"booking_id": "b42"})
    assert result.content == [TextContent(type="text", text="Complete the payment in your browser.")]
    (params,) = received
    assert isinstance(params, ElicitRequestURLParams)
    assert params.url == "https://pay.example.com/deposit/b42"
    assert params.elicitation_id == "deposit-b42"


async def test_a_declined_url_elicitation_is_an_ordinary_return_value() -> None:
    """tutorial002: the tool decides what a refusal means."""

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        return ElicitResult(action="decline")

    async with Client(tutorial002.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
        result = await client.call_tool("pay_deposit", {"booking_id": "b42"})
    assert result.content == [TextContent(type="text", text="No deposit taken. The booking expires in one hour.")]


async def test_send_elicit_complete_notifies_the_client_with_the_same_id() -> None:
    """tutorial002: `send_elicit_complete` emits `notifications/elicitation/complete`."""
    notifications: list[object] = []

    async def on_message(message: object) -> None:
        notifications.append(message)

    async with Client(tutorial002.mcp, mode="legacy", message_handler=on_message) as client:
        result = await client.call_tool("confirm_deposit", {"booking_id": "b42"})
    assert result.content == [TextContent(type="text", text="Deposit received for booking b42.")]
    (notification,) = notifications
    assert isinstance(notification, ElicitCompleteNotification)
    assert notification.params.elicitation_id == "deposit-b42"


async def test_the_docs_client_callback_handles_both_modes() -> None:
    """tutorial003: one `elicitation_callback` answers the form and the URL consent."""
    async with Client(tutorial001.mcp, mode="legacy", elicitation_callback=tutorial003.handle_elicitation) as client:
        booked = await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})
    async with Client(tutorial002.mcp, mode="legacy", elicitation_callback=tutorial003.handle_elicitation) as client:
        paid = await client.call_tool("pay_deposit", {"booking_id": "b42"})
    assert booked.content == [TextContent(type="text", text="Booked a table for 2 on 2025-12-27.")]
    assert paid.content == [TextContent(type="text", text="Complete the payment in your browser.")]


async def test_a_client_without_the_callback_cannot_be_asked() -> None:
    """`!!! check`: no `elicitation_callback` means no `elicitation` capability; the call is a protocol error."""
    async with Client(tutorial001.mcp, mode="legacy") as client:
        with pytest.raises(MCPError, match="Elicitation not supported"):
            await client.call_tool("book_table", {"date": "2025-12-25", "party_size": 2})


async def test_resolver_asks_only_when_the_folder_is_not_empty() -> None:
    """tutorial004: `confirm_delete` resolves an empty folder directly and elicits otherwise."""
    tutorial004._FOLDERS.update({"/tmp/empty": [], "/tmp/project": ["main.py", "README.md"]})
    asked: list[str] = []

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        assert isinstance(params, ElicitRequestFormParams)
        asked.append(params.message)
        return ElicitResult(action="accept", content={"ok": True})

    async with Client(tutorial004.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
        empty = await client.call_tool("delete_folder", {"path": "/tmp/empty"})
        non_empty = await client.call_tool("delete_folder", {"path": "/tmp/project"})

    assert empty.content == [TextContent(type="text", text="deleted /tmp/empty")]
    assert non_empty.content == [TextContent(type="text", text="deleted /tmp/project")]
    assert asked == ["/tmp/project has 2 file(s). Delete anyway?"]  # the empty folder was not queried


async def test_the_resolved_parameter_is_hidden_from_the_tool_schema() -> None:
    """tutorial004: the `Resolve`-filled parameter never appears in the client-facing input schema."""
    async with Client(tutorial004.mcp, mode="legacy") as client:
        (tool,) = (await client.list_tools()).tools
        assert tool.name == "delete_folder"
        assert set(tool.input_schema["properties"]) == {"path"}


@pytest.mark.parametrize(
    ("action", "content", "expected"),
    [
        ("accept", {"ok": False}, "kept the folder"),
        ("decline", None, "declined: folder not deleted"),
        ("cancel", None, "cancelled: folder not deleted"),
    ],
)
async def test_the_tool_branches_on_every_elicitation_outcome(
    action: Literal["accept", "decline", "cancel"],
    content: dict[str, str | int | float | bool | list[str] | None] | None,
    expected: str,
) -> None:
    """tutorial004: annotating the result union lets the tool handle accept/decline/cancel."""
    tutorial004._FOLDERS["/tmp/project"] = ["main.py", "README.md"]

    async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
        return ElicitResult(action=action, content=content)

    async with Client(tutorial004.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
        result = await client.call_tool("delete_folder", {"path": "/tmp/project"})
    assert result.content == [TextContent(type="text", text=expected)]