Skip to content

πŸš€ 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.mdx
index 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 scoping
By 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.py
index 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 _exc
import base64
+import math
from datetime import datetime, timezone
+from threading import RLock
+from time import monotonic
from typing import Any
from 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 custom
persistence (filesystem, S3, database, etc.). Each method receives
the 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 = title
self._description = description
self._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 default
implementation 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.py
new file mode 100644
index 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