prismic_get_documents

Instructions

Implementation Reference

• prismic_content_mcp/server.py:321-360 (handler)

  The core logic function 'handle_prismic_get_documents' that processes the Prismic API requests.

  async def handle_prismic_get_documents(
      *,
      type: str | None = None,
      lang: str | None = None,
      ref: str | None = None,
      page: int = 1,
      page_size: int = 20,
      q: Any | None = None,
      orderings: str | None = None,
      routes: Any | None = None,
      service_factory: ServiceFactory = _build_service,
  ) -> dict[str, Any]:
      """Read documents from the Prismic Content API.
  
      Query behavior:
      - `ref` overrides the default master ref resolution (useful for previews/drafts).
      - `q` is passed directly to the Content API `q` parameter.
        Treat `q` as trusted input only (do not forward untrusted prompt text).
      - If `PRISMIC_DISABLE_RAW_Q=1`, raw `q` is rejected and only server-built
        predicates (for example via `type`) are allowed.
      - `orderings` is passed directly to the Content API `orderings` parameter.
      - `routes` is passed to the Content API `routes` parameter (route resolvers).
      - `type` is a convenience mapping to `[[at(document.type,"<type>")]]`.
      - If both are provided, the type predicate is prepended to `q`.
  
      Effective merge behavior:
      - only `type`: q => [type_predicate]
      - only `q`: q => q (unchanged)
      - `type` + list q: q => [type_predicate, *q]
      - `type` + scalar q: q => [type_predicate, q]
      """
  
      async with service_factory() as service:
          result = await service.get_documents(
              document_type=type,
              lang=lang,
              ref=ref,
              page=page,
              page_size=page_size,
              q=q,

• prismic_content_mcp/server.py:690-726 (registration)

  The tool registration definition 'prismic_get_documents' that exposes the tool to the MCP server.

  @server.tool(name="prismic_get_documents")
  async def prismic_get_documents(
      type: str | None = None,
      lang: str | None = None,
      ref: str | None = None,
      page: int = 1,
      page_size: int = 20,
      q: Any | None = None,
      orderings: str | None = None,
      routes: Any | None = None,
  ) -> dict[str, Any]:
      """List documents with optional Prismic predicate filtering.
  
      Use `ref` to read from an explicit Prismic content ref (for example
      preview/draft refs). When omitted, master ref is used.
      Depending on repository API visibility settings, reading non-master refs
      may require `PRISMIC_CONTENT_API_TOKEN`.
      Use `q` for explicit Content API predicates (for example
      `[[at(document.tags,"news")]]`). `type` is a convenience shortcut
      for `[[at(document.type,"<type>")]]` and is merged into `q`.
      Use `orderings` for native Content API sort clauses (for example
      `[document.first_publication_date desc]`).
      Use `routes` for Content API route resolvers to populate the `url` field
      (for example `[{"type":"page","path":"/:uid"}]`).
      Note: there is no documented Content API `q` predicate for "published
      status". A release `ref` query returns a version snapshot, not only
      release-delta documents.
      Efficiency tips:
      - For large scans: call `prismic_get_refs` once and pass `ref` explicitly.
      - For counts/existence checks: set `page_size=1` and read `total_results`.
      - Only pass `routes` when you need populated `url` fields.
      - Paginate with `page` + `next_page` for full exports.
      Codex js_repl tip: `codex.tool(...)` wraps tool output; read payload from
      `result.Ok.structuredContent`.
      """
      return await handle_prismic_get_documents(
          type=type,