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.
Files changed (25) hide show
  1. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/PKG-INFO +20 -21
  2. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/README.md +18 -19
  3. holon_sh-0.0.1.dev6/holon/apps/__init__.py +19 -0
  4. holon_sh-0.0.1.dev6/holon/binding.py +20 -0
  5. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/holon/client.py +103 -94
  6. holon_sh-0.0.1.dev6/holon/context.py +87 -0
  7. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/pyproject.toml +2 -2
  8. holon_sh-0.0.1.dev6/tests/test_context.py +53 -0
  9. holon_sh-0.0.1.dev6/tests/test_elicit.py +165 -0
  10. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/test_package.py +23 -8
  11. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/test_runtime.py +42 -65
  12. holon_sh-0.0.1.dev4/holon/binding.py +0 -52
  13. holon_sh-0.0.1.dev4/holon/view.py +0 -55
  14. holon_sh-0.0.1.dev4/scripts/fixtures.sh +0 -7
  15. holon_sh-0.0.1.dev4/tests/fixtures/orders/server.json +0 -5
  16. holon_sh-0.0.1.dev4/tests/fixtures/orders/server.py +0 -57
  17. holon_sh-0.0.1.dev4/tests/test_elicit.py +0 -131
  18. holon_sh-0.0.1.dev4/tests/test_view.py +0 -47
  19. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/.gitignore +0 -0
  20. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/LICENSE +0 -0
  21. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/holon/py.typed +0 -0
  22. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/scripts/verify_distribution.py +0 -0
  23. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
  24. {holon_sh-0.0.1.dev4 → holon_sh-0.0.1.dev6}/tests/fixtures/caller/requirements.txt +0 -0
  25. {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.dev4
4
- Summary: Typed MCP clients, bindings, and app views
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, validated before sending; the result is validated against the output schema and returned.
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
- ... # call again with input_responses and request_state
80
+ ... # call again with input_responses and request_state
80
81
  elif result.is_error:
81
- ... # inspect result.content
82
+ ... # inspect result.content
82
83
  else:
83
- result.structured_content # typed as Outputs.bar.greet
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). Bind `elicit` to answer in place, and the call returns its usual typed output:
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
- async def elicit(context, params):
99
+
100
+ async def elicit(params):
100
101
  return ElicitResult(action="accept", content=await ask(params.message))
101
102
 
102
- apps = create_apps({"bar": {"endpoint": "https://bar.example.com/mcp", "elicit": elicit}})
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`, a client declares no capability, so a server that needs it rejects the call.
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
- ## Serve an [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) view
111
+ ## Identify the caller
111
112
 
112
- `holon.view.app_view` registers a built HTML file as an MCP App resource:
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.view import app_view
116
+ from holon.context import get_context
116
117
 
117
- server.add_resource(app_view(
118
- "ui://foo/index.html", "Foo", "dist/index.html",
119
- connect_domains=["https://bar.example.com"],
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, validated before sending; the result is validated against the output schema and returned.
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
- ... # call again with input_responses and request_state
67
+ ... # call again with input_responses and request_state
67
68
  elif result.is_error:
68
- ... # inspect result.content
69
+ ... # inspect result.content
69
70
  else:
70
- result.structured_content # typed as Outputs.bar.greet
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). Bind `elicit` to answer in place, and the call returns its usual typed output:
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
- async def elicit(context, params):
86
+
87
+ async def elicit(params):
87
88
  return ElicitResult(action="accept", content=await ask(params.message))
88
89
 
89
- apps = create_apps({"bar": {"endpoint": "https://bar.example.com/mcp", "elicit": elicit}})
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`, a client declares no capability, so a server that needs it rejects the call.
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
- ## Serve an [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) view
98
+ ## Identify the caller
98
99
 
99
- `holon.view.app_view` registers a built HTML file as an MCP App resource:
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.view import app_view
103
+ from holon.context import get_context
103
104
 
104
- server.add_resource(app_view(
105
- "ui://foo/index.html", "Foo", "dist/index.html",
106
- connect_domains=["https://bar.example.com"],
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 # type: ignore[import-untyped,unused-ignore]
11
- from mcp import Client, MCPError
12
- from mcp.client.session import ElicitationFnT
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, resolve_default_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. Bind ``elicit`` to
83
- answer questions in place, or use ``call_tool`` to continue later.
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
- if detail:
99
- message = f"{message}: {detail}"
105
+ if detail:
106
+ message = f"{message}: {detail}"
100
107
  super().__init__(f"{app}.{tool}: {message}")
101
108
 
102
109
 
103
- def validate(schema: dict[str, Any], value: object, label: str) -> None:
104
- try:
105
- jsonschema.validate(
106
- value,
107
- schema,
108
- registry=Registry(),
109
- format_checker=jsonschema.FormatChecker(),
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
- except jsonschema.ValidationError as error:
112
- raise ValueError(f"Invalid {label}: {error.message}") from error
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
- # None for a dependency without a contract: any tool, unvalidated.
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 metadata. Passed positionally, separate from tool input.
153
- **arguments: Tool input, validated against the contract if present.
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 when the binding has
157
- no ``elicit``. Tool error results are returned unchanged; successful
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 input/output, or undeclared dependency.
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
- validate(
174
- definition["inputSchema"],
175
- arguments,
176
- f"arguments for {self._name}.{name}",
177
- )
178
- binding = self._binding or resolve_default_binding(self._name)
179
- if binding is None and self._name not in self._identity["requires"]:
180
- raise ValueError(
181
- f"Dependency {self._name} is not declared by this application."
182
- )
183
- variable = self._name.upper().replace("-", "_") + "_MCP_URL"
184
- endpoint = binding["endpoint"] if binding else os.environ.get(variable)
185
- if not endpoint:
186
- raise RuntimeError(
187
- f"Dependency {self._name} is unavailable ({variable}). Set the endpoint or supply a binding."
188
- )
189
- elicit = binding.get("elicit") if binding else None
190
- http_client = partial(httpx2.AsyncClient, trust_env=False)
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.get("http_client", http_client) if binding else http_client
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=elicit,
239
+ elicitation_callback=_declare_elicitation,
203
240
  ) as client:
204
241
  try:
205
- result = await self._send(client, name, arguments, options, elicit)
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
- validate(
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
- @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"),
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
- 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
- )
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, or additional input requests when
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.dev4"
8
- description = "Typed MCP clients, bindings, and app views"
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"]