TicketDesk MCP — Servidor y cliente MCP de estilo producción

Un servidor del Model Context Protocol (MCP) que expone una cola interna de tickets de soporte, junto con un cliente que descubre e invoca sus herramientas, recursos y prompts. Construido para el laboratorio «Build a Production MCP Server & Client» (Módulo 4, Model Context Protocol).

Contenidos

• Arquitectura

• Configuración y ejecución de la demo

• docs/tools-resources-prompts.md — qué expone el servidor

• docs/architecture.md — elección del transporte y justificación

• docs/security-summary.md — autenticación, mínimo privilegio y gestión de errores

• demo/session_log.txt — una ejecución real capturada de descubrimiento e invocación

Related MCP server: TicketAI

Arquitectura

flowchart TD
    HOST["Host application\n(e.g. an AI assistant / chatbot)"] --> CLIENT

    subgraph Client["client.py — fastmcp.Client"]
        CLIENT["Discovery: list_tools / list_resources /\nlist_resource_templates / list_prompts"]
        ELICIT["elicitation_handler\n(client-side safety gate for\nhigh-impact actions)"]
        CLIENT <--> ELICIT
    end

    CLIENT <-->|"Streamable HTTP\nAuthorization: Bearer <token>"| SERVER

    subgraph Server["server.py — FastMCP('TicketDesk')"]
        AUTH["StaticTokenVerifier\n(read:tickets / write:tickets scopes)"]
        TOOLS["Tools: search_tickets, get_ticket,\nadd_ticket_note, close_ticket"]
        RES["Resources: ticket://{ticket_id},\npolicy://sla"]
        PROMPT["Prompt: triage_ticket"]
        AUTH --> TOOLS
        AUTH --> RES
        AUTH --> PROMPT
    end

    SERVER --> DATA[("data/tickets.json,\ndata/sla_policy.md")]

Transporte: Streamable HTTP — justificado en docs/architecture.md (versión breve: está pensado como una capacidad interna compartida a la que se conectan las aplicaciones de IA de varios equipos, no como un par de procesos locales único, que es el uso para el que está pensado stdio).

Qué expone el servidor

• 4 herramientas: search_tickets, get_ticket, add_ticket_note, close_ticket (la última es una acción de alto impacto restringida por elicitación en el lado del cliente)

• 2 recursos: ticket://{ticket_id} (con plantilla) y policy://sla (estático)

• 1 prompt: triage_ticket

Documentación completa de cada elemento: docs/tools-resources-prompts.md.

Configuración y ejecución de la demo

pip install -r requirements.txt

# Terminal 1
python server.py

# Terminal 2
python client.py                # interactive: real confirmation prompts via input()
python client.py --auto-confirm # non-interactive demo mode (used to produce demo/session_log.txt)

client.py se conecta con dev-agent-token (alcances de lectura y escritura), ejecuta el descubrimiento, invoca una de cada herramienta/recurso/prompt, demuestra ambos modos de fallo de la gestión de errores (Requisito 8), realiza la acción de alto impacto close_ticket mediante elicitación en el lado del cliente (Requisito 6) y concluye con una demo de mínimo privilegio que muestra cómo dev-readonly-token es rechazado correctamente de una herramienta con alcance de escritura.

Seguridad

Documento completo: docs/security-summary.md. Versión breve: autenticación por token de portador (bearer) mediante StaticTokenVerifier, comprobaciones de alcance explícitas por herramienta (se detectó y corrigió una brecha real durante el desarrollo: los requisitos de alcance a nivel de conexión, por sí solos, no restringen las llamadas individuales a herramientas; consulta el documento de seguridad para conocer la explicación honesta) y ToolError + mask_error_details=True para distinguir los errores sobre los que el usuario puede actuar de los fallos internos que nunca deben llegar al cliente tal cual.

Correspondencia de requisitos