TicketDesk MCP — MCP-сервер и клиент производственного уровня

Сервер на базе Model Context Protocol (MCP), предоставляющий доступ к внутренней очереди заявок службы поддержки, в паре с клиентом, который обнаруживает и вызывает его инструменты, ресурсы и промпты. Создан для лабораторной работы «Build a Production MCP Server & Client» (Module 4, Model Context Protocol).

Содержание

• Архитектура

• Настройка и запуск демонстрации

• docs/tools-resources-prompts.md — что предоставляет сервер

• docs/architecture.md — выбор транспорта и его обоснование

• docs/security-summary.md — аутентификация, минимальные привилегии, обработка ошибок

• demo/session_log.txt — реальный записанный сеанс обнаружения и вызова

Related MCP server: TicketAI

Архитектура

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")]

Транспорт: Streamable HTTP — обоснование приведено в docs/architecture.md (если коротко: это общий внутренний сервис, к которому подключаются ИИ-приложения нескольких команд, а не одна пара локальных процессов, для которой подходит stdio).

Что предоставляет сервер

• 4 инструмента: search_tickets, get_ticket, add_ticket_note, close_ticket (последний — действие с высоким уровнем влияния, защищённое запросом подтверждения на стороне клиента)

• 2 ресурса: ticket://{ticket_id} (шаблонный) и policy://sla (статический)

• 1 промпт: triage_ticket

Полная документация по каждому элементу: docs/tools-resources-prompts.md.

Настройка и запуск демонстрации

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 подключается с токеном dev-agent-token (права на чтение и запись), выполняет обнаружение, вызывает по одному представителю каждого инструмента/ресурса/промпта, демонстрирует оба режима обработки ошибок (Требование 8), выполняет действие с высоким влиянием close_ticket через запрос подтверждения на стороне клиента (Требование 6) и завершается демонстрацией наименьших привилегий: dev-readonly-token корректно получает отказ в инструменте с правом на запись.

Безопасность

Полное описание: docs/security-summary.md. Если коротко: аутентификация по bearer-токену через StaticTokenVerifier, явные проверки прав (scope) для каждого инструмента (реальный пробел — требований к scope на уровне соединения сами по себе не ограничивают вызовы отдельных инструментов — был обнаружен и исправлен в процессе разработки; честное изложение — в документе по безопасности), а также ToolError + mask_error_details=True, чтобы отделять ошибки, на которые пользователь может отреагировать, от внутренних сбоев, которые никогда не должны доходить до клиента в исходном виде.

Соответствие требованиям