fastmcp-lro

Large Result Offloading for MCP servers — demand-driven context management for tool-augmented language models.

When MCP tool responses exceed a configurable character threshold, the full dataset is written to JSONL files and the tool returns a compact descriptor with file paths, schemas, jq recipes, and a caller-defined summary.

Based on the LRO specification.

Installation

pip install fastmcp-lro

Quick Start

Decorator (recommended for FastMCP tools)

from fastmcp_lro import lro_offload, OffloadSection

@lro_offload(
    sections=[
        OffloadSection(
            key="results",
            filename_prefix="search",
            schema={"id": "string", "title": "string", "score": "number"},
        ),
    ],
    inline_keys=["query", "total_count"],
    session_id_key="request_id",
)
async def search_tool(query: str) -> dict:
    return {
        "request_id": "req-123",
        "query": query,
        "total_count": 500,
        "results": [...]  # large list
    }

Explicit call

from fastmcp_lro import LROOffloader, OffloadSection

offloader = LROOffloader(threshold=50000)

section = OffloadSection(
    key="results",
    filename_prefix="search",
    schema={"id": "string", "score": "number"},
)

result = offloader.offload_if_needed(
    data=large_response,
    sections=[section],
    inline_keys=["query"],
    session_id="req-123",
)

Context manager

from fastmcp_lro import LROContext, OffloadSection

section = OffloadSection(key="results", filename_prefix="search", schema={})

with LROContext(sections=[section], threshold=50000) as ctx:
    ctx.set_data(large_response)
offloaded = ctx.result

Configuration

Documentation

Full Diataxis documentation:

License

MIT