npm - @assistant-ui/mcp-docs-server - Versions diffs - 0.1.14 → 0.1.16 - Mend

@assistant-ui/mcp-docs-server 0.1.14 → 0.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

package/.docs/organized/code-examples/store-example.md +628 -0
package/.docs/organized/code-examples/with-ag-ui.md +792 -178
package/.docs/organized/code-examples/with-ai-sdk-v5.md +762 -209
package/.docs/organized/code-examples/with-assistant-transport.md +707 -254
package/.docs/organized/code-examples/with-cloud.md +848 -202
package/.docs/organized/code-examples/with-custom-thread-list.md +1855 -0
package/.docs/organized/code-examples/with-external-store.md +788 -172
package/.docs/organized/code-examples/with-ffmpeg.md +796 -196
package/.docs/organized/code-examples/with-langgraph.md +864 -230
package/.docs/organized/code-examples/with-parent-id-grouping.md +785 -255
package/.docs/organized/code-examples/with-react-hook-form.md +804 -226
package/.docs/organized/code-examples/with-tanstack.md +1574 -0
package/.docs/raw/blog/2024-07-29-hello/index.mdx +2 -3
package/.docs/raw/docs/api-reference/overview.mdx +6 -6
package/.docs/raw/docs/api-reference/primitives/ActionBar.mdx +85 -4
package/.docs/raw/docs/api-reference/primitives/AssistantIf.mdx +200 -0
package/.docs/raw/docs/api-reference/primitives/Composer.mdx +0 -20
package/.docs/raw/docs/api-reference/primitives/Message.mdx +0 -45
package/.docs/raw/docs/api-reference/primitives/Thread.mdx +0 -50
package/.docs/raw/docs/cli.mdx +396 -0
package/.docs/raw/docs/cloud/persistence/ai-sdk.mdx +2 -3
package/.docs/raw/docs/cloud/persistence/langgraph.mdx +2 -3
package/.docs/raw/docs/devtools.mdx +2 -3
package/.docs/raw/docs/getting-started.mdx +37 -1109
package/.docs/raw/docs/guides/Attachments.mdx +3 -25
package/.docs/raw/docs/guides/Branching.mdx +1 -1
package/.docs/raw/docs/guides/Speech.mdx +1 -1
package/.docs/raw/docs/guides/ToolUI.mdx +1 -1
package/.docs/raw/docs/legacy/styled/AssistantModal.mdx +2 -3
package/.docs/raw/docs/legacy/styled/Decomposition.mdx +6 -5
package/.docs/raw/docs/legacy/styled/Markdown.mdx +2 -3
package/.docs/raw/docs/legacy/styled/Thread.mdx +2 -3
package/.docs/raw/docs/react-compatibility.mdx +2 -5
package/.docs/raw/docs/runtimes/ai-sdk/use-chat.mdx +3 -4
package/.docs/raw/docs/runtimes/ai-sdk/v4-legacy.mdx +3 -6
package/.docs/raw/docs/runtimes/assistant-transport.mdx +891 -0
package/.docs/raw/docs/runtimes/custom/external-store.mdx +2 -3
package/.docs/raw/docs/runtimes/custom/local.mdx +11 -41
package/.docs/raw/docs/runtimes/data-stream.mdx +15 -11
package/.docs/raw/docs/runtimes/langgraph/index.mdx +4 -4
package/.docs/raw/docs/runtimes/langgraph/tutorial/part-2.mdx +1 -1
package/.docs/raw/docs/runtimes/langgraph/tutorial/part-3.mdx +2 -3
package/.docs/raw/docs/runtimes/langserve.mdx +2 -3
package/.docs/raw/docs/runtimes/mastra/full-stack-integration.mdx +2 -3
package/.docs/raw/docs/runtimes/mastra/separate-server-integration.mdx +2 -3
package/.docs/raw/docs/ui/AssistantModal.mdx +3 -25
package/.docs/raw/docs/ui/AssistantSidebar.mdx +2 -24
package/.docs/raw/docs/ui/Attachment.mdx +3 -25
package/.docs/raw/docs/ui/Markdown.mdx +2 -24
package/.docs/raw/docs/ui/Mermaid.mdx +2 -24
package/.docs/raw/docs/ui/Reasoning.mdx +2 -24
package/.docs/raw/docs/ui/Scrollbar.mdx +4 -6
package/.docs/raw/docs/ui/SyntaxHighlighting.mdx +3 -47
package/.docs/raw/docs/ui/Thread.mdx +38 -53
package/.docs/raw/docs/ui/ThreadList.mdx +4 -47
package/.docs/raw/docs/ui/ToolFallback.mdx +2 -24
package/package.json +15 -8

package/.docs/organized/code-examples/store-example.md ADDED Viewed

@@ -0,0 +1,628 @@
+# Example: store-example
+## app/globals.css
+```css
+@import "tailwindcss";
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: Arial, Helvetica, sans-serif;
+}
+```
+## app/layout.tsx
+```tsx
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+export const metadata: Metadata = {
+  title: "Create Next App",
+  description: "Generated by create next app",
+};
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body
+        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+      >
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+## app/page.tsx
+```tsx
+import { ExampleApp } from "@/lib/example-app";
+export default function Home() {
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-gray-50 to-gray-100 p-8 dark:from-gray-900 dark:to-gray-800">
+      <div className="mx-auto max-w-4xl">
+        <div className="mb-8">
+          <h1 className="mb-2 font-bold text-4xl text-gray-900 dark:text-white">
+            @assistant-ui/store Example
+          </h1>
+          <p className="text-gray-600 text-lg dark:text-gray-400">
+            Demonstrating tap-based state management with scopes, lists, and
+            providers
+          </p>
+        </div>
+        <ExampleApp />
+      </div>
+    </div>
+  );
+}
+```
+## lib/example-app.tsx
+```tsx
+"use client";
+import { useState } from "react";
+import {
+  useAssistantClient,
+  AssistantProvider,
+  useAssistantState,
+  useAssistantEvent,
+} from "@assistant-ui/store";
+import { FooList, FooListResource } from "./store/foo-store";
+/**
+ * Single Foo component - displays and allows editing a single foo
+ */
+const Foo = () => {
+  const aui = useAssistantClient();
+  const fooState = useAssistantState(({ foo }) => {
+    console.log("selector called with state", foo);
+    return foo;
+  });
+  const handleUpdate = () => {
+    aui.foo().updateBar(`Updated at ${new Date().toLocaleTimeString()}`);
+    console.log("Foo state", aui.foo().getState(), fooState);
+  };
+  return (
+    <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-md transition-shadow hover:shadow-lg dark:border-gray-700 dark:bg-gray-800">
+      <div className="space-y-3">
+        <div className="flex items-center gap-2">
+          <span className="font-semibold text-gray-500 text-sm dark:text-gray-400">
+            ID:
+          </span>
+          <span className="font-mono text-gray-900 text-sm dark:text-white">
+            {fooState.id}
+          </span>
+        </div>
+        <div className="flex items-center gap-2">
+          <span className="font-semibold text-gray-500 text-sm dark:text-gray-400">
+            Value:
+          </span>
+          <span className="text-gray-900 dark:text-white">{fooState.bar}</span>
+        </div>
+        <div className="mt-2 flex gap-2">
+          <button
+            onClick={handleUpdate}
+            className="flex-1 rounded-md bg-blue-600 px-4 py-2 font-medium text-white transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-800"
+          >
+            Update
+          </button>
+          <button
+            onClick={() => aui.foo().remove()}
+            className="rounded-md bg-red-600 px-4 py-2 font-medium text-white transition-colors hover:bg-red-700 focus:outline-none focus:ring-2 focus:ring-red-500 focus:ring-offset-2 dark:focus:ring-offset-gray-800"
+          >
+            Delete
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};
+const FooListLength = () => {
+  const fooListLength = useAssistantState(({ fooList }) => fooList.foos.length);
+  return (
+    <span className="text-gray-500 dark:text-gray-400">
+      ({fooListLength} items)
+    </span>
+  );
+};
+const AddFooButton = () => {
+  const aui = useAssistantClient();
+  return (
+    <button
+      onClick={() => aui.fooList().addFoo()}
+      className="rounded-md bg-green-600 px-4 py-2 font-medium text-white transition-colors hover:bg-green-700 focus:outline-none focus:ring-2 focus:ring-green-500 focus:ring-offset-2 dark:focus:ring-offset-gray-800"
+    >
+      Add New
+    </button>
+  );
+};
+type EventLogEntry = {
+  id: number;
+  event: string;
+  payload: unknown;
+  timestamp: Date;
+};
+let idCounter = 0;
+/**
+ * EventLog component - demonstrates event subscription
+ */
+const EventLog = () => {
+  const [logs, setLogs] = useState<EventLogEntry[]>([]);
+  // Subscribe to all events using the wildcard selector
+  useAssistantEvent("*", (data) => {
+    setLogs((prev) => [
+      {
+        id: ++idCounter,
+        event: data.event,
+        payload: data.payload,
+        timestamp: new Date(),
+      },
+      ...prev.slice(0, 9), // Keep last 10 entries
+    ]);
+  });
+  return (
+    <div className="rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-700 dark:bg-gray-800">
+      <h3 className="mb-3 font-semibold text-gray-900 dark:text-white">
+        Event Log
+      </h3>
+      <div className="max-h-48 space-y-2 overflow-y-auto">
+        {logs.length === 0 ? (
+          <p className="text-gray-500 text-sm dark:text-gray-400">
+            No events yet. Try updating or deleting a foo.
+          </p>
+        ) : (
+          logs.map((log) => (
+            <div
+              key={log.id}
+              className="rounded border border-gray-100 bg-gray-50 p-2 font-mono text-xs dark:border-gray-600 dark:bg-gray-700"
+            >
+              <span className="font-semibold text-blue-600 dark:text-blue-400">
+                {log.event}
+              </span>
+              <span className="ml-2 text-gray-600 dark:text-gray-300">
+                {JSON.stringify(log.payload)}
+              </span>
+              <span className="ml-2 text-gray-400 dark:text-gray-500">
+                {log.timestamp.toLocaleTimeString()}
+              </span>
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+};
+/**
+ * Example App - demonstrates the store with styled components
+ *
+ * Note: The fooList scope is also registered in foo-scope.ts as a default,
+ * but we're explicitly passing it here for clarity in the example.
+ */
+export const ExampleApp = () => {
+  const rootClient = useAssistantClient({
+    fooList: FooListResource(),
+  });
+  return (
+    <AssistantProvider client={rootClient}>
+      <div className="space-y-6">
+        <div className="rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-700 dark:bg-gray-800">
+          <div className="flex items-center justify-between">
+            <h2 className="font-semibold text-gray-900 text-xl dark:text-white">
+              Foo List <FooListLength />
+            </h2>
+            <AddFooButton />
+          </div>
+          <p className="mt-1 text-gray-600 text-sm dark:text-gray-400">
+            Each item is rendered in its own FooProvider with scoped access
+          </p>
+        </div>
+        <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+          <FooList components={{ Foo }} />
+        </div>
+        <EventLog />
+      </div>
+    </AssistantProvider>
+  );
+};
+```
+## lib/store/foo-scope.ts
+```typescript
+import { registerAssistantScope } from "@assistant-ui/store";
+declare module "@assistant-ui/store" {
+  interface AssistantScopeRegistry {
+    foo: {
+      value: {
+        getState: () => { id: string; bar: string };
+        updateBar: (newBar: string) => void;
+        remove: () => void;
+      };
+      meta: { source: "fooList"; query: { index: number } | { id: string } };
+      events: {
+        "foo.updated": { id: string; newValue: string };
+        "foo.removed": { id: string };
+      };
+    };
+    fooList: {
+      value: {
+        getState: () => { foos: Array<{ id: string; bar: string }> };
+        foo: (
+          lookup: { index: number } | { id: string },
+        ) => AssistantScopeRegistry["foo"]["value"];
+        addFoo: (id?: string) => void;
+      };
+      meta: { source: "root"; query: Record<string, never> };
+      events: {
+        "fooList.added": { id: string };
+      };
+    };
+  }
+}
+registerAssistantScope({
+  name: "fooList",
+  defaultInitialize: { error: "FooList is not configured" },
+});
+registerAssistantScope({
+  name: "foo",
+  defaultInitialize: { error: "Foo is not configured" },
+});
+```
+## lib/store/foo-store.tsx
+```tsx
+"use client";
+// Import scope types first to ensure module augmentation is available
+import "./foo-scope";
+import React from "react";
+import { resource, tapState } from "@assistant-ui/tap";
+import {
+  useAssistantClient,
+  AssistantProvider,
+  tapApi,
+  tapStoreList,
+  DerivedScope,
+  useAssistantState,
+  tapStoreContext,
+} from "@assistant-ui/store";
+export const FooItemResource = resource(
+  ({
+    initialValue: { id, initialBar },
+    remove,
+  }: {
+    initialValue: { id: string; initialBar: string };
+    remove: () => void;
+  }) => {
+    const { events } = tapStoreContext();
+    const [state, setState] = tapState<{ id: string; bar: string }>({
+      id,
+      bar: initialBar,
+    });
+    const updateBar = (newBar: string) => {
+      setState({ ...state, bar: newBar });
+      events.emit("foo.updated", { id, newValue: newBar });
+    };
+    const handleRemove = () => {
+      events.emit("foo.removed", { id });
+      remove();
+    };
+    return tapApi(
+      {
+        getState: () => state,
+        updateBar,
+        remove: handleRemove,
+      },
+      { key: id },
+    );
+  },
+);
+/**
+ * FooList resource implementation
+ * Manages a list of foos using tapStoreList
+ */
+let counter = 3;
+export const FooListResource = resource(() => {
+  const { events } = tapStoreContext();
+  const idGenerator = () => `foo-${++counter}`;
+  const foos = tapStoreList({
+    initialValues: [
+      { id: "foo-1", initialBar: "First Foo" },
+      { id: "foo-2", initialBar: "Second Foo" },
+      { id: "foo-3", initialBar: "Third Foo" },
+    ],
+    resource: FooItemResource,
+    idGenerator,
+  });
+  const addFoo = (id?: string) => {
+    const newId = id ?? idGenerator();
+    foos.add(newId);
+    events.emit("fooList.added", { id: newId });
+  };
+  return tapApi({
+    getState: () => ({ foos: foos.state }),
+    foo: foos.api,
+    addFoo,
+  });
+});
+/**
+ * FooProvider - Provides foo scope for a specific index
+ */
+export const FooProvider = ({
+  index,
+  children,
+}: {
+  index: number;
+  children: React.ReactNode;
+}) => {
+  // Create a derived client with the foo scope at the specified index
+  const aui = useAssistantClient({
+    foo: DerivedScope({
+      source: "fooList",
+      query: { index },
+      get: (aui) => aui.fooList().foo({ index }),
+    }),
+  });
+  return <AssistantProvider client={aui}>{children}</AssistantProvider>;
+};
+/**
+ * FooList component - minimal mapping component
+ * Maps over the list and renders each item in a FooProvider
+ */
+export const FooList = ({
+  components,
+}: {
+  components: { Foo: React.ComponentType };
+}) => {
+  const fooListState = useAssistantState(({ fooList }) => fooList.foos.length);
+  return (
+    <>
+      {Array.from({ length: fooListState }, (_, index) => (
+        <FooProvider key={index} index={index}>
+          <components.Foo />
+        </FooProvider>
+      ))}
+    </>
+  );
+};
+```
+## next.config.ts
+```typescript
+import type { NextConfig } from "next";
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+export default nextConfig;
+```
+## package.json
+```json
+{
+  "name": "store-example",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@assistant-ui/store": "workspace:*",
+    "@assistant-ui/tap": "workspace:*",
+    "next": "16.0.7",
+    "react": "19.2.1",
+    "react-dom": "19.2.1"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^24",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}
+```
+## README.md
+```markdown
+# @assistant-ui/store Example App
+This is a Next.js application demonstrating the `@assistant-ui/store` package.
+## Features Demonstrated
+- **Scope Definition**: Module augmentation for type-safe scopes
+- **tapApi**: Wrapping API objects for stability and reactivity
+- **tapLookupResources**: Managing lists with index and ID lookup
+- **Provider Pattern**: Scoped access to list items via FooProvider
+- **Component Composition**: Render props pattern with components prop
+## Getting Started
+```bash
+# Install dependencies (from monorepo root)
+pnpm install
+# Run the development server
+cd examples/store-example
+pnpm dev
+```
+Open [http://localhost:3000](http://localhost:3000) to see the example.
+## Project Structure
+- `lib/store/foo-store.tsx` - Clean store implementation with:
+  - Scope definitions (foo, fooList) via module augmentation
+  - Resource implementations (FooItemResource, FooListResource)
+  - Provider component (FooProvider)
+  - Minimal FooList mapping component
+- `lib/example-app.tsx` - Example app with styled components:
+  - Styled Foo component
+  - ExampleApp with layout and styling
+- `app/page.tsx` - Main page that renders the ExampleApp
+## Key Concepts
+### Scope Definition
+```typescript
+declare module "@assistant-ui/store" {
+  namespace AssistantStore {
+    interface Scopes {
+      foo: {
+        value: {
+          getState: () => { id: string; bar: string };
+          updateBar: (newBar: string) => void;
+        };
+        source: "fooList";
+        query: { index: number } | { id: string };
+      };
+    }
+  }
+}
+```
+### Resource Implementation
+```typescript
+const FooListResource = resource(() => {
+  const items = [
+    /* ... */
+  ];
+  const foos = tapLookupResources(
+    items.map((item) => FooItemResource(item, { key: item.id })),
+  );
+  return tapApi({
+    getState: () => ({ foos: foos.state }),
+    foo: foos.api,
+  });
+});
+```
+### Provider Pattern
+```typescript
+const FooProvider = ({ index, children }) => {
+  const parentAui = useAssistantClient();
+  const aui = useAssistantClient({
+    foo: resource(() => parentAui.fooList().foo({ index }))(),
+  });
+  return <AssistantClientProvider client={aui}>{children}</AssistantClientProvider>;
+};
+```
+## Learn More
+- [@assistant-ui/store Documentation](../store/README.md)
+- [Next.js Documentation](https://nextjs.org/docs)
+```
+## tsconfig.json
+```json
+{
+  "extends": "@assistant-ui/x-buildutils/ts/base",
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"],
+      "@assistant-ui/*": ["../../packages/*/src"],
+      "@assistant-ui/react/*": ["../../packages/react/src/*"],
+      "@assistant-ui/tap/*": ["../../packages/tap/src/*"],
+      "assistant-stream": ["../../packages/assistant-stream/src"],
+      "assistant-stream/*": ["../../packages/assistant-stream/src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+```