aui-mcp-server 0.0.1

package/src/catalog/entry.ts

@@ -0,0 +1,183 @@
+import type {
+  AuiXCatalogEntry,
+  AuiXLoaderConfig,
+  AuiXToolDefinition,
+  PropDefinition,
+  RemoteContext,
+} from '../types';
+import { join, dirname } from 'node:path';
+import { parseToolLogic } from './tool_parser';
+
+function propsToSchemaProperties(props: PropDefinition[]): AuiXCatalogEntry['properties'] {
+  const result: AuiXCatalogEntry['properties'] = {};
+
+  for (const prop of props) {
+    result[prop.name] = {
+      type: 'object',
+      ...(prop.description ? { description: prop.description } : {}),
+      properties: {
+        literalString: { type: 'string' },
+        path: { type: 'string' },
+      },
+    };
+  }
+
+  return result;
+}
+
+function getRequiredProps(props: PropDefinition[]): string[] {
+  return props.filter((p) => !p.optional).map((p) => p.name);
+}
+
+function buildXLoader(ctx: RemoteContext): AuiXLoaderConfig {
+  return {
+    type: 'module-federation',
+    url: ctx.remoteEntryUrl,
+    scope: ctx.stats.id,
+    module: ctx.expose.path,
+  };
+}
+
+function buildFallbackExample(ctx: RemoteContext): unknown {
+  const surfaceId = `${ctx.componentName.toLowerCase()}-surface-1`;
+  const componentId = `${ctx.componentName.toLowerCase()}-card`;
+
+  const required = getRequiredProps(ctx.props);
+  const propsPayload: Record<string, unknown> = {};
+  for (const name of required) {
+    propsPayload[name] = { literalString: `<!-- ${name} -->` };
+  }
+
+  return [
+    {
+      beginRendering: {
+        surfaceId,
+        root: 'root-column',
+      },
+    },
+    {
+      surfaceUpdate: {
+        surfaceId,
+        components: [
+          {
+            id: 'root-column',
+            component: {
+              Column: {
+                children: { explicitList: [componentId] },
+              },
+            },
+          },
+          {
+            id: componentId,
+            component: {
+              [ctx.componentName]: propsPayload,
+            },
+          },
+        ],
+      },
+    },
+  ];
+}
+
+export function generateCatalogEntry(ctx: RemoteContext): AuiXCatalogEntry {
+  const schemaProps = propsToSchemaProperties(ctx.props);
+  const required = getRequiredProps(ctx.props);
+
+  // ─── A2UI v0.9 Actions (Custom Props) ──────────────────────────────────────
+  // Convert `@action` tags into Action properties in the schema.
+  if (ctx.jsdoc.actions && ctx.jsdoc.actions.length > 0) {
+    for (const actionDef of ctx.jsdoc.actions) {
+      const propName = `${actionDef.name}Action`;
+      const desc = actionDef.description
+        ? `${actionDef.description}${actionDef.replyWith ? ` (Expected reply: ${actionDef.replyWith})` : ''}`
+        : `Trigger server event: ${actionDef.name}`;
+
+      schemaProps[propName] = {
+        type: 'object',
+        description: desc,
+        properties: {
+          name: { type: 'string' },
+          context: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                key: { type: 'string' },
+                value: { type: 'object' },
+              },
+              required: ['key', 'value'],
+            },
+          },
+        },
+        required: ['name'],
+      };
+    }
+  }
+
+  const entry: AuiXCatalogEntry = {
+    type: 'object',
+    description: ctx.jsdoc.description ?? `AUI-X MF Remote component: ${ctx.componentName}.`,
+    properties: schemaProps,
+    ...(required.length > 0 ? { required } : {}),
+    'x-loader': buildXLoader(ctx),
+    'x-example': ctx.jsdoc.example ?? buildFallbackExample(ctx),
+    ...(ctx.jsdoc.authRequired !== undefined
+      ? { 'x-auth-required': ctx.jsdoc.authRequired }
+      : {}),
+    ...(ctx.jsdoc.fallback ? { 'x-fallback': ctx.jsdoc.fallback } : {}),
+  };
+
+  // ─── x-tools wiring ───────────────────────────────────────────────────────
+  // 1) Prefer explicit `@tool <toolName> <logicFile>` tags.
+  const xTools: AuiXToolDefinition[] = [];
+
+  if (ctx.jsdoc.tools && ctx.jsdoc.tools.length > 0) {
+    for (const tool of ctx.jsdoc.tools) {
+      const sourceFile = ctx.expose.file;
+      const baseDir = join(process.cwd(), dirname(sourceFile));
+
+      const parsed = parseToolLogic(tool.name, tool.logicFile, baseDir);
+
+      if (parsed && ctx.loaderExpose?.path) {
+        xTools.push({
+          name: parsed.name,
+          description: parsed.description,
+          loader: ctx.loaderExpose.path,
+          parameters: parsed.parameters,
+          logicFilePath: parsed.logicFilePath,
+        });
+      }
+    }
+  }
+
+  // 2) Auto-detect MF 2.0 data loader as a tool.
+  if (ctx.loaderExpose) {
+    const loaderFile = ctx.loaderExpose.file;
+    const baseDir = process.cwd();
+
+    // Auto-generated tool naming convention: get_<ComponentName>_data
+    const defaultToolName = `get_${ctx.componentName.toLowerCase()}_data`;
+
+    const parsed = parseToolLogic(defaultToolName, loaderFile, baseDir);
+
+    if (parsed) {
+      // If the loader file defines an explicit `@tool`, `parseToolLogic` returns that tool name.
+      // Only add it when not duplicated.
+      if (!xTools.find(t => t.name === parsed.name || t.logicFilePath === parsed.logicFilePath)) {
+        xTools.push({
+          name: parsed.name,
+          description: parsed.description,
+          loader: ctx.loaderExpose.path,
+          parameters: parsed.parameters,
+          logicFilePath: parsed.logicFilePath,
+        });
+      }
+    }
+  }
+
+  if (xTools.length > 0) {
+    entry['x-tools'] = xTools;
+  }
+
+  return entry;
+}

package/src/catalog/parser.ts

@@ -0,0 +1,173 @@
+import type { AuiJsDocTags, PropDefinition } from '../types';
+
+/**
+ * Parse the first JSDoc block that contains `@aui-component`.
+ */
+export function parseJsDoc(dtsContent: string): AuiJsDocTags {
+  const jsdocBlockRegex = /\/\*\*([\s\S]*?)\*\//g;
+  let targetBlock: string | null = null;
+
+  for (const match of dtsContent.matchAll(jsdocBlockRegex)) {
+    const block = match[1];
+    if (block?.includes('@aui-component')) {
+      targetBlock = block;
+      break;
+    }
+  }
+
+  if (!targetBlock) {
+    return { isAuiComponent: false };
+  }
+
+  const result: AuiJsDocTags = { isAuiComponent: true };
+
+  const lines = targetBlock
+    .split('\n')
+    .map((l) => l.replace(/^\s*\*\s?/, '').trimEnd());
+
+  const descMatch = lines.find((l) => l.startsWith('@description'));
+  if (descMatch) {
+    result.description = descMatch.replace('@description', '').trim();
+  }
+
+  const authMatch = lines.find((l) => l.startsWith('@auth-required'));
+  if (authMatch) {
+    const val = authMatch.replace('@auth-required', '').trim().toLowerCase();
+    result.authRequired = val === 'true';
+  }
+
+  const fallbackMatch = lines.find((l) => l.startsWith('@fallback'));
+  if (fallbackMatch) {
+    result.fallback = fallbackMatch.replace('@fallback', '').trim();
+  }
+
+  const exampleStartIdx = lines.findIndex((l) => l.startsWith('@example'));
+  if (exampleStartIdx !== -1) {
+    const exampleLine = lines[exampleStartIdx];
+    if (exampleLine) {
+      const exampleFirstLine = exampleLine.replace('@example', '').trim();
+
+      const continuationLines: string[] = [];
+      for (let i = exampleStartIdx + 1; i < lines.length; i++) {
+        const l = lines[i];
+        if (!l) break;
+        if (/^@\w/.test(l)) break;
+        if (l && !/^[\s[\]{},"'0-9\-+tfn]/.test(l)) break;
+        continuationLines.push(l);
+      }
+
+      const rawJson = [exampleFirstLine, ...continuationLines].join('\n').trim();
+      if (rawJson) {
+        try {
+          result.example = JSON.parse(rawJson);
+        } catch {
+          // keep silent and fallback later
+        }
+      }
+    }
+  }
+
+  // ── @tool parsing ─────────────────────────────────────────────────────────
+  // Supported syntax:
+  //   @tool <toolName> <logicFile>
+  // Example:
+  //   @tool get_concert_tours ./getConcertTours
+  const toolLines = lines.filter((l) => l.startsWith('@tool '));
+  if (toolLines.length > 0) {
+    result.tools = toolLines.map((l) => {
+      const parts = l.replace('@tool', '').trim().split(/\s+/);
+      return {
+        name: parts[0] ?? '',
+        logicFile: parts[1] ?? '',
+      };
+    });
+  }
+
+  // ── @action parsing ───────────────────────────────────────────────────────
+  // Supported syntax:
+  //   @action name="wish_more_shows" replyWith="WishShowForm" contextKeys="artist,region" description="Wish for more tour shows"
+  const actionLines = lines.filter((l) => l.startsWith('@action '));
+  if (actionLines.length > 0) {
+    result.actions = actionLines.map((l) => {
+      const raw = l.replace('@action', '').trim();
+      const action: any = {};
+      const pairs = raw.match(/(\w+)="([^"]*)"/g) || [];
+      for (const p of pairs) {
+        const [k, v] = p.split('="');
+        const key = k?.trim();
+        const val = v?.replace(/"$/, '');
+        if (key === 'name') action.name = val;
+        if (key === 'description') action.description = val;
+        if (key === 'replyWith') action.replyWith = val;
+        if (key === 'contextKeys') action.contextKeys = val?.split(',').map((s: string) => s.trim());
+      }
+      return action;
+    });
+  }
+
+  return result;
+}
+
+export function needsJsDocFill(dtsContent: string): boolean {
+  return !dtsContent.includes('@aui-component');
+}
+
+/**
+ * Parse props interface in compiled d.ts.
+ */
+export function parsePropsInterface(dtsContent: string, componentName: string): PropDefinition[] {
+  const patterns = [
+    new RegExp(`interface\\s+${componentName}Properties\\s*\\{([\\s\\S]*?)\\}`, 'm'),
+    new RegExp(`interface\\s+${componentName}Props\\s*\\{([\\s\\S]*?)\\}`, 'm'),
+  ];
+
+  let interfaceBody: string | null = null;
+  for (const pattern of patterns) {
+    const m = dtsContent.match(pattern);
+    const body = m?.[1];
+    if (body) {
+      interfaceBody = body;
+      break;
+    }
+  }
+
+  if (!interfaceBody) {
+    return [];
+  }
+
+  // Handle nesting: node { properties { ... } }
+  // In the AUI spec, actual props are defined under `node.properties`.
+  const nodeMatch = interfaceBody.match(/node\s*:\s*\{\s*properties\s*:\s*\{([\s\S]*?)\}\s*\}/m);
+  if (nodeMatch) {
+    interfaceBody = nodeMatch[1]!;
+  }
+
+  const props: PropDefinition[] = [];
+  // A more tolerant regex for matching nested property definitions in the AUI shape.
+  const fieldRegex = /^\s*(\w+)(\??):\s*([\s\S]+?)(?:;|$)/;
+
+  const reserved = ['node', 'properties', 'literalString', 'path'];
+
+  for (const line of interfaceBody.split('\n')) {
+    const m = line.match(fieldRegex);
+    if (!m) continue;
+
+    const name = m[1];
+    if (!name || (nodeMatch && reserved.includes(name))) continue;
+
+    const questionMark = m[2];
+    let rawType = m[3]?.trim() ?? '';
+
+    // If the type is an inline object definition, simplify it to 'object'.
+    if (rawType.startsWith('{')) {
+      rawType = 'object';
+    }
+
+    const optional = questionMark === '?';
+    const type = rawType;
+
+    props.push({ name, type, optional });
+  }
+
+  return props;
+}

package/src/catalog/tool_parser.ts

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, isAbsolute } from 'node:path';
+
+export interface ParsedToolLogic {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  /** Absolute path to the local logic file (if resolved). */
+  logicFilePath: string;
+}
+
+/**
+ * A simple regex-based tool logic parser for AUI-X.
+ *
+ * Responsibilities:
+ * - Resolve a TS/JS file from a logicFilePath hint
+ * - Parse JSDoc description
+ * - Infer a minimal JSON-schema-like parameters shape from the
+ *   loader function's argument type
+ *
+ * NOTE: This function no longer infers or records any HTTP endpoint.
+ * Endpoint routing is now owned by the MCP server, which executes
+ * MF loaders directly via the Module Federation runtime.
+ */
+export function parseToolLogic(
+  toolName: string,
+  logicFilePath: string,
+  baseDir: string
+): ParsedToolLogic | null {
+  // 1. Resolve file path
+  let targetPath = '';
+  const extensions = ['.ts', '.tsx', '.js', '.jsx'];
+  
+  // Try absolute or relative
+  const absPath = isAbsolute(logicFilePath) ? logicFilePath : join(baseDir, logicFilePath);
+  for (const ext of ['', ...extensions]) {
+    if (existsSync(absPath + ext)) {
+      targetPath = absPath + ext;
+      break;
+    }
+  }
+
+  if (!targetPath) {
+    console.error(`[AUI-X] Tool logic file not found: ${logicFilePath} (base: ${baseDir})`);
+    return null;
+  }
+
+  const content = readFileSync(targetPath, 'utf-8');
+
+  // 2. Extract description (JSDoc before the function)
+  let description = `Automatically generated tool for ${toolName}.`;
+  
+  let jsdocContent = '';
+  let paramsContent = '';
+  let finalToolName = toolName;
+
+  // Search for ANY block that contains @tool
+  const jsdocRegex = /\/\*\*([\s\S]*?)\*\/[\s\S]*?(?:export\s+)?(?:async\s+)?function\s+(\w+)/g;
+  let match;
+  
+  while ((match = jsdocRegex.exec(content)) !== null) {
+    const block = match[1]!;
+    const funcName = match[2]!;
+    
+    // Pattern A: Manually specified @tool
+    const toolMatch = block.match(/@tool\s+(\w+)/);
+    if (toolMatch) {
+      // If we are looking for a specific tool name, check if it matches
+      // Or if we are looking for the 'loader' default, take the first @tool we find in the loader file
+      if (toolMatch[1] === toolName || toolName.includes('artistevents') || toolName.endsWith('_data')) {
+        jsdocContent = block;
+        finalToolName = toolMatch[1]!;
+        
+        const pRegex = new RegExp(`(?:export\\s+)?(?:async\\s+)?function\\s+${funcName}\\s*\\(\\s*(?:args|\\{[\\s\\S]*?\\}|)\\s*:\\s*\\{([\\s\\S]*?)\\}\\s*\\)`, 'm');
+        const pMatch = content.match(pRegex);
+        if (pMatch) {
+          paramsContent = pMatch[1] || '';
+        }
+        break;
+      }
+    }
+    
+    // Pattern B: Default MF 2.0 loader (if no @tool tag found yet)
+    if (funcName === 'loader' && !jsdocContent) {
+      jsdocContent = block;
+      const pRegex = /(?:export\s+)?(?:async\s+)?function\s+loader\s*\(\s*(?:args|\{[\s\S]*?\}|)\s*:\s*\{([\s\S]*?)\}\s*\)/m;
+      const pMatch = content.match(pRegex);
+      if (pMatch) {
+        paramsContent = pMatch[1] || '';
+      }
+    }
+  }
+
+  const properties: Record<string, any> = {};
+  const required: string[] = [];
+
+  if (jsdocContent) {
+    // Check if there is an @description override in JSDoc
+    const descriptionOverride = jsdocContent.match(/@description\s+([^\n@]+)/);
+    if (descriptionOverride?.[1]) {
+      description = descriptionOverride[1].trim();
+    } else {
+      description = jsdocContent
+        .split('\n')
+        .map(l => l.replace(/^\s*\*\s?/, '').trim())
+        .filter(l => l && !l.startsWith('@') && !l.startsWith('/') && !l.endsWith('/'))
+        .join('\n') // keep line breaks first
+        .trim();
+      
+      // If the extracted description still contains @tool-like remnants, clean it again
+      // (helps with some non-standard JSDoc indentation).
+      description = description.split('\n').filter(l => !l.trim().startsWith('@')).join(' ').trim();
+    }
+    
+    // Parse parameters
+    if (paramsContent) {
+      const fields = paramsContent.split(',').map(f => f.trim()).filter(Boolean);
+      for (const field of fields) {
+        const fieldMatch = field.match(/^(\w+)(\??):\s*(\w+)/);
+        if (fieldMatch) {
+          const name = fieldMatch[1]!;
+          const optional = fieldMatch[2] === '?';
+          const rawType = fieldMatch[3]!;
+          let type = 'string';
+          if (rawType === 'number') type = 'number';
+          if (rawType === 'boolean') type = 'boolean';
+          properties[name] = { type };
+          if (!optional) required.push(name);
+        }
+      }
+    }
+
+  }
+
+  return {
+    name: finalToolName,
+    description,
+    logicFilePath: targetPath,
+    parameters: {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined,
+    } as any,
+  };
+}