nimblebrain-synapse 0.1.0__tar.gz

nimblebrain_synapse-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+uv.lock

nimblebrain_synapse-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `nimblebrain-synapse` (the Python package) are documented here.
+It versions **independently** of the `@nimblebrain/synapse` npm package — the two
+meet only on the wire protocol, not on a shared version number.
+
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0]
+
+First published release to PyPI. The `SynapseUI` server descriptor previously
+shipped only as source in this repo and vendored copies; it is now an installable
+package so bundles depend on one source of truth instead of copying it.
+
+### Added
+
+- `SynapseUI` server descriptor: dual-MIME `ui://` registration (ChatGPT
+  `text/html+skybridge` + MCP Apps `text/html;profile=mcp-app`), tool/result
+  `_meta` in both dialects, widget CSP + domain, `<script>`-safe data embedding
+  (the XSS defense), and the quarantined `CallToolResult` render injection.
+- Bundled client IIFE (`window.SynapseUI`) from `@nimblebrain/synapse` 0.12.0,
+  inlined so a component stays self-contained (CSP-safe, no CDN).

nimblebrain_synapse-0.1.0/LICENSE

@@ -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.

nimblebrain_synapse-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,85 @@
+# 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/nimblebrain_synapse/__init__.py

@@ -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-0.1.0/nimblebrain_synapse/_assets/synapse-ui.iife.js

@@ -0,0 +1 @@
+(function(){'use strict';var de={"--color-background-primary":"#ffffff","--color-background-secondary":"#fafafa","--color-background-tertiary":"#f3f4f6","--color-text-primary":"#111827","--color-text-secondary":"#6b7280","--color-text-tertiary":"#9ca3af","--color-text-accent":"#2563eb","--nb-color-accent-foreground":"#ffffff","--color-border-primary":"#e5e7eb","--color-border-secondary":"#d1d5db","--color-ring-primary":"#2563eb","--nb-color-danger":"#dc2626","--nb-color-success":"#059669","--nb-color-warning":"#f59e0b","--nb-color-warm":"#d4620a","--nb-color-warm-light":"#fef5ee","--nb-color-processing":"#7c3aed","--nb-color-processing-light":"#f3eeff","--nb-color-info-light":"#eef4ff"},ue={"--color-background-primary":"#18181b","--color-background-secondary":"#27272a","--color-background-tertiary":"#2f2f34","--color-text-primary":"#fafafa","--color-text-secondary":"#a1a1aa","--color-text-tertiary":"#71717a","--color-text-accent":"#818cf8","--nb-color-accent-foreground":"#ffffff","--color-border-primary":"#3f3f46","--color-border-secondary":"#52525b","--color-ring-primary":"#818cf8","--nb-color-danger":"#f87171","--nb-color-success":"#34d399","--nb-color-warning":"#fbbf24","--nb-color-warm":"#fb923c","--nb-color-warm-light":"#3a2a1e","--nb-color-processing":"#a78bfa","--nb-color-processing-light":"#2a2440","--nb-color-info-light":"#1e2a44"},pe={light:de,dark:ue};function N(t,r){if(typeof document>"u")return;let n=document.documentElement.style;for(let[i,l]of Object.entries(pe[t]))n.setProperty(i,l);if(r&&typeof r=="object")for(let[i,l]of Object.entries(r))typeof i=="string"&&typeof l=="string"&&n.setProperty(i,l);}function R(t){typeof document<"u"&&document.documentElement.setAttribute("data-theme",t.mode),N(t.mode,t.tokens);}function C(t){try{if(t?.matchMedia?.("(prefers-color-scheme: dark)").matches)return "dark"}catch{}return "light"}function h(t,r){return t==="light"||t==="dark"?t:r}var b=class extends Error{constructor(r,n){super(`"${r}" is not supported by the "${n}" host`),this.name="HostUnsupportedError";}},A="synapse-ui-data",z="ui-lifecycle-iframe-ready",j="ui-lifecycle-iframe-render-data",G="ui-size-change",K="link",W="prompt",S="openai:set_globals",F="2026-01-26",Z="ui/initialize",q="ui/notifications/initialized",Y="ui/notifications/tool-result",V="ui/notifications/host-context-changed",B="ui/notifications/size-changed",Q="ui/open-link",$="ui/message",X="ui/resource-teardown",J="tools/call";function ee(t,r){let n=()=>t.openai,i=n()?.toolOutput??null,l={mode:h(n()?.theme,"light"),tokens:{}},a=new Set,p=new Set,f=false,m=s=>{if(f)return;let c=s.detail?.globals;if(c){if("toolOutput"in c&&c.toolOutput!=null){i=c.toolOutput;for(let u of a)u(i);}if("theme"in c&&c.theme!=null){let u=h(c.theme,l.mode);if(u!==l.mode){l={mode:u,tokens:{}};for(let P of p)P(l);}}}};return {host:"chatgpt",getData:()=>i,onData(s){return a.add(s),()=>a.delete(s)},getTheme:()=>l,onTheme(s){return p.add(s),()=>p.delete(s)},async callTool(s,c){let u=n()?.callTool;if(!u)throw new b("callTool","chatgpt");return await u(s,c??{})},sendPrompt(s){let c=n();(c?.sendFollowUpMessage??c?.sendFollowupMessage)?.({prompt:s});},openLink(s){let c=n()?.openExternal;c?c({href:s}):t.open(s,"_blank","noopener,noreferrer");},resize(){},capabilities(){let s=n();return {pull:typeof s?.callTool=="function",sendPrompt:typeof s?.sendFollowUpMessage=="function"||typeof s?.sendFollowupMessage=="function",openLink:true}},start(){t.addEventListener(S,m,{passive:true}),i=n()?.toolOutput??i;},destroy(){f||(f=true,t.removeEventListener(S,m),a.clear(),p.clear());}}}function O(t,r){if(!t)return null;let i=t.getElementById(r)?.textContent;if(!i)return null;try{return JSON.parse(i)??null}catch{return null}}function L(t){if(t==null||typeof t!="object")return null;let r=t,n=r.renderData,i=n!=null&&typeof n=="object"?n:r;return i.toolOutput!=null?i.toolOutput:i.structuredContent!=null?i.structuredContent:i}function te(t,r){let n=r.dataElementId??A,i=null,l={mode:C(t),tokens:{}},a=new Set,p=false,f=null,m=s=>{if(p)return;let c=h(s.matches?"dark":"light",l.mode);if(c!==l.mode){l={mode:c,tokens:{}};for(let u of a)u(l);}};return {host:"generic",getData:()=>i,onData(){return ()=>{}},getTheme:()=>l,onTheme(s){return a.add(s),()=>a.delete(s)},async callTool(s){throw new b("callTool","generic")},sendPrompt(){},openLink(s){t.open(s,"_blank","noopener,noreferrer");},resize(){},capabilities(){return {pull:false,sendPrompt:false,openLink:true}},start(){i=O(t.document,n);try{f=t.matchMedia?.("(prefers-color-scheme: dark)")??null,f?.addEventListener?.("change",m);}catch{f=null;}},destroy(){p||(p=true,f?.removeEventListener?.("change",m),f=null,a.clear());}}}var fe=3e4;function ne(t,r){let n=r.dataElementId??A,i=r.autoResize!==false,l=null,a={mode:C(t),tokens:{}},p=new Set,f=new Set,m=false,s=false,c=1,u=new Map,P=-1,v=null,k=null,U=()=>t.parent??t;function I(e){U().postMessage(e,"*");}function _(e){s||I(e);}function x(e,o){I({jsonrpc:"2.0",method:e,params:o??{}});}function w(e,o){let d=c++;return new Promise((g,y)=>{let T=setTimeout(()=>{u.delete(d),y(new Error(`"${e}" timed out`));},fe);u.set(d,{resolve:g,reject:y,timer:T}),I({jsonrpc:"2.0",id:d,method:e,params:o??{}});})}function D(e){if(e!=null){l=e;for(let o of p)o(e);}}function M(e){if(!e||typeof e!="object")return;let{mode:o,tokens:d}=a,g=false;if(e.theme!=null){let T=h(e.theme,o);T!==o&&(o=T,g=true);}let y=e.styles;if(y?.variables&&typeof y.variables=="object"&&(d={...d,...y.variables},g=true),g){a={mode:o,tokens:d};for(let T of f)T(a);}}function E(e){if(m)return;let o=typeof e=="number"?e:Math.ceil(t.document.body.scrollHeight);o!==P&&(P=o,x(B,{height:o}),_({type:G,payload:{height:o}}));}function se(e){let o=Number(e.id),d=u.get(o);if(d)if(u.delete(o),clearTimeout(d.timer),e.error!=null){let g=e.error;d.reject(new Error(g.message??"request failed"));}else d.resolve(e.result);}function ie(e,o){if(e===Y){let d=o.structuredContent;D(d??L(o));}else e===V&&M(o);}function ae(e){e.method===X&&I({jsonrpc:"2.0",id:e.id,result:{}});}function le(e){if(e.type===j||e.type==="renderData"){let{theme:o,...d}=e.payload??{};o!=null&&M({theme:o}),Object.keys(d).length>0&&D(L(d));}}let H=e=>{if(m||e.source&&e.source!==U())return;let o=e.data;if(!(!o||typeof o!="object")){if(o.jsonrpc!=="2.0"){le(o);return}o.id!=null&&("result"in o||"error"in o)?se(o):typeof o.method=="string"&&(o.id!=null?ae(o):ie(o.method,o.params??{}));}};function ce(){k=()=>E(),t.addEventListener("resize",k),typeof t.ResizeObserver<"u"&&(v=new t.ResizeObserver(()=>E()),v.observe(t.document.body));}return {host:"claude",getData:()=>l,onData(e){return p.add(e),()=>p.delete(e)},getTheme:()=>a,onTheme(e){return f.add(e),()=>f.delete(e)},async callTool(e,o){return await w(J,{name:e,arguments:o??{}})},sendPrompt(e){w($,{role:"user",content:[{type:"text",text:e}]}).catch(()=>{}),_({type:W,payload:{prompt:e}});},openLink(e){w(Q,{url:e}).catch(()=>{}),_({type:K,payload:{url:e}});},resize(e){E(e);},capabilities(){return {pull:true,sendPrompt:true,openLink:true}},start(){t.addEventListener("message",H),l=O(t.document,n),i&&ce(),I({type:z}),w(Z,{appInfo:{name:r.name??"synapse-ui",version:r.version??"0.0.0"},appCapabilities:{availableDisplayModes:["inline"]},protocolVersion:F}).then(e=>{m||(s=true,M(e?.hostContext),x(q,{}),P=-1,E());}).catch(()=>{}),E();},destroy(){if(!m){m=true,t.removeEventListener("message",H),k&&t.removeEventListener("resize",k),k=null,v?.disconnect(),v=null;for(let e of u.values())clearTimeout(e.timer),e.reject(new Error("adapter destroyed"));u.clear(),p.clear(),f.clear();}}}}function me(t){if(t.openai!=null)return "chatgpt";try{if(t.parent!=null&&t.parent!==t)return "claude"}catch{return "claude"}return "generic"}function ge(t,r,n){switch(t){case "chatgpt":return ee(r);case "claude":case "nimblebrain":return ne(r,n);default:return te(r,n)}}function oe(t,r){let n=r.host??me(t);return ge(n,t,r)}function re(t={}){let r=t.window??globalThis,n=oe(r,t);R(n.getTheme());let i=n.onTheme(R);n.start();let l=false;return {data:()=>n.getData(),onData:a=>n.onData(a),theme:()=>n.getTheme(),onTheme:a=>n.onTheme(a),callTool:(a,p)=>n.callTool(a,p),sendPrompt:a=>n.sendPrompt(a),openLink:a=>n.openLink(a),resize:a=>n.resize(a),capabilities:()=>n.capabilities(),host:()=>n.host,destroy(){l||(l=true,i(),n.destroy());}}}globalThis.SynapseUI={connect:re};})();

nimblebrain_synapse-0.1.0/nimblebrain_synapse/server.py

@@ -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/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "nimblebrain-synapse"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "NimbleBrain Inc." }]
+keywords = ["mcp", "fastmcp", "mcp-apps", "openai-apps", "synapse", "ui", "widget"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+    # register() passes meta= to @mcp.resource(); that kwarg landed in mcp 1.26.0.
+    "mcp>=1.26.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/NimbleBrainInc/synapse"
+Repository = "https://github.com/NimbleBrainInc/synapse"
+Issues = "https://github.com/NimbleBrainInc/synapse/issues"
+Changelog = "https://github.com/NimbleBrainInc/synapse/blob/main/python/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "ruff==0.15.21",
+    "ty==0.0.61",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.25",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["nimblebrain_synapse"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

nimblebrain_synapse-0.1.0/tests/test_synapse_ui.py

@@ -0,0 +1,297 @@
+"""Tests for the SynapseUI server helper — no network.
+
+Covers HTML preparation (SDK inlining + data baking), the `<script>`-safe escape
+(the XSS defense), the mcp-ui embedded resource, the `_meta` emitters, and the
+FastMCP wiring (dual-MIME registration + the bound CallToolResult injection).
+"""
+
+from __future__ import annotations
+
+from mcp import types
+from mcp.server.fastmcp import FastMCP
+from pydantic import BaseModel
+
+from nimblebrain_synapse import SynapseUI
+from nimblebrain_synapse.server import DATA_MARKER, SDK_MARKER
+
+UI_URI = "ui://test/report"
+
+
+class _IntegrationReport(BaseModel):
+    """Module-level model so FastMCP can resolve the tool's return annotation
+    and populate structuredContent in the real-FastMCP integration test."""
+
+    domain: str
+    company: dict
+
+
+TEMPLATE = f"""<!DOCTYPE html>
+<html><head><title>t</title></head><body>
+<script type="application/json" id="synapse-ui-data">{DATA_MARKER}</script>
+<div id="app"></div>
+{SDK_MARKER}
+<script>var s = window.SynapseUI.connect(); s.onData(function(){{}});</script>
+</body></html>"""
+
+
+def _ui() -> SynapseUI:
+    return SynapseUI(uri=UI_URI, template=TEMPLATE)
+
+
+def _dossier() -> dict:
+    return {"domain": "example.com", "company": {"name": "Example Co"}}
+
+
+def test_template_inlines_sdk_and_keeps_data_marker():
+    html = _ui().template_html()
+    assert SDK_MARKER not in html  # marker replaced
+    assert "window.SynapseUI" in html  # SDK inlined
+    assert DATA_MARKER in html  # served template stays data-free
+
+
+def test_render_bakes_data_and_removes_marker():
+    html = _ui().render_html(_dossier())
+    assert DATA_MARKER not in html
+    assert '"example.com"' in html
+    assert "window.SynapseUI" in html  # SDK still present in embedded copy
+
+
+def test_safe_json_escapes_script_breakout_but_keeps_spaces():
+    out = SynapseUI._safe_json({"x": "</script><img onerror=1>", "y": "two words"})
+    assert "</script>" not in out
+    assert "\\u003c" in out and "\\u003e" in out
+    assert "two words" in out  # ordinary spaces preserved
+
+
+def test_xss_probe_hostile_company_name_stays_inert():
+    """A hostile value in the payload cannot close the <script> or inject markup."""
+    hostile = "</script><script>alert('xss')</script>"
+    html = _ui().render_html({"domain": "evil.test", "company": {"name": hostile}})
+    # The raw breakout sequence must not appear in the rendered HTML.
+    assert "</script><script>alert" not in html
+    # It survives as escaped, inert JSON.
+    assert "\\u003c/script\\u003e" in html
+
+
+def test_embedded_resource_shape():
+    res = _ui().embedded_resource(_dossier())
+    assert res.type == "resource"
+    rc = res.resource
+    assert isinstance(rc, types.TextResourceContents)
+    assert str(rc.uri) == UI_URI
+    assert rc.mimeType == "text/html"
+    assert "example.com" in rc.text
+    assert res.meta == {"mcpui.dev/ui-preferred-frame-size": ["100%", "auto"]}
+
+
+def test_tool_and_result_meta():
+    ui = _ui()
+    tm = ui.tool_meta(invoking="Working…", invoked="Done")
+    assert tm["openai/outputTemplate"] == UI_URI
+    assert tm["openai/widgetAccessible"] is True
+    assert tm["openai/toolInvocation/invoking"] == "Working…"
+    assert tm["openai/toolInvocation/invoked"] == "Done"
+    # MCP Apps standard: nested resourceUri points at the sibling mcp-app resource.
+    assert tm["ui"] == {"resourceUri": f"{UI_URI}-mcp-app"}
+    assert ui.result_meta() == {"openai/outputTemplate": UI_URI}
+
+
+def test_register_installs_both_host_resources():
+    mcp = FastMCP("test")
+    _ui().register(mcp)
+    resources = {str(r.uri): r.mime_type for r in mcp._resource_manager.list_resources()}
+    # ChatGPT skybridge (unchanged) + the MCP Apps standard resource for Claude.
+    assert resources.get(UI_URI) == "text/html+skybridge"
+    assert resources.get(f"{UI_URI}-mcp-app") == "text/html;profile=mcp-app"
+
+
+class _CapturingMCP:
+    """Records the ``meta`` each ``@mcp.resource(...)`` registration carries."""
+
+    def __init__(self) -> None:
+        self.registered: dict[str, dict] = {}
+
+    def resource(self, uri: str, *, mime_type: str, meta: dict):
+        self.registered[uri] = {"mime_type": mime_type, "meta": meta}
+        return lambda fn: fn
+
+
+def test_register_emits_widget_csp_and_domain_in_both_dialects():
+    mcp = _CapturingMCP()
+    SynapseUI(uri=UI_URI, template=TEMPLATE, domain="https://example.com").register(mcp)
+
+    # ChatGPT (skybridge) — flat openai/* dialect, snake_case CSP.
+    sky = mcp.registered[UI_URI]["meta"]
+    assert sky["openai/widgetPrefersBorder"] is True
+    assert sky["openai/widgetDomain"] == "https://example.com"
+    assert sky["openai/widgetCSP"] == {"connect_domains": [], "resource_domains": []}
+
+    # MCP Apps standard — nested ui.* dialect, camelCase CSP.
+    app = mcp.registered[f"{UI_URI}-mcp-app"]["meta"]["ui"]
+    assert app["prefersBorder"] is True
+    assert app["domain"] == "https://example.com"
+    assert app["csp"] == {"connectDomains": [], "resourceDomains": []}
+
+
+def test_register_carries_non_empty_allowlists_and_omits_domain_when_unset():
+    mcp = _CapturingMCP()
+    SynapseUI(
+        uri=UI_URI,
+        template=TEMPLATE,
+        connect_domains=["https://api.example.com"],
+        resource_domains=["https://cdn.example.com"],
+    ).register(mcp)
+
+    sky = mcp.registered[UI_URI]["meta"]
+    # CSP is always present (a self-contained default); domain only when provided.
+    assert sky["openai/widgetCSP"]["connect_domains"] == ["https://api.example.com"]
+    assert sky["openai/widgetCSP"]["resource_domains"] == ["https://cdn.example.com"]
+    assert "openai/widgetDomain" not in sky
+    assert "domain" not in mcp.registered[f"{UI_URI}-mcp-app"]["meta"]["ui"]
+
+
+def test_bind_injects_embedded_resource_and_result_meta():
+    mcp = FastMCP("test")
+    ui = _ui()
+    ui.bind(mcp, tool="analyze")
+
+    ctr = types.CallToolResult(
+        content=[types.TextContent(type="text", text="{}")],
+        structuredContent=_dossier(),
+        isError=False,
+    )
+    # Drive the bound handler by calling the wrapped request handler directly is
+    # heavy; instead exercise the attach path the handler delegates to.
+    out = ui._attach(types.ServerResult(ctr), lambda d: bool(d)).root
+    assert isinstance(out, types.CallToolResult)
+    assert out.meta is not None
+    assert out.meta["openai/outputTemplate"] == UI_URI
+    embedded = [c for c in out.content if isinstance(c, types.EmbeddedResource)]
+    assert len(embedded) == 1
+    assert "example.com" in embedded[0].resource.text
+
+
+def test_bind_skips_errors_and_empty_results():
+    ui = _ui()
+    err = types.ServerResult(types.CallToolResult(content=[], isError=True))
+    err_root = err.root
+    assert ui._attach(err, lambda d: bool(d)).root is err_root
+    assert err_root.meta is None
+
+    empty = types.ServerResult(
+        types.CallToolResult(content=[], structuredContent=None, isError=False)
+    )
+    out = ui._attach(empty, lambda d: bool(d)).root
+    assert out.meta is None
+    assert all(not isinstance(c, types.EmbeddedResource) for c in out.content)
+
+
+def test_bind_respects_should_render_predicate():
+    ui = _ui()
+    ctr = types.CallToolResult(content=[], structuredContent={"unrelated": True}, isError=False)
+    out = ui._attach(types.ServerResult(ctr), lambda d: "domain" in d).root
+    # Predicate rejects → no injection.
+    assert out.meta is None
+    assert all(not isinstance(c, types.EmbeddedResource) for c in out.content)
+
+
+class _FakeServer:
+    """Minimal stand-in for FastMCP's low-level server: just the handler registry."""
+
+    def __init__(self, prev):
+        self.request_handlers = {types.CallToolRequest: prev}
+
+
+class _FakeMcp:
+    def __init__(self, prev):
+        self._mcp_server = _FakeServer(prev)
+
+
+def _call_tool_request(name: str) -> types.CallToolRequest:
+    return types.CallToolRequest(
+        method="tools/call",
+        params=types.CallToolRequestParams(name=name, arguments={}),
+    )
+
+
+async def test_bind_dispatches_by_tool_name():
+    """The installed wrapper injects for the bound tool and passes others through."""
+    ui = _ui()
+
+    async def prev(req: types.CallToolRequest) -> types.ServerResult:
+        return types.ServerResult(
+            types.CallToolResult(
+                content=[types.TextContent(type="text", text="{}")],
+                structuredContent=_dossier(),
+                isError=False,
+            )
+        )
+
+    mcp = _FakeMcp(prev)
+    ui.bind(mcp, tool="analyze")
+    handler = mcp._mcp_server.request_handlers[types.CallToolRequest]
+
+    # Bound tool → embedded resource + result meta injected.
+    hit = (await handler(_call_tool_request("analyze"))).root
+    assert hit.meta is not None and hit.meta["openai/outputTemplate"] == UI_URI
+    assert any(isinstance(c, types.EmbeddedResource) for c in hit.content)
+
+    # Other tool → passed through untouched.
+    miss = (await handler(_call_tool_request("other"))).root
+    assert miss.meta is None
+    assert all(not isinstance(c, types.EmbeddedResource) for c in miss.content)
+
+
+async def test_bind_against_real_fastmcp_drives_installed_handler():
+    """Bind against a real FastMCP and drive a real CallToolRequest through the
+    installed handler. The _FakeMcp tests can't catch drift in mcp's internal
+    request-handler registry — exactly the risk the bind() monkey-patch carries."""
+    mcp = FastMCP("test")
+
+    @mcp.tool()
+    def analyze(domain: str) -> _IntegrationReport:
+        return _IntegrationReport(domain=domain, company={"name": "Example Co"})
+
+    ui = _ui()
+    ui.register(mcp)
+    ui.bind(mcp, tool="analyze")
+
+    handler = mcp._mcp_server.request_handlers[types.CallToolRequest]
+    result = await handler(
+        types.CallToolRequest(
+            method="tools/call",
+            params=types.CallToolRequestParams(name="analyze", arguments={"domain": "example.com"}),
+        )
+    )
+    root = result.root
+    assert isinstance(root, types.CallToolResult)
+    assert not root.isError
+    # FastMCP built structuredContent the real way; the patch appended the UI + meta.
+    assert root.meta is not None
+    assert root.meta["openai/outputTemplate"] == UI_URI
+    embedded = [c for c in root.content if isinstance(c, types.EmbeddedResource)]
+    assert len(embedded) == 1
+    assert "example.com" in embedded[0].resource.text
+
+
+async def test_bind_is_idempotent_per_tool():
+    """Binding the same tool twice must not chain two wrappers (double-inject)."""
+    ui = _ui()
+
+    async def prev(req: types.CallToolRequest) -> types.ServerResult:
+        return types.ServerResult(
+            types.CallToolResult(
+                content=[types.TextContent(type="text", text="{}")],
+                structuredContent=_dossier(),
+                isError=False,
+            )
+        )
+
+    mcp = _FakeMcp(prev)
+    ui.bind(mcp, tool="analyze")
+    ui.bind(mcp, tool="analyze")  # second bind is a no-op
+
+    handler = mcp._mcp_server.request_handlers[types.CallToolRequest]
+    root = (await handler(_call_tool_request("analyze"))).root
+    embedded = [c for c in root.content if isinstance(c, types.EmbeddedResource)]
+    assert len(embedded) == 1  # injected exactly once, not twice