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

Parameter	Default	Env Override	Description
threshold	50,000	{PREFIX}_THRESHOLD	Character count threshold
output_dir	system temp	{PREFIX}_DIR	JSONL output directory
header_type	"mcp_lro"	—	JSONL header type field
env_prefix	"MCP_LRO"	—	Prefix for env overrides
enabled	True	{PREFIX}_ENABLED	Enable/disable LRO
ttl_seconds	3,600	—	File expiry for cleanup

Documentation

Full Diataxis documentation:

Type	Docs
Tutorials	Getting Started · FastMCP Integration
How-to	Custom Sections · Error Handling · Cleanup · Configuration · Server Instructions
Reference	API · JSONL Format · Offload Response · Configuration
Explanation	Why LRO? · Architecture · Security Model · Interface Comparison

License

MIT