aui-mcp-server 0.0.1

package/README.md

@@ -0,0 +1,122 @@
+# aui-mcp-server
+
+Automatically generates the **AUI-X Catalog** and **MCP server assets** during an MF Remote build.
+
+- Input: `dist/mf-stats.json` + `dist/@mf-types/compiled-types/*.d.ts`
+- Default output:
+  - `dist/aui-x-catalog.json`
+  - `dist/mcp/manifest.json`
+  - `dist/mcp/server.mjs`
+
+> Note: the generated MCP server only exposes component metadata (including `x-loader`). Actual MF import/rendering should be done by the AUI-X runtime on the client side.
+
+## CLI
+
+Install in an MF Remote project:
+
+```bash
+pnpm add -D aui-mcp-server
+```
+
+Generate `aui-x-catalog.json` (from `mf-stats.json`):
+
+```bash
+pnpm exec aui-mcp catalog ./dist/mf-stats.json -o ./aui-x-catalog.json
+```
+
+Generate MCP assets (from `aui-x-catalog.json`):
+
+```bash
+pnpm exec aui-mcp generate --catalog ./aui-x-catalog.json --outDir dist
+```
+
+Serve locally (SSE example):
+
+```bash
+pnpm exec aui-mcp serve \
+  --manifest ./dist/mcp/manifest.json \
+  --transport sse \
+  --port 8001 \
+  --watch
+```
+
+## Build Plugin (recommended)
+
+### Rspack / Webpack
+
+Place this plugin after the MF plugin (so `mf-stats.json` already exists in compilation assets).
+
+```ts
+import { AuiMcpRspackPlugin } from 'aui-mcp-server/rspack';
+
+export default {
+  plugins: [
+    // ModuleFederationPlugin / pluginModuleFederation(...) etc.
+    new AuiMcpRspackPlugin({
+      transport: 'sse',
+      port: 8001,
+    }),
+  ],
+};
+```
+
+In dev mode (`watch` or `mode=development`), it automatically starts the MCP server. Generation failures are reported as warnings and will not fail the build.
+
+### Rsbuild
+
+```ts
+import { defineConfig } from '@rsbuild/core';
+import { auiMcpRsbuildPlugin } from 'aui-mcp-server/rsbuild';
+
+export default defineConfig({
+  plugins: [
+    auiMcpRsbuildPlugin({
+      transport: 'sse',
+      port: 8001,
+    }),
+  ],
+});
+```
+
+## Verify
+
+```bash
+npx @modelcontextprotocol/inspector node dist/mcp/server.mjs
+```
+
+## React SDK Entry: `aui-mcp-server/react`
+
+Install dependencies (example):
+
+```bash
+pnpm add aui-mcp-server @a2ui/react react react-dom @module-federation/enhanced
+```
+
+In a React host app:
+
+```ts
+import {
+  performHandshake,
+  createMFRegistry,
+  syncRegistryFromCatalog,
+  registerMFComponent,
+  useA2UIStream,
+  createLogger,
+  useLogger,
+  type XLoaderConfig,
+  type ChatMessage,
+  type A2UIStreamOptions,
+  type CreateLoggerOptions,
+} from 'aui-mcp-server/react';
+```
+
+Core capabilities:
+
+- `performHandshake(agentUrl)`: fetches A2A AgentCard, parses `inlineCatalogs`, and calls `syncRegistryFromCatalog` to register `x-loader` components as Module Federation remotes.
+- `createMFRegistry(options?)`: creates/returns a `ComponentRegistry` instance. Shares `react` / `react-dom` / `@a2ui/react` as singletons by default; supports `options.shared` for extra shared deps and `options.exposeGlobal` to expose `window.__AUI_REGISTRY__`.
+- `syncRegistryFromCatalog(registry, catalog)`: registers all `x-loader` entries from a Catalog into a registry.
+- `registerMFComponent(registry, componentType, xLoader)`: registers a single MF component on demand, falling back to an inline `ErrorPlaceholder` on failure.
+- `useA2UIStream(options?)`: wraps A2A JSON-RPC 2.0 + SSE streaming. Returns `{ messages, isLoading, sendMessage, processLocalMessages }`. `options.agentUrl` defaults to `/api` and supports `defaultIsActionPayload` mode.
+- `createLogger(options?)` / `useLogger(options?)`: unified frontend logging + remote reporting. `options.endpoint` defaults to `/api/log`; `options.hijackConsole` controls whether `console.*` is hijacked.
+
+All SDK types (e.g. `XLoaderConfig`, `ChatMessage`, `A2UIStreamOptions`, `CreateLoggerOptions`) are also exported from `aui-mcp-server/react` to keep host apps fully type-safe.