dsh-py-codeact 0.2.2 → 0.2.3

package/README.md

@@ -52,7 +52,7 @@ A dunder-named package reads as harness-owned, survives `%reset`, and leaves the
 
 ```
 In [1]: read?
-Signature: read(*, file_path: 'str', offset: 'int' = Ellipsis, limit: 'int' = Ellipsis) -> 'str'
+Signature: read(*, file_path: 'str', offset: 'int' = ..., limit: 'int' = ...) -> 'str'
 Docstring: Read a file from the workspace. Results include line numbers…
 ```
 
@@ -66,7 +66,8 @@ Each object in that schema whose keys — and whose own generated class name —
 class McpCalendarListEventsOutput(TypedDict):
     result: str
 
-async def mcp__calendar__list_events(*, calendar_id: str) -> McpCalendarListEventsOutput: ...
+class _McpCalendar(Protocol):
+    async def list_events(self, *, calendar_id: str) -> McpCalendarListEventsOutput: ...
 ```
 
 `jsonSchemaToPy` cannot do this and says so — it is context-free, and naming a `TypedDict` needs the render context `renderToolsSdkPy` supplies. That renderer is not reusable here: it emits a whole document in Code Mode's own `tools.name(args)` contract. So only the object and array branches are handled locally, every leaf still going through `jsonSchemaToPy` — a place to hang the names, not a second JSON-Schema mapper. The binding set is resent with every cell, because restrictions and mid-conversation tool changes can move a tool in or out between calls.
@@ -88,19 +89,32 @@ Unwrapping keys off the tool's declared output schema, not off the value that co
 
 ### MCP tools work, with nothing special
 
-MCP servers register into the same `ctx.tools` registry as everything else, so they arrive in `__dsh__.tools` like any other binding and dispatch through the same pipeline:
+MCP servers register into the same `ctx.tools` registry as everything else, so they arrive in `__dsh__.tools` like any other binding and dispatch through the same pipeline. They are *presented* grouped, under one `mcp`:
 
 ```python
-from __dsh__.tools import mcp__gh__github_graphql as gh
+from __dsh__.tools import mcp
 
-data = await gh(query="{ viewer { login } }")
+data = await mcp.gh.github_graphql(query="{ viewer { login } }")
 ```
 
+dsh names them `mcp__<server>__<rawName>`, and with a hundred mounted that import line was most of the prompt block while every call site respelled its server. The flat names stay bound — `mcp` is how they are shown, not what they are — so a cell written before this still runs, `import *` still binds them, and only the listings drop them. A name the grouping cannot serve is still shown: dsh hashes a public name that needed normalising and the cut can land before the second `__`, and a raw name that is a true dunder is refused by `__getattr__`; either way the flat name is the only one that works. They are kept out of `dir(__dsh__.tools)` for the same reason the block stopped printing them; a name the grouping cannot reach (dsh hashes a public name that needed normalising, and the cut can land before the second `__`) stays listed, because `mcp` is not another way to say it. The block declares the grouping as `Protocol` stubs, one per server, which is the shape dsh's own SDK renderer uses for the same problem.
+
+It is a real package, so a server can be imported as a module — which reads better than `mcp.` at every call site when a cell leans on one server:
+
+```python
+from __dsh__.tools.mcp.calendar import list_events, create_event
+from __dsh__.tools.mcp import calendar          # or the server itself
+```
+
+The deep form is why each server gets a `sys.modules` entry of its own: `__getattr__` can serve `from __dsh__.tools.mcp import calendar`, but not `from __dsh__.tools.mcp.calendar import list_events` — the import machinery looks that one up as a module. No meta path finder is needed; registration is enough.
+
+`mcp` and its server modules are live views of the catalogue, not snapshots of the cell they were imported in: a restriction or a reconnecting server moves tools in and out between calls, and unlike a single tool the model has no reason to ever import the namespace twice. (A name pulled OUT with `from ... import` is a snapshot, as it is for any Python import.) The name is reserved — a native tool called `mcp` is not bound.
+
 dsh's MCP client is explicitly aware of this route — its canonical value "retains the complete JSON MCP blocks and optional structured content for programmatic and Code Mode callers" — and the sub-call logs a `SUBTOOL` row like any other.
 
 Worth contrasting: Anthropic's server-side [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) is *not* compatible with MCP tools. Owning the bridge host-side is what buys this.
 
-(A tool whose name is not a valid Python identifier cannot be `import`ed, but is still reachable as `getattr(__dsh__.tools, "odd-name")`. dsh's MCP naming — `mcp__<server>__<tool>` — always is one.)
+(A tool whose name is not a valid Python identifier cannot be `import`ed, but is still reachable with `getattr` — `getattr(__dsh__.tools, "odd-name")`, or one level deeper for an MCP tool, `getattr(mcp.notion, "API-patch-block-children")`. A raw MCP name is a routine place to find a hyphen.)
 
 ## Exclusive mode
 
@@ -174,7 +188,7 @@ Sub-dispatches carry the outer execution's `parent` token, so they re-enter the
 - **Redundant-import hints.** When an `import` rebinds a name to the object it already held, the result carries `` `json` is already imported in this session — no need to re-import it. `` A model driving a persistent REPL re-imports constantly; telling it is cheaper than letting it burn a line every cell. (Implemented with a `dict` subclass that watches top-level `STORE_NAME` and checks the preceding opcode was `IMPORT_NAME`/`IMPORT_FROM`, so `x = x` does not trip it.)
 - **Readable reprs.** `objprint` + IPython's `pretty` for objects whose own `__repr__` is `object.__repr__` — an agent reading values needs structure, not `<Foo object at 0x…>`.
 - **Tagged observations.** `<stdout>`, `<stderr>`, `<return>`, `<traceback>`, `<note>` — with four things possibly present at once, the model needs to know which is which. A plain successful value stays bare.
-- **Introspection over prompt text.** `read?` for one tool's full description, `dir(__dsh__.tools)` for the whole list, `%whos` for its own bindings.
+- **Introspection over prompt text.** `read?` for one tool's full description, `dir(__dsh__.tools)` for the list — `mcp` rather than the hundred flat names under it, matching what the block printed — then `dir(mcp)` and `dir(mcp.<server>)` for those, and `%whos` for its own bindings. `__all__` is left alone: it is what `import *` binds, not what the model is shown. What it introspects matches what the block showed it: the listing carries `mcp` rather than the hundred flat names under it, and an optional parameter renders `= ...` there as it does here — `inspect.signature` uses `repr`, and `repr(...)` is `Ellipsis`, which is what `read?` used to say.
 
 ## Cancellation
 

package/lib/index.js

@@ -124,7 +124,10 @@ function toolSpec(schema, declarations) {
  */
 function toolSpecs(schemas) {
   const declarations = new Map()
-  const sorted = [...schemas].sort(byName)
+  // The kernel reserves `mcp` for the namespace, so a tool of that name is never bound. Dropped
+  // here rather than at the render, which is downstream of the declarations: one with an object
+  // output still had its `TypedDict` emitted, referenced by nothing.
+  const sorted = [...schemas].filter((schema) => schema.name !== 'mcp').sort(byName)
   // Which tools DECLARE the wrapper. Unwrapping keys off this rather than the returned value:
   // a tool whose own payload happens to be `{content: [...]}` is not wrapping anything, and
   // replacing its value with the joined text would change what it returns with nothing to say so.
@@ -140,8 +143,22 @@ function mcpReturn(schema, declarations) {
   return payload === undefined ? 'str' : declareType(payload, `${pascal(schema.name)}Output`, declarations)
 }
 
+/**
+ * `mcp__calendar__list_events` -> `{ server: 'calendar', tool: 'list_events' }`, matching the
+ * kernel's own split. Only the first two separators are consumed: dsh's name is
+ * `mcp__<serverName>__<rawName>` and a raw name may itself contain `__`.
+ */
+function splitMcp(name) {
+  if (!name.startsWith('mcp__')) return null
+  const rest = name.slice(5)
+  const at = rest.indexOf('__')
+  if (at <= 0 || at + 2 >= rest.length) return null
+  return { server: rest.slice(0, at), tool: rest.slice(at + 2) }
+}
+
 /** Deterministic (lexicographic) order, so an unchanged tool set renders byte-identically. */
-const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+const by = (key) => (a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0)
+const byName = by((spec) => spec.name)
 
 /** The kernel's own wording for a shell whose previous cell has not finished. Matched, not parsed: it is the one failure that leaves the bindings uninstalled. */
 const KERNEL_BUSY = 'kernel busy: a previous cell is still running'
@@ -237,45 +254,105 @@ export function renderToolsSection(schemas) {
   // MCP tools are named `mcp__<server>__<rawName>` over a `[A-Za-z0-9_-]` alphabet, so hyphens are routine — and legal nowhere in `import` or `def`. One such tool used to make the ENTIRE block a SyntaxError, so not a single line in it could be copied, with nothing saying why.
   //
   // A keyword is the same failure wearing a legal shape: `class` and `None` match the identifier pattern and then break `import` and `def` just as hard. `_` and the soft keywords (`match`, `case`, `type`) are in the list because they are legal identifiers everywhere EXCEPT where this block puts them.
-  const importable = specs.filter((spec) => isUsableName(spec.name))
-  const awkward = specs.filter((spec) => !isUsableName(spec.name))
-  const signature = (spec) => {
+  // MCP tools are grouped under one `mcp` binding instead of being listed individually. With a
+  // hundred of them the import line was most of this block, and `mcp__calendar__list_events`
+  // carried its server in the name at every call site; `mcp.calendar.list_events` says the same
+  // thing once. The flat names stay bound — this is how they are PRESENTED, not what they are.
+  const grouped = new Map()
+  const plain = []
+  for (const spec of specs) {
+    const parts = splitMcp(spec.name)
+    if (parts === null) { plain.push(spec); continue }
+    if (!grouped.has(parts.server)) grouped.set(parts.server, [])
+    grouped.get(parts.server).push({ ...spec, tool: parts.tool, server: parts.server })
+  }
+  const importable = plain.filter((spec) => isUsableName(spec.name))
+  const awkward = plain.filter((spec) => !isUsableName(spec.name))
+  // A server or tool whose name Python cannot take keeps its `getattr` route, one level deeper.
+  const servers = [...grouped].filter(([server]) => isUsableName(server)).sort(by(([server]) => server))
+  const oddMcp = [...grouped].flatMap(([server, tools]) =>
+    (isUsableName(server) ? tools.filter((t) => !isUsableName(t.tool)) : tools).map((t) => ({ server, tool: t.tool, usableServer: isUsableName(server) })))
+  // `self` is a parameter here rather than a splice into the finished line, because a Protocol
+  // method needs it in front of BOTH shapes below — and `async def f(*, ) -> T` is a SyntaxError:
+  // a `*` needs at least one name after it, and a parameterless tool takes no keywords at all.
+  // `head` has NO default, so this can never be handed to `.map` — whose second argument is the
+  // index, which a default would silently accept and which is not iterable.
+  const signature = (spec, head) => {
     // The same rule applies one level down, and used to not be applied at all: `file-path` is routine for MCP tools, and one such PARAMETER made every other tool's signature unusable too. The binding still takes it — the kernel folds unnameable parameters into `**kwargs` — so the tool stays importable and only its signature goes vague; `name?` still shows the real one.
-    if (!spec.params.every((p) => isUsableName(p.name))) return `async def ${spec.name}(**kwargs: Any) -> ${spec.returns}: ...  # parameter names are not all valid Python; see ${spec.name}?`
+    if (!spec.params.every((p) => isUsableName(p.name))) return `async def ${spec.name}(${[...head, '**kwargs: Any'].join(', ')}) -> ${spec.returns}: ...  # parameter names are not all valid Python; see ${spec.name}?`
     const fields = spec.params.map((p) => (p.required ? `${p.name}: ${p.type}` : `${p.name}: ${p.type} = ...`))
-    // `async def f(*, ) -> T` is a SyntaxError: a `*` needs at least one name after it, and a parameterless tool takes no keywords at all.
-    return `async def ${spec.name}(${fields.length === 0 ? '' : `*, ${fields.join(', ')}`}) -> ${spec.returns}: ...`
+    return `async def ${spec.name}(${[...head, ...(fields.length === 0 ? [] : [`*, ${fields.join(', ')}`])].join(', ')}) -> ${spec.returns}: ...`
   }
   // `ToolCallError` leads the import because the instructions tell the model to catch it; without it here the natural `except ToolCallError` NameErrors on the failure path, masking the tool failure it was meant to handle. It also keeps the line valid when no tool is importable.
   // The declarations are stubs, not runtime objects — nothing constructs them — so the import line
   // lists exactly what the render used. `Any` has always been reachable from a signature
   // (`**kwargs: Any`, and any degraded annotation) and was never imported at all.
-  const signatures = importable.map(signature)
+  const signatures = importable.map((spec) => signature(spec, []))
+  // A Protocol, not a class of `staticmethod`s: `mcp` is an INSTANCE, so `mcp.calendar.list_events(...)`
+  // binds `self` on its own and the stub says exactly what the call site does. It is also the shape
+  // dsh's own SDK renderer uses for the same problem.
+  const method = (spec) => `    ${signature({ ...spec, name: spec.tool }, ['self'])}`
+  const protocols = servers.flatMap(([server, tools]) => {
+    const body = tools.filter((t) => isUsableName(t.tool)).sort(by((t) => t.tool)).map(method)
+    // A server whose every tool name Python refuses would otherwise emit a class with an empty
+    // body — a SyntaxError that takes the whole block with it. The attribute still has to exist:
+    // the `getattr` line below reaches its tools through it.
+    return ['', `class _Mcp${pascal(server)}(Protocol):`, ...(body.length === 0 ? ['    ...'] : body)]
+  })
+  const mcpBlock = servers.length === 0 ? [] : [
+    ...protocols,
+    '',
+    'class _Mcp(Protocol):',
+    ...servers.map(([server]) => `    ${server}: _Mcp${pascal(server)}`),
+    '',
+    'mcp: _Mcp',
+  ]
   const classes = [...declarations].flatMap(([name, body]) => ['', `class ${name}(TypedDict):`, ...body.split('\n')])
   const typing = [
     // Whole identifiers: `AnyReportOutput` is a class name, not a use of `Any`, and a bare
     // `includes` imports a symbol a tool can spell into existence without ever needing it.
-    signatures.concat(classes).some((line) => /\bAny\b/.test(line)) && 'Any',
+    signatures.concat(classes, mcpBlock).some((line) => /\bAny\b/.test(line)) && 'Any',
     classes.some((line) => line.includes('NotRequired[')) && 'NotRequired',
     declarations.size > 0 && 'TypedDict',
   ].filter(Boolean)
+  const protocolImport = servers.length === 0 ? [] : ['Protocol']
   const lines = [
     INSTRUCTIONS,
     '',
     renderEnvironment(),
     '',
     '```python',
-    ...(typing.length === 0 ? [] : [`from typing import ${typing.join(', ')}`]),
-    `from __dsh__.tools import ToolCallError${importable.map((spec) => `, ${spec.name}`).join('')}`,
+    ...(typing.concat(protocolImport).length === 0 ? [] : [`from typing import ${typing.concat(protocolImport).sort().join(', ')}`]),
+    // `grouped`, not `servers`: a server whose own name Python refuses has no Protocol stub, but its
+    // tools are still reached through `mcp` — the `getattr` line below names it. Keyed on the stubs,
+    // a catalogue of nothing but such servers advertised `getattr(getattr(mcp, …))` without ever
+    // importing `mcp`. The kernel binds it whenever an MCP tool exists, which is this condition.
+    `from __dsh__.tools import ToolCallError${grouped.size === 0 ? '' : ', mcp'}${importable.map((spec) => `, ${spec.name}`).join('')}`,
     ...classes,
+    ...mcpBlock,
     '',
     ...signatures,
     '```',
   ]
+  if (oddMcp.length > 0) {
+    lines.push('', `Under \`mcp\`, but not valid Python identifiers — reach these with \`getattr\`: ${oddMcp.map(({ server, tool, usableServer }) => (usableServer ? `\`getattr(mcp.${server}, ${JSON.stringify(tool)})\`` : `\`getattr(getattr(mcp, ${JSON.stringify(server)}), ${JSON.stringify(tool)})\``)).join(', ')}.`)
+  }
   if (awkward.length > 0) {
     lines.push('', `Not valid Python identifiers — reach these with \`getattr\`: ${awkward.map((spec) => `\`getattr(__dsh__.tools, ${JSON.stringify(spec.name)})\``).join(', ')}.`)
   }
-  lines.push('', 'Each is a real function: `name?` shows its full description, `dir(__dsh__.tools)` lists them.')
+  // The grouping is a real package, so a server can also be imported as a module — which reads
+  // better than `mcp.` at every call site when a cell leans on one server. The example is built
+  // from a server that HAS an importable tool, not just the first one: a server whose every tool
+  // name Python refuses would have put `import ...` in the line, handing the model a SyntaxError
+  // as its example. If no server has one, the `getattr` route above is the only honest advice.
+  const example = servers.flatMap(([server, tools]) => tools.filter((t) => isUsableName(t.tool)).map((t) => [server, t.tool])).at(0)
+  if (example !== undefined) {
+    lines.push('', `Each server is also a module: \`from __dsh__.tools.mcp.${example[0]} import ${example[1]}\` binds its tools directly.`)
+  }
+  // Naming the second level matters once the grouping exists: `dir(__dsh__.tools)` shows `mcp`,
+  // not the hundred tools under it, so a model told only the first level reads a real catalogue as
+  // a broken mount.
+  lines.push('', `Each is a real function: \`name?\` shows its full description, \`dir(__dsh__.tools)\` lists them${servers.length === 0 ? '' : ', and `dir(mcp)` / `dir(mcp.<server>)` the ones under `mcp`'}.`)
   return lines.join('\n')
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-py-codeact",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "CodeAct agent loop for the DeepSeek Harness: a persistent IPython session as the model's action space, with harness tools bridged in as a virtual `__dsh__.tools` module.",
   "license": "MIT",
   "repository": {

package/py/kernel.py

@@ -2,7 +2,7 @@
 # /// script
 # requires-python = ">=3.12"
 # dependencies = [
-#     "ipython~=9.16.0",
+#     "ipython~=9.17.0",
 #     "objprint~=0.3.0",
 # ]
 # # Checked with `TY_UV=scripts ty check py/kernel.py` — that prefix is what hands ty this script's venv. A `ty.toml` would be found and then silently ignored for PEP 723 scripts (astral-sh/ty#4083), so any ty config has to live here.
@@ -238,6 +238,12 @@ def _make_binding(bridge: Bridge, spec):
     return call
 
 
+def bound_tools() -> dict:
+    """The calling shell's catalogue, or nothing outside a cell."""
+    session = _current_session.get()
+    return {} if session is None else session.bindings
+
+
 class ToolsModule(types.ModuleType):
     """`__dsh__.tools` — the bridged tool surface of the CALLING shell.
 
@@ -245,38 +251,211 @@ class ToolsModule(types.ModuleType):
 
     def __init__(self) -> None:
         super().__init__("__dsh__.tools", "Harness tools, bridged into this session as awaitables.")
+        self.__path__ = []  # a package, so `__dsh__.tools.mcp` resolves under it
         self.ToolCallError = ToolCallError
 
-    @staticmethod
-    def _bindings():
-        session = _current_session.get()
-        return {} if session is None else session.bindings
-
     def __getattr__(self, name):  # only reached when the attribute is absent
         if name.startswith("__"):
             raise AttributeError(name)  # import/introspection probing — never answer with a tool
-        bindings = ToolsModule._bindings()
+        bindings = bound_tools()
         if name in bindings:
             return bindings[name]
-        available = ", ".join(sorted(bindings)) or "(none)"
+        # The shown listing, not the bound one: a typo used to push the whole flat catalogue into
+        # the trajectory at the one moment the model is guaranteed to be reading it.
+        available = ", ".join(sorted(listed_tools())) or "(none)"
         raise AttributeError(f"no such tool: {name!r}. Available: {available}")
 
     def __dir__(self):
-        return sorted(ToolsModule._bindings())
+        return sorted(listed_tools())
+
+    # NOT `listed_tools()`: `__all__` is what `from __dsh__.tools import *` BINDS, and narrowing it
+    # left `mcp__gh__ok` undefined in a cell that used to work. Display is `__dir__`'s job.
+    @property
+    def __all__(self):
+        return sorted(bound_tools())
+
+    def __repr__(self) -> str:
+        # The cell's trailing expression is echoed back, so ending on `__dsh__.tools` is the
+        # cheapest "what do I have" move there is — and it used to re-emit the whole flat catalogue.
+        return f"<module '__dsh__.tools': {', '.join(sorted(listed_tools())) or 'no tools bound'}>"
+
+
+MCP_PREFIX = "mcp__"
+
+
+def split_mcp(name: str) -> tuple[str, str] | None:
+    """`mcp__calendar__list_events` -> `("calendar", "list_events")`.
+
+    dsh names every MCP tool `mcp__<serverName>__<rawName>`, and a raw name may itself contain
+    `__` — `split("__")` would tear such a tool apart and file it under a server that does not
+    exist, so only the first two separators are ever consumed.
+
+    PRESENTATION ONLY. dsh's own naming contract says the public name "is never parsed to recover"
+    the raw one, and it is right: a name that needed normalizing, or that ran past 64 characters,
+    becomes `<truncated>_<12 hex of sha256>`, and the cut can land anywhere — including before the
+    second `__`. That case returns `None` here and the tool simply stays flat, reachable under its
+    full public name, which is the only name dispatch ever uses.
+    """
+    if not name.startswith(MCP_PREFIX):
+        return None
+    server, sep, raw = name[len(MCP_PREFIX) :].partition("__")
+    return (server, raw) if sep and server and raw else None
+
+
+def servable(name: str) -> tuple[str, str] | None:
+    """`(server, tool)` when `mcp.<server>.<tool>` can actually ANSWER, else `None`.
+
+    Not `split_mcp` alone. Two ways a name splits cleanly and the grouping still cannot serve it:
+    `McpModule.__getattr__` refuses a true dunder — import and introspection probing (`__path__`,
+    `__all__`, `__spec__`) all wear that shape — and dsh hashes a public name that needed
+    normalising, where the cut can land before the second `__` and `split_mcp` returns `None`.
+
+    The one predicate for the whole file, because the listing and the lookup have to agree: hiding
+    a flat name on the strength of the split alone left `mcp__gh____weird__` in no listing the
+    model ever reads, while `mcp.gh.__weird__` raised `AttributeError`.
+    """
+    parts = split_mcp(name)
+    if parts is None or (parts[1].startswith("__") and parts[1].endswith("__")):
+        return None
+    return parts
+
+
+def listed_tools() -> dict:
+    """What the model is SHOWN: `dir()`, `repr()`, and the `Available:` list of a failed lookup.
+
+    Not `__all__` — that is the star-import BINDING contract, and narrowing it unbound every flat
+    name from `from __dsh__.tools import *`, which is a regression on running code rather than a
+    quieter listing.
+
+    Every flat `mcp__server__tool` name stays bound; showing them contradicted the prompt block,
+    which stopped printing them. Of 103 entries 86 were flat MCP names, and a model asked to
+    introspect its own tools filtered them out by hand. A name the grouping cannot serve stays
+    shown — it is then the only name that works.
+    """
+    return {name: call for name, call in bound_tools().items() if servable(name) is None}
+
+
+def mcp_servers(bindings: dict) -> dict[str, dict]:
+    """Group the flat `mcp__server__tool` bindings into `{server: {tool: call}}`.
+
+    The flat names stay bound too. They are what dsh dispatches on and what an older session may
+    already have imported; dropping them to tidy the surface would break a cell mid-conversation.
+    """
+    servers: dict[str, dict] = {}
+    for name, call in bindings.items():
+        if (parts := split_mcp(name)) is not None:
+            servers.setdefault(parts[0], {})[parts[1]] = call
+    return servers
+
+
+MCP_MODULE = "__dsh__.tools.mcp"
+
+
+def mcp_members(module_name: str) -> dict:
+    """One level of the `mcp` tree, resolved against the catalogue in force NOW.
+
+    Deliberately not a method: a non-dunder attribute on the class would shadow a tool or a server
+    of that name, and a raw MCP name is the server's to choose — `_private` is a legal one.
+    """
+    servers = mcp_servers({name: call for name, call in bound_tools().items() if servable(name) is not None})
+    if module_name == MCP_MODULE:
+        return {server: mcp_server_module(server) for server in servers}
+    # `removeprefix`, not `rpartition`: a raw server name is not guaranteed dot-free, and taking
+    # the last segment of one would look up a server that does not exist and resolve it empty.
+    return servers.get(module_name.removeprefix(f"{MCP_MODULE}."), {})
+
+
+class McpModule(types.ModuleType):
+    """`__dsh__.tools.mcp`, and one of these per server under it.
+
+    Real modules, so every import form the model might reach for resolves the way it does for
+    `__dsh__.tools` itself — including `from __dsh__.tools.mcp.calendar import list_events`, which
+    needs a `sys.modules` entry of its own (the shallower forms can be served by `__getattr__`,
+    that one cannot).
+
+    Their CONTENTS still come from the ContextVar, because `sys.modules` is process-global while
+    the catalogue is per shell — and because a restriction or a reconnecting server moves tools in
+    and out between cells. A name pulled OUT with `from ... import` is a snapshot, as it is for any
+    Python import; the module itself stays live.
+    """
+
+    def __getattr__(self, name):
+        # True dunders only. The guard is here to refuse import and introspection probing
+        # (`__path__`, `__all__`, `__spec__`, `__deepcopy__`), which always ends in `__` too —
+        # and a leading-`__` raw tool name is the server's to choose, so `startswith` alone
+        # advertised `mcp.<server>.__weird` in `dir()` and then refused the call.
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        members = mcp_members(self.__name__)
+        if name not in members:
+            available = ", ".join(sorted(members)) or "(none)"
+            raise AttributeError(f"no such tool: {self.__name__.removeprefix('__dsh__.tools.')}.{name}. Available: {available}")
+        return members[name]
+
+    def __setattr__(self, name, value):
+        # One module per server for the whole PROCESS, so a write here would shadow that name for
+        # every other agent in it — permanently, and invisibly to `dir()`, which keeps reporting
+        # the tool it no longer reaches. The old per-call `Namespace` made this a local mistake.
+        if not (name.startswith("__") and name.endswith("__")):
+            raise AttributeError(f"{self.__name__.removeprefix('__dsh__.tools.')} belongs to the harness and is shared by every agent in this process — bind your own name instead of writing to it")
+        super().__setattr__(name, value)
+
+    def __dir__(self):
+        return sorted(mcp_members(self.__name__))
 
+    # Star-import reads `__all__` (or `vars()`), never `__getattr__` or `__dir__`, and nothing ever
+    # lands in these modules' `__dict__` — so without this `from __dsh__.tools.mcp.x import *`
+    # succeeded and bound nothing. `ToolsModule` carries the same property for the same reason.
     @property
     def __all__(self):
-        return sorted(ToolsModule._bindings())
+        return sorted(mcp_members(self.__name__))
 
     def __repr__(self) -> str:
-        return f"<module '__dsh__.tools': {', '.join(sorted(ToolsModule._bindings())) or 'no tools bound'}>"
+        members = mcp_members(self.__name__)
+        return f"<module {self.__name__!r}: {', '.join(sorted(members)) or 'empty'}>"
+
+
+MCP_ROOT = McpModule(MCP_MODULE, "MCP tools, one module per server.")
+MCP_ROOT.__path__ = []  # a package, like `__dsh__` and `__dsh__.tools`, so its server modules resolve
+sys.modules[MCP_MODULE] = MCP_ROOT
+
+
+def mcp_server_module(server: str) -> McpModule:
+    """The one module for `server`, made on first ask.
+
+    The single construction site, so a module that went missing — a cell can `del sys.modules[…]`
+    — comes back instead of leaving `dir(mcp)` raising `KeyError` for the rest of the session.
+    """
+    name = f"{MCP_MODULE}.{server}"
+    if not isinstance(module := sys.modules.get(name), McpModule):
+        module = McpModule(name, f"Tools bridged from the `{server}` MCP server.")
+        sys.modules[name] = module
+    return module
+
+
+def install_mcp_modules(bindings: dict) -> None:
+    """Register a module per visible MCP server.
+
+    Eager, because the deep import form never reaches `mcp_members`: `from __dsh__.tools.mcp.x
+    import y` is resolved by the import machinery against `sys.modules`, before any attribute
+    lookup happens.
+
+    `sys.modules` only ever gains entries: a server another shell can see costs this one an unused
+    module, while removing it would break an import that shell is mid-conversation with. What a
+    shell can actually reach is decided by `mcp_members`, not by what is registered.
+    """
+    for server in mcp_servers(bindings):
+        mcp_server_module(server)
 
 
 def build_bindings(bridge: Bridge, specs) -> dict:
     """Project one agent's visible tools into awaitables for its shell."""
-    # A tool named `ToolCallError` or `_bindings` would be shadowed by the module's own attributes, and one named `_rebind` used to overwrite a bound method outright. dsh's own SDK renderer refuses `_`-leading tool names for exactly this collision class.
-    reserved = set(vars(ToolsModule)) | set(vars(types.ModuleType)) | {"ToolCallError"}
-    return {spec["name"]: _make_binding(bridge, spec) for spec in specs if not spec["name"].startswith("_") and spec["name"] not in reserved}
+    # A tool named `ToolCallError` would be shadowed by the module's own attributes, and one named `_rebind` used to overwrite a bound method outright. dsh's own SDK renderer refuses `_`-leading tool names for exactly this collision class.
+    # `mcp` joins them, and unconditionally: it used to be bound and then overwritten by the namespace, so the tool was uncallable anyway — but only when an MCP server happened to be mounted. A name that means the namespace in one catalogue and a tool in the next is worse than one that always means the same thing.
+    reserved = set(vars(ToolsModule)) | set(vars(types.ModuleType)) | {"ToolCallError", "mcp"}
+    flat = {spec["name"]: _make_binding(bridge, spec) for spec in specs if not spec["name"].startswith("_") and spec["name"] not in reserved}
+    # `mcp` only when something is under it: an empty namespace in `dir()` reads as a broken mount.
+    return {**flat, "mcp": MCP_ROOT} if mcp_servers(flat) else flat
 
 
 def install_bridge_modules() -> ToolsModule:
@@ -386,7 +565,7 @@ class Session:
         history = Config()
         history.HistoryAccessor.hist_file = ":memory:"
         self.shell = InteractiveShell(user_ns=namespace, config=history)
-        self.bindings = build_bindings(bridge, specs)
+        self.rebind(bridge, specs)
         self.sinks: list = [None, None]  # the Capped buffers of the cell in flight
         install_bridge_modules()
 
@@ -434,7 +613,14 @@ class Session:
             self.sinks[:] = previous
 
     def rebind(self, bridge: Bridge, specs) -> None:
+        """Swap in a catalogue — a restriction or a reconnecting server moves tools between cells.
+
+        The one place the `sys.modules` registration lives, so `build_bindings` stays the pure
+        projection its name promises and no caller can produce bindings the import machinery
+        cannot follow.
+        """
         self.bindings = build_bindings(bridge, specs)
+        install_mcp_modules(self.bindings)
 
     def format_exc(self) -> str:
         """IPython's own traceback, rendered without ANSI colors."""