π The fast, Pythonic way to build MCP servers and clients.
enhancement: Configure upload retention in memory (#5463)
Jeremiah Lowin980f2a930965
diff --git a/docs/apps/providers/file-upload.mdx b/docs/apps/providers/file-upload.mdxindex f28b99fec..f47d2794c 100644--- a/docs/apps/providers/file-upload.mdx+++ b/docs/apps/providers/file-upload.mdx@@ -48,6 +48,25 @@ FileUpload(The `max_file_size` limit is enforced both in the UI (the DropZone rejects oversized files) and on the server (the `store_files` tool validates before calling `on_store`).+### Retention in memory++Set `max_total_size` to cap the combined decoded file bytes in the default in-memory store across every session. A batch is accepted in full or rejected; replacing a filename uses the size of its final contents. This limit counts file contents, rather than base64 encoding overhead or file metadata.++Set `file_ttl_seconds` to expire files after a fixed age since upload. Replacing a file starts a new expiry period; reading it does not. Expired files are removed across all scopes when the default storage methods store, list, or read files. Cleanup runs on these operations, without a background timer.++```python+from fastmcp import FastMCP+from fastmcp.apps.file_upload import FileUpload++mcp = FastMCP("My Server")+mcp.add_provider(FileUpload(+ max_total_size=50 * 1024 * 1024,+ file_ttl_seconds=3600,+))+```++Both options default to `None`, keeping files for the server process's lifetime without an aggregate size limit. `max_total_size` accepts a nonnegative integer; `file_ttl_seconds` accepts a positive, finite duration. These controls apply to the default in-memory methods. If you override the storage methods, your implementation sets its own retention policy.+## Storage scopingBy default, files are stored in memory and scoped by MCP session ID. Each session gets its own isolated file store β files uploaded in one conversation aren't visible in another.diff --git a/fastmcp_slim/fastmcp/apps/file_upload.py b/fastmcp_slim/fastmcp/apps/file_upload.pyindex ed302ce9d..e7edec74b 100644--- a/fastmcp_slim/fastmcp/apps/file_upload.py+++ b/fastmcp_slim/fastmcp/apps/file_upload.py@@ -60,7 +60,10 @@ except ImportError as _exc:) from _excimport base64+import mathfrom datetime import datetime, timezone+from threading import RLock+from time import monotonicfrom typing import Anyfrom fastmcp.apps.app import FastMCPApp@@ -106,6 +109,10 @@ class FileUpload(FastMCPApp):model-visible tools for listing and reading uploaded files.Files are scoped by MCP session and stored in memory by default.+ Set `max_total_size` to limit decoded file bytes across all scopes or+ `file_ttl_seconds` to expire files by age since upload. Both default to+ None. Expired files are removed on storage operations, without a timer.+ These options apply to the default in-memory storage methods.Override ``on_store``, ``on_list``, and ``on_read`` for custompersistence (filesystem, S3, database, etc.). Each method receivesthe current ``Context``, giving access to session ID, auth tokens,@@ -137,6 +144,8 @@ class FileUpload(FastMCPApp):name: str = "Files",*,max_file_size: int = 10 * 1024 * 1024,+ max_total_size: int | None = None,+ file_ttl_seconds: float | None = None,title: str = "File Upload",description: str = ("Drop files to upload them to the server. "@@ -145,8 +154,17 @@ class FileUpload(FastMCPApp):),drop_label: str = "Drop files here",) -> None:+ if max_total_size is not None and max_total_size < 0:+ raise ValueError("max_total_size must be nonnegative")+ if file_ttl_seconds is not None and (+ not math.isfinite(file_ttl_seconds) or file_ttl_seconds <= 0+ ):+ raise ValueError("file_ttl_seconds must be positive and finite")super().__init__(name)self._max_file_size = max_file_size+ self._max_total_size = max_total_size+ self._file_ttl_seconds = file_ttl_seconds+ self._store_lock = RLock()self._title = titleself._description = descriptionself._drop_label = drop_label@@ -180,6 +198,17 @@ class FileUpload(FastMCPApp):except RuntimeError:return "__default__"+ def _prune_expired(self, now: float) -> None:+ """Remove expired files while holding the default storage lock."""+ if self._file_ttl_seconds is None:+ return+ for scope, entries in list(self._store.items()):+ for name, entry in list(entries.items()):+ if entry["_expires_at"] <= now:+ del entries[name]+ if not entries:+ del self._store[scope]+def on_store(self,files: list[dict[str, Any]],@@ -195,23 +224,56 @@ class FileUpload(FastMCPApp):Override this method for custom persistence. The defaultimplementation stores files in memory, scoped by- ``_get_scope_key(ctx)``.+ ``_get_scope_key(ctx)``. The optional `max_total_size` applies to+ decoded file bytes across every scope. An entire batch is rejected+ when its final contents would exceed the limit, including replacements.Returns:List of file summary dicts (``name``, ``type``, ``size``,``size_display``, ``uploaded_at``)."""scope = self._get_scope_key(ctx)- session_files = self._store.setdefault(scope, {})- for f in files:- session_files[f["name"]] = {- "name": f["name"],- "size": f["size"],- "type": f["type"],- "data": f["data"],- "uploaded_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),- }- return [_make_summary(e) for e in session_files.values()]+ with self._store_lock:+ now = monotonic()+ self._prune_expired(now)+ updates: dict[str, dict[str, Any]] = {}+ for f in files:+ entry = {+ "name": f["name"],+ "size": f["size"],+ "type": f["type"],+ "data": f["data"],+ "uploaded_at": datetime.now(timezone.utc).isoformat(+ timespec="seconds"+ ),+ }+ if self._file_ttl_seconds is not None:+ entry["_expires_at"] = now + self._file_ttl_seconds+ updates[f["name"]] = entry++ session_files = self._store.get(scope, {})+ if self._max_total_size is not None:+ total_size = sum(+ max(0, _b64_decoded_size(entry["data"]))+ for entries in self._store.values()+ for entry in entries.values()+ )+ for name, entry in updates.items():+ total_size += max(0, _b64_decoded_size(entry["data"]))+ if name in session_files:+ total_size -= max(+ 0, _b64_decoded_size(session_files[name]["data"])+ )+ if total_size > self._max_total_size:+ raise ValueError(+ "Files exceed total storage size "+ f"({_format_size(total_size)} > "+ f"{_format_size(self._max_total_size)})"+ )++ session_files = self._store.setdefault(scope, {})+ session_files.update(updates)+ return [_make_summary(e) for e in session_files.values()]def on_list(self, ctx: Context) -> list[dict[str, Any]]:"""List all stored files.@@ -226,8 +288,10 @@ class FileUpload(FastMCPApp):List of file summary dicts."""scope = self._get_scope_key(ctx)- session_files = self._store.get(scope, {})- return [_make_summary(e) for e in session_files.values()]+ with self._store_lock:+ self._prune_expired(monotonic())+ session_files = self._store.get(scope, {})+ return [_make_summary(e) for e in session_files.values()]def on_read(self, name: str, ctx: Context) -> dict[str, Any]:"""Read a file's contents by name.@@ -249,11 +313,13 @@ class FileUpload(FastMCPApp):ValueError: If the file is not found."""scope = self._get_scope_key(ctx)- session_files = self._store.get(scope, {})- if name not in session_files:- available = list(session_files.keys())- raise ValueError(f"File {name!r} not found. Available: {available}")- entry = session_files[name]+ with self._store_lock:+ self._prune_expired(monotonic())+ session_files = self._store.get(scope, {})+ if name not in session_files:+ available = list(session_files.keys())+ raise ValueError(f"File {name!r} not found. Available: {available}")+ entry = session_files[name]result: dict[str, Any] = {"name": entry["name"],"size": entry["size"],diff --git a/tests/apps/test_file_upload_retention.py b/tests/apps/test_file_upload_retention.pynew file mode 100644index 000000000..29aaefebf--- /dev/null+++ b/tests/apps/test_file_upload_retention.py@@ -0,0 +1,214 @@+"""Optional capacity and expiry for the default upload store."""++import base64+from concurrent.futures import ThreadPoolExecutor+from typing import Any+from unittest.mock import Mock++import pytest++from fastmcp import FastMCP+from fastmcp.apps import file_upload+from fastmcp.apps.file_upload import FileUpload+from fastmcp.server.context import Context+from fastmcp.server.providers.addressing import hashed_backend_name+from tests.apps.test_file_upload import _make_file+++def clock(monkeypatch: pytest.MonkeyPatch) -> list[float]:+ now = [100.0]+ monkeypatch.setattr(file_upload, "monotonic", lambda: now[0])+ return now+++def scope(name: str) -> Context:+ return Mock(spec=Context, session_id=name)+++async def test_total_size_uses_payload_sizes():+ upload = FileUpload(max_total_size=4)+ server = FastMCP("test", providers=[upload])+ first = _make_file("a.txt", "abcd")+ first["size"] = 0+ await server.call_tool(+ hashed_backend_name("Files", "store_files"), {"files": [first]}+ )++ with pytest.raises(Exception, match="total storage size"):+ await server.call_tool(+ hashed_backend_name("Files", "store_files"),+ {"files": [_make_file("b.txt", "b")]},+ )++ assert len(upload._store["__default__"]) == 1+++def test_total_size_spans_scopes():+ upload = FileUpload(max_total_size=4)+ a, b = scope("a"), scope("b")+ upload.on_store([_make_file("a.txt", "abc")], a)++ with pytest.raises(ValueError, match="total storage size"):+ upload.on_store([_make_file("b.txt", "ab")], b)+ upload.on_store([_make_file("b.txt", "b")], b)++ assert [f["name"] for f in upload.on_list(a)] == ["a.txt"]+ assert [f["name"] for f in upload.on_list(b)] == ["b.txt"]+++def test_rejected_batch_keeps_existing_contents():+ upload = FileUpload(max_total_size=4)+ ctx = scope("a")+ upload.on_store([_make_file("a.txt", "a")], ctx)++ with pytest.raises(ValueError, match="total storage size"):+ upload.on_store([_make_file("a.txt", "abc"), _make_file("b.txt", "bb")], ctx)++ assert upload.on_read("a.txt", ctx)["content"] == "a"+ assert [f["name"] for f in upload.on_list(ctx)] == ["a.txt"]+++def test_replacements_return_capacity():+ upload = FileUpload(max_total_size=4)+ ctx = scope("a")+ upload.on_store([_make_file("a.txt", "abcd")], ctx)+ upload.on_store([_make_file("a.txt", "a")], ctx)+ upload.on_store([_make_file("b.txt", "bcd")], ctx)++ with pytest.raises(ValueError, match="total storage size"):+ upload.on_store([_make_file("a.txt", "abcd")], ctx)+ assert upload.on_read("a.txt", ctx)["content"] == "a"+ assert upload.on_read("b.txt", ctx)["content"] == "bcd"+++def test_repeated_names_use_final_contents():+ upload = FileUpload(max_total_size=1)+ ctx = scope("a")+ upload.on_store([_make_file("a.txt", "abcd"), _make_file("a.txt", "a")], ctx)++ assert upload.on_read("a.txt", ctx)["content"] == "a"+++def test_zero_capacity_accepts_empty_files():+ upload = FileUpload(max_total_size=0)+ ctx = scope("a")+ upload.on_store([_make_file("empty.txt", "")], ctx)++ assert upload.on_read("empty.txt", ctx)["content"] == ""+ with pytest.raises(ValueError, match="total storage size"):+ upload.on_store([_make_file("a.txt", "a")], ctx)+++def test_default_storage_persists_across_calls(clock: list[float]):+ upload = FileUpload()+ ctx = scope("a")+ upload.on_store([_make_file("a.txt", "abc")], ctx)+ clock[0] += 10000+ upload.on_store([_make_file("b.txt", "bcd")], ctx)++ assert [f["name"] for f in upload.on_list(ctx)] == ["a.txt", "b.txt"]+ assert upload.on_read("a.txt", ctx)["content"] == "abc"+++def test_expiry_does_not_refresh_on_read(clock: list[float]):+ upload = FileUpload(file_ttl_seconds=5)+ ctx = scope("a")+ upload.on_store([_make_file("a.txt", "abc")], ctx)+ clock[0] = 104.9+ assert upload.on_read("a.txt", ctx)["content"] == "abc"+ clock[0] = 105++ with pytest.raises(ValueError, match="not found"):+ upload.on_read("a.txt", ctx)+ assert upload.on_list(ctx) == []+ assert upload._store == {}+++def test_replacement_starts_new_expiry(clock: list[float]):+ upload = FileUpload(file_ttl_seconds=5)+ ctx = scope("a")+ upload.on_store([_make_file("a.txt", "abc")], ctx)+ clock[0] = 104+ upload.on_store([_make_file("a.txt", "def")], ctx)+ clock[0] = 105+ assert upload.on_read("a.txt", ctx)["content"] == "def"+ clock[0] = 109+ assert upload.on_list(ctx) == []+++def test_expiry_returns_global_capacity(clock: list[float]):+ upload = FileUpload(max_total_size=4, file_ttl_seconds=5)+ a, b = scope("a"), scope("b")+ upload.on_store([_make_file("a.txt", "abcd")], a)+ clock[0] = 105+ upload.on_store([_make_file("b.txt", "abcd")], b)++ assert upload.on_list(a) == []+ assert upload.on_read("b.txt", b)["content"] == "abcd"+ assert set(upload._store) == {"b"}+++def test_list_prunes_expired_files_in_other_scopes(clock: list[float]):+ upload = FileUpload(file_ttl_seconds=5)+ a, b = scope("a"), scope("b")+ upload.on_store([_make_file("a.txt", "a")], a)+ clock[0] = 104+ upload.on_store([_make_file("b.txt", "b")], b)+ clock[0] = 105++ assert [f["name"] for f in upload.on_list(b)] == ["b.txt"]+ assert set(upload._store) == {"b"}++[email protected]("total_size", [-1, -1024])+def test_total_size_requires_nonnegative_value(total_size: int):+ with pytest.raises(ValueError, match="max_total_size"):+ FileUpload(max_total_size=total_size)++[email protected]("ttl", [0, -1, float("inf"), float("-inf"), float("nan")])+def test_expiry_requires_positive_finite_value(ttl: float):+ with pytest.raises(ValueError, match="file_ttl_seconds"):+ FileUpload(file_ttl_seconds=ttl)+++def test_custom_storage_controls_its_own_retention(clock: list[float]):+ stored: dict[str, dict[str, Any]] = {}++ class CustomUpload(FileUpload):+ def on_store(self, files: list[dict[str, Any]], ctx: Context):+ stored.update({f["name"]: f for f in files})+ return self.on_list(ctx)++ def on_list(self, ctx: Context):+ return [{"name": name} for name in stored]++ def on_read(self, name: str, ctx: Context):+ return stored[name]++ upload = CustomUpload(max_total_size=0, file_ttl_seconds=1)+ ctx = scope("a")+ upload.on_store([_make_file("a.txt", "abc")], ctx)+ clock[0] += 10000++ assert upload.on_list(ctx) == [{"name": "a.txt"}]+ assert base64.b64decode(upload.on_read("a.txt", ctx)["data"]) == b"abc"+ assert upload._store == {}+++def test_concurrent_batches_share_capacity():+ upload = FileUpload(max_total_size=4)++ def store(name: str) -> bool:+ try:+ upload.on_store([_make_file("file.txt", "abcd")], scope(name))+ except ValueError:+ return False+ return True++ with ThreadPoolExecutor(max_workers=2) as executor:+ results = list(executor.map(store, ["a", "b"]))++ assert sorted(results) == [False, True]+ assert sum(len(files) for files in upload._store.values()) == 1