openapi: 3.1.0
info:
  title: Dewey MCP
  version: '0.1'
  summary: FastMCP server exposing read-only search over the Inquirer archive.
  description: >-
    Dewey MCP is a containerized FastMCP server for read-only search over a
    news archive backed by Azure AI Search. It exposes a single MCP tool,
    `search_archive`, that accepts a search query plus optional date and
    author filters and returns ranked article chunks with metadata. The
    server is open source under `phillymedia/dewey-mcp` and is the protocol
    surface for the broader Dewey AI librarian project (Lenfest Institute
    fellowship, supported by Microsoft and OpenAI). This OpenAPI describes
    the server's HTTP envelope (MCP protocol endpoint, liveness, and
    readiness probes); the MCP tool itself is described in `components.schemas`.
  contact:
    name: Dewey MCP
    url: https://github.com/phillymedia/dewey-mcp
servers:
- url: http://127.0.0.1:8000
  description: Default local server (configurable via MCP_HOST and MCP_PORT)
tags:
- name: MCP
  description: Model Context Protocol surface.
- name: Health
  description: Liveness and readiness probes.
paths:
  /mcp:
    post:
      operationId: postMcp
      summary: Invoke MCP Protocol
      description: MCP protocol endpoint. Path is configurable via
        `MCP_PATH` (default `/mcp`). Exposes the `search_archive` tool.
      tags:
      - MCP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: MCP JSON-RPC envelope.
      responses:
        '200':
          description: MCP JSON-RPC response envelope.
          content:
            application/json:
              schema:
                type: object
  /livez:
    get:
      operationId: getLiveness
      summary: Get Liveness Probe
      description: Returns process liveness status.
      tags:
      - Health
      responses:
        '200':
          description: Process is alive.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /readyz:
    get:
      operationId: getReadiness
      summary: Get Readiness Probe
      description: Returns readiness status; ready when the configured
        Azure AI Search index is reachable.
      tags:
      - Health
      responses:
        '200':
          description: Service is ready to serve search traffic.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ready
        '503':
          description: Service is not ready (Azure AI Search unreachable).
components:
  schemas:
    SearchArchiveRequest:
      type: object
      description: Input for the `search_archive` MCP tool.
      properties:
        search_text:
          type: string
          description: Search query. Use `*` with filters only.
        filters:
          type: array
          description: Optional list of filter clauses.
          items:
            type: object
            properties:
              field:
                type: string
                description: Field to filter on (e.g. author, published_date).
              start:
                type: string
                format: date-time
                description: Inclusive start of a date range.
              end:
                type: string
                format: date-time
                description: Inclusive end of a date range.
              value:
                type: string
                description: Exact value for equality filters.
        limit:
          type: integer
          default: 10
          maximum: 20
          description: Number of results to return (max 20).
      required:
      - search_text
    SearchArchiveResult:
      type: object
      description: A single ranked article chunk returned by `search_archive`.
      properties:
        chunk_id:
          type: string
        article_id:
          type: string
        title:
          type: string
        published_date:
          type: string
          format: date-time
        author:
          type: string
        link:
          type: string
          format: uri
        chunk_text:
          type: string
        score:
          type: number
          format: float