PyPI - nimblebrain-synapse - Versions diffs - 0.1.0__py3-none-any.whl - Mend

nimblebrain-synapse 0.1.0__py3-none-any.whl

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 (8) hide show

nimblebrain_synapse/__init__.py +34 -0
nimblebrain_synapse/_assets/synapse-ui.iife.js +1 -0
nimblebrain_synapse/py.typed +0 -0
nimblebrain_synapse/server.py +300 -0
nimblebrain_synapse-0.1.0.dist-info/METADATA +109 -0
nimblebrain_synapse-0.1.0.dist-info/RECORD +8 -0
nimblebrain_synapse-0.1.0.dist-info/WHEEL +4 -0
nimblebrain_synapse-0.1.0.dist-info/licenses/LICENSE +21 -0

nimblebrain_synapse/__init__.py ADDED Viewed

@@ -0,0 +1,34 @@
+"""nimblebrain-synapse — the server (Python) half of the Synapse cross-host UI framework.
+Pairs with the `@nimblebrain/synapse` client (`connectUI` / `window.SynapseUI`).
+See `SynapseUI` in `nimblebrain_synapse.server`.
+"""
+from __future__ import annotations
+from importlib.metadata import PackageNotFoundError, version
+from .server import (
+    DEFAULT_DATA_ELEMENT_ID,
+    MCPAPP_MIME,
+    MCPUI_MIME,
+    SKYBRIDGE_MIME,
+    SynapseUI,
+)
+__all__ = ["SynapseUI", "SKYBRIDGE_MIME", "MCPUI_MIME", "MCPAPP_MIME", "DEFAULT_DATA_ELEMENT_ID"]
+# Derived from the installed distribution metadata, so it can't drift from
+# pyproject's version. Falls back only when imported from an uninstalled source
+# tree — the vendoring pattern this package exists to retire.
+try:
+    __version__ = version("nimblebrain-synapse")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+# The `@nimblebrain/synapse` npm release the vendored client IIFE
+# (`_assets/synapse-ui.iife.js`) was built from. This package versions
+# independently of the JS one (different cadence, different consumers); the two
+# meet only on the wire protocol. CI keeps this equal to the sibling package.json
+# version (ci.yml build job), so the pin can't silently go stale.
+__client_version__ = "0.12.0"

nimblebrain_synapse/_assets/synapse-ui.iife.js ADDED Viewed

@@ -0,0 +1 @@

nimblebrain_synapse/py.typed ADDED Viewed

File without changes

nimblebrain_synapse/server.py ADDED Viewed

@@ -0,0 +1,300 @@
+"""SynapseUI — the server (Python) half of the Synapse cross-host UI framework.
+One declaration wires a self-contained HTML component into every host bridge a
+Synapse app can render in, replacing the hand-rolled per-app shim:
+- **register** the component as two data-free ``ui://`` resources (SDK inlined):
+  the ChatGPT skybridge MIME (``text/html+skybridge``) and the MCP Apps standard
+  MIME (``text/html;profile=mcp-app``, Claude Desktop et al.) — so each host reads
+  the template and feeds it the tool's ``structuredContent``.
+- **tool_meta / result_meta** emit the `_meta` a host binds an output template
+  with (``openai/outputTemplate`` etc.).
+- **bind** installs the ``CallToolResult`` post-process that, for one tool, appends
+  the mcp-ui embedded resource (``text/html``, dossier baked into a ``<script>``)
+  and mirrors the result ``_meta`` — so Claude / mcp-ui render with no round-trip.
+The client SDK (`window.SynapseUI`) is inlined into the served + embedded HTML so
+the component is fully self-contained (no CDN, CSP-safe). Plain MCP clients ignore
+the UI pieces and still read ``structuredContent``, so degradation is graceful.
+The payload is escaped for `<script>` embedding (the XSS defense) in one place
+here, framework-owned and on by default.
+"""
+from __future__ import annotations
+import json
+from collections.abc import Callable
+from importlib import resources
+from typing import TYPE_CHECKING, Any
+from mcp import types
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+__all__ = ["SynapseUI"]
+# ChatGPT requires this exact MIME to render an Apps SDK widget template.
+SKYBRIDGE_MIME = "text/html+skybridge"
+# mcp-ui renders a ui:// resource whose content is raw HTML as text/html.
+MCPUI_MIME = "text/html"
+# MCP Apps standard (SEP-1865): a host mounts the component in an iframe only when
+# the resource is served under this exact MIME (Claude Desktop and other MCP Apps
+# hosts). No space after the semicolon — the string is matched verbatim.
+MCPAPP_MIME = "text/html;profile=mcp-app"
+# The client reads pushed data from this element by id (mcp-ui / SSR path). Keep
+# in lockstep with the SDK's SYNAPSE_DATA_ELEMENT_ID.
+DEFAULT_DATA_ELEMENT_ID = "synapse-ui-data"
+# Markers the template carries; substituted at render time.
+# Server↔client template placeholders — the SDK's test fixtures embed the same
+# literals; keep in lockstep (like DEFAULT_DATA_ELEMENT_ID above).
+DATA_MARKER = "/*__SYNAPSE_DATA__*/"  # inside the JSON <script>; unreplaced → client reads null
+SDK_MARKER = "<!--__SYNAPSE_SDK__-->"  # replaced with the inlined client SDK <script>
+# The bundled client SDK IIFE (`window.SynapseUI`). Vendored from the JS build
+# (`dist/synapse-ui.iife.global.js`) so the server and client ship together.
+_SDK_ASSET = "synapse-ui.iife.js"
+def _load_bundled_sdk() -> str:
+    # `__package__ or __name__` is always this package (never None for an imported
+    # submodule) and carries no hardcoded name to update on a rename.
+    return (resources.files(__package__ or __name__) / "_assets" / _SDK_ASSET).read_text(
+        encoding="utf-8"
+    )
+class SynapseUI:
+    """A cross-host `ui://` component declared once and wired into every bridge.
+    Args:
+        uri: The single ``ui://`` resource URI both hosts point at.
+        template: The data-free component HTML. Should carry {@link SDK_MARKER}
+            (where the client SDK is inlined) and a JSON ``<script>`` holding
+            {@link DATA_MARKER} with ``id`` = ``data_element_id``.
+        preferred_size: mcp-ui preferred frame size, emitted on the embedded
+            resource as ``mcpui.dev/ui-preferred-frame-size``.
+        data_element_id: ``id`` of the JSON ``<script>`` the client reads.
+        inline_sdk: Inline the bundled client SDK into the HTML (default). Set
+            ``False`` if the template already carries the SDK.
+        sdk_source: Override the inlined SDK source (defaults to the bundled IIFE).
+        domain: Unique HTTPS origin for the hosted component (``openai/widgetDomain``
+            / ``ui.domain``). Required to submit an Apps SDK app; ChatGPT renders the
+            component under ``<hash>.web-sandbox.oaiusercontent.com`` keyed by it.
+        connect_domains: Origins the component may reach via fetch/XHR (widget CSP
+            ``connect_domains``). Empty for a self-contained component.
+        resource_domains: Origins the component may load static assets from (widget
+            CSP ``resource_domains``). Empty for a self-contained component.
+    """
+    def __init__(
+        self,
+        *,
+        uri: str,
+        template: str,
+        preferred_size: tuple[str, str] = ("100%", "auto"),
+        data_element_id: str = DEFAULT_DATA_ELEMENT_ID,
+        inline_sdk: bool = True,
+        sdk_source: str | None = None,
+        domain: str | None = None,
+        connect_domains: list[str] | None = None,
+        resource_domains: list[str] | None = None,
+    ) -> None:
+        self.uri = uri
+        # The MCP Apps standard resource is a sibling URI: a resource carries a
+        # single MIME, and Claude (text/html;profile=mcp-app) and ChatGPT
+        # (text/html+skybridge) require different ones — so self.uri stays the
+        # skybridge resource and the standard resource lives alongside it.
+        self.mcp_app_uri = f"{uri}-mcp-app"
+        self.data_element_id = data_element_id
+        self.preferred_size = preferred_size
+        # Widget CSP + a unique hosted-component origin: required to submit an
+        # Apps SDK app. A self-contained component (SDK inlined, no fetch/assets)
+        # takes empty allowlists — the most restrictive, accurate policy.
+        self.domain = domain
+        self.connect_domains = connect_domains or []
+        self.resource_domains = resource_domains or []
+        self._bound: set[str] = set()
+        self._template = self._inline_sdk(template, sdk_source) if inline_sdk else template
+    # -- HTML -------------------------------------------------------------
+    @staticmethod
+    def _inline_sdk(template: str, sdk_source: str | None) -> str:
+        sdk = sdk_source if sdk_source is not None else _load_bundled_sdk()
+        script = f"<script>{sdk}</script>"
+        if SDK_MARKER in template:
+            return template.replace(SDK_MARKER, script, 1)
+        # Fallback: inject before </body> (or </html>) so the component still loads.
+        for close in ("</body>", "</html>"):
+            if close in template:
+                return template.replace(close, script + close, 1)
+        return template + script
+    def template_html(self) -> str:
+        """Data-free HTML (served resource / ChatGPT): SDK inlined, data marker intact."""
+        return self._template
+    @staticmethod
+    def _safe_json(data: Any) -> str:
+        """JSON safe to embed inside a ``<script>`` element.
+        Escapes ``<``/``>``/``&`` and the U+2028/U+2029 separators so a value in
+        the payload can neither close the script tag (``</script>``) nor break the
+        surrounding HTML/JS — the JSON stays valid and inert. This is the XSS
+        defense, framework-owned and on by default.
+        """
+        raw = json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+        return (
+            raw.replace("<", "\\u003c")
+            .replace(">", "\\u003e")
+            .replace("&", "\\u0026")
+            .replace(" ", "\\u2028")
+            .replace(" ", "\\u2029")
+        )
+    def render_html(self, data: Any) -> str:
+        """HTML with ``data`` baked into the JSON ``<script>`` (mcp-ui embedded copy)."""
+        return self._template.replace(DATA_MARKER, self._safe_json(data), 1)
+    # -- MCP wiring -------------------------------------------------------
+    def embedded_resource(self, data: Any) -> types.EmbeddedResource:
+        """The mcp-ui content block: a ``ui://`` resource carrying ``data`` inline."""
+        return types.EmbeddedResource(
+            type="resource",
+            resource=types.TextResourceContents(
+                uri=self.uri,
+                mimeType=MCPUI_MIME,
+                text=self.render_html(data),
+            ),
+            annotations=types.Annotations(audience=["user"]),
+            _meta={"mcpui.dev/ui-preferred-frame-size": list(self.preferred_size)},
+        )
+    def tool_meta(
+        self,
+        *,
+        invoking: str | None = None,
+        invoked: str | None = None,
+        widget_accessible: bool = True,
+    ) -> dict[str, Any]:
+        """`_meta` for the tool descriptor — how a host binds the output template.
+        ChatGPT reads ``openai/outputTemplate``; Claude and other MCP Apps hosts
+        read the nested ``ui.resourceUri`` (SEP-1865). The flat
+        ``_meta["ui/resourceUri"]`` form is deprecated and slated for removal
+        before GA, so it is not emitted.
+        """
+        meta: dict[str, Any] = {
+            "openai/outputTemplate": self.uri,
+            "openai/widgetAccessible": widget_accessible,
+            "ui": {"resourceUri": self.mcp_app_uri},
+        }
+        if invoking is not None:
+            meta["openai/toolInvocation/invoking"] = invoking
+        if invoked is not None:
+            meta["openai/toolInvocation/invoked"] = invoked
+        return meta
+    def result_meta(self) -> dict[str, Any]:
+        """`_meta` for the tool *result* — mirrors the template pointer per call."""
+        return {"openai/outputTemplate": self.uri}
+    def register(self, mcp: FastMCP, *, meta: dict[str, Any] | None = None) -> None:
+        """Register both host-facing ``ui://`` resources (data-free, SDK inlined).
+        The same component is served twice because a resource carries one MIME and
+        the hosts disagree: ``self.uri`` under ``text/html+skybridge`` for ChatGPT,
+        and ``self.mcp_app_uri`` under ``text/html;profile=mcp-app`` for Claude and
+        other MCP Apps hosts. Both point at the same inlined HTML.
+        """
+        html = self.template_html()
+        # ChatGPT (skybridge): the flat `openai/*` dialect. CSP + a unique domain
+        # are required to submit the app; without them ChatGPT's dev view flags the
+        # template as submission-incomplete.
+        resource_meta: dict[str, Any] = {
+            "openai/widgetPrefersBorder": True,
+            "openai/widgetCSP": {
+                "connect_domains": self.connect_domains,
+                "resource_domains": self.resource_domains,
+            },
+        }
+        if self.domain is not None:
+            resource_meta["openai/widgetDomain"] = self.domain
+        resource_meta.update(meta or {})
+        @mcp.resource(self.uri, mime_type=SKYBRIDGE_MIME, meta=resource_meta)
+        def _synapse_ui_resource() -> str:
+            return html
+        # MCP Apps standard (Claude et al.): the nested `ui.*` dialect, camelCase.
+        ui_meta: dict[str, Any] = {
+            "prefersBorder": True,
+            "csp": {
+                "connectDomains": self.connect_domains,
+                "resourceDomains": self.resource_domains,
+            },
+        }
+        if self.domain is not None:
+            ui_meta["domain"] = self.domain
+        @mcp.resource(
+            self.mcp_app_uri,
+            mime_type=MCPAPP_MIME,
+            meta={"ui": ui_meta},
+        )
+        def _synapse_ui_mcp_app_resource() -> str:
+            return html
+    def bind(
+        self,
+        mcp: FastMCP,
+        *,
+        tool: str,
+        should_render: Callable[[Any], bool] | None = None,
+    ) -> None:
+        """Install the ``CallToolResult`` post-process that renders `tool`'s output.
+        For a successful, non-error result of ``tool`` that carries
+        ``structuredContent`` (and passes ``should_render``), appends the mcp-ui
+        embedded resource and mirrors the ChatGPT ``_meta``. Plain clients ignore
+        both and still read the structured JSON.
+        Quarantine note: this wraps FastMCP's ``CallToolRequest`` handler — a leak
+        into FastMCP internals kept in this one place so no app pokes them.
+        # TODO: upstream a real FastMCP result-transform hook and drop this patch.
+        """
+        if tool in self._bound:  # idempotent: don't chain a second wrapper for the same tool
+            return
+        self._bound.add(tool)
+        predicate = should_render if should_render is not None else (lambda data: bool(data))
+        prev = mcp._mcp_server.request_handlers[types.CallToolRequest]
+        async def _handler(req: types.CallToolRequest) -> types.ServerResult:
+            result = await prev(req)
+            if req.params.name == tool:
+                return self._attach(result, predicate)
+            return result
+        mcp._mcp_server.request_handlers[types.CallToolRequest] = _handler
+    def _attach(
+        self,
+        result: types.ServerResult,
+        predicate: Callable[[Any], bool],
+    ) -> types.ServerResult:
+        root = result.root
+        if not isinstance(root, types.CallToolResult) or root.isError:
+            return result
+        data = root.structuredContent
+        if not data or not predicate(data):
+            return result
+        root.content.append(self.embedded_resource(data))
+        root.meta = {**(root.meta or {}), **self.result_meta()}
+        return result

nimblebrain_synapse-0.1.0.dist-info/METADATA ADDED Viewed

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: nimblebrain-synapse
+Version: 0.1.0
+Summary: Server half of the Synapse cross-host UI framework: register one self-contained ui:// component from a FastMCP server and render it in ChatGPT (OpenAI Apps SDK), Claude (MCP Apps), and the NimbleBrain runtime.
+Project-URL: Homepage, https://github.com/NimbleBrainInc/synapse
+Project-URL: Repository, https://github.com/NimbleBrainInc/synapse
+Project-URL: Issues, https://github.com/NimbleBrainInc/synapse/issues
+Project-URL: Changelog, https://github.com/NimbleBrainInc/synapse/blob/main/python/CHANGELOG.md
+Author: NimbleBrain Inc.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastmcp,mcp,mcp-apps,openai-apps,synapse,ui,widget
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.26.0
+Description-Content-Type: text/markdown
+# nimblebrain-synapse (Python)
+The **server half** of the Synapse cross-host UI framework. Pairs with the
+`@nimblebrain/synapse` client (`connectUI` / `window.SynapseUI`).
+```bash
+pip install nimblebrain-synapse   # or: uv add nimblebrain-synapse
+```
+One `SynapseUI` declaration wires a self-contained HTML component into every host
+bridge a Synapse app renders in — **ChatGPT** (OpenAI Apps SDK), **Claude** (MCP
+Apps), and the **NimbleBrain** runtime — from a FastMCP server, replacing the
+per-app hand-rolled shim.
+```python
+from mcp.server.fastmcp import FastMCP
+from nimblebrain_synapse import SynapseUI
+mcp = FastMCP("bassethound")
+report_ui = SynapseUI(
+    uri="ui://bassethound/report",
+    template=load_template(),            # data-free HTML (carries the SDK + data markers)
+    preferred_size=("100%", "auto"),
+)
+report_ui.register(mcp)                   # skybridge ui:// resource, SDK inlined
+@mcp.tool(meta=report_ui.tool_meta(invoking="Picking up the scent…", invoked="Dossier ready"))
+async def analyze_domain(domain: str) -> Dossier:
+    ...
+report_ui.bind(mcp, tool="analyze_domain", should_render=lambda d: "domain" in d)
+```
+`register` serves the ChatGPT-facing skybridge resource (data-free). `bind`
+post-processes the `CallToolResult` for one tool: appends the mcp-ui embedded
+`ui://` resource (dossier baked into a `<script>`) and mirrors the ChatGPT
+`_meta`. Plain MCP clients ignore both and still read `structuredContent`.
+## Template contract
+The `template` is data-free HTML that carries two markers:
+- `<!--__SYNAPSE_SDK__-->` — replaced with the inlined client SDK `<script>`.
+- `<script type="application/json" id="synapse-ui-data">/*__SYNAPSE_DATA__*/</script>`
+  — the data slot; `render_html(data)` substitutes the escaped payload here (the
+  served copy leaves the marker, so the client reads `null` and falls back to the
+  host's push).
+`SynapseUI._safe_json` escapes the payload for `<script>` embedding (the XSS
+defense) — framework-owned and on by default.
+## Interface debt
+`bind` wraps FastMCP's `CallToolRequest` handler — a leak into FastMCP internals,
+quarantined in this one place. See the `# TODO: upstream a real FastMCP
+result-transform hook` note in `server.py`.
+## Client SDK asset
+`nimblebrain_synapse/_assets/synapse-ui.iife.js` is the vendored client IIFE
+(`window.SynapseUI`), regenerated from the JS build
+(`dist/synapse-ui.iife.global.js`) and inlined at register time so a component
+is fully self-contained (CSP-safe, no CDN). CI fails on drift from the build.
+`nimblebrain_synapse.__client_version__` records which `@nimblebrain/synapse` release the
+bundled IIFE was built from.
+## Versioning & compatibility
+`nimblebrain-synapse` (PyPI) versions **independently** of `@nimblebrain/synapse` (npm).
+They change for different reasons at different cadences — the server descriptor is
+thin and stable; the JS client evolves with host adapters and theming — so they do
+not share a version number. The exact client build a given release bundles is
+recorded in `nimblebrain_synapse.__client_version__` (and, per release, in the
+[CHANGELOG](https://github.com/NimbleBrainInc/synapse/blob/main/python/CHANGELOG.md));
+CI keeps it equal to the sibling `package.json` at HEAD.
+What both halves share is the **wire protocol** — the `ui://` resource MIMEs, the
+`_meta` dialects, and the data-element contract:
+- ext-apps `2026-01-26`
+- MCP Apps (SEP-1865)
+- OpenAI Apps SDK
+Releases publish on a `nimblebrain-synapse-v*` tag (distinct from the npm `v*` tags).

nimblebrain_synapse-0.1.0.dist-info/RECORD ADDED Viewed

@@ -0,0 +1,8 @@
+nimblebrain_synapse/__init__.py,sha256=sbR73hDwy-YXu8Ql-PxTV08hjy7crBKa5RcaD57oJaw,1279
+nimblebrain_synapse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nimblebrain_synapse/server.py,sha256=eKs93-xY9QzyDNvKOaQKY0NZRpDrI9oXHfhLLyUzmmw,13259
+nimblebrain_synapse/_assets/synapse-ui.iife.js,sha256=5GSX3Lq69y1Q2rd6soYke760Z6IAgM0h7N7nhegXefc,8336
+nimblebrain_synapse-0.1.0.dist-info/METADATA,sha256=RLZcrhlOeu7nqKFcQwO5I0pft2mTEyjoWF1P0gdcazg,4769
+nimblebrain_synapse-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+nimblebrain_synapse-0.1.0.dist-info/licenses/LICENSE,sha256=RTSjbg00L14JSy_hagMUQk7gs0-BolAfQKLBMDFF4XE,1074
+nimblebrain_synapse-0.1.0.dist-info/RECORD,,

nimblebrain_synapse-0.1.0.dist-info/WHEEL ADDED Viewed

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nimblebrain_synapse-0.1.0.dist-info/licenses/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 NimbleBrain, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.