Skip to main content

PageServe

Python SDK and MCP server for PageIndex — the self-hosted, reasoning-based RAG engine.

PyPI version Python versions License Checked with mypy Ruff

Installation · Quick Start · MCP Server · CLI · Documentation


PageServe is a typed, batteries-included client for PageIndex, a reasoning-based RAG engine that navigates document structure instead of doing vector similarity search. It reads the table of contents, picks the right sections, and synthesizes answers with page-level citations — no embeddings, no vector database, no chunking heuristics.

One install gives you three ways to talk to your PageIndex deployment:

  • 🐍 A Python SDK — synchronous and asynchronous clients, fully typed with Pydantic models.
  • 🤖 An MCP server — drop your documents into Claude Desktop, Cursor, or any MCP-compatible agent.
  • ⌨️ A CLI — query, upload, and manage documents straight from the terminal.

Features

  • Vector-free retrieval — answers come with exact page references (Employment Contract p.5, 6), not opaque similarity scores.
  • Query or retrieve — query() synthesizes an answer; retrieve() returns the raw section content (cheaper, ideal for your own prompts).
  • Sync & async — PageServeClient and AsyncPageServeClient, including concurrent query_many.
  • Streaming — token-by-token responses over Server-Sent Events.
  • Model Context Protocol — expose your corpus to LLM agents with keys kept out of the model's context.
  • Fully typed — Pydantic v2 models and strict, descriptive exceptions for every failure mode.
  • Minimal core — only httpx and pydantic required; MCP and CLI are opt-in extras.

Installation

pip install pageserve              # SDK only (sync + async)
pip install "pageserve[mcp]"       # + MCP server for agent frameworks
pip install "pageserve[cli]"       # + CLI commands
pip install "pageserve[all]"       # everything

Requires Python 3.10+.

Quick Start

from pageserve import PageServeClient

client = PageServeClient(
    base_url   = "https://pageindex.company.com",
    public_key = "<your-public-key>",
    secret_key = "<your-secret-key>",
)

# List indexed documents
docs = client.list_documents()

# Ask a question
result = client.query(docs[0].doc_id, "What are the probation terms?")
print(result.answer)
print(result.citation)   # "Employment Contract p.5, 6"
print(result.page_refs)  # [5, 6]

# Or retrieve the raw source sections without synthesizing an answer (cheaper)
retrieved = client.retrieve(docs[0].doc_id, "What are the probation terms?")
print(retrieved.text)    # all relevant section text, ready to drop into a prompt

# Upload and wait for indexing to complete
upload = client.upload("./contract.pdf", wait=True)

# Read specific pages (no LLM, instant)
pages = client.get_pages(docs[0].doc_id, "22-24")

Async Usage

import asyncio
from pageserve import AsyncPageServeClient

async def main():
    async with AsyncPageServeClient(
        base_url   = "https://pageindex.company.com",
        public_key = "<your-public-key>",
        secret_key = "<your-secret-key>",
    ) as client:
        docs = await client.list_documents()

        # Query multiple documents concurrently
        results = await client.query_many([
            (docs[0].doc_id, "What are the probation terms?"),
            (docs[1].doc_id, "What does the law say about probation?"),
        ])
        for r in results:
            print(r.answer)

asyncio.run(main())

Streaming

for event in client.query_stream(doc_id, "What are the key clauses?"):
    if event.type == "token":
        print(event.content, end="", flush=True)
    elif event.type == "sources":
        for src in event.sources:
            print(f"\nSource: {src.citation}")
    elif event.type == "done":
        break

MCP Server

Run the MCP server so Claude Desktop, Cursor, or any MCP-compatible agent can query your documents:

{
  "mcpServers": {
    "pageindex": {
      "command": "pageserve",
      "args": ["mcp"],
      "env": {
        "PAGESERVE_URL":        "https://pageindex.company.com",
        "PAGESERVE_PUBLIC_KEY": "<your-public-key>",
        "PAGESERVE_SECRET_KEY": "<your-secret-key>"
      }
    }
  }
}

The server exposes five tools:

Tool Description
list_documents See what documents are available
retrieve_document Return raw section content (with summaries) for the host to read — no second synthesis pass
get_page_content Read raw page text (no LLM, instant)
get_document_structure Browse the table of contents
get_service_health Check service status and queue

Keys live in environment variables and never appear in tool arguments or the model's context window.

CLI

export PAGESERVE_URL=https://pageindex.company.com
export PAGESERVE_PUBLIC_KEY=<your-public-key>
export PAGESERVE_SECRET_KEY=<your-secret-key>

pageserve list                                      # list documents
pageserve query <doc_id> "question"                 # ask a question
pageserve query <doc_id> "question" --stream        # streaming output
pageserve retrieve <doc_id> "question"              # raw sections, no answer
pageserve upload ./report.pdf --watch               # upload + progress bar
pageserve health                                    # service status
pageserve keys list                                 # list API keys
pageserve keys create "My App"                      # create a key
pageserve mcp                                       # run MCP server (stdio)
pageserve mcp --transport sse --port 3000           # MCP over SSE

Error Handling

Every failure mode maps to a specific, catchable exception:

from pageserve import (
    AuthError,
    NotFoundError,
    DocumentNotReadyError,
    FileTooLargeError,
    RateLimitError,
    ServiceUnavailableError,
    ServiceError,
)

try:
    result = client.query(doc_id, "question")
except AuthError:
    print("Invalid or expired API key")
except NotFoundError:
    print("Document not found")
except RateLimitError as e:
    import time; time.sleep(e.retry_after)
except ServiceError as e:
    print(f"Server error [{e.status_code}]")

Documentation

Guide
Getting Started Install, configure, and run your first query
Authentication API keys and credential handling
Sync Client Reference PageServeClient API
Async Client Reference AsyncPageServeClient API
Streaming (SSE) Token-by-token responses
MCP Server Tools, transports, and agent setup
CLI Reference All commands and flags
Data Models Pydantic response models
Error Handling Exception hierarchy

Contributing

Contributions are welcome! To set up a development environment:

git clone https://github.com/pageserve/pageserve.git
cd pageserve
pip install -e ".[all,dev]"

pytest          # run the test suite
ruff check .    # lint
mypy pageserve  # type-check

Please open an issue to discuss substantial changes before submitting a pull request.

License

Licensed under the Apache License 2.0. © 2026 PageServe.

Metadata

Release files for pageserve 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pageserve 0.1.2
File Size Uploaded Provenance Actions
pageserve-0.1.2.tar.gz 26.9 kB With provenance Details for pageserve-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pageserve 0.1.2
File Interpreter ABI Platform Actions
pageserve-0.1.2-py3-none-any.whl Python 3 none any Details for pageserve-0.1.2-py3-none-any.whl

Total release size: 58.7 kB

Release files / pageserve-0.1.2.tar.gz

Download URL pageserve-0.1.2.tar.gz
Size 26.9 kB
Tags Source
SHA-256 checksum
How to use checksums
dbffb93ab4b191db2b28702d59aa8155cdcd65eead50b42c1772731e201ca313
BLAKE2b-256 checksum
How to use checksums
6187f2f9c23859141450ae77cd882036ca01245ca184d85d8fe88b3c084d3e64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 14, 2026.

Transparency log

Release files / pageserve-0.1.2-py3-none-any.whl

Download URL pageserve-0.1.2-py3-none-any.whl
Size 31.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d5ff70ad0d1f167715a72d7ce7b2b515cf2e34a652e9ab3868c74eb7a2fcfd4b
BLAKE2b-256 checksum
How to use checksums
bf23c4d8184293677062ac7cad63277830bd53ddc69f3d4be9bf0496048a7707
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 14, 2026.

Transparency log

Security for pageserve 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pageserve-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page