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

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

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 (16) hide show

package/.docs/organized/code-examples/store-example.md +554 -0
package/.docs/organized/code-examples/with-ag-ui.md +582 -32
package/.docs/organized/code-examples/with-ai-sdk-v5.md +549 -47
package/.docs/organized/code-examples/with-assistant-transport.md +547 -46
package/.docs/organized/code-examples/with-cloud.md +634 -39
package/.docs/organized/code-examples/with-external-store.md +581 -31
package/.docs/organized/code-examples/with-ffmpeg.md +581 -47
package/.docs/organized/code-examples/with-langgraph.md +633 -50
package/.docs/organized/code-examples/with-parent-id-grouping.md +581 -31
package/.docs/organized/code-examples/with-react-hook-form.md +582 -70
package/.docs/raw/blog/2024-07-29-hello/index.mdx +0 -1
package/.docs/raw/docs/cli.mdx +396 -0
package/.docs/raw/docs/getting-started.mdx +31 -37
package/.docs/raw/docs/runtimes/assistant-transport.mdx +891 -0
package/.docs/raw/docs/runtimes/langgraph/index.mdx +1 -1
package/package.json +13 -5

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

@@ -0,0 +1,554 @@
+# 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 text-4xl font-bold text-gray-900 dark:text-white">
+            @assistant-ui/store Example
+          </h1>
+          <p className="text-lg text-gray-600 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 {
+  useAssistantClient,
+  AssistantProvider,
+  useAssistantState,
+} from "@assistant-ui/store";
+import { FooList, FooListResource } from "./store/foo-store";
+import "./store/foo-scope"; // Register the fooList scope (demonstrates scope registry)
+/**
+ * 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="text-sm font-semibold text-gray-500 dark:text-gray-400">
+            ID:
+          </span>
+          <span className="font-mono text-sm text-gray-900 dark:text-white">
+            {fooState.id}
+          </span>
+        </div>
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-semibold text-gray-500 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:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:outline-none 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:ring-2 focus:ring-red-500 focus:ring-offset-2 focus:outline-none 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:ring-2 focus:ring-green-500 focus:ring-offset-2 focus:outline-none dark:focus:ring-offset-gray-800"
+    >
+      Add New
+    </button>
+  );
+};
+/**
+ * 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="text-xl font-semibold text-gray-900 dark:text-white">
+              Foo List <FooListLength />
+            </h2>
+            <AddFooButton />
+          </div>
+          <p className="mt-1 text-sm text-gray-600 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>
+      </div>
+    </AssistantProvider>
+  );
+};
+```
+## lib/store/foo-scope.ts
+```typescript
+/**
+ * Scope registration for the foo example
+ * Import this file to register the default fooList scope
+ */
+import { registerAssistantScope } from "@assistant-ui/store";
+/**
+ * Define scopes via module augmentation
+ * Implement the scope definition raw without importing ScopeDefinition
+ */
+declare module "@assistant-ui/store" {
+  interface AssistantScopeRegistry {
+    foo: {
+      value: {
+        getState: () => { id: string; bar: string };
+        updateBar: (newBar: string) => void;
+        remove: () => void;
+      };
+      source: "fooList";
+      query: { index: number } | { id: string };
+    };
+    fooList: {
+      value: {
+        getState: () => { foos: Array<{ id: string; bar: string }> };
+        foo: (
+          lookup: { index: number } | { id: string },
+        ) => AssistantScopeRegistry["foo"]["value"];
+        addFoo: (id?: string) => void;
+      };
+      source: "root";
+      query: Record<string, never>;
+    };
+  }
+}
+// Register the fooList scope with a default implementation
+registerAssistantScope({
+  name: "fooList",
+  defaultInitialize: { error: "FooList is not configured" },
+});
+```
+## lib/store/foo-store.tsx
+```tsx
+"use client";
+import React from "react";
+import { resource, tapState } from "@assistant-ui/tap";
+import {
+  useAssistantClient,
+  AssistantProvider,
+  tapApi,
+  tapStoreList,
+  DerivedScope,
+  useAssistantState,
+} from "@assistant-ui/store";
+/**
+ * Single Foo item resource
+ * Manages the state and actions for a single foo item
+ */
+export const FooItemResource = resource(
+  ({
+    initialValue: { id, initialBar },
+    remove,
+  }: {
+    initialValue: { id: string; initialBar: string };
+    remove: () => void;
+  }) => {
+    const [state, setState] = tapState<{ id: string; bar: string }>({
+      id,
+      bar: initialBar,
+    });
+    const updateBar = (newBar: string) => {
+      setState({ ...state, bar: newBar });
+    };
+    return tapApi(
+      {
+        getState: () => state,
+        updateBar,
+        remove,
+      },
+      { key: id },
+    );
+  },
+);
+/**
+ * FooList resource implementation
+ * Manages a list of foos using tapStoreList
+ */
+let counter = 3;
+export const FooListResource = resource(() => {
+  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,
+  });
+  return tapApi({
+    getState: () => ({ foos: foos.state }),
+    foo: foos.api,
+    addFoo: (id?: string) => foos.add(id),
+  });
+});
+/**
+ * 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",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@assistant-ui/store": "workspace:*",
+    "@assistant-ui/tap": "workspace:*",
+    "next": "16.0.4",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^24",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "eslint": "^9",
+    "eslint-config-next": "16.0.4",
+    "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"]
+}
+```