@mcp-b/embedded-agent 1.2.5-beta.0 → 1.2.6

package/LICENSE

@@ -0,0 +1,23 @@
+Kukumis Inc. Proprietary License
+
+Copyright (c) 2025 Kukumis Inc. All rights reserved.
+
+This software, including all source code, object code, documentation, and any
+related materials (collectively, the "Software"), is proprietary to Kukumis
+Inc. and is protected by applicable intellectual property laws.
+
+No part of the Software may be used, copied, modified, merged, published,
+distributed, sublicensed, and/or sold, in whole or in part, except as expressly
+authorized in a written license agreement signed by Kukumis Inc.
+
+No license or other rights are granted by Kukumis Inc. under any patents,
+copyrights, trade secrets, trademarks, or other intellectual property rights,
+whether by implication, estoppel, or otherwise, except as expressly set forth
+in such written license agreement.
+
+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
+KUKUMIS INC. 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.

package/README.md

@@ -2,89 +2,258 @@
 
 An Intercom-like AI chat widget with MCP tool support and voice mode. Drop it into your app and you're done.
 
+Styles are isolated using Shadow DOM. Customize appearance by setting CSS variables on the host page.
+
+## Build Architecture
+
+This package provides the `<webmcp-agent>` custom element in two formats:
+
+| Export | Format | Use Case |
+|--------|--------|----------|
+| `@mcp-b/embedded-agent` / `@mcp-b/embedded-agent/web-component` | ESM web component | Bundlers, monorepo dev |
+| `@mcp-b/embedded-agent/standalone` | IIFE web component | `<script>` tag embeds |
+
+### Why Two Builds?
+
+**ESM Build** (root export or `/web-component`)
+- Web component entrypoint for bundlers
+- React is externalized via `peerDependencies` (install `react` and `react-dom`)
+- Smaller bundle; no duplicate React if the host already uses it
+- Uses Shadow DOM for style isolation
+- Use for: bundlers, monorepo consumers
+
+**Standalone IIFE Build** (`/standalone`)
+- Web component via `<script>` tag
+- React is bundled inside the package
+- Uses Shadow DOM for complete JS/CSS isolation
+- Separate React instances in separate DOM trees = no conflict
+- Use for: `<script>` tag embedding on any website (React or not)
+
+### The "Two Reacts" Problem
+
+When a React app loads the standalone bundle, you get duplicate React instances which causes the infamous "hooks can only be called inside a function component" error.
+
+**Shadow DOM solves this**: Each React instance manages its own separate DOM tree inside the shadow boundary, so they never conflict.
+
+```
+Host Page (React 18)
+├── <div id="root">  ← Host's React
+│   └── ... host app ...
+│
+└── <webmcp-agent>
+    └── #shadow-root  ← Isolation boundary
+        └── <div>  ← Bundled React 19
+            └── ... widget ...
+```
+
 ## Installation
 
 ```bash
 npm install @mcp-b/embedded-agent
 ```
 
-## Quick Start
+## Usage
 
-### React
+`<webmcp-agent>` renders as a full-viewport overlay.
 
-```tsx
-import { EmbeddedAgent } from '@mcp-b/embedded-agent'
+### Web Component (ESM)
 
-import '@mcp-b/embedded-agent/styles'
+```tsx
+import "@mcp-b/embedded-agent/web-component";
 
 function App() {
-	return <EmbeddedAgent appId="your-app-id" />
+  return <webmcp-agent auth-token="eyJhbGciOi..." />;
 }
 ```
 
-### Web Component
+### Monorepo Dogfooding
+
+```tsx
+import "@mcp-b/embedded-agent/web-component";
+
+// authToken from your existing IDP session
+const authToken = session?.idToken ?? "";
+
+useEffect(() => {
+  const agent =
+    document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");
+
+  if (!agent.isConnected) {
+    document.body.appendChild(agent);
+  }
+
+  agent.setAttribute("auth-token", authToken ?? "");
+  agent.setAttribute("dev-mode", JSON.stringify({ useLocalApi: true }));
+  agent.setAttribute("enable-debug-tools", String(import.meta.env.DEV));
+}, [authToken]);
+```
+
+### Script Tag (Any Website)
 
 ```html
 <script src="https://cdn.webmcp.ai/agent.js"></script>
-<webmcp-agent app-id="your-app-id"></webmcp-agent>
+<webmcp-agent auth-token="eyJhbGciOi..."></webmcp-agent>
 ```
 
-That's it. No configuration needed.
+### Web Component Attributes
+
+```html
+<webmcp-agent
+  auth-token="eyJhbGciOi..."
+  dev-mode='{"anthropicApiKey": "sk-ant-..."}'
+  enable-debug-tools="true"
+></webmcp-agent>
+```
+
+## Props / Attributes
+
+| Prop | Attribute | Type | Description |
+|------|-----------|------|-------------|
+| `authToken` | `auth-token` | string | IDP token for stateful sessions (optional; omit for stateless) |
+| `open` | `open` | boolean | Controlled open state (optional) |
+| `devMode` | `dev-mode` | object/JSON | Development mode config (optional) |
+| `enableDebugTools` | `enable-debug-tools` | boolean | Enable debug tools (default: false) |
+
+## Customization
+
+Customize appearance by setting CSS variables on the host page:
+
+```css
+webmcp-agent {
+  /* Brand colors */
+  --wm-color-primary: #8b5cf6;
+  --wm-color-primary-foreground: #ffffff;
+
+  /* Layout */
+  --wm-radius: 12px;
+  --wm-font-sans: 'Inter', sans-serif;
+
+  /* Backgrounds */
+  --wm-color-background: #ffffff;
+  --wm-color-foreground: #1a1a1a;
+  --wm-color-muted: #f5f5f5;
+
+  /* Messages */
+  --wm-user-bubble-bg: #8b5cf6;
+  --wm-user-bubble-text: #ffffff;
+  --wm-assistant-bubble-bg: #f5f5f5;
+  --wm-assistant-bubble-text: #1a1a1a;
+
+  /* Composer */
+  --wm-composer-bg: #ffffff;
+  --wm-composer-border: #e5e5e5;
+  --wm-composer-button-bg: #8b5cf6;
+
+  /* Tools */
+  --wm-tool-bg: #f9fafb;
+  --wm-tool-border: #e5e7eb;
+  --wm-tool-approve-bg: #10b981;
+  --wm-tool-deny-bg: #ef4444;
+
+  /* Code blocks */
+  --wm-code-bg: #1e1e1e;
+  --wm-code-text: #d4d4d4;
+
+  /* Font sizes */
+  --wm-font-size-xs: 0.75rem;
+  --wm-font-size-sm: 0.875rem;
+  --wm-font-size-base: 1rem;
+  --wm-font-size-lg: 1.125rem;
+}
+
+/* Dark mode */
+webmcp-agent.dark {
+  --wm-color-background: #1a1a1a;
+  --wm-color-foreground: #ffffff;
+  --wm-color-muted: #2a2a2a;
+  /* ... other dark mode overrides */
+}
+```
 
 ## Development Mode
 
-During development, use your own API keys to avoid costs:
+Use your own API keys during development (stateless):
 
-```tsx
-<EmbeddedAgent
-	appId="your-app-id"
-	devMode={{
-		anthropicApiKey: 'sk-ant-...', // Required for chat
-		openaiApiKey: 'sk-...', // Optional, enables voice mode
-	}}
-/>
+```html
+<webmcp-agent
+  dev-mode='{"anthropicApiKey":"sk-ant-...","openaiApiKey":"sk-...","useLocalApi":true}'
+></webmcp-agent>
 ```
 
-In production, remove `devMode` to use your WebMCP plan.
+**Development modes:**
+- `anthropicApiKey`: Use your own Anthropic API key (falls back to Gemini if not provided)
+- `openaiApiKey`: Enable voice mode with your OpenAI key
+- `useLocalApi`: Point to localhost instead of production API
+
+Common combinations:
+- `{ useLocalApi: true }` - Internal monorepo development
+- `{ anthropicApiKey: "sk-ant-..." }` - External dev with your own key
+- `{ anthropicApiKey: "...", openaiApiKey: "...", useLocalApi: true }` - Full stack local dev
 
 ## Features
 
 - **MCP Tool Support** - Connect to any MCP server
-- **Voice Mode** - Talk to your AI assistant (requires OpenAI key in dev mode)
-- **Action-First UI** - Shows what the AI is doing, not just typing
-- **Drop-in Widget** - Works like Intercom, just add your app ID
+- **Voice Mode** - Talk to your AI assistant
+- **Action-First UI** - Shows what the AI is doing
+- **Shadow DOM Isolation** - Styles don't leak in or out
+- **Stateful Sessions** - Messages persist across page refreshes (when authToken is provided)
+- **CSS Variable Theming** - Customize appearance without JavaScript
 
-## API Reference
+## Migration Guide
 
-### EmbeddedAgent Props
+### Upgrading from Previous Versions
 
-| Prop      | Type            | Required | Description                               |
-| --------- | --------------- | -------- | ----------------------------------------- |
-| `appId`   | `string`        | Yes      | Your WebMCP app ID (get one at webmcp.ai) |
-| `devMode` | `DevModeConfig` | No       | Development mode with your own API keys   |
+**Removed props:**
+- `apiKey` / `userId` - Replaced by `authToken` (use your existing IDP token)
+- `appId` - No longer needed (removed dead code)
+- `siteId` - Org-level routing in SSO-first mode (no site scoping)
+- `theme` - Use CSS variables instead (see Customization section)
+- `isolateStyles` - Always enabled (Shadow DOM is always used)
+- `disableShadowDOM` - Deprecated (Shadow DOM is always enabled)
 
-### DevModeConfig
+**Migration examples:**
 
-| Property          | Type     | Required | Description                        |
-| ----------------- | -------- | -------- | ---------------------------------- |
-| `anthropicApiKey` | `string` | Yes      | Your Anthropic API key for chat    |
-| `openaiApiKey`    | `string` | No       | Your OpenAI API key for voice mode |
+```html
+<!-- OLD: -->
+<webmcp-agent
+  app-id="app_123"
+  site-id="site_123"
+  api-key="sk_live_xxx"
+  theme='{"primaryColor":"#ff0000","mode":"dark"}'
+  isolate-styles="false"
+></webmcp-agent>
 
-## How It Works
+<!-- NEW (SSO-first): -->
+<webmcp-agent auth-token="eyJhbGciOi..."></webmcp-agent>
 
-The widget connects to WebMCP's infrastructure (Cloudflare Workers) which handles:
+<!-- NEW (stateless): -->
+<webmcp-agent></webmcp-agent>
 
-- Chat completions via Anthropic Claude
-- Voice mode via OpenAI Realtime API
-- MCP tool execution
+<!-- Customize via CSS: -->
+<style>
+  webmcp-agent {
+    --wm-color-primary: #ff0000;
+  }
+  webmcp-agent.dark {
+    --wm-color-background: #1a1a1a;
+  }
+</style>
+```
 
-In development mode, your API keys are used. In production, your WebMCP plan covers the costs.
+**Benefits:**
+- Smaller bundle size (~200 lines removed)
+- Simpler API (fewer required attributes)
+- More flexible styling (CSS variables work everywhere)
+- Consistent Shadow DOM isolation (no edge cases)
+- No API keys to manage (uses existing IDP tokens)
 
 ## Development
 
 ```bash
-pnpm build       # Build the package
-pnpm check:types # Type check
-pnpm check:lint  # Lint
-pnpm test        # Run tests
+pnpm --filter @mcp-b/embedded-agent dev        # Watch TS build
+pnpm --filter @mcp-b/embedded-agent dev:css    # Watch Tailwind CSS
+pnpm --filter @mcp-b/embedded-agent storybook  # http://localhost:6006
+pnpm --filter @mcp-b/embedded-agent build
+pnpm --filter @mcp-b/embedded-agent check:types
+pnpm --filter @mcp-b/embedded-agent test
 ```

package/dist/jsx.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TypeScript JSX type declarations for the webmcp-agent custom element.
+ *
+ * This file provides proper typing for the <webmcp-agent> custom element
+ * when used in React/TypeScript projects.
+ *
+ * @see https://www.totaltypescript.com/workshops/advanced-typescript-patterns/advanced-challenges/custom-jsx-elements
+ * @see https://www.typescriptlang.org/docs/handbook/jsx.html
+ */
+
+import 'react';
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'webmcp-agent': React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement> & {
+          /**
+           * IDP token for SSO-First authentication.
+           * When provided, the agent will authenticate the user and persist threads to the backend.
+           * When omitted, the agent runs in stateless mode (memory-only).
+           */
+          'auth-token'?: string;
+
+          /**
+           * Whether the agent panel should be open by default.
+           */
+          open?: boolean;
+
+          /**
+           * Development mode configuration (JSON string).
+           * Example: JSON.stringify({ useLocalApi: true })
+           */
+          'dev-mode'?: string;
+
+          /**
+           * Enable debug tools panel for development.
+           */
+          'enable-debug-tools'?: boolean;
+        },
+        HTMLElement
+      >;
+    }
+  }
+}