nimblebrain-server-sdk 0.3.0__py3-none-any.whl

nimblebrain_server_sdk/__init__.py

@@ -0,0 +1,92 @@
+"""The SDK for building MCP servers that run on NimbleBrain.
+
+What a server shares with the host it runs in: the tool annotation hints, the change
+announcement its views re-read on, the platform extensions (facets, lifecycle handlers, the
+view a record opens in), skills served through the MCP Skills extension
+(``io.modelcontextprotocol/skills``), the bounded row a listing returns, the opaque record id it
+mints, and reads of workspace files through ``ai.nimblebrain/host-resources``.
+"""
+
+from nimblebrain_server_sdk.annotations import ADDS, CHANGES, READS
+from nimblebrain_server_sdk.announce import announce_resource_list_changed
+from nimblebrain_server_sdk.errors import HostCapabilityMissing
+from nimblebrain_server_sdk.extensions.facets import (
+    FACET_LEVELS,
+    FACETS_EXTENSION_ID,
+    FacetLevel,
+    facet_count,
+    facet_meta,
+)
+from nimblebrain_server_sdk.extensions.lifecycle import (
+    LIFECYCLE_EVENTS,
+    LIFECYCLE_EXTENSION_ID,
+    LifecycleEvent,
+    LifecycleExtension,
+    add_lifecycle_extension,
+    lifecycle_meta,
+)
+from nimblebrain_server_sdk.extensions.platform import PlatformExtension, add_platform_extension
+from nimblebrain_server_sdk.extensions.views import RECORD_VIEW_META, record_view_meta
+from nimblebrain_server_sdk.host import HostResources, host
+from nimblebrain_server_sdk.ids import new_prefixed_id, new_ulid
+from nimblebrain_server_sdk.methods import (
+    HOST_RESOURCES_CAPABILITY_KEY,
+    HOST_RESOURCES_LIST_METHOD,
+    HOST_RESOURCES_READ_METHOD,
+    INVALID_PARAMS,
+    RATE_LIMITED,
+    RESOURCE_NOT_FOUND,
+    RESPONSE_TOO_LARGE,
+)
+from nimblebrain_server_sdk.rows import PREVIEW_CHARS, listing_row, preview_text
+from nimblebrain_server_sdk.skills import (
+    SKILLS_EXTENSION_ID,
+    MCPServerSkillsExtension,
+    SkillDefinition,
+    SkillsExtension,
+    add_skills,
+)
+
+__all__ = [
+    "ADDS",
+    "CHANGES",
+    "FACETS_EXTENSION_ID",
+    "FACET_LEVELS",
+    "HOST_RESOURCES_CAPABILITY_KEY",
+    "HOST_RESOURCES_LIST_METHOD",
+    "HOST_RESOURCES_READ_METHOD",
+    "INVALID_PARAMS",
+    "LIFECYCLE_EVENTS",
+    "LIFECYCLE_EXTENSION_ID",
+    "PREVIEW_CHARS",
+    "RATE_LIMITED",
+    "READS",
+    "RECORD_VIEW_META",
+    "RESOURCE_NOT_FOUND",
+    "RESPONSE_TOO_LARGE",
+    "SKILLS_EXTENSION_ID",
+    "FacetLevel",
+    "HostCapabilityMissing",
+    "HostResources",
+    "LifecycleEvent",
+    "LifecycleExtension",
+    "MCPServerSkillsExtension",
+    "PlatformExtension",
+    "SkillDefinition",
+    "SkillsExtension",
+    "add_lifecycle_extension",
+    "add_platform_extension",
+    "add_skills",
+    "announce_resource_list_changed",
+    "facet_count",
+    "facet_meta",
+    "host",
+    "lifecycle_meta",
+    "listing_row",
+    "new_prefixed_id",
+    "new_ulid",
+    "preview_text",
+    "record_view_meta",
+]
+
+__version__ = "0.3.0"

nimblebrain_server_sdk/annotations.py

@@ -0,0 +1,22 @@
+"""What a tool call can change, as the MCP spec's annotation hints say it.
+
+``readOnlyHint`` is how a client tells a read from a write without knowing the tool. Under the
+spec's defaults a tool with no annotation reads as a destructive write, so leaving one off
+does not leave a tool unclassified: it declares the tool the most dangerous kind. Every tool
+a server built on this SDK serves carries one of these. On a server with views, exactly the tools that
+are not read-only announce a change.
+"""
+
+from __future__ import annotations
+
+from mcp.types import ToolAnnotations
+
+READS = ToolAnnotations(read_only_hint=True)
+"""Changes nothing a view shows. A read that records an audit row or refreshes provider state
+on the way in is still a read."""
+
+ADDS = ToolAnnotations(read_only_hint=False, destructive_hint=False)
+"""A write that loses nothing already there."""
+
+CHANGES = ToolAnnotations(read_only_hint=False, destructive_hint=True)
+"""A write that overwrites, removes, or acts on what is already there."""

nimblebrain_server_sdk/announce.py

@@ -0,0 +1,46 @@
+"""Tell the client that made a write that this server's resource list changed."""
+
+from __future__ import annotations
+
+import logging
+
+from fastmcp import Context
+from fastmcp.server.dependencies import get_context
+from mcp.types import ResourceListChangedNotification
+
+logger = logging.getLogger(__name__)
+
+
+async def announce_resource_list_changed(
+    ctx: Context | None = None, *, tool: str | None = None
+) -> None:
+    """Send ``notifications/resources/list_changed`` in the response to the call that wrote.
+
+    That call came from the host that holds this workspace, so the notification is scoped to
+    the workspace without the server keeping a map of sessions. The host relays it to this
+    server's views, which re-read.
+
+    Call it only from a write, once the write has committed. A read never calls it: a view
+    re-reads when told the list changed, so a read that announced would have every open view
+    refreshing itself forever.
+
+    ``ctx`` defaults to the active MCP request's context. With neither there is no response to
+    announce in — a tool body called directly, or a write made outside any tool call — and
+    that is not a failure. Nor is a send that fails: the write is stored either way, and
+    reporting a stored write as failed would have the agent make it a second time. A view
+    that misses one catches up on its next read.
+
+    ``tool`` names the calling tool on that failure's log line.
+    """
+    if ctx is None:
+        try:
+            ctx = get_context()
+        except RuntimeError:
+            return
+    try:
+        # Tied to the request, so it travels in the call's own response. A 2026-07-28
+        # connection has no other way out, and a session-era client need not hold the
+        # standalone stream open.
+        await ctx.send_notification(ResourceListChangedNotification())
+    except Exception:  # noqa: BLE001 — the write already committed; see above
+        logger.warning("announce_resource_list_changed_failed", exc_info=True, extra={"tool": tool})

nimblebrain_server_sdk/errors.py

@@ -0,0 +1,38 @@
+"""SDK-specific exceptions.
+
+Wire-level errors from the platform come through as
+`mcp.shared.exceptions.McpError` — the SDK does not wrap those, so
+bundle authors can match on the JSON-RPC error code via the standard
+exception path. `HostCapabilityMissing` is the only error the SDK
+itself raises, and it signals a local condition ("this host hasn't
+advertised the extension") rather than a wire response.
+"""
+
+
+class HostCapabilityMissing(Exception):
+    """Raised when bundle code calls a host-resources method but the
+    host hasn't advertised the capability in `initialize`.
+
+    Catch this to implement the Level-C fallback pattern: when the
+    capability is absent, return a structured tool error that tells
+    the agent to call the tool again with inline content instead.
+
+    Example:
+        ```python
+        try:
+            result = await host(ctx).read(seed_uri)
+        except HostCapabilityMissing:
+            raise ValueError(
+                "This host doesn't support ai.nimblebrain/host-resources. "
+                "Pass file contents inline via `seed_data` instead."
+            )
+        ```
+    """
+
+    def __init__(self, capability_key: str):
+        super().__init__(
+            f"Host has not advertised the {capability_key!r} capability. "
+            "Check `host(ctx).available` before calling read/list, or pass "
+            "content via tool arguments instead."
+        )
+        self.capability_key = capability_key

nimblebrain_server_sdk/extensions/__init__.py

@@ -0,0 +1,5 @@
+"""NimbleBrain's platform extensions: advertised identifiers whose contract rides a primitive.
+
+``platform`` advertises any such extension; ``facets``, ``lifecycle`` and ``views`` are the
+``ai.nimblebrain/*`` extensions a host reads from marked resources, tools and templates.
+"""

nimblebrain_server_sdk/extensions/facets.py

@@ -0,0 +1,61 @@
+"""Serve facets: how many things are waiting in this server (``ai.nimblebrain/facets``).
+
+A facet is one countable obligation, such as drafts awaiting review. The extension adds no
+method. A server advertises the identifier, lists each facet as a resource whose ``_meta``
+carries the identifier (holding the facet's urgency level) and whose ``title`` is the label a
+host renders after the count, and answers ``resources/read`` with ``{"count": n}``. The
+specification is https://docs.nimblebrain.ai/extensions/facets/.
+
+A bundle registers a facet where it builds its server::
+
+    add_platform_extension(mcp, FACETS_EXTENSION_ID)
+
+    @mcp.resource(
+        "acme://facets/blocked",
+        name="tickets-blocked",
+        title="Tickets blocked",
+        mime_type="application/json",
+        meta=facet_meta("critical"),
+    )
+    async def tickets_blocked() -> str:
+        return facet_count(await count_blocked())
+
+The read takes no arguments: it counts for the identity the transport established, with the
+same session and identity function the server's tools use.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+FACETS_EXTENSION_ID = "ai.nimblebrain/facets"
+
+FacetLevel = Literal["critical", "warning", "info"]
+#: How urgent a non-zero count is, most urgent first: something has stopped, someone should
+#: act, worth knowing. A host orders by it and shows it; one that sees none reads ``warning``.
+FACET_LEVELS: tuple[FacetLevel, ...] = ("critical", "warning", "info")
+
+
+def facet_meta(level: FacetLevel) -> dict[str, Any]:
+    """The ``_meta`` a facet resource carries: the extension's marker, holding its level.
+
+    The level belongs to the facet, not to a reading, so it is declared once here and never
+    changes with the count. Raises :class:`ValueError` for a level the extension does not
+    define, which a host would read as ``warning``.
+    """
+    if level not in FACET_LEVELS:
+        raise ValueError(f"a facet level is one of {FACET_LEVELS}, not {level!r}")
+    return {FACETS_EXTENSION_ID: {"level": level}}
+
+
+def facet_count(count: int) -> str:
+    """The body of a facet read: ``{"count": count}`` as JSON text.
+
+    Raises :class:`ValueError` for anything but a non-negative integer, because a host treats
+    any other count as a failed read. Failing here names the server's own bug instead of
+    leaving it to show up as a facet that never renders.
+    """
+    if isinstance(count, bool) or not isinstance(count, int) or count < 0:
+        raise ValueError(f"a facet count is a non-negative integer, not {count!r}")
+    return json.dumps({"count": count})

nimblebrain_server_sdk/extensions/lifecycle.py

@@ -0,0 +1,141 @@
+"""Serve lifecycle handlers: the tools a host calls when it installs and removes this server.
+
+``ai.nimblebrain/lifecycle`` tells a server that a host made it available to a scope
+(``ready``) and that the host is about to take it away (``removing``). The extension adds no
+method. A server advertises the identifier and marks one tool per event with
+``_meta["ai.nimblebrain/lifecycle"]: {"event": ...}``. The host calls that tool as a plain
+``tools/call``, with ``{"reason": "install" | "resume"}`` to a ``ready`` handler that declares
+``reason``, and with ``{}`` otherwise. The specification is
+https://docs.nimblebrain.ai/extensions/lifecycle/.
+
+A bundle advertises the extension and marks its handlers where it builds its server::
+
+    lifecycle = add_lifecycle_extension(mcp)
+
+    @lifecycle.handler("ready", annotations=CHANGES)
+    async def workspace_ready(reason: str | None = None) -> str: ...
+
+    @lifecycle.handler("removing", annotations=CHANGES)
+    async def workspace_removing() -> str: ...
+
+Registering through the extension refuses, at import, what a host would refuse at install:
+a handler whose input schema requires a property (spec §3), and a second handler for one event,
+which a host treats as no handler at all. It also registers each handler without task support,
+because the host calls synchronously and the NimbleBrain host refuses a handler that offers
+tasks. A tool marked by hand with ``meta=lifecycle_meta(...)`` gets none of these checks.
+
+**Handlers stay listed to every client.** The spec (§6) says a server SHOULD NOT list its
+handlers to a client that did not advertise the extension, and FastMCP 4 could do that without
+patching it: a ``Middleware.on_list_tools`` reading ``Context.client_extension_settings``. This
+library does not, by default or as an option. A host that reads the declaration from its
+operator catalog rather than from the wire finds each handler by name in ``tools/list`` and
+advertises nothing, so withholding would break that host's lifecycle calls for as long as it
+reads the catalog. What makes listing safe is the server's own duty (spec §5): every handler is
+safe for any caller holding the scope's identity, so ``removing`` records intent and never
+destroys. Revisit once no host reads ``lifecycle`` from a catalog.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal, TypeVar
+
+from fastmcp import FastMCP
+from fastmcp.tools import FunctionTool
+from mcp_types import ToolAnnotations
+
+from nimblebrain_server_sdk.extensions.platform import PlatformExtension
+
+LIFECYCLE_EXTENSION_ID = "ai.nimblebrain/lifecycle"
+
+LifecycleEvent = Literal["ready", "removing"]
+#: The two moments a host can reach the server: it has been made available to the scope,
+#: and it is about to be removed from it.
+LIFECYCLE_EVENTS: tuple[LifecycleEvent, ...] = ("ready", "removing")
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def lifecycle_meta(event: LifecycleEvent) -> dict[str, Any]:
+    """The ``_meta`` a handler tool carries: the extension's marker, naming its event.
+
+    Raises :class:`ValueError` for an event the extension does not define, which a host
+    ignores, so the handler would never be called.
+    """
+    if event not in LIFECYCLE_EVENTS:
+        raise ValueError(f"a lifecycle event is one of {LIFECYCLE_EVENTS}, not {event!r}")
+    return {LIFECYCLE_EXTENSION_ID: {"event": event}}
+
+
+class LifecycleExtension(PlatformExtension):
+    """The advertised extension, and the record of which tool handles which event."""
+
+    def __init__(self) -> None:
+        super().__init__(LIFECYCLE_EXTENSION_ID)
+        self._handlers: dict[LifecycleEvent, str] = {}
+
+    @property
+    def handlers(self) -> dict[LifecycleEvent, str]:
+        """The tool registered for each event, by event."""
+        return dict(self._handlers)
+
+    def handler(
+        self,
+        event: LifecycleEvent,
+        *,
+        name: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        annotations: ToolAnnotations | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> Callable[[F], F]:
+        """Register the decorated function as this server's handler for ``event``.
+
+        The tool is an ordinary tool carrying :func:`lifecycle_meta` merged into ``meta``.
+        Raises :class:`ValueError`, before anything is registered, for a second handler for
+        ``event``, for a handler whose input schema requires a property, and for a ``meta``
+        that already carries the marker.
+        """
+        marker = lifecycle_meta(event)
+        if LIFECYCLE_EXTENSION_ID in (meta or {}):
+            raise ValueError(
+                f"the {LIFECYCLE_EXTENSION_ID} marker comes from the event, not from meta"
+            )
+
+        def register(fn: F) -> F:
+            tool = FunctionTool.from_function(
+                fn,
+                name=name,
+                title=title,
+                description=description,
+                annotations=annotations,
+                meta={**(meta or {}), **marker},
+                task=False,
+            )
+            if event in self._handlers:
+                raise ValueError(
+                    f"{tool.name!r} and {self._handlers[event]!r} both handle {event!r}; a host "
+                    "treats an event with two handlers as having none"
+                )
+            required = tool.parameters.get("required") or []
+            if required:
+                raise ValueError(
+                    f"lifecycle handler {tool.name!r} requires {sorted(required)}; a host calls "
+                    "it with no required arguments, so give each parameter a default"
+                )
+            self.server.add_tool(tool)
+            self._handlers[event] = tool.name
+            return fn
+
+        return register
+
+
+def add_lifecycle_extension(mcp: FastMCP) -> LifecycleExtension:
+    """Advertise ``ai.nimblebrain/lifecycle`` on ``mcp`` and return it, to register handlers on.
+
+    Like any platform extension it is advertised in ``server/discover`` only, so a host on a
+    2025-era connection sees no extension and makes no lifecycle calls (spec §2, §6).
+    """
+    extension = LifecycleExtension()
+    mcp.add_extension(extension)
+    return extension

nimblebrain_server_sdk/extensions/platform.py

@@ -0,0 +1,47 @@
+"""Advertise a platform extension under ``capabilities.extensions``.
+
+An MCP extension (SEP-2133) is a capability a server offers under a reverse-DNS identifier,
+negotiated per request and discovered through ``server/discover``. A legacy ``initialize``
+never carries the map, so only a 2026-07-28 peer sees an extension.
+
+The set is fixed at construction: FastMCP refuses a registration once the server's lifespan
+has started, because a peer that already discovered the map would never see the new entry.
+So a bundle advertises its extensions where it builds its ``FastMCP``, before serving.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from fastmcp import FastMCP
+from fastmcp.server.extensions import ServerExtension
+
+
+class PlatformExtension(ServerExtension):
+    """An extension that only advertises: an identifier and its settings, no methods.
+
+    What a platform extension serves rides the primitives a peer already calls (a marked
+    resource, a tool), so the advertisement is the whole contract. An extension that serves
+    methods of its own subclasses ``ServerExtension`` directly.
+    """
+
+    def __init__(self, identifier: str, settings: Mapping[str, Any] | None = None) -> None:
+        self.identifier = identifier
+        self._settings = dict(settings or {})
+
+    def settings(self) -> dict[str, Any]:
+        return dict(self._settings)
+
+
+def add_platform_extension(
+    mcp: FastMCP, identifier: str, settings: Mapping[str, Any] | None = None
+) -> PlatformExtension:
+    """Advertise ``identifier`` with ``settings`` at ``capabilities.extensions[identifier]``.
+
+    The SDK validates the identifier (a ``vendor-prefix/name`` pair), and FastMCP refuses a
+    second registration of the same one and any registration after the server started.
+    """
+    extension = PlatformExtension(identifier, settings)
+    mcp.add_extension(extension)
+    return extension

nimblebrain_server_sdk/extensions/views.py

@@ -0,0 +1,33 @@
+"""Name the view that shows a kind of record (``ai.nimblebrain/view``).
+
+A server with several sidebar views keeps each kind of record in one of them. Its resource
+template for that record carries the key, holding the ``ui://`` URI of the view (its
+placement's ``resourceUri``), and a host that opens a record by its URI opens it in that view
+rather than the server's first. A host that does not read the key opens the first view; the
+key names only one of the server's own views.
+
+    @mcp.resource(
+        "acme://boards/{board_id}",
+        name="board",
+        mime_type="application/json",
+        meta=record_view_meta("ui://acme/boards"),
+    )
+    async def board(board_id: str) -> str: ...
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+RECORD_VIEW_META = "ai.nimblebrain/view"
+
+
+def record_view_meta(view_uri: str) -> dict[str, Any]:
+    """The ``_meta`` a record's resource template carries to name the view that shows it.
+
+    Raises :class:`ValueError` for anything but a ``ui://`` URI, which a host would ignore and
+    which would leave the record opening in the server's first view without a sign of why.
+    """
+    if not view_uri.startswith("ui://") or len(view_uri) <= len("ui://"):
+        raise ValueError(f"a record's view is a ui:// URI, not {view_uri!r}")
+    return {RECORD_VIEW_META: view_uri}