@cosmoops/connect-sdk 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -3,6 +3,92 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.16.1
+
+### Fixed
+
+- **`McpToolResult` is a type alias, not an interface** — so `callTool()` can be
+  returned straight from `server.setRequestHandler(CallToolRequestSchema, ...)`.
+
+  The MCP SDK types a request handler's return as a union whose members carry an
+  index signature. TypeScript does not grant an interface the implicit index
+  signature it grants a type alias, so as an interface the result was assignable
+  to none of them, and the four-line wiring in 0.16.0's own documentation failed
+  to compile with a misleading `Property 'task' is missing`. The only way past it
+  was a cast, at exactly the boundary where a cast hides shape errors.
+
+  Type-level only; no runtime change, and nothing that compiled against 0.16.0
+  stops compiling.
+
+## 0.16.0
+
+### Added
+
+- **`@cosmoops/connect-sdk/mcp` - your store declaration, as MCP tools.**
+
+  ```ts
+  import { createStoreToolset } from "@cosmoops/connect-sdk/mcp";
+
+  const toolset = createStoreToolset({
+    collections: STORE_SCHEMA,      // the array you already seed to Connect
+    data: connect.data,
+    workspaceId: session.workspaceId,
+    asUser: session.sessionToken,   // every call runs as this user
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, () => toolset.listTools());
+  server.setRequestHandler(CallToolRequestSchema, (request) =>
+    toolset.callTool(request.params.name, request.params.arguments ?? {}),
+  );
+  ```
+
+  `Application.storeSchema` already says what each collection holds, which
+  fields may be filtered on, which query shapes the database can serve, and
+  whether it refuses everything but a create. Writing tools over that by hand
+  means keeping a second copy of all of it, and the copy is wrong the first time
+  a filter is added to a screen. So they are derived: adding a queryable field
+  and re-seeding widens the tools on the next boot, with no tool code to touch.
+
+  Three read tools per collection (`_get`, `_list`, `_aggregate`), and writes
+  only if you ask - `writes: "create" | "all"`, defaulting to `"none"`. An
+  `appendOnly` collection never derives an update or a delete, because Connect
+  would refuse them anyway and a tool that can only fail is worse than no tool.
+
+  Each tool's description carries the collection's queryable fields and its
+  declared composite indexes, and an unservable query is refused locally with
+  the index it would need - so a model adapts instead of spending a turn
+  discovering the shape.
+
+  **Every call carries an end user's session token.** Connect resolves it to a
+  member and checks the collection's declared `readPermission`/`writePermission`
+  against that member's live roles, so a toolset never reaches further than the
+  person it runs for, and a permission revoked in the console is gone from the
+  next call. Build one per request from `getConnectSession()`, or pass a
+  function for `asUser`.
+
+  There is deliberately **no scan tool**. `data.scan` reads across every
+  workspace and for that reason takes no `asUser` - deriving one would mean that
+  single call escalating to your API key while every tool beside it ran as the
+  user. Cross-tenant reads belong behind their own gate.
+
+  Server-only, like `/server` and `/next`: a browser import resolves to the
+  guard stub and fails the build. **No new dependency** - `listTools()` and
+  `callTool()` answer in the shapes the MCP protocol defines, so the official
+  MCP SDK stays yours to install and version.
+
+  **Pass `include`.** Measured on the reference applications, deriving over
+  every collection yields 45 read tools for club and 21 for CRM - whole-catalogue
+  numbers, and a model offered them chooses worse than one offered a handful.
+  Name the collections the surface at hand is about. Where a collection declares
+  more index shapes than are worth listing (club's ledger declares around
+  forty), the description states the rule and leaves the specifics to the
+  refusal, which names the exact index a rejected query needed.
+
+- **`StoreCollectionDeclaration`, `describeQueryRejection` and
+  `storeIndexCovers`** on the root entry. The declaration type is the shape
+  Connect stores on `Application.storeSchema`, so an app deriving its schema
+  from its own query matrix can stop declaring a local copy of it.
+
 ## 0.15.0
 
 Your application's own database stops being a toy. Real queries, real

package/README.md

@@ -12,13 +12,14 @@ npm install @cosmoops/connect-sdk
 npm install streamdown   # optional — Ask AI's markdown renderer, see step 4
 ```
 
-Two entry points, and the split is a security boundary, not a preference:
+Five entry points, and the split is a security boundary, not a preference:
 
 | Import | Runs in | Holds the API key |
 | --- | --- | --- |
 | `@cosmoops/connect-sdk/server` | your backend | **yes** |
 | `@cosmoops/connect-sdk/client` | the browser | never |
 | `@cosmoops/connect-sdk/next` | your backend | **yes** (Next.js plug-and-play) |
+| `@cosmoops/connect-sdk/mcp` | your backend | **yes** (store, as MCP tools) |
 | `@cosmoops/connect-sdk` | anywhere | types + `ConnectError` only |
 
 The browser half never sees a credential. It calls your own origin, and

package/dist/cjs/client/components/ai-screens.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchConnectScreen = matchConnectScreen;
+exports.isLinkableConnectScreen = isLinkableConnectScreen;
+/**
+ * Matching a live path against the screens your application declared.
+ *
+ * The same rule Connect uses for its own routes, and it has to be here too
+ * because only this side knows what your app's routes are: a dynamic segment
+ * matches exactly one path segment, and where several patterns fit, the most
+ * *literal* wins - so `/deals/new` resolves to itself rather than to
+ * `/deals/[dealId]` merely because that also fits.
+ *
+ * Plain functions with no React and no imports beyond the type, so the panel,
+ * the action links and any host that wants to reuse the matching can share one
+ * implementation.
+ */
+/** Trims the query string, the hash and any trailing slash. */
+function normalise(path) {
+    const withoutQuery = path.split(/[?#]/)[0] ?? "";
+    return withoutQuery.length > 1 ? withoutQuery.replace(/\/+$/, "") : withoutQuery;
+}
+/**
+ * The declared screen a live path is on, or `null` if none matches.
+ *
+ * `null` is a normal outcome, not an error: an application need only describe
+ * the screens it wants the assistant to know about, and an undescribed one
+ * simply costs the assistant its orientation rather than costing the user an
+ * answer.
+ */
+function matchConnectScreen(screens, path) {
+    const segments = normalise(path).split("/").filter(Boolean);
+    let best = null;
+    for (const screen of screens) {
+        const pattern = normalise(screen.path).split("/").filter(Boolean);
+        if (pattern.length !== segments.length)
+            continue;
+        let literals = 0;
+        let matches = true;
+        for (let i = 0; i < pattern.length; i++) {
+            const part = pattern[i];
+            if (part.startsWith("[") && part.endsWith("]"))
+                continue;
+            if (part !== segments[i]) {
+                matches = false;
+                break;
+            }
+            literals++;
+        }
+        if (matches && (!best || literals > best.literals))
+            best = { screen, literals };
+    }
+    return best?.screen ?? null;
+}
+/**
+ * Whether an href the model produced may be rendered as a link.
+ *
+ * Same reasoning as Connect's own `showActions` check, and the same conclusion:
+ * an assistant that can emit an arbitrary URL is a redirect the model can be
+ * talked into, and retrieved content shares a context window with its
+ * tool-calling authority. So a link is drawn only when it resolves to a screen
+ * *your application declared* - which makes an external destination structurally
+ * impossible, since no route pattern has a scheme or a host.
+ *
+ * The protocol-relative form is refused separately: `//evil.example.com` has no
+ * scheme for a path matcher to trip over, and would otherwise reach an anchor
+ * as an absolute destination.
+ */
+function isLinkableConnectScreen(screens, href) {
+    if (!href.startsWith("/") || href.startsWith("//"))
+        return false;
+    return matchConnectScreen(screens, href) !== null;
+}

package/dist/cjs/client/components/ai-widgets.js

@@ -8,10 +8,12 @@ exports.AiTimeline = AiTimeline;
 exports.AiDetails = AiDetails;
 exports.AiSteps = AiSteps;
 exports.AiSources = AiSources;
+exports.AiActions = AiActions;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const react_2 = require("@heroui/react");
 const lucide_react_1 = require("lucide-react");
+const ai_screens_js_1 = require("./ai-screens.js");
 const ai_format_js_1 = require("./ai-format.js");
 /**
  * What Ask AI draws.
@@ -230,3 +232,38 @@ function AiSources({ sources }) {
                     return ((0, jsx_runtime_1.jsx)("li", { children: source.uri ? ((0, jsx_runtime_1.jsxs)("a", { href: source.uri, target: "_blank", rel: "noopener noreferrer", className: "flex gap-1.5 rounded-sm hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus", children: [label, (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "mt-0.5 size-3 shrink-0 text-muted", "aria-hidden": true })] })) : ((0, jsx_runtime_1.jsx)("span", { className: "flex gap-1.5", children: label })) }, `${source.uri ?? source.title}-${index}`));
                 }) })] }));
 }
+/**
+ * Where to go next, as links into *your* application.
+ *
+ * ## Why links and not navigation
+ *
+ * The obvious version of "the assistant can act" moves the user. It is also the
+ * version that breaks the property the whole design rests on: nothing happens
+ * without a click. Retrieved content shares a context window with the model's
+ * tool-calling authority, so an auto-navigate is a redirect primitive that
+ * content can reach. A link cannot be, and loses nothing - the user was going
+ * to click something anyway.
+ *
+ * ## Why every href is checked against your declared screens
+ *
+ * The model can emit any string. Only your application knows which strings are
+ * real routes, which is why `screens` is a prop rather than something Connect
+ * could supply. A link that does not resolve is *dropped* rather than rendered
+ * broken - the prose around it still stands, so a missing link reads as terse
+ * rather than wrong.
+ *
+ * `renderLink` is how this stays router-agnostic. Given one, a link is your
+ * framework's - a Next `<Link>`, a TanStack `<Link>` - and navigation is a
+ * client transition. Without one it falls back to an anchor, which works
+ * everywhere and costs a document load.
+ */
+function AiActions({ title, actions, screens, renderLink, }) {
+    const resolved = actions.filter((action) => (0, ai_screens_js_1.isLinkableConnectScreen)(screens, action.href));
+    if (resolved.length === 0)
+        return null;
+    const className = "group flex items-center gap-2 rounded-lg border border-separator bg-surface px-3 py-2 no-underline transition-colors hover:border-accent";
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "my-3", children: [title ? (0, jsx_runtime_1.jsx)("p", { className: "mb-1.5 text-xs font-medium text-muted", children: title }) : null, (0, jsx_runtime_1.jsx)("div", { className: "flex flex-col gap-1.5", children: resolved.map((action) => {
+                    const body = ((0, jsx_runtime_1.jsxs)("span", { className: "min-w-0 flex-1", children: [(0, jsx_runtime_1.jsx)("span", { className: "block truncate text-xs font-medium text-foreground", children: action.label }), action.detail ? ((0, jsx_runtime_1.jsx)("span", { className: "block truncate text-[11px] text-muted", children: action.detail })) : null] }));
+                    return ((0, jsx_runtime_1.jsx)(react_1.Fragment, { children: renderLink ? (renderLink({ href: action.href, className, children: body })) : ((0, jsx_runtime_1.jsx)("a", { href: action.href, className: className, children: body })) }, action.href));
+                }) })] }));
+}

package/dist/cjs/client/components/ask-ai.js

@@ -8,6 +8,8 @@ const react_2 = require("@heroui/react");
 const lucide_react_1 = require("lucide-react");
 const streamdown_1 = require("streamdown");
 const provider_js_1 = require("../provider.js");
+const use_active_path_js_1 = require("../use-active-path.js");
+const ai_screens_js_1 = require("./ai-screens.js");
 const ai_widgets_js_1 = require("./ai-widgets.js");
 /**
  * The panel's open width. The *inner* pane always carries it, so the content
@@ -66,7 +68,7 @@ function ThinkingDisclosure({ text, isStreaming }) {
  */
 const isArray = (value) => Array.isArray(value) && value.length > 0;
 const field = (input, key) => typeof input === "object" && input !== null ? input[key] : undefined;
-function renderTool(name, input, renderMarkdown) {
+function renderTool(name, input, renderMarkdown, screens, renderLink) {
     switch (name) {
         case "showTable":
             return isArray(field(input, "columns")) && Array.isArray(field(input, "rows")) ? ((0, jsx_runtime_1.jsx)(ai_widgets_js_1.AiTable, { ...input })) : null;
@@ -82,6 +84,12 @@ function renderTool(name, input, renderMarkdown) {
             return isArray(field(input, "steps")) ? ((0, jsx_runtime_1.jsx)(ai_widgets_js_1.AiSteps, { ...input, renderDetail: renderMarkdown })) : null;
         case "showSources":
             return isArray(field(input, "sources")) ? (0, jsx_runtime_1.jsx)(ai_widgets_js_1.AiSources, { ...input }) : null;
+        case "showActions":
+            // Every href is checked against the declared screens before anything is
+            // drawn - see `AiActions`. With none declared, nothing resolves and the
+            // tool renders nothing, which is the correct outcome rather than a
+            // collection of dead links.
+            return isArray(field(input, "actions")) ? ((0, jsx_runtime_1.jsx)(ai_widgets_js_1.AiActions, { ...input, screens: screens, renderLink: renderLink })) : null;
         default:
             return null;
     }
@@ -223,7 +231,7 @@ function appendText(blocks, text) {
  * Neither is something the browser can discover, so both surface as a message
  * in the panel rather than as a hidden button.
  */
-function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placeholder = "Ask a question...", hint = "Ask a question about your workspace - answers are grounded in what your team has indexed.", defaultOpen = false, markdownPlugins, }) {
+function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placeholder = "Ask a question...", hint = "Ask a question about your workspace - answers are grounded in what your team has indexed.", defaultOpen = false, markdownPlugins, screens = [], activePath, renderLink, }) {
     const { session, isLoading, streamResource } = (0, provider_js_1.useConnect)();
     const [isOpen, setIsOpen] = (0, react_1.useState)(defaultOpen);
     const [turns, setTurns] = (0, react_1.useState)([]);
@@ -242,6 +250,16 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
     // A conversation left mid-stream should stop costing tokens the moment the
     // panel goes away.
     (0, react_1.useEffect)(() => () => abortRef.current?.abort(), []);
+    /**
+     * The declared screen the user is on, if any.
+     *
+     * Drives the opening chips here and travels with each message so the answer
+     * is written from where they are standing. `null` whenever nothing matches -
+     * an application need only describe the screens it wants the assistant to
+     * know about.
+     */
+    const resolvedPath = (0, use_active_path_js_1.useActivePath)(activePath);
+    const currentScreen = (0, react_1.useMemo)(() => (resolvedPath ? (0, ai_screens_js_1.matchConnectScreen)(screens, resolvedPath) : null), [screens, resolvedPath]);
     const renderMarkdown = (0, react_1.useCallback)((text, isStreaming = false) => ((0, jsx_runtime_1.jsx)(streamdown_1.Streamdown, { className: "connect-ai-body", mode: isStreaming ? "streaming" : "static", isAnimating: isStreaming, animated: ANIMATED, caret: isStreaming ? "block" : undefined, plugins: markdownPlugins, 
         // Retrieved documents cite real URLs; an interstitial on every one of
         // them turns a citation into a chore. The renderer still sanitises the
@@ -286,7 +304,15 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
         try {
             // Relative to the provider's own `basePath` - `streamResource` prefixes
             // it, the same way every other bridge call is addressed.
-            const response = await streamResource("/ai/chat", { messages: history }, { signal: controller.signal });
+            const response = await streamResource("/ai/chat", {
+                messages: history,
+                // What the assistant is told about where the user is, and what your
+                // application's screens are. Both are prose: Connect uses them to
+                // write a better answer and to validate action links, never to
+                // decide what anyone may do. See `ConnectScreen`.
+                ...(resolvedPath ? { screenContext: { pathname: resolvedPath } } : {}),
+                ...(screens.length > 0 ? { screens } : {}),
+            }, { signal: controller.signal });
             // The assistant's turn is appended only once the stream is live, so a
             // failed request leaves an error under the question rather than an
             // empty bubble that never fills.
@@ -333,7 +359,7 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
                 // The user's own turn is shown as they typed it - running a
                 // question that happens to start with `#` through the markdown
                 // renderer would turn it into a heading.
-                (0, jsx_runtime_1.jsx)("div", { children: turn.role === "user" ? ((0, jsx_runtime_1.jsx)("p", { className: "whitespace-pre-wrap", children: block.text })) : (renderMarkdown(block.text, isLive && index === lastTextIndex)) }, index)) : block.input === null ? ((0, jsx_runtime_1.jsx)(ToolSkeleton, {}, block.id)) : ((0, jsx_runtime_1.jsx)("div", { children: renderTool(block.name, block.input, renderMarkdown) }, block.id))), isLive && lastTextIndex === -1 && turn.blocks.length === 0 && (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] }, turn.id));
+                (0, jsx_runtime_1.jsx)("div", { children: turn.role === "user" ? ((0, jsx_runtime_1.jsx)("p", { className: "whitespace-pre-wrap", children: block.text })) : (renderMarkdown(block.text, isLive && index === lastTextIndex)) }, index)) : block.input === null ? ((0, jsx_runtime_1.jsx)(ToolSkeleton, {}, block.id)) : ((0, jsx_runtime_1.jsx)("div", { children: renderTool(block.name, block.input, renderMarkdown, screens, renderLink) }, block.id))), isLive && lastTextIndex === -1 && turn.blocks.length === 0 && (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] }, turn.id));
     }), [turns, isAnswering, lastTurn?.id, assistantName, renderMarkdown]);
     // Signed out there is no workspace to ground an answer in, and the bridge
     // would answer 401 - so there is nothing to offer, not even a button.
@@ -347,7 +373,7 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
         setInput("");
         void send(text);
     };
-    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [!isOpen && ((0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, variant: "primary", "aria-label": title, onPress: () => setIsOpen(true), className: "fixed bottom-4 end-4 z-30 size-12 rounded-full shadow-lg sm:bottom-6 sm:end-6", children: (0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-5" }) })), (0, jsx_runtime_1.jsx)("div", { className: `fixed inset-0 z-40 bg-backdrop transition-opacity lg:hidden ${isOpen ? "pointer-events-auto opacity-100" : "pointer-events-none opacity-0"}`, onClick: () => setIsOpen(false), "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("aside", { "aria-hidden": !isOpen, className: `fixed inset-y-0 end-0 z-50 flex flex-col border-s border-border bg-surface shadow-xl transition-transform duration-300 ease-in-out ${panelShellWidth(isOpen)} ${isOpen ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"} lg:static lg:z-auto lg:translate-x-0 lg:shadow-none lg:transition-[width]`, children: (0, jsx_runtime_1.jsxs)("div", { className: `flex h-full shrink-0 flex-col ${PANEL_WIDTH}`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2 border-b border-border px-4 py-3", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-4 shrink-0 text-accent" }), (0, jsx_runtime_1.jsx)("span", { className: "flex-1 text-sm font-semibold", children: title }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [turns.length === 0 && (0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: hint }), rendered, isBusy && lastTurn?.role === "user" && ((0, jsx_runtime_1.jsxs)("div", { className: "rounded-md border border-border bg-accent/5 p-2.5 text-sm", children: [(0, jsx_runtime_1.jsx)("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: assistantName }), (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] })), error && (0, jsx_runtime_1.jsx)("p", { className: "text-xs text-danger", children: error }), (0, jsx_runtime_1.jsx)("div", { ref: bottomRef })] }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "flex gap-2 border-t border-border p-3", children: [(0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", className: "flex-1", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "sr-only", children: placeholder }), (0, jsx_runtime_1.jsx)(react_2.Input, { placeholder: placeholder, value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: isBusy })] }), isBusy ? ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "button", isIconOnly: true, variant: "secondary", "aria-label": "Stop generating", onPress: stop, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Square, { className: "size-3.5" }) })) : ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", isDisabled: !input.trim(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Send, { className: "size-3.5" }) }))] })] }) })] }));
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [!isOpen && ((0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, variant: "primary", "aria-label": title, onPress: () => setIsOpen(true), className: "fixed bottom-4 end-4 z-30 size-12 rounded-full shadow-lg sm:bottom-6 sm:end-6", children: (0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-5" }) })), (0, jsx_runtime_1.jsx)("div", { className: `fixed inset-0 z-40 bg-backdrop transition-opacity lg:hidden ${isOpen ? "pointer-events-auto opacity-100" : "pointer-events-none opacity-0"}`, onClick: () => setIsOpen(false), "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("aside", { "aria-hidden": !isOpen, className: `fixed inset-y-0 end-0 z-50 flex flex-col border-s border-border bg-surface shadow-xl transition-transform duration-300 ease-in-out ${panelShellWidth(isOpen)} ${isOpen ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"} lg:static lg:z-auto lg:translate-x-0 lg:shadow-none lg:transition-[width]`, children: (0, jsx_runtime_1.jsxs)("div", { className: `flex h-full shrink-0 flex-col ${PANEL_WIDTH}`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2 border-b border-border px-4 py-3", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-4 shrink-0 text-accent" }), (0, jsx_runtime_1.jsx)("span", { className: "flex-1 text-sm font-semibold", children: title }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [turns.length === 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "space-y-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: hint }), currentScreen?.suggestions?.length ? ((0, jsx_runtime_1.jsx)("div", { className: "flex flex-wrap gap-1.5", children: currentScreen.suggestions.map((suggestion) => ((0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "secondary", className: "h-auto rounded-full px-2.5 py-1 text-start text-xs whitespace-normal", isDisabled: isBusy, onPress: () => void send(suggestion), children: suggestion }, suggestion))) })) : null] })), rendered, isBusy && lastTurn?.role === "user" && ((0, jsx_runtime_1.jsxs)("div", { className: "rounded-md border border-border bg-accent/5 p-2.5 text-sm", children: [(0, jsx_runtime_1.jsx)("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: assistantName }), (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] })), error && (0, jsx_runtime_1.jsx)("p", { className: "text-xs text-danger", children: error }), (0, jsx_runtime_1.jsx)("div", { ref: bottomRef })] }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "flex gap-2 border-t border-border p-3", children: [(0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", className: "flex-1", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "sr-only", children: placeholder }), (0, jsx_runtime_1.jsx)(react_2.Input, { placeholder: placeholder, value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: isBusy })] }), isBusy ? ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "button", isIconOnly: true, variant: "secondary", "aria-label": "Stop generating", onPress: stop, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Square, { className: "size-3.5" }) })) : ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", isDisabled: !input.trim(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Send, { className: "size-3.5" }) }))] })] }) })] }));
 }
 /** Hoisted for the same reference-equality reason as `ANIMATED` - Streamdown compares it by identity. */
 const LINK_SAFETY = { enabled: false };

package/dist/cjs/client/index.js

@@ -2,8 +2,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizePath = exports.flattenNav = exports.normalizeNav = exports.useActivePath = exports.ConnectSideNav = exports.ConnectSidebarNav = exports.RAIL_EXPANDED = exports.RAIL_COLLAPSED = exports.sidebarRowClass = exports.useConnectShell = exports.ConnectShellProvider = exports.ConnectSidebarRow = exports.ConnectSidebarFooter = exports.ConnectSidebarBody = exports.ConnectSidebarHeader = exports.ConnectSidebar = exports.AppShell = exports.ConnectAccountSessions = exports.ConnectSignOutButton = exports.ConnectHomeButton = exports.ConnectProfileButton = exports.ConnectInvoicesButton = exports.ConnectManageSubscriptionButton = exports.ConnectUserMenu = exports.ConnectProfileModal = exports.ConnectUserButton = exports.ConnectRegisterButton = exports.ConnectLoginButton = exports.ConnectLogo = exports.ConnectMark = exports.ConnectGrievanceNotice = exports.isConnectError = exports.ConnectError = exports.normalizePlanFeatures = exports.blockingBlockers = exports.CONNECT_APP_URL = exports.useConnectResource = exports.useConnectIntegrations = exports.useConnectSessions = exports.useConnectAddonUsage = exports.useConnectCompanyProfile = exports.useConnectApps = exports.useConnectPlans = exports.useConnectEntitlements = exports.useConnectPlatformAccess = exports.useConnectAudience = exports.useConnectWorkspaceType = exports.useConnectUser = exports.useConnect = exports.ConnectProvider = void 0;
-exports.ACTION_LABEL = exports.discountLabel = exports.annualSaving = exports.resolveAction = exports.monthlyOf = exports.formatPrice = exports.buildCheckoutUrl = exports.useConnectCheckout = exports.ConnectFilterTabs = exports.ConnectCursorPagination = exports.ConnectConfirmDialog = exports.ConnectLinkButton = exports.ConnectPlansPage = exports.ConnectUsageMeter = exports.ConnectPlatformGate = exports.ConnectWorkspaceTypeGate = exports.useConnectFeature = exports.ConnectFeatureGate = exports.useConnectAccessGate = exports.ConnectAccessGate = exports.ConnectReadinessGate = exports.ConnectReadinessBanner = exports.resolveSubscriptionState = exports.ConnectSeatUsage = exports.ConnectTrialBanner = exports.ConnectSubscriptionCard = exports.ConnectNoSubscriptionCard = exports.ConnectSubscriptionGate = exports.ConnectSubscribeDialog = exports.ConnectPlans = exports.ConnectIntegrationsModal = exports.AI_TONE_DOT = exports.AI_TONE_CHIP = exports.AI_EMPTY_VALUE = exports.aiStatusTone = exports.isNumericAiFormat = exports.formatAiValue = exports.AiSources = exports.AiSteps = exports.AiDetails = exports.AiTimeline = exports.AiMetrics = exports.AiChart = exports.AiTable = exports.ConnectAskAi = exports.ConnectAppsGrid = exports.filterNavForAudience = exports.gateExemptPaths = exports.isNavItemActive = exports.resolveActivePath = void 0;
-exports.useConnectWorkspaceMembers = exports.useConnectWorkspaces = exports.ConnectWorkspaceSwitcher = exports.resolvePlanGroup = exports.groupPlansByTier = void 0;
+exports.annualSaving = exports.resolveAction = exports.monthlyOf = exports.formatPrice = exports.buildCheckoutUrl = exports.useConnectCheckout = exports.ConnectFilterTabs = exports.ConnectCursorPagination = exports.ConnectConfirmDialog = exports.ConnectLinkButton = exports.ConnectPlansPage = exports.ConnectUsageMeter = exports.ConnectPlatformGate = exports.ConnectWorkspaceTypeGate = exports.useConnectFeature = exports.ConnectFeatureGate = exports.useConnectAccessGate = exports.ConnectAccessGate = exports.ConnectReadinessGate = exports.ConnectReadinessBanner = exports.resolveSubscriptionState = exports.ConnectSeatUsage = exports.ConnectTrialBanner = exports.ConnectSubscriptionCard = exports.ConnectNoSubscriptionCard = exports.ConnectSubscriptionGate = exports.ConnectSubscribeDialog = exports.ConnectPlans = exports.ConnectIntegrationsModal = exports.AI_TONE_DOT = exports.AI_TONE_CHIP = exports.AI_EMPTY_VALUE = exports.aiStatusTone = exports.isNumericAiFormat = exports.formatAiValue = exports.AiSources = exports.AiSteps = exports.AiDetails = exports.AiTimeline = exports.AiMetrics = exports.AiChart = exports.AiTable = exports.ConnectAskAi = exports.ConnectAppsGrid = exports.isLinkableConnectScreen = exports.matchConnectScreen = exports.filterNavForAudience = exports.gateExemptPaths = exports.isNavItemActive = exports.resolveActivePath = void 0;
+exports.useConnectWorkspaceMembers = exports.useConnectWorkspaces = exports.ConnectWorkspaceSwitcher = exports.resolvePlanGroup = exports.groupPlansByTier = exports.ACTION_LABEL = exports.discountLabel = void 0;
 /**
  * Browser half of `@cosmoops/connect-sdk` - React components and hooks.
  *
@@ -114,6 +114,9 @@ Object.defineProperty(exports, "resolveActivePath", { enumerable: true, get: fun
 Object.defineProperty(exports, "isNavItemActive", { enumerable: true, get: function () { return nav_js_1.isNavItemActive; } });
 Object.defineProperty(exports, "gateExemptPaths", { enumerable: true, get: function () { return nav_js_1.gateExemptPaths; } });
 Object.defineProperty(exports, "filterNavForAudience", { enumerable: true, get: function () { return nav_js_1.filterNavForAudience; } });
+var ai_screens_js_1 = require("./components/ai-screens.js");
+Object.defineProperty(exports, "matchConnectScreen", { enumerable: true, get: function () { return ai_screens_js_1.matchConnectScreen; } });
+Object.defineProperty(exports, "isLinkableConnectScreen", { enumerable: true, get: function () { return ai_screens_js_1.isLinkableConnectScreen; } });
 var apps_grid_js_1 = require("./components/apps-grid.js");
 Object.defineProperty(exports, "ConnectAppsGrid", { enumerable: true, get: function () { return apps_grid_js_1.ConnectAppsGrid; } });
 // `AppShell askAi` mounts this; exported for an app that wants the panel

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.unchangedSince = exports.storeIndexSignature = exports.storeIndexFor = exports.serverTimestamp = exports.increment = exports.documentExists = exports.deleteField = exports.arrayUnion = exports.arrayRemove = exports.normalizePlanFeatures = exports.blockingBlockers = exports.isConnectError = exports.ConnectError = void 0;
+exports.storeIndexCovers = exports.describeQueryRejection = exports.unchangedSince = exports.storeIndexSignature = exports.storeIndexFor = exports.serverTimestamp = exports.increment = exports.documentExists = exports.deleteField = exports.arrayUnion = exports.arrayRemove = exports.normalizePlanFeatures = exports.blockingBlockers = exports.isConnectError = exports.ConnectError = void 0;
 /**
  * `@cosmoops/connect-sdk` - the official client for the CosmoOps Connect
  * **application-partner API** (`/api/v1/application/*`).
@@ -13,6 +13,8 @@ exports.unchangedSince = exports.storeIndexSignature = exports.storeIndexFor = e
  *   Holds the API key. Never import this from browser code.
  * - `@cosmoops/connect-sdk/client` - React components and hooks. Talks to your
  *   own origin only.
+ * - `@cosmoops/connect-sdk/mcp` - your store's declaration, derived into MCP
+ *   tools. Holds the API key; never import this from browser code.
  */
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "ConnectError", { enumerable: true, get: function () { return errors_js_1.ConnectError; } });
@@ -30,3 +32,6 @@ Object.defineProperty(exports, "serverTimestamp", { enumerable: true, get: funct
 Object.defineProperty(exports, "storeIndexFor", { enumerable: true, get: function () { return store_js_1.storeIndexFor; } });
 Object.defineProperty(exports, "storeIndexSignature", { enumerable: true, get: function () { return store_js_1.storeIndexSignature; } });
 Object.defineProperty(exports, "unchangedSince", { enumerable: true, get: function () { return store_js_1.unchangedSince; } });
+var store_schema_js_1 = require("./store-schema.js");
+Object.defineProperty(exports, "describeQueryRejection", { enumerable: true, get: function () { return store_schema_js_1.describeQueryRejection; } });
+Object.defineProperty(exports, "storeIndexCovers", { enumerable: true, get: function () { return store_schema_js_1.storeIndexCovers; } });

package/dist/cjs/mcp/index.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveStoreTools = void 0;
+exports.createStoreToolset = createStoreToolset;
+/**
+ * `@cosmoops/connect-sdk/mcp` - your application's store, as an MCP server.
+ *
+ * Server-only: every call goes out through `ConnectClient`, which holds the API
+ * key. The `browser` export condition resolves this entry to a stub, so an
+ * import from client code fails the build rather than shipping the key.
+ *
+ * ## Zero dependencies, on purpose
+ *
+ * This entry does not import `@modelcontextprotocol/sdk`, and the package takes
+ * no dependency on it. `listTools()` and `callTool()` answer in the shapes the
+ * MCP protocol defines, so wiring them to the official server is four lines and
+ * a transport you choose:
+ *
+ * ```ts
+ * const toolset = createStoreToolset({
+ *   collections: STORE_SCHEMA,
+ *   data: connect.data,
+ *   workspaceId: session.workspaceId,
+ *   asUser: session.sessionToken,
+ * })
+ *
+ * server.setRequestHandler(ListToolsRequestSchema, () => toolset.listTools())
+ * server.setRequestHandler(CallToolRequestSchema, (request) =>
+ *   toolset.callTool(request.params.name, request.params.arguments ?? {}),
+ * )
+ * ```
+ *
+ * The alternative - depending on the MCP SDK so this file could return an
+ * `McpServer` - would put a version of it in every install of this package,
+ * including the ones that never touch MCP, and pin partners to whichever
+ * version shipped here. The protocol shapes are stable and small; the coupling
+ * would not be.
+ *
+ * ## One toolset per session
+ *
+ * `asUser` is an end user's Connect session token, and Connect checks each
+ * collection's declared permission against that member's live roles. A toolset
+ * is therefore scoped to one signed-in user - build it per request from
+ * `getConnectSession()`, or pass a function for `asUser` if the surrounding
+ * server outlives a session.
+ */
+var tools_js_1 = require("./tools.js");
+Object.defineProperty(exports, "deriveStoreTools", { enumerable: true, get: function () { return tools_js_1.deriveStoreTools; } });
+const tools_js_2 = require("./tools.js");
+/**
+ * A refusal is a result, not a thrown error.
+ *
+ * MCP draws that distinction deliberately: a protocol error is a fault the
+ * model cannot act on, while `isError: true` is a tool result the model reads
+ * and can respond to. An unservable query and a permission Connect refused are
+ * both things a model should see and adapt to - naming a field it may not
+ * filter on, or telling the user it cannot reach that data - so they come back
+ * as content rather than as a transport failure.
+ */
+function asResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+function createStoreToolset(options) {
+    const tools = (0, tools_js_2.deriveStoreTools)(options);
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    return {
+        tools,
+        listTools: () => ({
+            tools: tools.map((tool) => ({
+                name: tool.name,
+                title: tool.title,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                annotations: tool.annotations,
+            })),
+        }),
+        async callTool(name, args) {
+            const tool = byName.get(name);
+            if (!tool) {
+                return asResult(`No such tool: "${name}". Available: ${[...byName.keys()].join(", ")}.`, true);
+            }
+            try {
+                return asResult(JSON.stringify(await tool.execute(args), null, 2));
+            }
+            catch (error) {
+                return asResult(error instanceof Error ? error.message : String(error), true);
+            }
+        },
+    };
+}