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가 적합한 단일 로컬 프로세스 쌍이 아니라, 여러 팀의 AI 애플리케이션이 연결하는 공유된 내부 역량을 위한 것입니다.)

서버가 제공하는 기능

• 도구 4개: search_tickets, get_ticket, add_ticket_note, close_ticket (마지막은 클라이언트 측 사용자 확인(elicitation)을 거쳐야 하는 고영향 작업)

• 리소스 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(읽기 및 쓰기 스코프)으로 연결하고, 발견(discovery)을 실행하며, 도구/리소스/프롬프트를 각각 하나씩 호출합니다. 또한 두 가지 오류 처리 실패 모드(요구사항 8)를 시연하고, 클라이언트 측 사용자 확인(elicitation)을 통해 고위험 close_ticket 작업을 수행한 뒤(요구사항 6), 마지막으로 dev-readonly-token이 쓰기 스코프 도구에서 올바르게 거부되는 최소 권한 데모를 보여줍니다.

보안

자세한 내용은 docs/security-summary.md를 참조하세요. 간단히 요약하면: StaticTokenVerifier를 통한 bearer-token 인증, 도구별 명시적 스코프 검사(개발 중 발견되어 수정된 실제 격차 — 연결 수준의 스코프 요구만으로는 개별 도구 호출을 제한할 수 없음 — 이에 대한 솔직한 설명은 보안 문서에 있습니다), 그리고 ToolError와 mask_error_details=True를 사용해 사용자가 해결할 수 있는 오류와 클라이언트에 원문 그대로 전달되어서는 안 되는 내부 오류를 구분합니다.

요구사항 매핑