holon-sh 0.0.1.dev19__tar.gz → 0.0.1.dev20__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/PKG-INFO +1 -1
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/files/__init__.py +2 -1
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/files/_server.py +46 -25
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/pyproject.toml +1 -1
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/tests/test_files.py +44 -11
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/.gitignore +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/LICENSE +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/README.md +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/client.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/context.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/__init__.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/events/__init__.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/events/_client.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/events/_server.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/events/_wire.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/files/_client.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/ext/files/_wire.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/py.typed +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/holon/serve.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/scripts/verify_distribution.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/tests/test_context.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/tests/test_elicit.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/tests/test_events.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/tests/test_package.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/tests/test_runtime.py +0 -0
- {holon_sh-0.0.1.dev19 → holon_sh-0.0.1.dev20}/tests/test_serve.py +0 -0
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
"""Files in MCP tool calls.
|
|
2
2
|
|
|
3
3
|
Clients pass a :class:`File` and read returned files with :func:`downloads`. Servers accept files with
|
|
4
|
-
:class:`FileServer` and a :class:`Storage` such as :class:`LocalStorage
|
|
4
|
+
:class:`FileServer` and a :class:`Storage` such as :class:`LocalStorage`; a tool declares each file argument a
|
|
5
|
+
:class:`ReceivedFile`.
|
|
5
6
|
|
|
6
7
|
https://github.com/modelcontextprotocol/experimental-ext-file-uploads/blob/main/specification/draft/file-uploads.md
|
|
7
8
|
"""
|
|
@@ -13,9 +13,9 @@ import shutil
|
|
|
13
13
|
import tempfile
|
|
14
14
|
import time
|
|
15
15
|
from collections.abc import Callable, Mapping
|
|
16
|
-
from dataclasses import
|
|
16
|
+
from dataclasses import replace
|
|
17
17
|
from pathlib import Path
|
|
18
|
-
from typing import Annotated, Any, Literal, Protocol
|
|
18
|
+
from typing import Annotated, Any, Literal, Protocol, final
|
|
19
19
|
from urllib.parse import quote
|
|
20
20
|
|
|
21
21
|
import anyio
|
|
@@ -38,6 +38,7 @@ from mcp.types import (
|
|
|
38
38
|
TextContent,
|
|
39
39
|
)
|
|
40
40
|
from pydantic import BaseModel, ConfigDict, Field, ValidationError
|
|
41
|
+
from pydantic_core import CoreSchema, core_schema
|
|
41
42
|
from starlette import status
|
|
42
43
|
from starlette.requests import ClientDisconnect, Request
|
|
43
44
|
from starlette.responses import FileResponse, Response
|
|
@@ -50,6 +51,7 @@ from holon.ext.files._wire import (
|
|
|
50
51
|
b64url,
|
|
51
52
|
declared,
|
|
52
53
|
digest_required,
|
|
54
|
+
file_input_schema,
|
|
53
55
|
media_type,
|
|
54
56
|
sha256,
|
|
55
57
|
walk_files,
|
|
@@ -61,23 +63,50 @@ _STATE = "files."
|
|
|
61
63
|
_TTL = 900.0
|
|
62
64
|
|
|
63
65
|
|
|
64
|
-
@
|
|
66
|
+
@final
|
|
65
67
|
class ReceivedFile:
|
|
66
|
-
"""A file argument, its bytes checked against its size and any digest.
|
|
68
|
+
"""A file argument of the current call, its bytes checked against its size and any digest.
|
|
69
|
+
|
|
70
|
+
A tool takes one by declaring an argument ``ReceivedFile``. ``ReceivedFile(value)`` decodes
|
|
71
|
+
an argument's value where Pydantic does not, such as in a msgspec ``dec_hook``.
|
|
67
72
|
|
|
68
73
|
Attributes:
|
|
69
74
|
name: Client-given name. Untrusted.
|
|
70
75
|
mime_type: Client-claimed media type. Untrusted.
|
|
71
76
|
size: Size in bytes.
|
|
72
77
|
digest: Base64url SHA-256, when verified.
|
|
78
|
+
|
|
79
|
+
Raises:
|
|
80
|
+
ValueError: ``value`` is not a file argument of the current call.
|
|
73
81
|
"""
|
|
74
82
|
|
|
83
|
+
__slots__ = ("_source", "digest", "mime_type", "name", "size")
|
|
75
84
|
name: str | None
|
|
76
85
|
mime_type: str
|
|
77
86
|
size: int
|
|
78
87
|
digest: str | None
|
|
79
88
|
_source: Path | bytes
|
|
80
89
|
|
|
90
|
+
def __new__(cls, value: object) -> ReceivedFile:
|
|
91
|
+
file_id = value.get("id") if isinstance(value, dict) else None
|
|
92
|
+
found = (
|
|
93
|
+
(_received.get() or {}).get(file_id) if isinstance(file_id, str) else None
|
|
94
|
+
)
|
|
95
|
+
if found is None:
|
|
96
|
+
raise ValueError("not a file argument of this call")
|
|
97
|
+
return found
|
|
98
|
+
|
|
99
|
+
def __setattr__(self, name: str, value: object) -> None:
|
|
100
|
+
raise AttributeError(f"ReceivedFile.{name} is read-only")
|
|
101
|
+
|
|
102
|
+
@classmethod
|
|
103
|
+
def __get_pydantic_core_schema__(cls, *_: object) -> CoreSchema:
|
|
104
|
+
return core_schema.no_info_plain_validator_function(cls)
|
|
105
|
+
|
|
106
|
+
@classmethod
|
|
107
|
+
def __get_pydantic_json_schema__(cls, *_: object) -> dict[str, Any]:
|
|
108
|
+
return file_input_schema()
|
|
109
|
+
|
|
81
110
|
async def read(self) -> bytes:
|
|
82
111
|
if isinstance(self._source, bytes):
|
|
83
112
|
return self._source
|
|
@@ -153,6 +182,16 @@ class _FileInput(BaseModel):
|
|
|
153
182
|
class _Refused(Exception): ...
|
|
154
183
|
|
|
155
184
|
|
|
185
|
+
def _verified(
|
|
186
|
+
file: _FileInput, digest: str | None, source: Path | bytes
|
|
187
|
+
) -> ReceivedFile:
|
|
188
|
+
made = object.__new__(ReceivedFile)
|
|
189
|
+
values = (source, digest, file.mimeType, file.name, file.size)
|
|
190
|
+
for slot, value in zip(ReceivedFile.__slots__, values, strict=True):
|
|
191
|
+
object.__setattr__(made, slot, value)
|
|
192
|
+
return made
|
|
193
|
+
|
|
194
|
+
|
|
156
195
|
_received: contextvars.ContextVar[dict[str, ReceivedFile] | None] = (
|
|
157
196
|
contextvars.ContextVar("holon_files_received", default=None)
|
|
158
197
|
)
|
|
@@ -161,7 +200,7 @@ _received: contextvars.ContextVar[dict[str, ReceivedFile] | None] = (
|
|
|
161
200
|
class FileServer:
|
|
162
201
|
"""Low-level server middleware that accepts file arguments in ``tools/call``.
|
|
163
202
|
|
|
164
|
-
Insert it first::
|
|
203
|
+
Tools declare each file argument as a ``ReceivedFile``. Insert it first::
|
|
165
204
|
|
|
166
205
|
server.extensions[EXTENSION] = files.settings()
|
|
167
206
|
server.middleware.insert(0, files)
|
|
@@ -192,20 +231,6 @@ class FileServer:
|
|
|
192
231
|
return {"upload": {}, "maxInlineBytes": self._max_inline_bytes}
|
|
193
232
|
return {"upload": {}}
|
|
194
233
|
|
|
195
|
-
def received(self, file_input: Mapping[str, Any]) -> ReceivedFile:
|
|
196
|
-
"""The checked bytes of a file argument of the current call.
|
|
197
|
-
|
|
198
|
-
Raises:
|
|
199
|
-
LookupError: The argument is not a file of this call.
|
|
200
|
-
"""
|
|
201
|
-
file_id = file_input.get("id")
|
|
202
|
-
found = (
|
|
203
|
-
(_received.get() or {}).get(file_id) if isinstance(file_id, str) else None
|
|
204
|
-
)
|
|
205
|
-
if found is None:
|
|
206
|
-
raise LookupError("not a file argument of this call")
|
|
207
|
-
return found
|
|
208
|
-
|
|
209
234
|
async def reply(
|
|
210
235
|
self,
|
|
211
236
|
ctx: ServerRequestContext[Any, Any],
|
|
@@ -331,9 +356,7 @@ class FileServer:
|
|
|
331
356
|
return _error(
|
|
332
357
|
f"The bytes of file {file.name or file.id!r} did not arrive intact."
|
|
333
358
|
)
|
|
334
|
-
received[file.id] =
|
|
335
|
-
file.name, file.mimeType, file.size, digest, path
|
|
336
|
-
)
|
|
359
|
+
received[file.id] = _verified(file, digest, path)
|
|
337
360
|
annotations = definition.get("annotations") or {}
|
|
338
361
|
if annotations.get("idempotentHint") is not True and not (
|
|
339
362
|
await self._storage.consume(record["n"], record["e"])
|
|
@@ -441,9 +464,7 @@ def _inspect(
|
|
|
441
464
|
if digest is not None and sha256(raw) != digest:
|
|
442
465
|
raise _Refused(f"File {label} does not match its digest.")
|
|
443
466
|
inline += file.size
|
|
444
|
-
received[file.id] =
|
|
445
|
-
file.name, file.mimeType, file.size, digest, raw
|
|
446
|
-
)
|
|
467
|
+
received[file.id] = _verified(file, digest, raw)
|
|
447
468
|
if inline > max_inline_bytes:
|
|
448
469
|
raise _Refused("The inline file data is larger than this server accepts.")
|
|
449
470
|
return received, owed
|
|
@@ -13,7 +13,9 @@ from pathlib import Path
|
|
|
13
13
|
import httpx2
|
|
14
14
|
import pytest
|
|
15
15
|
import uvicorn
|
|
16
|
+
from mcp.server import MCPServer
|
|
16
17
|
from mcp.server.lowlevel import Server
|
|
18
|
+
from mcp.server.mcpserver import Context
|
|
17
19
|
from mcp.server.streamable_http import CONTENT_TYPE_JSON, CONTENT_TYPE_SSE
|
|
18
20
|
from mcp.shared.inbound import (
|
|
19
21
|
MCP_METHOD_HEADER,
|
|
@@ -48,6 +50,7 @@ from holon.ext.files import (
|
|
|
48
50
|
FileTransferError,
|
|
49
51
|
LocalStorage,
|
|
50
52
|
OutcomeUnknownError,
|
|
53
|
+
ReceivedFile,
|
|
51
54
|
downloads,
|
|
52
55
|
file_input_schema,
|
|
53
56
|
)
|
|
@@ -84,6 +87,16 @@ TOOLS = [
|
|
|
84
87
|
]
|
|
85
88
|
|
|
86
89
|
|
|
90
|
+
def asking():
|
|
91
|
+
question = ElicitRequestFormParams(
|
|
92
|
+
message="Why?", requested_schema={"type": "object", "properties": {}}
|
|
93
|
+
)
|
|
94
|
+
return InputRequiredResult(
|
|
95
|
+
input_requests={"why": ElicitRequest(params=question)},
|
|
96
|
+
request_state="asked",
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
|
|
87
100
|
def serve(tmp_path):
|
|
88
101
|
"""A server whose tools save, check and export files; returns (app, ran)."""
|
|
89
102
|
storage = LocalStorage(tmp_path / "storage")
|
|
@@ -102,15 +115,9 @@ def serve(tmp_path):
|
|
|
102
115
|
if params.name == "export":
|
|
103
116
|
return await files.reply(ctx, CSV, name="report.csv", text="Exported.")
|
|
104
117
|
if arguments.get("note") == "ask" and not params.input_responses:
|
|
105
|
-
|
|
106
|
-
message="Why?", requested_schema={"type": "object", "properties": {}}
|
|
107
|
-
)
|
|
108
|
-
return InputRequiredResult(
|
|
109
|
-
input_requests={"why": ElicitRequest(params=question)},
|
|
110
|
-
request_state="asked",
|
|
111
|
-
)
|
|
118
|
+
return asking()
|
|
112
119
|
for value in arguments.get("files") or [arguments["file"]]:
|
|
113
|
-
received =
|
|
120
|
+
received = ReceivedFile(value)
|
|
114
121
|
if params.name == "save":
|
|
115
122
|
await received.save(tmp_path / "saved" / Path(received.name).name)
|
|
116
123
|
return CallToolResult(content=[TextContent(type="text", text="ok")])
|
|
@@ -176,15 +183,16 @@ def run(app, body):
|
|
|
176
183
|
asyncio.run(asyncio.wait_for(main(), timeout=20))
|
|
177
184
|
|
|
178
185
|
|
|
186
|
+
async def answer(params):
|
|
187
|
+
return ElicitResult(action="accept", content={})
|
|
188
|
+
|
|
189
|
+
|
|
179
190
|
def test_files_reach_the_tool_inline_and_out_of_band(tmp_path):
|
|
180
191
|
(tmp_path / "notes.txt").write_bytes(b"x" * 100)
|
|
181
192
|
app, ran = serve(tmp_path)
|
|
182
193
|
seen = []
|
|
183
194
|
files = client(app, seen)
|
|
184
195
|
|
|
185
|
-
async def answer(params):
|
|
186
|
-
return ElicitResult(action="accept", content={})
|
|
187
|
-
|
|
188
196
|
async def body():
|
|
189
197
|
await files.tools.save(file=File(b"tiny", name="a.txt"), cover=None)
|
|
190
198
|
[inline] = tool_calls(seen)
|
|
@@ -220,6 +228,31 @@ def test_files_reach_the_tool_inline_and_out_of_band(tmp_path):
|
|
|
220
228
|
assert ran == ["save"] * 3
|
|
221
229
|
|
|
222
230
|
|
|
231
|
+
def test_a_declared_file_reaches_its_tool_across_an_input_request(tmp_path):
|
|
232
|
+
storage, server, read = LocalStorage(tmp_path), MCPServer("files"), []
|
|
233
|
+
|
|
234
|
+
async def save(file: ReceivedFile, ctx: Context) -> str:
|
|
235
|
+
if not ctx.input_responses:
|
|
236
|
+
return asking()
|
|
237
|
+
read.append(await file.read())
|
|
238
|
+
return "ok"
|
|
239
|
+
|
|
240
|
+
server.add_tool(save)
|
|
241
|
+
[tool] = asyncio.run(server.list_tools())
|
|
242
|
+
declared = tool.model_dump(by_alias=True, exclude_none=True)
|
|
243
|
+
files = FileServer(storage, tools=lambda name: declared, max_inline_bytes=16)
|
|
244
|
+
server._lowlevel_server.extensions[EXTENSION] = files.settings()
|
|
245
|
+
server.middleware.insert(0, files)
|
|
246
|
+
app = server.streamable_http_app(stateless_http=True, json_response=True)
|
|
247
|
+
app.mount("/mcp/files", storage.app)
|
|
248
|
+
|
|
249
|
+
async def body():
|
|
250
|
+
await client(app, []).tools.save({"elicit": answer}, file=File(b"x" * 100))
|
|
251
|
+
|
|
252
|
+
run(app, body)
|
|
253
|
+
assert read == [b"x" * 100]
|
|
254
|
+
|
|
255
|
+
|
|
223
256
|
def sink(attempts, served=None):
|
|
224
257
|
"""Where transfers land: records each (method, authorization), serves
|
|
225
258
|
``served`` by name, and answers 503 for ``busy``."""
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|