@mcp-b/char 0.0.0-beta-20260124143827

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

@@ -0,0 +1,367 @@
+# @mcp-b/embedded-agent
+
+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 `` 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 |
+
+### Bundle Sizes
+
+| Build | Size | Gzipped | Use Case |
+|-------|------|---------|----------|
+| ESM | ~560 KB | ~115 KB | Bundlers (React externalized) |
+| Standalone IIFE | ~2.2 MB | ~400 KB | Script tag embeds |
+
+The standalone IIFE includes React, so it's larger but works on any website without dependencies.
+
+### 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 ...
+│
+└──
+    └── #shadow-root  ← Isolation boundary
+        └── <div>  ← Bundled React 19
+            └── ... widget ...
+```
+
+## Installation
+
+```bash
+npm install @mcp-b/embedded-agent
+```
+
+## Usage
+
+`` renders as a full-viewport overlay.
+
+### Recommended: Imperative Authentication (Secure)
+
+The `connect()` method is the recommended way to authenticate. It keeps tokens out of DOM attributes, preventing exposure to session replay tools, error reporters, and DOM inspectors.
+
+```tsx
+import { useRef, useEffect } from "react";
+import "@mcp-b/embedded-agent/web-component";
+import type { WebMCPAgentElement } from "@mcp-b/embedded-agent/web-component";
+
+function App() {
+  const { session } = useOktaAuth(); // or Azure, Auth0, Google, etc.
+  const agentRef = useRef<WebMCPAgentElement>(null);
+
+  useEffect(() => {
+    if (agentRef.current && session?.idToken) {
+      agentRef.current.connect({ idToken: session.idToken });
+    }
+  }, [session?.idToken]);
+
+  return <char-agent ref={agentRef} />;
+}
+```
+
+### Vanilla JavaScript
+
+```html
+</char-agent>
+
+<script type="module">
+  import "@mcp-b/embedded-agent/web-component";
+
+  const agent = document.querySelector("char-agent");
+  // Call connect() when you have the token
+  agent.connect({ idToken: "eyJhbGciOi..." });
+</script>
+```
+
+### Monorepo Dogfooding
+
+```tsx
+import { useRef, useEffect } from "react";
+import "@mcp-b/embedded-agent/web-component";
+import type { WebMCPAgentElement } from "@mcp-b/embedded-agent/web-component";
+
+const authToken = session?.idToken ?? "";
+const agentRef = useRef<WebMCPAgentElement>(null);
+
+useEffect(() => {
+  const agent = agentRef.current ?? document.querySelector("char-agent");
+
+  if (!agent) {
+    const newAgent = document.createElement("char-agent");
+    document.body.appendChild(newAgent);
+    // Connect after element is in DOM
+    (newAgent as WebMCPAgentElement).connect({ idToken: authToken });
+  } else if (authToken) {
+    (agent as WebMCPAgentElement).connect({ idToken: authToken });
+  }
+
+  // Set other attributes (these don't contain sensitive data)
+  agent?.setAttribute("dev-mode", JSON.stringify({ useLocalApi: true }));
+  agent?.setAttribute("enable-debug-tools", String(import.meta.env.DEV));
+}, [authToken]);
+
+return <char-agent ref={agentRef} />;
+```
+
+### Script Tag (Any Website)
+
+Use `defer` for best performance - it loads the script without blocking page rendering:
+
+```html
+<!-- Recommended: defer loads async, executes after DOM ready -->
+<script src="https://unpkg.com/@mcp-b/embedded-agent/dist/web-component-standalone.iife.js" defer></script>
+</char-agent>
+
+<script>
+  // Authenticate after the page loads (tokens not in DOM attributes)
+  document.addEventListener('DOMContentLoaded', () => {
+    const agent = document.querySelector('char-agent');
+    // Get your token from your auth provider
+    agent.connect({ idToken: yourIdpToken });
+  });
+</script>
+```
+
+Alternative CDN (jsdelivr):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@mcp-b/embedded-agent/dist/web-component-standalone.iife.js" defer></script>
+```
+
+Pin to a specific version for production:
+
+```html
+<script src="https://unpkg.com/@mcp-b/embedded-agent@1.2.7/dist/web-component-standalone.iife.js" defer></script>
+```
+
+### Web Component Attributes
+
+```html
+<!-- PREFERRED: Use connect() method instead of auth-token attribute -->
+<char-agent
+  dev-mode='{"anthropicApiKey": "sk-ant-..."}'
+  enable-debug-tools="true"
+></char-agent>
+
+<script>
+  const agent = document.querySelector('char-agent');
+  agent.connect({ idToken: 'eyJhbGciOi...' });
+</script>
+```
+
+## Props / Attributes
+
+| Prop | Attribute | Type | Description |
+|------|-----------|------|-------------|
+| - | - | method | `connect({ idToken })` - Secure authentication (token not in DOM) |
+| - | - | method | `connect({ ticketAuth })` - SSR-friendly authentication (pre-fetched ticket) |
+| - | - | method | `disconnect()` - Clear authentication |
+| `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
+char {
+  /* 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 */
+char.dark {
+  --wm-color-background: #1a1a1a;
+  --wm-color-foreground: #ffffff;
+  --wm-color-muted: #2a2a2a;
+  /* ... other dark mode overrides */
+}
+```
+
+## Development Mode
+
+Use your own API keys during development (stateless):
+
+```html
+<char-agent
+  dev-mode='{"anthropicApiKey":"sk-ant-...","openaiApiKey":"sk-...","useLocalApi":true}'
+></char-agent>
+```
+
+**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
+
+## Performance
+
+### Script Loading
+
+Always use `defer` or `async` when embedding the standalone script to avoid blocking page rendering:
+
+```html
+<!-- GOOD: defer - loads in parallel, executes after DOM ready -->
+<script src="https://unpkg.com/@mcp-b/embedded-agent/dist/web-component-standalone.iife.js" defer></script>
+
+<!-- GOOD: async - loads in parallel, executes ASAP -->
+<script src="https://unpkg.com/@mcp-b/embedded-agent/dist/web-component-standalone.iife.js" async></script>
+
+<!-- BAD: blocks page rendering until script loads -->
+<script src="https://unpkg.com/@mcp-b/embedded-agent/dist/web-component-standalone.iife.js"></script>
+```
+
+**When to use which:**
+- `defer` (recommended) - Script executes after HTML is parsed, preserves execution order
+- `async` - Script executes as soon as it loads, good for independent widgets
+
+### Preconnect Hint
+
+Speed up loading by adding a preconnect hint in your `<head>`:
+
+```html
+<link rel="preconnect" href="https://unpkg.com" crossorigin>
+```
+
+## Features
+
+- **MCP Tool Support** - Connect to any MCP server
+- **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
+
+## Migration Guide
+
+### Upgrading from Previous Versions
+
+**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` - Removed (Shadow DOM is always enabled)
+
+**Migration examples:**
+
+```html
+<!-- OLD: -->
+<char-agent
+  app-id="app_123"
+  site-id="site_123"
+  api-key="sk_live_xxx"
+  theme='{"primaryColor":"#ff0000","mode":"dark"}'
+  isolate-styles="false"
+></char-agent>
+
+<!-- NEW (SSO-first with connect method): -->
+</char-agent>
+<script>
+  const agent = document.querySelector('char-agent');
+  agent.connect({ idToken: 'eyJhbGciOi...' });
+</script>
+
+<!-- NEW (anonymous dev mode): -->
+<char-agent dev-mode='{"anthropicApiKey":"sk-ant-..."}'></char-agent>
+
+<!-- Customize via CSS: -->
+<style>
+  char {
+    --wm-color-primary: #ff0000;
+  }
+  char.dark {
+    --wm-color-background: #1a1a1a;
+  }
+</style>
+```
+
+**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 --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
+```