holon-sh 0.0.1.dev4__tar.gz → 0.0.1.dev5__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.dev4 → holon_sh-0.0.1.dev5}/PKG-INFO +5 -7
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/README.md +4 -6
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/holon/binding.py +0 -5
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/holon/client.py +63 -57
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/pyproject.toml +1 -1
- holon_sh-0.0.1.dev5/tests/test_elicit.py +195 -0
- holon_sh-0.0.1.dev4/tests/test_elicit.py +0 -131
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/.gitignore +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/LICENSE +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/holon/py.typed +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/holon/view.py +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/scripts/fixtures.sh +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/scripts/verify_distribution.py +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/tests/fixtures/caller/requirements.txt +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/tests/fixtures/caller/server.json +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/tests/fixtures/orders/server.json +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/tests/fixtures/orders/server.py +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/tests/test_package.py +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/tests/test_runtime.py +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev5}/tests/test_view.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: holon-sh
|
|
3
|
-
Version: 0.0.1.
|
|
3
|
+
Version: 0.0.1.dev5
|
|
4
4
|
Summary: Typed MCP clients, bindings, and app views
|
|
5
5
|
Project-URL: Repository, https://github.com/holon-sh/sdk-py
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -90,20 +90,18 @@ The options dict also accepts `input_responses`, `request_state` and `meta`.
|
|
|
90
90
|
<details open>
|
|
91
91
|
<summary><h3>Answer a server's question</h3></summary>
|
|
92
92
|
|
|
93
|
-
A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation).
|
|
93
|
+
A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Pass `elicit` to answer in place, and the call returns its usual typed output:
|
|
94
94
|
|
|
95
95
|
```python
|
|
96
|
-
from holon.apps import create_apps
|
|
97
96
|
from mcp.types import ElicitResult
|
|
98
97
|
|
|
99
|
-
async def elicit(
|
|
98
|
+
async def elicit(params):
|
|
100
99
|
return ElicitResult(action="accept", content=await ask(params.message))
|
|
101
100
|
|
|
102
|
-
|
|
103
|
-
greeting = await apps.bar.tools.greet(name="world")
|
|
101
|
+
greeting = await apps.bar.tools.greet({"elicit": elicit}, name="world")
|
|
104
102
|
```
|
|
105
103
|
|
|
106
|
-
Without `elicit`,
|
|
104
|
+
Without `elicit`, the question arrives on `ToolCallError.result`, or as an `input_required` result from `call_tool`. To answer later, for example in another request, call again with `input_responses` and `request_state`.
|
|
107
105
|
|
|
108
106
|
</details>
|
|
109
107
|
|
|
@@ -77,20 +77,18 @@ The options dict also accepts `input_responses`, `request_state` and `meta`.
|
|
|
77
77
|
<details open>
|
|
78
78
|
<summary><h3>Answer a server's question</h3></summary>
|
|
79
79
|
|
|
80
|
-
A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation).
|
|
80
|
+
A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Pass `elicit` to answer in place, and the call returns its usual typed output:
|
|
81
81
|
|
|
82
82
|
```python
|
|
83
|
-
from holon.apps import create_apps
|
|
84
83
|
from mcp.types import ElicitResult
|
|
85
84
|
|
|
86
|
-
async def elicit(
|
|
85
|
+
async def elicit(params):
|
|
87
86
|
return ElicitResult(action="accept", content=await ask(params.message))
|
|
88
87
|
|
|
89
|
-
|
|
90
|
-
greeting = await apps.bar.tools.greet(name="world")
|
|
88
|
+
greeting = await apps.bar.tools.greet({"elicit": elicit}, name="world")
|
|
91
89
|
```
|
|
92
90
|
|
|
93
|
-
Without `elicit`,
|
|
91
|
+
Without `elicit`, the question arrives on `ToolCallError.result`, or as an `input_required` result from `call_tool`. To answer later, for example in another request, call again with `input_responses` and `request_state`.
|
|
94
92
|
|
|
95
93
|
</details>
|
|
96
94
|
|
|
@@ -4,7 +4,6 @@ from collections.abc import Callable
|
|
|
4
4
|
from typing import NotRequired, TypedDict
|
|
5
5
|
|
|
6
6
|
import httpx2
|
|
7
|
-
from mcp.client.session import ElicitationFnT
|
|
8
7
|
|
|
9
8
|
|
|
10
9
|
class Binding(TypedDict):
|
|
@@ -15,14 +14,10 @@ class Binding(TypedDict):
|
|
|
15
14
|
http_client: Factory returning a fresh ``httpx2.AsyncClient`` for each
|
|
16
15
|
call. Configure authentication headers or a custom transport here.
|
|
17
16
|
The SDK closes the returned client when the call finishes.
|
|
18
|
-
elicit: Answers a server's elicitations in place, so ``tools.<name>`` and
|
|
19
|
-
``call_tool`` return the completed result. Declares the elicitation
|
|
20
|
-
capability to the server.
|
|
21
17
|
"""
|
|
22
18
|
|
|
23
19
|
endpoint: str
|
|
24
20
|
http_client: NotRequired[Callable[[], httpx2.AsyncClient]]
|
|
25
|
-
elicit: NotRequired[ElicitationFnT]
|
|
26
21
|
|
|
27
22
|
|
|
28
23
|
_resolver: Callable[[str], Binding | None] | None = None
|
|
@@ -1,22 +1,24 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
3
|
import os
|
|
4
|
-
from collections.abc import Mapping
|
|
4
|
+
from collections.abc import Awaitable, Callable, Mapping
|
|
5
5
|
from functools import partial
|
|
6
6
|
from types import SimpleNamespace
|
|
7
7
|
from typing import Any, Generic, Literal, Protocol, TypeAlias, TypedDict, TypeVar
|
|
8
8
|
|
|
9
9
|
import httpx2
|
|
10
10
|
import jsonschema # type: ignore[import-untyped,unused-ignore]
|
|
11
|
-
from mcp import Client
|
|
12
|
-
from mcp.client.session import
|
|
11
|
+
from mcp import Client
|
|
12
|
+
from mcp.client.session import ClientRequestContext
|
|
13
13
|
from mcp.client.streamable_http import streamable_http_client
|
|
14
14
|
from mcp.types import (
|
|
15
|
-
MISSING_REQUIRED_CLIENT_CAPABILITY,
|
|
16
15
|
CallToolRequest,
|
|
17
16
|
CallToolRequestParams,
|
|
18
17
|
CallToolResult,
|
|
19
18
|
ContentBlock,
|
|
19
|
+
ElicitRequest,
|
|
20
|
+
ElicitRequestParams,
|
|
21
|
+
ElicitResult,
|
|
20
22
|
Implementation,
|
|
21
23
|
InputRequiredResult,
|
|
22
24
|
InputResponses,
|
|
@@ -73,14 +75,15 @@ class CallOptions(TypedDict, total=False):
|
|
|
73
75
|
input_responses: InputResponses | None
|
|
74
76
|
request_state: str | None
|
|
75
77
|
meta: RequestParamsMeta | None
|
|
78
|
+
elicit: Callable[[ElicitRequestParams], Awaitable[ElicitResult]]
|
|
76
79
|
|
|
77
80
|
|
|
78
81
|
class ToolCallError(RuntimeError):
|
|
79
82
|
"""Raised by ``tools.<name>`` for tool errors or additional input requests.
|
|
80
83
|
|
|
81
84
|
Attributes:
|
|
82
|
-
result: Original MCP error or input-required result.
|
|
83
|
-
answer questions in place, or
|
|
85
|
+
result: Original MCP error or input-required result. Pass ``elicit`` to
|
|
86
|
+
answer questions in place, or continue later through ``call_tool``.
|
|
84
87
|
"""
|
|
85
88
|
|
|
86
89
|
def __init__(
|
|
@@ -89,17 +92,62 @@ class ToolCallError(RuntimeError):
|
|
|
89
92
|
self.result = result
|
|
90
93
|
if isinstance(result, InputRequiredResult):
|
|
91
94
|
message = "additional input required"
|
|
95
|
+
detail = " ".join(
|
|
96
|
+
f"{request.params.message} {getattr(request.params, 'url', '')}".strip()
|
|
97
|
+
for request in (result.input_requests or {}).values()
|
|
98
|
+
if isinstance(request, ElicitRequest)
|
|
99
|
+
)
|
|
92
100
|
else:
|
|
93
101
|
message = "tool failed"
|
|
94
102
|
detail = next(
|
|
95
103
|
(part.text for part in result.content if isinstance(part, TextContent)),
|
|
96
104
|
"",
|
|
97
105
|
)
|
|
98
|
-
|
|
99
|
-
|
|
106
|
+
if detail:
|
|
107
|
+
message = f"{message}: {detail}"
|
|
100
108
|
super().__init__(f"{app}.{tool}: {message}")
|
|
101
109
|
|
|
102
110
|
|
|
111
|
+
async def _declare_elicitation(
|
|
112
|
+
context: ClientRequestContext, params: ElicitRequestParams
|
|
113
|
+
) -> ElicitResult:
|
|
114
|
+
"""Declare that every client can be asked; the MCP client infers it from this."""
|
|
115
|
+
return ElicitResult(action="decline")
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
async def _send(
|
|
119
|
+
client: Client, name: str, arguments: dict[str, Any], options: CallOptions
|
|
120
|
+
) -> CallToolResult | InputRequiredResult:
|
|
121
|
+
elicit = options.get("elicit")
|
|
122
|
+
responses, state = options.get("input_responses"), options.get("request_state")
|
|
123
|
+
answered = 0
|
|
124
|
+
while True:
|
|
125
|
+
result = await client.session.send_request(
|
|
126
|
+
CallToolRequest(
|
|
127
|
+
params=CallToolRequestParams(
|
|
128
|
+
name=name,
|
|
129
|
+
arguments=arguments,
|
|
130
|
+
input_responses=responses,
|
|
131
|
+
request_state=state,
|
|
132
|
+
_meta=options.get("meta"),
|
|
133
|
+
)
|
|
134
|
+
),
|
|
135
|
+
_result,
|
|
136
|
+
request_read_timeout_seconds=options.get("timeout"),
|
|
137
|
+
)
|
|
138
|
+
# A server may keep asking, so answering stops after ten rounds, the MCP
|
|
139
|
+
# clients' own limit, and the last question reaches the caller.
|
|
140
|
+
if not (elicit and answered < 10 and isinstance(result, InputRequiredResult)):
|
|
141
|
+
return result
|
|
142
|
+
answered += 1
|
|
143
|
+
responses = {
|
|
144
|
+
key: await elicit(request.params)
|
|
145
|
+
for key, request in (result.input_requests or {}).items()
|
|
146
|
+
if isinstance(request, ElicitRequest)
|
|
147
|
+
}
|
|
148
|
+
state = result.request_state
|
|
149
|
+
|
|
150
|
+
|
|
103
151
|
def validate(schema: dict[str, Any], value: object, label: str) -> None:
|
|
104
152
|
try:
|
|
105
153
|
jsonschema.validate(
|
|
@@ -149,12 +197,13 @@ class _App:
|
|
|
149
197
|
Args:
|
|
150
198
|
name: Tool name. Contracted dependencies reject unknown tools.
|
|
151
199
|
options: Request timeout in seconds, input responses, continuation
|
|
152
|
-
state, and
|
|
200
|
+
state, metadata, and ``elicit`` to answer the server's questions in
|
|
201
|
+
place. Passed positionally, separate from tool input.
|
|
153
202
|
**arguments: Tool input, validated against the contract if present.
|
|
154
203
|
|
|
155
204
|
Returns:
|
|
156
|
-
A complete result, or an input-required result
|
|
157
|
-
|
|
205
|
+
A complete result, or an input-required result for a question left
|
|
206
|
+
unanswered. Tool error results are returned unchanged; successful
|
|
158
207
|
structured output is contract-validated.
|
|
159
208
|
|
|
160
209
|
Raises:
|
|
@@ -186,7 +235,6 @@ class _App:
|
|
|
186
235
|
raise RuntimeError(
|
|
187
236
|
f"Dependency {self._name} is unavailable ({variable}). Set the endpoint or supply a binding."
|
|
188
237
|
)
|
|
189
|
-
elicit = binding.get("elicit") if binding else None
|
|
190
238
|
http_client = partial(httpx2.AsyncClient, trust_env=False)
|
|
191
239
|
failure: Exception | None = None
|
|
192
240
|
async with (
|
|
@@ -199,22 +247,13 @@ class _App:
|
|
|
199
247
|
name=self._identity["name"], version=self._identity["version"]
|
|
200
248
|
),
|
|
201
249
|
mode="2026-07-28",
|
|
202
|
-
elicitation_callback=
|
|
250
|
+
elicitation_callback=_declare_elicitation,
|
|
203
251
|
) as client:
|
|
204
252
|
try:
|
|
205
|
-
result = await
|
|
253
|
+
result = await _send(client, name, arguments, options)
|
|
206
254
|
except Exception as error: # noqa: BLE001
|
|
207
255
|
# Raised below: the client's task group would wrap it in an ExceptionGroup.
|
|
208
256
|
failure = error
|
|
209
|
-
if (
|
|
210
|
-
isinstance(failure, MCPError)
|
|
211
|
-
and failure.code == MISSING_REQUIRED_CLIENT_CAPABILITY
|
|
212
|
-
):
|
|
213
|
-
raise MCPError(
|
|
214
|
-
failure.code,
|
|
215
|
-
f"{self._name}.{name}: {failure.message}. Set elicit on the binding.",
|
|
216
|
-
failure.data,
|
|
217
|
-
) from failure
|
|
218
257
|
if failure is not None:
|
|
219
258
|
raise failure
|
|
220
259
|
if (
|
|
@@ -230,38 +269,6 @@ class _App:
|
|
|
230
269
|
)
|
|
231
270
|
return result
|
|
232
271
|
|
|
233
|
-
@staticmethod
|
|
234
|
-
async def _send(
|
|
235
|
-
client: Client,
|
|
236
|
-
name: str,
|
|
237
|
-
arguments: dict[str, Any],
|
|
238
|
-
options: CallOptions,
|
|
239
|
-
elicit: ElicitationFnT | None,
|
|
240
|
-
) -> CallToolResult | InputRequiredResult:
|
|
241
|
-
if elicit:
|
|
242
|
-
# The MCP client answers input requests through the callback and retries.
|
|
243
|
-
return await client.call_tool(
|
|
244
|
-
name,
|
|
245
|
-
arguments,
|
|
246
|
-
read_timeout_seconds=options.get("timeout"),
|
|
247
|
-
input_responses=options.get("input_responses"),
|
|
248
|
-
request_state=options.get("request_state"),
|
|
249
|
-
meta=options.get("meta"),
|
|
250
|
-
)
|
|
251
|
-
return await client.session.send_request(
|
|
252
|
-
CallToolRequest(
|
|
253
|
-
params=CallToolRequestParams(
|
|
254
|
-
name=name,
|
|
255
|
-
arguments=arguments,
|
|
256
|
-
input_responses=options.get("input_responses"),
|
|
257
|
-
request_state=options.get("request_state"),
|
|
258
|
-
_meta=options.get("meta"),
|
|
259
|
-
)
|
|
260
|
-
),
|
|
261
|
-
_result,
|
|
262
|
-
request_read_timeout_seconds=options.get("timeout"),
|
|
263
|
-
)
|
|
264
|
-
|
|
265
272
|
async def _call_tool(
|
|
266
273
|
self,
|
|
267
274
|
tool: dict[str, Any],
|
|
@@ -294,8 +301,7 @@ class Apps:
|
|
|
294
301
|
Access a client with ``clients[name]`` or ``clients.name``. Its
|
|
295
302
|
``tools.<name>(**arguments)`` methods return structured output, or the
|
|
296
303
|
complete result for a tool without an output schema, and raise
|
|
297
|
-
:class:`ToolCallError` for tool errors
|
|
298
|
-
the binding has no ``elicit``.
|
|
304
|
+
:class:`ToolCallError` for tool errors or questions left unanswered.
|
|
299
305
|
Use its ``call_tool`` method for the full result envelope.
|
|
300
306
|
"""
|
|
301
307
|
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
import asyncio
|
|
2
|
+
from typing import Annotated
|
|
3
|
+
|
|
4
|
+
import httpx2
|
|
5
|
+
import pytest
|
|
6
|
+
from mcp.server import MCPServer
|
|
7
|
+
from mcp.server.mcpserver import Elicit, Resolve
|
|
8
|
+
from mcp.types import (
|
|
9
|
+
CallToolResult,
|
|
10
|
+
ElicitRequest,
|
|
11
|
+
ElicitRequestFormParams,
|
|
12
|
+
ElicitRequestURLParams,
|
|
13
|
+
ElicitResult,
|
|
14
|
+
InputRequiredResult,
|
|
15
|
+
)
|
|
16
|
+
from pydantic import BaseModel
|
|
17
|
+
|
|
18
|
+
from holon.client import Apps, ToolCallError
|
|
19
|
+
|
|
20
|
+
QUESTION = "Which size should I ship?"
|
|
21
|
+
ID_ONLY = {
|
|
22
|
+
"type": "object",
|
|
23
|
+
"properties": {"id": {"type": "string"}},
|
|
24
|
+
"required": ["id"],
|
|
25
|
+
}
|
|
26
|
+
CONTRACT = {
|
|
27
|
+
"tools": [
|
|
28
|
+
{
|
|
29
|
+
"name": "ship",
|
|
30
|
+
"inputSchema": ID_ONLY,
|
|
31
|
+
"outputSchema": {
|
|
32
|
+
"type": "object",
|
|
33
|
+
"properties": {"shipped": {"type": "string"}},
|
|
34
|
+
"required": ["shipped"],
|
|
35
|
+
},
|
|
36
|
+
},
|
|
37
|
+
{"name": "nag", "inputSchema": ID_ONLY},
|
|
38
|
+
]
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class Choice(BaseModel):
|
|
43
|
+
size: str
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class Shipped(BaseModel):
|
|
47
|
+
shipped: str
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def ask_size() -> Elicit[Choice]:
|
|
51
|
+
return Elicit(QUESTION, Choice)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def exercise(body, contract=CONTRACT):
|
|
55
|
+
"""Run body against a real server."""
|
|
56
|
+
|
|
57
|
+
async def run():
|
|
58
|
+
server = MCPServer("orders")
|
|
59
|
+
|
|
60
|
+
@server.tool()
|
|
61
|
+
async def ship(
|
|
62
|
+
id: str, choice: Annotated[Choice, Resolve(ask_size)]
|
|
63
|
+
) -> Shipped:
|
|
64
|
+
return Shipped(shipped=choice.size)
|
|
65
|
+
|
|
66
|
+
@server.tool()
|
|
67
|
+
async def nag(id: str) -> CallToolResult | InputRequiredResult:
|
|
68
|
+
params = ElicitRequestFormParams(
|
|
69
|
+
message=QUESTION,
|
|
70
|
+
requested_schema={"type": "object", "properties": {}},
|
|
71
|
+
)
|
|
72
|
+
return InputRequiredResult(
|
|
73
|
+
input_requests={"q": ElicitRequest(params=params)}
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
app = server.streamable_http_app(stateless_http=True)
|
|
77
|
+
|
|
78
|
+
def http_client():
|
|
79
|
+
return httpx2.AsyncClient(transport=httpx2.ASGITransport(app=app))
|
|
80
|
+
|
|
81
|
+
apps = Apps(
|
|
82
|
+
{"name": "checkout", "version": "1", "requires": {}},
|
|
83
|
+
{"orders": contract},
|
|
84
|
+
{
|
|
85
|
+
"orders": {
|
|
86
|
+
"endpoint": "http://127.0.0.1:8000/mcp",
|
|
87
|
+
"http_client": http_client,
|
|
88
|
+
}
|
|
89
|
+
},
|
|
90
|
+
)
|
|
91
|
+
async with app.router.lifespan_context(app):
|
|
92
|
+
await body(apps.orders)
|
|
93
|
+
|
|
94
|
+
asyncio.run(asyncio.wait_for(run(), timeout=15))
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
async def large(params):
|
|
98
|
+
return ElicitResult(action="accept", content={"size": "large"})
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def test_elicit_answers_in_place_and_the_call_returns_typed_output():
|
|
102
|
+
asked = []
|
|
103
|
+
|
|
104
|
+
async def elicit(params):
|
|
105
|
+
asked.append(params.message)
|
|
106
|
+
return await large(params)
|
|
107
|
+
|
|
108
|
+
async def body(orders):
|
|
109
|
+
assert await orders.tools.ship({"elicit": elicit}, id="A-1") == {
|
|
110
|
+
"shipped": "large"
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
exercise(body)
|
|
114
|
+
assert asked == [QUESTION]
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def test_accepted_output_is_still_validated():
|
|
118
|
+
tool = CONTRACT["tools"][0]
|
|
119
|
+
wrong = {"type": "object", "required": ["total"]}
|
|
120
|
+
|
|
121
|
+
async def body(orders):
|
|
122
|
+
with pytest.raises(ValueError, match="structured output"):
|
|
123
|
+
await orders.tools.ship({"elicit": large}, id="A-1")
|
|
124
|
+
|
|
125
|
+
exercise(body, {"tools": [{**tool, "outputSchema": wrong}]})
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def test_a_declined_question_reaches_the_tool():
|
|
129
|
+
async def decline(params):
|
|
130
|
+
return ElicitResult(action="decline")
|
|
131
|
+
|
|
132
|
+
async def body(orders):
|
|
133
|
+
with pytest.raises(ToolCallError, match="elicitation was decline"):
|
|
134
|
+
await orders.tools.ship({"elicit": decline}, id="A-1")
|
|
135
|
+
|
|
136
|
+
exercise(body)
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def test_a_server_that_keeps_asking_stops_after_ten_answers():
|
|
140
|
+
answers = []
|
|
141
|
+
|
|
142
|
+
async def elicit(params):
|
|
143
|
+
answers.append(params)
|
|
144
|
+
return ElicitResult(action="decline")
|
|
145
|
+
|
|
146
|
+
async def body(orders):
|
|
147
|
+
with pytest.raises(ToolCallError, match=QUESTION):
|
|
148
|
+
await orders.tools.nag({"elicit": elicit}, id="A-1")
|
|
149
|
+
|
|
150
|
+
exercise(body)
|
|
151
|
+
assert len(answers) == 10
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def test_without_elicit_the_question_reaches_the_caller_who_continues():
|
|
155
|
+
async def body(orders):
|
|
156
|
+
with pytest.raises(ToolCallError) as error:
|
|
157
|
+
await orders.tools.ship(id="A-1")
|
|
158
|
+
assert str(error.value) == f"orders.ship: additional input required: {QUESTION}"
|
|
159
|
+
result = error.value.result
|
|
160
|
+
assert isinstance(result, InputRequiredResult)
|
|
161
|
+
[(key, request)] = result.input_requests.items()
|
|
162
|
+
assert request.params.message == QUESTION
|
|
163
|
+
answer = ElicitResult(action="accept", content={"size": "small"})
|
|
164
|
+
continued = await orders.call_tool(
|
|
165
|
+
"ship",
|
|
166
|
+
{"input_responses": {key: answer}, "request_state": result.request_state},
|
|
167
|
+
id="A-1",
|
|
168
|
+
)
|
|
169
|
+
assert continued.structured_content == {"shipped": "small"}
|
|
170
|
+
|
|
171
|
+
exercise(body)
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def test_an_error_while_answering_reaches_the_caller_unwrapped():
|
|
175
|
+
async def elicit(params):
|
|
176
|
+
raise LookupError("no answer")
|
|
177
|
+
|
|
178
|
+
async def body(orders):
|
|
179
|
+
with pytest.raises(LookupError, match="no answer"):
|
|
180
|
+
await orders.tools.ship({"elicit": elicit}, id="A-1")
|
|
181
|
+
|
|
182
|
+
exercise(body)
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def test_a_url_question_names_its_url():
|
|
186
|
+
params = ElicitRequestURLParams(
|
|
187
|
+
message="Connect your account.",
|
|
188
|
+
url="https://orders.example/connect",
|
|
189
|
+
elicitation_id="link",
|
|
190
|
+
)
|
|
191
|
+
result = InputRequiredResult(input_requests={"link": ElicitRequest(params=params)})
|
|
192
|
+
assert str(ToolCallError("orders", "ship", result)) == (
|
|
193
|
+
"orders.ship: additional input required: "
|
|
194
|
+
"Connect your account. https://orders.example/connect"
|
|
195
|
+
)
|
|
@@ -1,131 +0,0 @@
|
|
|
1
|
-
import asyncio
|
|
2
|
-
from typing import Annotated
|
|
3
|
-
|
|
4
|
-
import httpx2
|
|
5
|
-
import pytest
|
|
6
|
-
from mcp import MCPError
|
|
7
|
-
from mcp.server import MCPServer
|
|
8
|
-
from mcp.server.mcpserver import Elicit, Resolve
|
|
9
|
-
from mcp.types import MISSING_REQUIRED_CLIENT_CAPABILITY, CallToolResult, ElicitResult
|
|
10
|
-
from pydantic import BaseModel
|
|
11
|
-
|
|
12
|
-
from holon.client import Apps, ToolCallError
|
|
13
|
-
|
|
14
|
-
QUESTION = "Which size should I ship?"
|
|
15
|
-
CONTRACT = {
|
|
16
|
-
"tools": [
|
|
17
|
-
{
|
|
18
|
-
"name": "ship",
|
|
19
|
-
"inputSchema": {
|
|
20
|
-
"type": "object",
|
|
21
|
-
"properties": {"id": {"type": "string"}},
|
|
22
|
-
"required": ["id"],
|
|
23
|
-
},
|
|
24
|
-
"outputSchema": {
|
|
25
|
-
"type": "object",
|
|
26
|
-
"properties": {"shipped": {"type": "string"}},
|
|
27
|
-
"required": ["shipped"],
|
|
28
|
-
},
|
|
29
|
-
}
|
|
30
|
-
]
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
class Choice(BaseModel):
|
|
35
|
-
size: str
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
class Shipped(BaseModel):
|
|
39
|
-
shipped: str
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
def ask_size() -> Elicit[Choice]:
|
|
43
|
-
return Elicit(QUESTION, Choice)
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
def exercise(body, elicit=None, contract=CONTRACT):
|
|
47
|
-
"""Run body against a real server, through a binding that may answer its question."""
|
|
48
|
-
|
|
49
|
-
async def run():
|
|
50
|
-
server = MCPServer("orders")
|
|
51
|
-
|
|
52
|
-
@server.tool()
|
|
53
|
-
async def ship(
|
|
54
|
-
id: str, choice: Annotated[Choice, Resolve(ask_size)]
|
|
55
|
-
) -> Shipped:
|
|
56
|
-
return Shipped(shipped=choice.size)
|
|
57
|
-
|
|
58
|
-
app = server.streamable_http_app(stateless_http=True)
|
|
59
|
-
|
|
60
|
-
def http_client():
|
|
61
|
-
return httpx2.AsyncClient(transport=httpx2.ASGITransport(app=app))
|
|
62
|
-
|
|
63
|
-
apps = Apps(
|
|
64
|
-
{"name": "checkout", "version": "1", "requires": {}},
|
|
65
|
-
{"orders": contract},
|
|
66
|
-
{
|
|
67
|
-
"orders": {
|
|
68
|
-
"endpoint": "http://127.0.0.1:8000/mcp",
|
|
69
|
-
"http_client": http_client,
|
|
70
|
-
"elicit": elicit,
|
|
71
|
-
}
|
|
72
|
-
},
|
|
73
|
-
)
|
|
74
|
-
async with app.router.lifespan_context(app):
|
|
75
|
-
await body(apps.orders)
|
|
76
|
-
|
|
77
|
-
asyncio.run(asyncio.wait_for(run(), timeout=15))
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
def test_elicit_answers_in_place_and_the_tool_returns_typed_output():
|
|
81
|
-
asked = []
|
|
82
|
-
|
|
83
|
-
async def elicit(context, params):
|
|
84
|
-
asked.append(params.message)
|
|
85
|
-
return ElicitResult(action="accept", content={"size": "large"})
|
|
86
|
-
|
|
87
|
-
async def body(orders):
|
|
88
|
-
assert await orders.tools.ship(id="A-1") == {"shipped": "large"}
|
|
89
|
-
whole = await orders.call_tool("ship", id="A-1")
|
|
90
|
-
assert isinstance(whole, CallToolResult)
|
|
91
|
-
assert whole.structured_content == {"shipped": "large"}
|
|
92
|
-
|
|
93
|
-
exercise(body, elicit)
|
|
94
|
-
assert asked == [QUESTION, QUESTION]
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
def test_accepted_output_is_still_validated():
|
|
98
|
-
async def elicit(context, params):
|
|
99
|
-
return ElicitResult(action="accept", content={"size": "large"})
|
|
100
|
-
|
|
101
|
-
tool = CONTRACT["tools"][0]
|
|
102
|
-
wrong = {"type": "object", "required": ["total"]}
|
|
103
|
-
|
|
104
|
-
async def body(orders):
|
|
105
|
-
with pytest.raises(ValueError, match="structured output"):
|
|
106
|
-
await orders.tools.ship(id="A-1")
|
|
107
|
-
|
|
108
|
-
exercise(body, elicit, {"tools": [{**tool, "outputSchema": wrong}]})
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
def test_a_declined_elicitation_reaches_the_tool():
|
|
112
|
-
async def elicit(context, params):
|
|
113
|
-
return ElicitResult(action="decline")
|
|
114
|
-
|
|
115
|
-
async def body(orders):
|
|
116
|
-
with pytest.raises(ToolCallError, match="elicitation was decline"):
|
|
117
|
-
await orders.tools.ship(id="A-1")
|
|
118
|
-
|
|
119
|
-
exercise(body, elicit)
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
def test_a_client_without_the_capability_is_told_how_to_declare_it():
|
|
123
|
-
async def body(orders):
|
|
124
|
-
with pytest.raises(MCPError) as error:
|
|
125
|
-
await orders.tools.ship(id="A-1")
|
|
126
|
-
assert error.value.code == MISSING_REQUIRED_CLIENT_CAPABILITY
|
|
127
|
-
assert str(error.value).startswith("orders.ship: ")
|
|
128
|
-
assert str(error.value).endswith("Set elicit on the binding.")
|
|
129
|
-
assert error.value.data["requiredCapabilities"]["elicitation"]["form"] == {}
|
|
130
|
-
|
|
131
|
-
exercise(body)
|
|
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
|