mcp.json

{
  "name": "MCP",
  "access": {
    "anon": "Cannot call MCP tools that require user context.",
    "user": "After authorization, can call personal workspace-related tools.",
    "admin": "Currently does not automatically gain additional MCP admin tools due to admin status.",
    "agent": "MCP is one of the protocol entry points alongside REST, covering capabilities aligned with the web by default and sharing the same OAuth permission boundary."
  },
  "rules": {
    "personal-workspace-focus": "MCP focuses by default on personal learning workspace, public query, and low-risk personal state write capabilities; admin capabilities are not exposed by default.",
    "text-formatted-json": "Current tool output is uniformly text-formatted JSON.",
    "output-modes": "Output mode has three levels: summary for counts/returned-item totals plus top samples, default for compact structured data, and full for exact raw records. Default is recommended for most agent calls.",
    "coverage": "MCP currently covers profile, todos, courses, sections, teachers, semesters, subscriptions, schedules, calendar events, assistant dashboard snapshots, and bus discovery/next-trip queries; comment, upload, description governance, link management, and admin capabilities do not yet have corresponding tools.",
    "aggregate-before-fanout": "Prefer assistant-oriented aggregate or filtered tools first; raw dataset tools remain available for power clients that need local post-processing.",
    "privacy-safe-summary": "Summary/default outputs may omit repeated low-value nested objects and redact token-bearing URLs or other sensitive strings; full mode is the escape hatch when exact raw values are required.",
    "actionable-errors": "Validation and common not-found payloads prefer plain-language messages and may include a hint that points to the next useful tool or query to recover.",
    "resource-bound-access-token": "MCP transport requests must present a resource-bound Bearer token for /api/mcp. JWT access tokens minted with the canonical public MCP resource URL as the resource indicator are accepted; opaque tokens minted without a resource indicator are rejected because the server cannot prove MCP audience binding from those token records. Refresh-token grants whose stored grant includes mcp:tools are normalized to that MCP resource URL when clients omit the resource parameter.",
    "transport-observability": "MCP transport handling emits production-safe structured request/response logs and bounded metrics with JSON-RPC method summaries, tool names, argument keys, auth/origin phase, status, duration, registered tool count, and per-tool result status/duration; it never logs bearer tokens, cookies, or tool argument values.",
    "flexible-date-inputs": "Date and datetime parameters on MCP tools accept ISO 8601 with timezone offset (2026-05-01T08:00:00+08:00), bare date strings (2026-05-01, treated as UTC midnight for @db.Date columns), or timezone-less datetimes (2026-05-01T08:00:00, interpreted as Asia/Shanghai). Invalid strings produce a descriptive error response rather than a validation rejection.",
    "time-override": "Time-sensitive tools (get_my_7days_timeline, get_upcoming_deadlines, get_my_overview, get_next_buses) accept an optional atTime parameter to anchor their internal clock to a caller-supplied moment instead of the server clock, enabling reproducible queries and future-scenario planning."
  },
  "capabilities": {
    "protocol-endpoint": {
      "title": "Protocol Endpoint",
      "auth": "anon",
      "web": "unavailable",
      "rest": {
        "routes": [
          {
            "path": "/api/mcp",
            "method": "POST",
            "returns": "MCP JSON-RPC response",
            "notes": [
              "All tool calls are handled through this endpoint and require a Bearer token bound to the MCP protected resource /api/mcp; transport handling records bounded in-memory metrics for HTTP phase/status/duration, JSON-RPC method counts, and tool-call counts by tool name.",
              "Trusted browser-origin Bearer-token clients receive CORS headers, including exposed MCP-Session-Id and WWW-Authenticate response headers for browser transports.",
              "Answers browser CORS preflight requests for the MCP transport headers used by POST/DELETE browser clients.",
              "Requests with a foreign Origin header are rejected before MCP auth/tool handling."
            ]
          },
          {
            "path": "/api/mcp",
            "returns": "MCP transport response"
          },
          {
            "path": "/api/mcp",
            "method": "DELETE",
            "returns": "MCP transport response"
          }
        ]
      },
      "display": {
        "fields": [
          "MCP protocol server endpoint",
          "GET/POST/DELETE transport methods",
          "Returns JSON-RPC or transport responses"
        ]
      }
    },
    "tool-groups": {
      "title": "Tool Groups",
      "auth": "anon",
      "mcp": {
        "groups": [
          {
            "name": "Profile & Todo",
            "tools": [
              "get_my_profile",
              "list_my_todos",
              "create_my_todo",
              "update_my_todo",
              "delete_my_todo"
            ]
          },
          {
            "name": "Dashboard & Overview",
            "tools": [
              "get_my_dashboard",
              "get_my_overview",
              "get_next_class",
              "get_upcoming_deadlines"
            ]
          },
          {
            "name": "Course, Section & Semester",
            "tools": [
              "list_semesters",
              "get_current_semester",
              "search_courses",
              "get_course_by_jw_id",
              "search_sections",
              "get_section_by_jw_id",
              "search_teachers",
              "get_teacher_by_id",
              "match_section_codes"
            ]
          },
          {
            "name": "Calendar & Subscription",
            "tools": [
              "list_my_calendar_events",
              "get_my_7days_timeline",
              "get_my_calendar_subscription",
              "list_my_subscribed_sections",
              "subscribe_section_by_jw_id",
              "unsubscribe_section_by_jw_id",
              "get_section_calendar_subscription",
              "subscribe_my_sections_by_codes"
            ]
          },
          {
            "name": "Homework, Schedule & Exam",
            "tools": [
              "list_my_homeworks",
              "set_my_homework_completion",
              "list_my_schedules",
              "list_my_exams",
              "list_homeworks_by_section",
              "create_homework_on_section",
              "update_homework_on_section",
              "query_schedules",
              "list_schedules_by_section",
              "list_exams_by_section"
            ]
          },
          {
            "name": "Bus",
            "tools": [
              "query_bus_timetable",
              "list_bus_routes",
              "get_bus_route_timetable",
              "search_bus_routes",
              "get_next_buses"
            ]
          }
        ]
      },
      "display": {
        "fields": [
          "Schedule tools",
          "Homework tools",
          "Section tools",
          "Tool name",
          "Tool description",
          "Input schema",
          "Preferred tool for common prompts"
        ]
      }
    }
  }
}