holon-sh 0.0.1.dev4__tar.gz → 0.0.1.dev6__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.dev6}/PKG-INFO +20 -21
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/README.md +18 -19
- holon_sh-0.0.1.dev6/holon/apps/__init__.py +19 -0
- holon_sh-0.0.1.dev6/holon/binding.py +20 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/holon/client.py +103 -94
- holon_sh-0.0.1.dev6/holon/context.py +87 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/pyproject.toml +2 -2
- holon_sh-0.0.1.dev6/tests/test_context.py +53 -0
- holon_sh-0.0.1.dev6/tests/test_elicit.py +165 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/test_package.py +23 -8
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/test_runtime.py +42 -65
- holon_sh-0.0.1.dev4/holon/binding.py +0 -52
- holon_sh-0.0.1.dev4/holon/view.py +0 -55
- holon_sh-0.0.1.dev4/scripts/fixtures.sh +0 -7
- holon_sh-0.0.1.dev4/tests/fixtures/orders/server.json +0 -5
- holon_sh-0.0.1.dev4/tests/fixtures/orders/server.py +0 -57
- holon_sh-0.0.1.dev4/tests/test_elicit.py +0 -131
- holon_sh-0.0.1.dev4/tests/test_view.py +0 -47
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/.gitignore +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/LICENSE +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/holon/py.typed +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/scripts/verify_distribution.py +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/fixtures/caller/requirements.txt +0 -0
- {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/fixtures/caller/server.json +0 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: holon-sh
|
|
3
|
-
Version: 0.0.1.
|
|
4
|
-
Summary: Typed MCP clients
|
|
3
|
+
Version: 0.0.1.dev6
|
|
4
|
+
Summary: Typed MCP clients and the caller of an MCP request
|
|
5
5
|
Project-URL: Repository, https://github.com/holon-sh/sdk-py
|
|
6
6
|
License-Expression: Apache-2.0
|
|
7
7
|
License-File: LICENSE
|
|
@@ -45,12 +45,13 @@ uv run holon types check
|
|
|
45
45
|
```python
|
|
46
46
|
from holon.apps import apps
|
|
47
47
|
|
|
48
|
+
|
|
48
49
|
async def greet(name: str) -> str:
|
|
49
50
|
greeting = await apps.bar.tools.greet({"timeout": 5.0}, name=name)
|
|
50
51
|
return greeting["result"]
|
|
51
52
|
```
|
|
52
53
|
|
|
53
|
-
Arguments are keywords
|
|
54
|
+
Arguments are keywords; the result is validated against the output schema and returned.
|
|
54
55
|
|
|
55
56
|
</details>
|
|
56
57
|
|
|
@@ -76,11 +77,11 @@ except ToolCallError as error:
|
|
|
76
77
|
```python
|
|
77
78
|
result = await apps.bar.call_tool("greet", name="world")
|
|
78
79
|
if result.result_type == "input_required":
|
|
79
|
-
...
|
|
80
|
+
... # call again with input_responses and request_state
|
|
80
81
|
elif result.is_error:
|
|
81
|
-
...
|
|
82
|
+
... # inspect result.content
|
|
82
83
|
else:
|
|
83
|
-
result.structured_content
|
|
84
|
+
result.structured_content # typed as Outputs.bar.greet
|
|
84
85
|
```
|
|
85
86
|
|
|
86
87
|
The options dict also accepts `input_responses`, `request_state` and `meta`.
|
|
@@ -90,34 +91,32 @@ The options dict also accepts `input_responses`, `request_state` and `meta`.
|
|
|
90
91
|
<details open>
|
|
91
92
|
<summary><h3>Answer a server's question</h3></summary>
|
|
92
93
|
|
|
93
|
-
A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation).
|
|
94
|
+
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
95
|
|
|
95
96
|
```python
|
|
96
|
-
from holon.apps import create_apps
|
|
97
97
|
from mcp.types import ElicitResult
|
|
98
98
|
|
|
99
|
-
|
|
99
|
+
|
|
100
|
+
async def elicit(params):
|
|
100
101
|
return ElicitResult(action="accept", content=await ask(params.message))
|
|
101
102
|
|
|
102
|
-
|
|
103
|
-
greeting = await apps.bar.tools.greet(name="world")
|
|
103
|
+
|
|
104
|
+
greeting = await apps.bar.tools.greet({"elicit": elicit}, name="world")
|
|
104
105
|
```
|
|
105
106
|
|
|
106
|
-
Without `elicit`,
|
|
107
|
+
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
108
|
|
|
108
109
|
</details>
|
|
109
110
|
|
|
110
|
-
##
|
|
111
|
+
## Identify the caller
|
|
111
112
|
|
|
112
|
-
`
|
|
113
|
+
Inside a tool handler, `get_context().principal` is the user Holon admitted for the request, or `None` for anonymous requests:
|
|
113
114
|
|
|
114
115
|
```python
|
|
115
|
-
from holon.
|
|
116
|
+
from holon.context import get_context
|
|
116
117
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
)
|
|
118
|
+
principal = get_context().principal
|
|
119
|
+
if principal is not None:
|
|
120
|
+
principal.issuer, principal.subject, principal.scopes
|
|
121
|
+
principal.claims.get("email") # standard OpenID claims are typed: str | None
|
|
121
122
|
```
|
|
122
|
-
|
|
123
|
-
The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).
|
|
@@ -32,12 +32,13 @@ uv run holon types check
|
|
|
32
32
|
```python
|
|
33
33
|
from holon.apps import apps
|
|
34
34
|
|
|
35
|
+
|
|
35
36
|
async def greet(name: str) -> str:
|
|
36
37
|
greeting = await apps.bar.tools.greet({"timeout": 5.0}, name=name)
|
|
37
38
|
return greeting["result"]
|
|
38
39
|
```
|
|
39
40
|
|
|
40
|
-
Arguments are keywords
|
|
41
|
+
Arguments are keywords; the result is validated against the output schema and returned.
|
|
41
42
|
|
|
42
43
|
</details>
|
|
43
44
|
|
|
@@ -63,11 +64,11 @@ except ToolCallError as error:
|
|
|
63
64
|
```python
|
|
64
65
|
result = await apps.bar.call_tool("greet", name="world")
|
|
65
66
|
if result.result_type == "input_required":
|
|
66
|
-
...
|
|
67
|
+
... # call again with input_responses and request_state
|
|
67
68
|
elif result.is_error:
|
|
68
|
-
...
|
|
69
|
+
... # inspect result.content
|
|
69
70
|
else:
|
|
70
|
-
result.structured_content
|
|
71
|
+
result.structured_content # typed as Outputs.bar.greet
|
|
71
72
|
```
|
|
72
73
|
|
|
73
74
|
The options dict also accepts `input_responses`, `request_state` and `meta`.
|
|
@@ -77,34 +78,32 @@ The options dict also accepts `input_responses`, `request_state` and `meta`.
|
|
|
77
78
|
<details open>
|
|
78
79
|
<summary><h3>Answer a server's question</h3></summary>
|
|
79
80
|
|
|
80
|
-
A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation).
|
|
81
|
+
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
82
|
|
|
82
83
|
```python
|
|
83
|
-
from holon.apps import create_apps
|
|
84
84
|
from mcp.types import ElicitResult
|
|
85
85
|
|
|
86
|
-
|
|
86
|
+
|
|
87
|
+
async def elicit(params):
|
|
87
88
|
return ElicitResult(action="accept", content=await ask(params.message))
|
|
88
89
|
|
|
89
|
-
|
|
90
|
-
greeting = await apps.bar.tools.greet(name="world")
|
|
90
|
+
|
|
91
|
+
greeting = await apps.bar.tools.greet({"elicit": elicit}, name="world")
|
|
91
92
|
```
|
|
92
93
|
|
|
93
|
-
Without `elicit`,
|
|
94
|
+
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
95
|
|
|
95
96
|
</details>
|
|
96
97
|
|
|
97
|
-
##
|
|
98
|
+
## Identify the caller
|
|
98
99
|
|
|
99
|
-
`
|
|
100
|
+
Inside a tool handler, `get_context().principal` is the user Holon admitted for the request, or `None` for anonymous requests:
|
|
100
101
|
|
|
101
102
|
```python
|
|
102
|
-
from holon.
|
|
103
|
+
from holon.context import get_context
|
|
103
104
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
)
|
|
105
|
+
principal = get_context().principal
|
|
106
|
+
if principal is not None:
|
|
107
|
+
principal.issuer, principal.subject, principal.scopes
|
|
108
|
+
principal.claims.get("email") # standard OpenID claims are typed: str | None
|
|
108
109
|
```
|
|
109
|
-
|
|
110
|
-
The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import sys
|
|
2
|
+
from importlib.util import module_from_spec, spec_from_file_location
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
|
|
5
|
+
import holon
|
|
6
|
+
|
|
7
|
+
_here = Path(__file__).resolve().parent
|
|
8
|
+
for _portion in holon.__path__:
|
|
9
|
+
_generated = Path(_portion, "apps")
|
|
10
|
+
if _generated.resolve() != _here and (_generated / "__init__.py").is_file():
|
|
11
|
+
_spec = spec_from_file_location(__name__, _generated / "__init__.py")
|
|
12
|
+
assert _spec and _spec.loader
|
|
13
|
+
sys.modules[__name__] = _module = module_from_spec(_spec)
|
|
14
|
+
_spec.loader.exec_module(_module)
|
|
15
|
+
break
|
|
16
|
+
else:
|
|
17
|
+
raise ImportError(
|
|
18
|
+
"no generated holon.apps on sys.path: run `holon types generate` in the project"
|
|
19
|
+
)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from collections.abc import Callable
|
|
4
|
+
from typing import NotRequired, TypedDict
|
|
5
|
+
|
|
6
|
+
import httpx2
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class Binding(TypedDict):
|
|
10
|
+
"""Connection settings for an MCP dependency.
|
|
11
|
+
|
|
12
|
+
Attributes:
|
|
13
|
+
endpoint: Streamable HTTP MCP URL.
|
|
14
|
+
http_client: Factory returning a fresh ``httpx2.AsyncClient`` for each
|
|
15
|
+
call. Configure authentication headers or a custom transport here.
|
|
16
|
+
The SDK closes the returned client when the call finishes.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
endpoint: str
|
|
20
|
+
http_client: NotRequired[Callable[[], httpx2.AsyncClient]]
|
|
@@ -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
|
-
import jsonschema
|
|
11
|
-
from mcp import Client
|
|
12
|
-
from mcp.client.session import
|
|
10
|
+
import jsonschema
|
|
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,
|
|
@@ -26,9 +28,8 @@ from mcp.types import (
|
|
|
26
28
|
from pydantic import TypeAdapter
|
|
27
29
|
from referencing import Registry
|
|
28
30
|
|
|
29
|
-
from holon.binding import Binding
|
|
31
|
+
from holon.binding import Binding
|
|
30
32
|
|
|
31
|
-
# Binding is re-exported for the generated holon.apps module.
|
|
32
33
|
__all__ = [
|
|
33
34
|
"Apps",
|
|
34
35
|
"Binding",
|
|
@@ -73,14 +74,15 @@ class CallOptions(TypedDict, total=False):
|
|
|
73
74
|
input_responses: InputResponses | None
|
|
74
75
|
request_state: str | None
|
|
75
76
|
meta: RequestParamsMeta | None
|
|
77
|
+
elicit: Callable[[ElicitRequestParams], Awaitable[ElicitResult]]
|
|
76
78
|
|
|
77
79
|
|
|
78
80
|
class ToolCallError(RuntimeError):
|
|
79
81
|
"""Raised by ``tools.<name>`` for tool errors or additional input requests.
|
|
80
82
|
|
|
81
83
|
Attributes:
|
|
82
|
-
result: Original MCP error or input-required result.
|
|
83
|
-
answer questions in place, or
|
|
84
|
+
result: Original MCP error or input-required result. Pass ``elicit`` to
|
|
85
|
+
answer questions in place, or continue later through ``call_tool``.
|
|
84
86
|
"""
|
|
85
87
|
|
|
86
88
|
def __init__(
|
|
@@ -89,27 +91,57 @@ class ToolCallError(RuntimeError):
|
|
|
89
91
|
self.result = result
|
|
90
92
|
if isinstance(result, InputRequiredResult):
|
|
91
93
|
message = "additional input required"
|
|
94
|
+
detail = " ".join(
|
|
95
|
+
f"{request.params.message} {getattr(request.params, 'url', '')}".strip()
|
|
96
|
+
for request in (result.input_requests or {}).values()
|
|
97
|
+
if isinstance(request, ElicitRequest)
|
|
98
|
+
)
|
|
92
99
|
else:
|
|
93
100
|
message = "tool failed"
|
|
94
101
|
detail = next(
|
|
95
102
|
(part.text for part in result.content if isinstance(part, TextContent)),
|
|
96
103
|
"",
|
|
97
104
|
)
|
|
98
|
-
|
|
99
|
-
|
|
105
|
+
if detail:
|
|
106
|
+
message = f"{message}: {detail}"
|
|
100
107
|
super().__init__(f"{app}.{tool}: {message}")
|
|
101
108
|
|
|
102
109
|
|
|
103
|
-
def
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
+
async def _declare_elicitation(
|
|
111
|
+
context: ClientRequestContext, params: ElicitRequestParams
|
|
112
|
+
) -> ElicitResult:
|
|
113
|
+
return ElicitResult(action="decline")
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
async def _send(
|
|
117
|
+
client: Client, name: str, arguments: dict[str, Any], options: CallOptions
|
|
118
|
+
) -> CallToolResult | InputRequiredResult:
|
|
119
|
+
elicit = options.get("elicit")
|
|
120
|
+
responses, state = options.get("input_responses"), options.get("request_state")
|
|
121
|
+
answered = 0
|
|
122
|
+
while True:
|
|
123
|
+
result = await client.session.send_request(
|
|
124
|
+
CallToolRequest(
|
|
125
|
+
params=CallToolRequestParams(
|
|
126
|
+
name=name,
|
|
127
|
+
arguments=arguments,
|
|
128
|
+
input_responses=responses,
|
|
129
|
+
request_state=state,
|
|
130
|
+
_meta=options.get("meta"),
|
|
131
|
+
)
|
|
132
|
+
),
|
|
133
|
+
_result,
|
|
134
|
+
request_read_timeout_seconds=options.get("timeout"),
|
|
110
135
|
)
|
|
111
|
-
|
|
112
|
-
|
|
136
|
+
if not (elicit and answered < 10 and isinstance(result, InputRequiredResult)):
|
|
137
|
+
return result
|
|
138
|
+
answered += 1
|
|
139
|
+
responses = {
|
|
140
|
+
key: await elicit(request.params)
|
|
141
|
+
for key, request in (result.input_requests or {}).items()
|
|
142
|
+
if isinstance(request, ElicitRequest)
|
|
143
|
+
}
|
|
144
|
+
state = result.request_state
|
|
113
145
|
|
|
114
146
|
|
|
115
147
|
class _App:
|
|
@@ -123,7 +155,7 @@ class _App:
|
|
|
123
155
|
self._name = name
|
|
124
156
|
self._identity = identity
|
|
125
157
|
self._binding = binding
|
|
126
|
-
|
|
158
|
+
self._validators: dict[str, Any] = {}
|
|
127
159
|
self._definitions = (
|
|
128
160
|
None
|
|
129
161
|
if contract is None
|
|
@@ -149,16 +181,17 @@ class _App:
|
|
|
149
181
|
Args:
|
|
150
182
|
name: Tool name. Contracted dependencies reject unknown tools.
|
|
151
183
|
options: Request timeout in seconds, input responses, continuation
|
|
152
|
-
state, and
|
|
153
|
-
|
|
184
|
+
state, metadata, and ``elicit`` to answer the server's questions in
|
|
185
|
+
place. Passed positionally, separate from tool input.
|
|
186
|
+
**arguments: Tool input, which the server validates.
|
|
154
187
|
|
|
155
188
|
Returns:
|
|
156
|
-
A complete result, or an input-required result
|
|
157
|
-
|
|
189
|
+
A complete result, or an input-required result for a question left
|
|
190
|
+
unanswered. Tool error results are returned unchanged; successful
|
|
158
191
|
structured output is contract-validated.
|
|
159
192
|
|
|
160
193
|
Raises:
|
|
161
|
-
ValueError: Unknown tool, invalid
|
|
194
|
+
ValueError: Unknown tool, invalid output, or undeclared dependency.
|
|
162
195
|
RuntimeError: Endpoint resolution failed.
|
|
163
196
|
|
|
164
197
|
Transport and protocol exceptions propagate. Each call closes its HTTP
|
|
@@ -170,51 +203,45 @@ class _App:
|
|
|
170
203
|
definition = self._definitions.get(name)
|
|
171
204
|
if definition is None:
|
|
172
205
|
raise ValueError(f"Unknown tool {self._name}.{name}.")
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
)
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
206
|
+
timeout = options.get("timeout")
|
|
207
|
+
http_client = partial(
|
|
208
|
+
httpx2.AsyncClient,
|
|
209
|
+
trust_env=False,
|
|
210
|
+
timeout=httpx2.Timeout(timeout, read=None),
|
|
211
|
+
)
|
|
212
|
+
binding = self._binding
|
|
213
|
+
if binding is None:
|
|
214
|
+
if self._name not in self._identity["requires"]:
|
|
215
|
+
raise ValueError(
|
|
216
|
+
f"Dependency {self._name} is not declared by this application."
|
|
217
|
+
)
|
|
218
|
+
prefix = self._name.upper().replace("-", "_") + "_MCP_"
|
|
219
|
+
endpoint = os.environ.get(prefix + "URL")
|
|
220
|
+
if not endpoint:
|
|
221
|
+
raise RuntimeError(
|
|
222
|
+
f"Dependency {self._name} is unavailable ({prefix}URL). Set the endpoint or supply a binding."
|
|
223
|
+
)
|
|
224
|
+
token = os.environ.get(prefix + "TOKEN")
|
|
225
|
+
headers = {"Authorization": f"Bearer {token}"} if token else None
|
|
226
|
+
binding = {
|
|
227
|
+
"endpoint": endpoint,
|
|
228
|
+
"http_client": partial(http_client, headers=headers),
|
|
229
|
+
}
|
|
191
230
|
failure: Exception | None = None
|
|
192
|
-
async with (
|
|
193
|
-
binding
|
|
194
|
-
)() as http:
|
|
195
|
-
transport = streamable_http_client(endpoint, http_client=http)
|
|
231
|
+
async with binding.get("http_client", http_client)() as http:
|
|
232
|
+
transport = streamable_http_client(binding["endpoint"], http_client=http)
|
|
196
233
|
async with Client(
|
|
197
234
|
transport,
|
|
198
235
|
client_info=Implementation(
|
|
199
236
|
name=self._identity["name"], version=self._identity["version"]
|
|
200
237
|
),
|
|
201
238
|
mode="2026-07-28",
|
|
202
|
-
elicitation_callback=
|
|
239
|
+
elicitation_callback=_declare_elicitation,
|
|
203
240
|
) as client:
|
|
204
241
|
try:
|
|
205
|
-
result = await
|
|
242
|
+
result = await _send(client, name, arguments, options)
|
|
206
243
|
except Exception as error: # noqa: BLE001
|
|
207
|
-
# Raised below: the client's task group would wrap it in an ExceptionGroup.
|
|
208
244
|
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
245
|
if failure is not None:
|
|
219
246
|
raise failure
|
|
220
247
|
if (
|
|
@@ -223,44 +250,28 @@ class _App:
|
|
|
223
250
|
and not result.is_error
|
|
224
251
|
and "outputSchema" in definition
|
|
225
252
|
):
|
|
226
|
-
|
|
253
|
+
self._validate(
|
|
254
|
+
name,
|
|
227
255
|
definition["outputSchema"],
|
|
228
256
|
result.structured_content,
|
|
229
257
|
f"structured output from {self._name}.{name}",
|
|
230
258
|
)
|
|
231
259
|
return result
|
|
232
260
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
name
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
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"),
|
|
261
|
+
def _validate(
|
|
262
|
+
self, name: str, schema: dict[str, Any], value: Any, label: str
|
|
263
|
+
) -> None:
|
|
264
|
+
validator = self._validators.get(name)
|
|
265
|
+
if validator is None or validator.schema is not schema:
|
|
266
|
+
cls = jsonschema.validators.validator_for(schema)
|
|
267
|
+
cls.check_schema(schema)
|
|
268
|
+
validator = self._validators[name] = cls(
|
|
269
|
+
schema, registry=Registry(), format_checker=jsonschema.FormatChecker()
|
|
250
270
|
)
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
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
|
-
)
|
|
271
|
+
if (
|
|
272
|
+
error := jsonschema.exceptions.best_match(validator.iter_errors(value))
|
|
273
|
+
) is not None:
|
|
274
|
+
raise ValueError(f"Invalid {label}: {error.message}") from error
|
|
264
275
|
|
|
265
276
|
async def _call_tool(
|
|
266
277
|
self,
|
|
@@ -294,8 +305,7 @@ class Apps:
|
|
|
294
305
|
Access a client with ``clients[name]`` or ``clients.name``. Its
|
|
295
306
|
``tools.<name>(**arguments)`` methods return structured output, or the
|
|
296
307
|
complete result for a tool without an output schema, and raise
|
|
297
|
-
:class:`ToolCallError` for tool errors
|
|
298
|
-
the binding has no ``elicit``.
|
|
308
|
+
:class:`ToolCallError` for tool errors or questions left unanswered.
|
|
299
309
|
Use its ``call_tool`` method for the full result envelope.
|
|
300
310
|
"""
|
|
301
311
|
|
|
@@ -305,7 +315,6 @@ class Apps:
|
|
|
305
315
|
contracts: dict[str, Any],
|
|
306
316
|
bindings: Mapping[str, Binding] | None = None,
|
|
307
317
|
) -> None:
|
|
308
|
-
# Every declared dependency gets a client; those without a contract are untyped.
|
|
309
318
|
available = dict.fromkeys(identity["requires"]) | contracts
|
|
310
319
|
self._apps = {}
|
|
311
320
|
for name in available if bindings is None else bindings:
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from typing import Any, TypedDict
|
|
5
|
+
|
|
6
|
+
from mcp.server.auth.middleware.auth_context import get_access_token
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class AddressClaims(TypedDict, total=False):
|
|
10
|
+
formatted: str
|
|
11
|
+
street_address: str
|
|
12
|
+
locality: str
|
|
13
|
+
region: str
|
|
14
|
+
postal_code: str
|
|
15
|
+
country: str
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class IdentityClaims(TypedDict, total=False):
|
|
19
|
+
"""Standard OpenID Connect claims.
|
|
20
|
+
|
|
21
|
+
Holon drops one whose value has the wrong type; other claims pass through.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
name: str
|
|
25
|
+
given_name: str
|
|
26
|
+
family_name: str
|
|
27
|
+
middle_name: str
|
|
28
|
+
nickname: str
|
|
29
|
+
preferred_username: str
|
|
30
|
+
profile: str
|
|
31
|
+
picture: str
|
|
32
|
+
website: str
|
|
33
|
+
email: str
|
|
34
|
+
email_verified: bool
|
|
35
|
+
gender: str
|
|
36
|
+
birthdate: str
|
|
37
|
+
zoneinfo: str
|
|
38
|
+
locale: str
|
|
39
|
+
phone_number: str
|
|
40
|
+
phone_number_verified: bool
|
|
41
|
+
address: AddressClaims
|
|
42
|
+
updated_at: float
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class Principal:
|
|
47
|
+
"""The user a request acts for, as Holon admitted it."""
|
|
48
|
+
|
|
49
|
+
issuer: str
|
|
50
|
+
subject: str
|
|
51
|
+
client_id: str
|
|
52
|
+
scopes: list[str]
|
|
53
|
+
claims: IdentityClaims
|
|
54
|
+
actor: dict[str, Any] | None = None
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass(frozen=True)
|
|
58
|
+
class RequestContext:
|
|
59
|
+
principal: Principal | None
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def get_context() -> RequestContext:
|
|
63
|
+
"""Read the caller of the current MCP request.
|
|
64
|
+
|
|
65
|
+
Holon validates the request before it reaches the application and hands the
|
|
66
|
+
caller over as MCP's access token, so this reads ``get_access_token()``.
|
|
67
|
+
|
|
68
|
+
Returns:
|
|
69
|
+
A ``RequestContext`` whose ``principal`` is ``None`` for anonymous requests.
|
|
70
|
+
|
|
71
|
+
Example:
|
|
72
|
+
``principal = get_context().principal``
|
|
73
|
+
"""
|
|
74
|
+
admitted = get_access_token()
|
|
75
|
+
extra = (admitted.claims or {}) if admitted else {}
|
|
76
|
+
if admitted is None or admitted.subject is None or "iss" not in extra:
|
|
77
|
+
return RequestContext(principal=None)
|
|
78
|
+
return RequestContext(
|
|
79
|
+
Principal(
|
|
80
|
+
issuer=extra["iss"],
|
|
81
|
+
subject=admitted.subject,
|
|
82
|
+
client_id=admitted.client_id,
|
|
83
|
+
scopes=admitted.scopes,
|
|
84
|
+
claims=extra.get("claims", {}),
|
|
85
|
+
actor=extra.get("act"),
|
|
86
|
+
)
|
|
87
|
+
)
|
|
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "holon-sh"
|
|
7
|
-
version = "0.0.1.
|
|
8
|
-
description = "Typed MCP clients
|
|
7
|
+
version = "0.0.1.dev6"
|
|
8
|
+
description = "Typed MCP clients and the caller of an MCP request"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "Apache-2.0"
|
|
11
11
|
license-files = ["LICENSE"]
|