openapi.yaml

openapi: 3.1.0
info:
  title: MikWeb API
  description: |
    Minecraft 服务器 Web 面板公开 API，提供玩家在线状态、历史记录、建筑列表、封禁列表和公告等数据。

    所有 `/api/*` 路由均启用 CORS（`Access-Control-Allow-Origin: *`），支持跨域访问。
  version: 1.0.0

servers:
  - url: https://mik.noctiro.moe/api
    description: 公共实例
  - url: /api
    description: 相对路径（本地开发）

security: []

paths:
  /players/online:
    get:
      summary: 获取在线玩家
      description: 返回当前在线玩家列表及人数。当上游服务不可用时可能降级到第三方查询服务（仅返回人数）。
      operationId: getPlayersOnline
      responses:
        "200":
          description: 成功
          headers:
            X-Proxy-Cache:
              $ref: "#/components/headers/X-Proxy-Cache"
            X-Proxy-Source:
              $ref: "#/components/headers/X-Proxy-Source"
            X-Cache:
              $ref: "#/components/headers/X-Cache"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlayerOnlinePayload"
        "502":
          $ref: "#/components/responses/UpstreamError"

  /players/history:
    get:
      summary: 获取玩家在线历史
      description: 返回一段时间内的在线人数历史数据，包含峰值、均值等统计摘要。
      operationId: getPlayersHistory
      parameters:
        - name: from
          in: query
          description: 查询起始时间（ISO 8601 格式）
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: 查询截止时间（ISO 8601 格式）。若为过去时间则响应可被缓存 300 秒。
          required: false
          schema:
            type: string
            format: date-time
        - name: interval
          in: query
          description: 数据采样间隔（秒）
          required: false
          schema:
            type: integer
            minimum: 120
      responses:
        "200":
          description: 成功
          headers:
            X-Proxy-Cache:
              $ref: "#/components/headers/X-Proxy-Cache"
            X-Proxy-Source:
              $ref: "#/components/headers/X-Proxy-Source"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlayersHistoryPayload"
        "502":
          $ref: "#/components/responses/UpstreamError"

  /players/{uuid}/history:
    get:
      summary: 获取单个玩家的会话历史
      description: 返回指定玩家的登录会话记录及统计信息。所有查询参数会被透传到上游服务。
      operationId: getPlayerHistory
      parameters:
        - name: uuid
          in: path
          required: true
          description: 玩家 UUID
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: 成功
          headers:
            X-Proxy-Cache:
              $ref: "#/components/headers/X-Proxy-Cache"
            X-Proxy-Source:
              $ref: "#/components/headers/X-Proxy-Source"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlayerHistoryPayload"
        "502":
          $ref: "#/components/responses/UpstreamError"

  /buildings:
    get:
      summary: 获取建筑列表
      description: 返回服务器中所有已登记建筑的详细信息，包含坐标、建造者、标签等。
      operationId: getBuildings
      responses:
        "200":
          description: 成功
          headers:
            X-Proxy-Cache:
              $ref: "#/components/headers/X-Proxy-Cache"
            X-Proxy-Source:
              $ref: "#/components/headers/X-Proxy-Source"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Building"
        "502":
          $ref: "#/components/responses/UpstreamError"

  /bans:
    get:
      summary: 获取封禁列表
      description: 返回当前所有被封禁玩家的记录。
      operationId: getBans
      responses:
        "200":
          description: 成功
          headers:
            X-Proxy-Cache:
              $ref: "#/components/headers/X-Proxy-Cache"
            X-Proxy-Source:
              $ref: "#/components/headers/X-Proxy-Source"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BanItem"
        "502":
          $ref: "#/components/responses/UpstreamError"

  /announcements:
    get:
      summary: 获取公告列表
      description: 返回服务器公告。
      operationId: getAnnouncements
      responses:
        "200":
          description: 成功
          headers:
            X-Proxy-Cache:
              $ref: "#/components/headers/X-Proxy-Cache"
            X-Proxy-Source:
              $ref: "#/components/headers/X-Proxy-Source"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AnnouncementItem"
        "502":
          $ref: "#/components/responses/UpstreamError"

  /mcp:
    get:
      summary: MCP SSE 端点
      description: Model Context Protocol 服务端点（Server-Sent Events 传输）。提供 get_players、get_buildings、get_bans、get_announcements、search_wiki 等工具。
      operationId: mcpGet
      responses:
        "200":
          description: SSE 流
          content:
            text/event-stream: {}
    post:
      summary: MCP 消息端点
      description: Model Context Protocol 消息端点，用于接收客户端发送的 JSON-RPC 消息。
      operationId: mcpPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: JSON-RPC 响应
          content:
            application/json:
              schema:
                type: object

components:
  headers:
    X-Proxy-Cache:
      description: 代理缓存状态
      schema:
        type: string
        enum: [MISS, HIT, STALE, COALESCED]
    X-Proxy-Source:
      description: 数据来源
      schema:
        type: string
        enum: [UPSTREAM, FALLBACK]
    X-Cache:
      description: 当数据来自降级源时设置为 FALLBACK
      schema:
        type: string
        enum: [FALLBACK]

  responses:
    UpstreamError:
      description: 上游服务不可用
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error:
                type: string

  schemas:
    PlayerOnlinePayload:
      type: object
      required: [online, players]
      properties:
        online:
          type: integer
          description: 当前在线人数。-1 表示服务器离线（降级查询失败）。
        players:
          type: array
          items:
            $ref: "#/components/schemas/OnlinePlayer"

    OnlinePlayer:
      type: object
      required: [name, uuid, joined_at]
      properties:
        name:
          type: string
        uuid:
          type: string
          format: uuid
        joined_at:
          type: string
          format: date-time
          description: 本次登录时间

    PlayersHistoryPayload:
      type: object
      required: [meta, summary, data]
      properties:
        meta:
          $ref: "#/components/schemas/PlayersHistoryMeta"
        summary:
          $ref: "#/components/schemas/PlayersHistorySummary"
        data:
          type: array
          items:
            $ref: "#/components/schemas/PlayersHistoryPoint"

    PlayersHistoryMeta:
      type: object
      required: [from, to, interval, total_points]
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        interval:
          oneOf:
            - type: integer
            - type: string
          description: 数据点间隔（秒数或描述字符串）
        total_points:
          type: integer

    PlayersHistorySummary:
      type: object
      required: [peak_online, peak_time, avg_online, total_unique_players]
      properties:
        peak_online:
          type: integer
        peak_time:
          type: ["string", "null"]
          format: date-time
        avg_online:
          type: number
        total_unique_players:
          type: integer

    PlayersHistoryPoint:
      type: object
      required: [timestamp, online, players]
      properties:
        timestamp:
          type: string
          format: date-time
        online:
          type: integer
        players:
          type: array
          items:
            type: string
          description: 该时间点在线玩家的名称列表

    PlayerHistoryPayload:
      type: object
      required: [uuid, name, sessions, stats]
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/PlayerSession"
        stats:
          $ref: "#/components/schemas/PlayerHistoryStats"

    PlayerSession:
      type: object
      required: [joined_at, left_at]
      properties:
        joined_at:
          type: string
          format: date-time
        left_at:
          type: ["string", "null"]
          format: date-time
        duration_min:
          type: number
          description: 会话时长（分钟），可能不存在

    PlayerHistoryStats:
      type: object
      required: [total_sessions, total_hours, first_seen]
      properties:
        total_sessions:
          type: integer
        total_hours:
          type: number
        first_seen:
          type: ["string", "null"]
          format: date-time

    Building:
      type: object
      required:
        - name
        - description
        - coordinates
        - builders
        - buildType
        - images
        - buildDate
      properties:
        name:
          $ref: "#/components/schemas/LocalizedText"
        description:
          $ref: "#/components/schemas/LocalizedText"
        coordinates:
          $ref: "#/components/schemas/Coordinates"
        builders:
          type: array
          items:
            $ref: "#/components/schemas/Builder"
        buildType:
          type: string
          enum: [original, derivative, replica]
        images:
          type: array
          items:
            type: string
        buildDate:
          type: string
          description: 建造日期
        tags:
          type: array
          items:
            $ref: "#/components/schemas/LocalizedText"
        source:
          $ref: "#/components/schemas/BuildingSource"

    LocalizedText:
      type: object
      additionalProperties:
        type: string
      description: "键为 locale（如 zh-CN、en），值为对应语言的文本"
      example:
        zh-CN: 示例文本
        en: Example text

    Coordinates:
      type: object
      required: [x, y, z]
      properties:
        x:
          type: number
        y:
          type: number
        z:
          type: number
      description: Minecraft 世界坐标

    Builder:
      type: object
      required: [name, uuid, weight]
      properties:
        name:
          type: string
        uuid:
          type: string
          format: uuid
        weight:
          type: number
          description: 贡献权重，用于计算贡献百分比

    BuildingSource:
      type: ["object", "null"]
      properties:
        originalAuthor:
          type: string
        originalLink:
          type: string
          format: uri
        notes:
          $ref: "#/components/schemas/LocalizedText"

    BanItem:
      type: object
      required:
        - playerName
        - playerUuid
        - reason
        - bannedBy
        - bannedAt
        - expiresAt
        - isPermanent
      properties:
        playerName:
          type: string
        playerUuid:
          type: string
          format: uuid
        reason:
          type: string
        bannedBy:
          type: string
        bannedAt:
          type: string
          format: date-time
        expiresAt:
          type: ["string", "null"]
          format: date-time
        isPermanent:
          type: boolean

    AnnouncementItem:
      type: object
      required: [content, timestamp]
      properties:
        content:
          type: string
        timestamp:
          type: string
          format: date-time