aui-mcp-server 0.0.1

package/src/cli.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+import chokidar from 'chokidar';
+
+import { buildCatalogFromStats } from './catalog/build';
+import { generateAuiMcpAssets } from './generator';
+import type { AuiXCatalog, MfStats } from './types';
+import { serveAuiMcpServer, type TransportType } from './server';
+
+function getArg(flag: string): string | undefined {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) return undefined;
+  return process.argv[idx + 1];
+}
+
+function hasFlag(flag: string): boolean {
+  return process.argv.includes(flag);
+}
+
+function getTransportType(): TransportType {
+  const v = getArg('--transport') ?? process.env['AUI_MCP_TRANSPORT'];
+  return v === 'sse' ? 'sse' : 'stdio';
+}
+
+function getPort(): number {
+  const v = getArg('--port') ?? process.env['AUI_MCP_PORT'];
+  return v ? Number(v) : 8001;
+}
+
+function printHelp(): void {
+  console.log(`aui-mcp (from aui-mcp-server)
+
+Commands:
+  aui-mcp catalog <mf-stats...>  Generate aui-x-catalog.json
+  aui-mcp generate [options]     Generate dist/mcp assets
+  aui-mcp serve [options]        Start MCP server (stdio or SSE)
+  aui-mcp dev [options]          Generate then start server (watch)
+
+Catalog options:
+  -o, --output <path>    Output file (default: aui-x-catalog.json)
+  --dry-run              Print output to stdout
+  -v, --verbose          Verbose logs
+
+Common options:
+  --catalog <path>       Path to aui-x-catalog.json (default: aui-x-catalog.json)
+  --outDir <dir>         Remote dist directory (default: dist)
+  --mcpDirname <name>    Subdir under outDir (default: mcp)
+
+Generate options:
+  --noServer             Only emit manifest.json
+
+Serve options:
+  --manifest <path>      Path to manifest.json (default: dist/mcp/manifest.json)
+  --watch                Enable hot reload (manifest/catalog)
+  --transport <type>     stdio|sse (default: stdio; env: AUI_MCP_TRANSPORT)
+  --port <number>        SSE port (default: 8001; env: AUI_MCP_PORT)
+
+Dev options:
+  --noAutoGenerate       Do not re-generate when catalog changes
+`);
+}
+
+function readCompiledTypesFromDist(distDir: string, componentName: string): string | undefined {
+  const dtsPath = path.join(distDir, '@mf-types', 'compiled-types', `${componentName}.d.ts`);
+  if (!fs.existsSync(dtsPath)) return undefined;
+  return fs.readFileSync(dtsPath, 'utf-8');
+}
+
+interface CatalogCliOptions {
+  statsFiles: string[];
+  output: string;
+  dryRun: boolean;
+  verbose: boolean;
+}
+
+function parseCatalogArgs(argv: string[]): CatalogCliOptions {
+  const args = argv.slice(3);
+  const opts: CatalogCliOptions = {
+    statsFiles: [],
+    output: 'aui-x-catalog.json',
+    dryRun: false,
+    verbose: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a) continue;
+
+    if (a === '-o' || a === '--output') {
+      opts.output = args[++i] ?? opts.output;
+      continue;
+    }
+
+    if (a === '--dry-run') {
+      opts.dryRun = true;
+      continue;
+    }
+
+    if (a === '--verbose' || a === '-v') {
+      opts.verbose = true;
+      continue;
+    }
+
+    if (!a.startsWith('-')) {
+      opts.statsFiles.push(a);
+    }
+  }
+
+  return opts;
+}
+
+async function cmdCatalog(): Promise<void> {
+  const opts = parseCatalogArgs(process.argv);
+
+  if (opts.statsFiles.length === 0) {
+    console.error('Usage: aui-mcp catalog [options] <mf-stats.json...>');
+    console.error('Example: aui-mcp catalog ./dist/mf-stats.json -o ./aui-x-catalog.json');
+    process.exitCode = 1;
+    return;
+  }
+
+  const catalog: AuiXCatalog = {};
+  let hasErrors = false;
+
+  for (const statsFile of opts.statsFiles) {
+    const absFile = path.resolve(process.cwd(), statsFile);
+
+    if (!fs.existsSync(absFile)) {
+      console.error(`[aui-mcp] Cannot find mf-stats.json: ${absFile}`);
+      hasErrors = true;
+      continue;
+    }
+
+    let stats: MfStats;
+    try {
+      stats = JSON.parse(fs.readFileSync(absFile, 'utf-8')) as MfStats;
+    } catch (e) {
+      console.error(`[aui-mcp] Failed to parse mf-stats.json: ${absFile}`);
+      console.error(e);
+      hasErrors = true;
+      continue;
+    }
+
+    const distDir = path.dirname(absFile);
+
+    const result = buildCatalogFromStats({
+      stats,
+      readCompiledTypes: (componentName) => readCompiledTypesFromDist(distDir, componentName),
+    });
+
+    for (const [name, entry] of Object.entries(result.catalog)) {
+      catalog[name] = entry;
+    }
+
+    for (const issue of result.issues) {
+      console.warn(
+        `[aui-mcp] ⚠ ${issue.componentName ?? 'unknown'}: ${issue.message}${issue.detail ? ` (${issue.detail})` : ''}`
+      );
+      hasErrors = true;
+    }
+
+    if (result.missingJsdocComponents.length > 0) {
+      const names = result.missingJsdocComponents.join(', ');
+      console.warn(
+        `[aui-mcp] ⚠ Missing @aui-component JSDoc: ${names}. Please run skills/aui-jsdoc-gen to write back to source files and retry.`
+      );
+      hasErrors = true;
+    }
+  }
+
+  if (Object.keys(catalog).length === 0) {
+    console.error('[aui-mcp] No catalog entries were generated successfully.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const outputJson = JSON.stringify(catalog, null, 2) + '\n';
+
+  if (opts.dryRun) {
+    console.log(outputJson);
+    return;
+  }
+
+  const outPath = path.resolve(process.cwd(), opts.output);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, outputJson, 'utf-8');
+  console.log(`[aui-mcp] Written: ${outPath}`);
+
+  if (hasErrors) {
+    console.warn(
+      '[aui-mcp] Some components failed to generate catalog entries (see warnings above), but partial output has been written.'
+    );
+  }
+}
+
+async function cmdGenerate(): Promise<void> {
+  const outDir = getArg('--outDir') ?? 'dist';
+  const catalogPath = getArg('--catalog') ?? 'aui-x-catalog.json';
+  const mcpDirname = getArg('--mcpDirname');
+  const emitServer = !hasFlag('--noServer');
+
+  const result = await generateAuiMcpAssets({
+    outDir,
+    catalogPath: path.resolve(process.cwd(), catalogPath),
+    mcpDirname,
+    emitServer,
+  });
+
+  console.log(`Generated: ${result.manifestPath}`);
+  if (result.serverPath) {
+    console.log(`Generated: ${result.serverPath}`);
+  }
+
+  // dev shortcut: generate then serve
+  if (hasFlag('--dev')) {
+    const manifestPath = result.manifestPath;
+    await serveAuiMcpServer({
+      manifestPath,
+      watch: true,
+      transport: getTransportType(),
+      port: getPort(),
+    });
+  }
+}
+
+async function cmdServe(): Promise<void> {
+  const outDir = getArg('--outDir') ?? 'dist';
+  const mcpDirname = getArg('--mcpDirname') ?? 'mcp';
+
+  const catalogPath = getArg('--catalog') ?? 'aui-x-catalog.json';
+  const manifestPath =
+    getArg('--manifest') ?? path.join(outDir, mcpDirname, 'manifest.json');
+
+  // If user explicitly sets --catalog, use it.
+  // Otherwise default to manifest.json if it exists.
+  const useCatalog = hasFlag('--catalog');
+
+  await serveAuiMcpServer({
+    catalogPath: useCatalog ? path.resolve(process.cwd(), catalogPath) : undefined,
+    manifestPath: useCatalog ? undefined : path.resolve(process.cwd(), manifestPath),
+    watch: hasFlag('--watch') || Boolean(process.env['AUI_MCP_WATCH']),
+    transport: getTransportType(),
+    port: getPort(),
+  });
+}
+
+async function cmdDev(): Promise<void> {
+  const outDir = getArg('--outDir') ?? 'dist';
+  const catalogPath = path.resolve(process.cwd(), getArg('--catalog') ?? 'aui-x-catalog.json');
+  const mcpDirname = getArg('--mcpDirname') ?? 'mcp';
+
+  const enableAutoGenerate = !hasFlag('--noAutoGenerate');
+
+  const result = await generateAuiMcpAssets({ outDir, catalogPath, mcpDirname, emitServer: true });
+
+  if (enableAutoGenerate) {
+    chokidar
+      .watch(catalogPath, { ignoreInitial: true })
+      .on('change', async () => {
+        try {
+          await generateAuiMcpAssets({ outDir, catalogPath, mcpDirname, emitServer: true });
+          // eslint-disable-next-line no-console
+          console.error(`[aui-mcp] regenerated from ${catalogPath}`);
+        } catch (err) {
+          // eslint-disable-next-line no-console
+          console.error('[aui-mcp] regenerate failed:', err);
+        }
+      });
+  }
+
+  await serveAuiMcpServer({
+    manifestPath: result.manifestPath,
+    watch: true,
+    transport: getTransportType(),
+    port: getPort(),
+  });
+}
+
+async function main(): Promise<void> {
+  const cmd = process.argv[2];
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (cmd === 'catalog') {
+    await cmdCatalog();
+    return;
+  }
+
+  if (cmd === 'generate') {
+    await cmdGenerate();
+    return;
+  }
+
+  if (cmd === 'serve') {
+    await cmdServe();
+    return;
+  }
+
+  if (cmd === 'dev') {
+    await cmdDev();
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  printHelp();
+  process.exitCode = 1;
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/src/client/handshake.ts

@@ -0,0 +1,166 @@
+import type { ComponentRegistry } from '@a2ui/react';
+import type { ServerToClientMessage } from '@a2ui/react';
+import { logger } from './useLogger';
+import { createMFRegistry, syncRegistryFromCatalog } from './registry';
+import type { ToolCallPayload } from './types';
+import { A2UI_EXTENSION_URI } from './types';
+
+interface A2UIValue {
+  literalString?: string;
+  path?: string;
+}
+
+/** Convert any input into an A2UI literalString value object. */
+function toLiteralStringValue(value: unknown): A2UIValue | undefined {
+  if (value === undefined || value === null) return undefined;
+
+  if (typeof value === 'string') {
+    return { literalString: value };
+  }
+
+  if (typeof value === 'object') {
+    const obj = value as Partial<A2UIValue>;
+    if (typeof obj.literalString === 'string' || typeof obj.path === 'string') {
+      return {
+        ...(obj.literalString ? { literalString: obj.literalString } : {}),
+        ...(obj.path ? { path: obj.path } : {}),
+      };
+    }
+  }
+
+  return { literalString: String(value) };
+}
+
+/**
+ * A2A handshake:
+ * - Fetch AgentCard from `{agentUrl}/agent-card`
+ * - Parse `inlineCatalogs` from `capabilities.extensions`
+ * - Auto-register MF components via `syncRegistryFromCatalog()`
+ */
+export async function performHandshake(
+  agentUrl: string,
+  registry?: ComponentRegistry,
+): Promise<Record<string, unknown>> {
+  try {
+    const base = agentUrl.replace(/\/$/, '');
+    const handshakeUrl = base.endsWith('/agent-card') ? base : `${base}/agent-card`;
+
+    const response = await fetch(handshakeUrl);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch AgentCard from ${handshakeUrl}: ${response.statusText}`);
+    }
+
+    const agentCard = await response.json();
+
+    const a2uiExt = agentCard.capabilities?.extensions?.find(
+      (ext: any) => ext.uri === A2UI_EXTENSION_URI,
+    );
+
+    if (!a2uiExt || !a2uiExt.params?.inlineCatalogs) {
+      logger.warn('[AUI-X] No inlineCatalogs found in AgentCard. Handshake skipped.');
+      return {};
+    }
+
+    const catalogs = a2uiExt.params.inlineCatalogs as Array<{
+      id?: string;
+      components?: Record<string, unknown>;
+    }>;
+
+    const allComponents: Record<string, unknown> = {};
+    const effectiveRegistry = registry ?? createMFRegistry();
+
+    catalogs.forEach((cat) => {
+      if (!cat.components) return;
+      const count = Object.keys(cat.components).length;
+      logger.info(
+        `[AUI-X] Found catalog "${cat.id ?? 'inline'}", syncing ${count} components from handshake`,
+      );
+      Object.assign(allComponents, cat.components);
+      syncRegistryFromCatalog(effectiveRegistry, cat.components);
+    });
+
+    return allComponents;
+  } catch (error) {
+    logger.error('[AUI-X] Handshake error:', error);
+    return {};
+  }
+}
+
+/**
+ * Generic renderer: map a tool call to A2UI messages based on the Catalog schema.
+ */
+export function render(
+  toolCall: ToolCallPayload,
+  catalog: Record<string, any>,
+): ServerToClientMessage[] {
+  const { tool_name, tool_input } = toolCall;
+
+  // 1) Derive component type
+  let componentType = tool_name;
+  if (tool_name.startsWith('render_')) {
+    const parts = tool_name.split('_').slice(1);
+    componentType = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+  }
+
+  const schema = catalog[componentType];
+  if (!schema) {
+    throw new Error(
+      `[AUI-X] Component type "${componentType}" not found in catalog for tool "${tool_name}"`,
+    );
+  }
+
+  const surfaceId = `${tool_name}-surface-handshake`;
+  const rootId = 'root-column';
+
+  // 2) Map props
+  const props: Record<string, unknown> = {};
+  if (tool_input) {
+    Object.entries(tool_input).forEach(([key, value]) => {
+      if (key === 'mfData' || key === 'dataModel') {
+        props[key] = value;
+      } else {
+        const val = toLiteralStringValue(value);
+        if (val) props[key] = val;
+      }
+    });
+  }
+
+  // 3) Build rendering instructions
+  const components = [
+    {
+      id: rootId,
+      component: {
+        Column: {
+          children: {
+            explicitList: ['dynamic-card'],
+          },
+        },
+      },
+    },
+    {
+      id: 'dynamic-card',
+      component: {
+        [componentType]: props,
+      },
+    },
+  ];
+
+  return [
+    {
+      beginRendering: {
+        surfaceId,
+        root: rootId,
+        styles: {
+          primaryColor: '#1DB954',
+          font: 'Roboto',
+        },
+      },
+    },
+    {
+      surfaceUpdate: {
+        surfaceId,
+        components,
+      },
+    },
+  ];
+}

package/src/client/index.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './handshake';
+export * from './registry';
+export * from './useA2UIStream';
+export * from './useLogger';
+

package/src/client/registry.tsx

@@ -0,0 +1,184 @@
+import React, { lazy } from 'react';
+import ReactDOM from 'react-dom';
+import { createInstance } from '@module-federation/enhanced/runtime';
+import * as A2UI from '@a2ui/react';
+import {
+  ComponentRegistry,
+  registerDefaultCatalog,
+  type ComponentRegistration,
+} from '@a2ui/react';
+import type { CreateMFRegistryOptions, XLoaderConfig } from './types';
+import { logger } from './useLogger';
+
+// ── Inline ErrorPlaceholder (avoid depending on sample app components) ──────
+
+const ErrorPlaceholder: React.FC<{ title?: string; message?: string }> = ({
+  title = 'Component load failed',
+  message,
+}) => (
+  <div
+    style={{
+      padding: '0.75rem 1rem',
+      borderRadius: 6,
+      border: '1px solid #f5c2c7',
+      background: '#f8d7da',
+      color: '#842029',
+      fontSize: 14,
+    }}
+  >
+    <strong>{title}</strong>
+    {message && <div style={{ marginTop: 4 }}>{message}</div>}
+  </div>
+);
+
+// ── MF Runtime singleton ────────────────────────────────────────────────────
+
+type MFInstance = ReturnType<typeof createInstance>;
+
+let mfInstance: MFInstance | null = null;
+let registryInstance: ComponentRegistry | null = null;
+
+function ensureMFInstance(options?: CreateMFRegistryOptions): MFInstance {
+  if (mfInstance) return mfInstance;
+
+  const baseShared = {
+    react: {
+      version: React.version,
+      scope: 'default',
+      lib: () => React,
+      shareConfig: {
+        singleton: true,
+        requiredVersion: '^18.0.0',
+      },
+    },
+    'react-dom': {
+      version: React.version,
+      scope: 'default',
+      lib: () => ReactDOM,
+      shareConfig: {
+        singleton: true,
+        requiredVersion: '^18.0.0',
+      },
+    },
+    '@a2ui/react': {
+      version: '0.8.0',
+      scope: 'default',
+      lib: () => A2UI,
+      shareConfig: {
+        singleton: true,
+        requiredVersion: '^0.8.0',
+      },
+    },
+  } as const;
+
+  const shared = {
+    ...baseShared,
+    ...(options?.shared ?? {}),
+  } as any;
+
+  mfInstance = createInstance({
+    name: 'aui_mcp_client',
+    remotes: [],
+    shared,
+  });
+
+  return mfInstance;
+}
+
+/**
+ * Create (or get) a `ComponentRegistry` instance and initialize the default catalog.
+ *
+ * - Share `react` / `react-dom` / `@a2ui/react` as singletons
+ * - Allow extra shared deps via `options.shared`
+ * - Optionally expose `window.__AUI_REGISTRY__` via `options.exposeGlobal`
+ */
+export function createMFRegistry(options?: CreateMFRegistryOptions): ComponentRegistry {
+  ensureMFInstance(options);
+
+  if (!registryInstance) {
+    registryInstance = ComponentRegistry.getInstance();
+    registerDefaultCatalog(registryInstance);
+    logger.info('[aui-mcp-server/react] ComponentRegistry initialized with default catalog');
+  }
+
+  if (typeof window !== 'undefined' && options?.exposeGlobal) {
+    (window as any).__AUI_REGISTRY__ = registryInstance;
+  }
+
+  return registryInstance;
+}
+
+/**
+ * Register a single MF component (lazy-loaded with a safe ErrorPlaceholder fallback).
+ */
+export function registerMFComponent(
+  registry: ComponentRegistry,
+  componentType: string,
+  xLoader: XLoaderConfig,
+): void {
+  const mf = ensureMFInstance();
+  const { url, scope, module: modulePath } = xLoader;
+
+  const exposeName = modulePath.replace(/^\.\//, '');
+  const remoteId = `${scope}/${exposeName}`;
+
+  const LazyComponent = lazy(async () => {
+    logger.debug(`[AUI-X] MF lazy load triggered: ${componentType} (${remoteId})`);
+    try {
+      mf.registerRemotes([{ name: scope, entry: url }], { force: false });
+
+      const mod = await mf.loadRemote<{
+        default: React.ComponentType<Record<string, unknown>>;
+      }>(remoteId);
+
+      if (!mod) {
+        throw new Error(`[AUI-X] loadRemote returned null for "${remoteId}"`);
+      }
+
+      const Component =
+        mod.default ?? (mod as unknown as React.ComponentType<Record<string, unknown>>);
+      logger.info(`[AUI-X] ✅ MF component loaded OK: ${componentType}`);
+      return { default: Component };
+    } catch (error) {
+      logger.error(
+        `[AUI-X] ❌ Failed to load MF component "${componentType}" from "${remoteId}":`,
+        error,
+      );
+
+      const Fallback: React.FC = () => (
+        <ErrorPlaceholder
+          title="Failed to load MF component"
+          message={`Unable to load remote component: ${componentType}`}
+        />
+      );
+
+      return { default: Fallback };
+    }
+  });
+
+  const registration: ComponentRegistration = {
+    component: LazyComponent as never,
+  };
+
+  registry.register(componentType, registration as never);
+  logger.info(
+    `[AUI-X] MF component registered (runtime): ${componentType} ← ${url} → ${remoteId}`,
+  );
+}
+
+/**
+ * Register all `x-loader` components from a Catalog into the given registry.
+ */
+export function syncRegistryFromCatalog(
+  registry: ComponentRegistry,
+  catalog: Record<string, unknown>,
+): void {
+  Object.entries(catalog).forEach(([type, schema]) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const anySchema = schema as any;
+    const xLoader = (anySchema.x_loader || anySchema['x-loader']) as XLoaderConfig | undefined;
+    if (!xLoader || xLoader.type !== 'module-federation') return;
+
+    registerMFComponent(registry, type, xLoader);
+  });
+}