@open-mercato/ai-assistant 0.4.2-canary-c02407ff85

package/src/modules/ai_assistant/lib/schema-utils.ts

@@ -0,0 +1,142 @@
+import { z, type ZodType } from 'zod'
+
+/**
+ * Cache for converted safe schemas to avoid repeated conversions per request.
+ */
+const safeSchemaCache = new WeakMap<ZodType, ZodType>()
+
+/**
+ * Convert a JSON Schema to a simple Zod schema.
+ * This creates a schema that can be converted back to JSON Schema without errors.
+ *
+ * Supports:
+ * - Basic types: string, number, integer, boolean, null
+ * - Arrays with item types
+ * - Objects with properties and required fields
+ * - Records/dictionaries via additionalProperties
+ * - Union types via anyOf/oneOf
+ * - Enum values
+ */
+export function jsonSchemaToZod(jsonSchema: Record<string, unknown>): ZodType {
+  const type = jsonSchema.type as string | undefined
+
+  if (type === 'string') {
+    return z.string()
+  }
+  if (type === 'number' || type === 'integer') {
+    return z.number()
+  }
+  if (type === 'boolean') {
+    return z.boolean()
+  }
+  if (type === 'null') {
+    return z.null()
+  }
+  if (type === 'array') {
+    const items = jsonSchema.items as Record<string, unknown> | undefined
+    if (items) {
+      return z.array(jsonSchemaToZod(items))
+    }
+    return z.array(z.unknown())
+  }
+  if (type === 'object') {
+    const properties = jsonSchema.properties as Record<string, Record<string, unknown>> | undefined
+    const required = (jsonSchema.required as string[]) || []
+    const additionalProperties = jsonSchema.additionalProperties
+
+    // Handle z.record() - objects with additionalProperties but no fixed properties
+    if (additionalProperties && (!properties || Object.keys(properties).length === 0)) {
+      // This is a record/dictionary type - allow any properties
+      if (typeof additionalProperties === 'object') {
+        return z.record(z.string(), jsonSchemaToZod(additionalProperties as Record<string, unknown>))
+      }
+      // additionalProperties: true means any value
+      return z.record(z.string(), z.unknown())
+    }
+
+    if (properties) {
+      const shape: Record<string, ZodType> = {}
+      for (const [key, propSchema] of Object.entries(properties)) {
+        let fieldSchema = jsonSchemaToZod(propSchema)
+        // Make field optional if not in required array
+        if (!required.includes(key)) {
+          fieldSchema = fieldSchema.optional()
+        }
+        shape[key] = fieldSchema
+      }
+      // If additionalProperties is allowed, use passthrough
+      if (additionalProperties) {
+        return z.object(shape).passthrough()
+      }
+      return z.object(shape)
+    }
+
+    // Empty object with additionalProperties - treat as record
+    if (additionalProperties) {
+      return z.record(z.string(), z.unknown())
+    }
+    return z.object({})
+  }
+
+  // Handle union types (anyOf, oneOf)
+  const anyOf = jsonSchema.anyOf as Record<string, unknown>[] | undefined
+  const oneOf = jsonSchema.oneOf as Record<string, unknown>[] | undefined
+  const unionTypes = anyOf || oneOf
+  if (unionTypes && unionTypes.length >= 2) {
+    const schemas = unionTypes.map(s => jsonSchemaToZod(s))
+    return z.union(schemas as [ZodType, ZodType, ...ZodType[]])
+  }
+
+  // Handle nullable via anyOf with null
+  if (anyOf && anyOf.length === 2) {
+    const types = anyOf.map((s) => s.type)
+    if (types.includes('null')) {
+      const nonNullSchema = anyOf.find((s) => s.type !== 'null')
+      if (nonNullSchema) {
+        return jsonSchemaToZod(nonNullSchema).nullable()
+      }
+    }
+  }
+
+  // Handle enum
+  const enumValues = jsonSchema.enum as string[] | undefined
+  if (enumValues && enumValues.length > 0) {
+    return z.enum(enumValues as [string, ...string[]])
+  }
+
+  // Fallback for empty schemas (like Date converted with unrepresentable: 'any')
+  return z.unknown()
+}
+
+/**
+ * Convert a Zod schema to a safe Zod schema that has no Date types.
+ * Uses JSON Schema as an intermediate format to handle all Zod v4 internal complexities.
+ * Results are cached to avoid repeated conversions.
+ *
+ * @param schema - The original Zod schema
+ * @returns A safe Zod schema without Date types
+ */
+export function toSafeZodSchema(schema: ZodType): ZodType {
+  // Check cache first
+  const cached = safeSchemaCache.get(schema)
+  if (cached) {
+    return cached
+  }
+
+  try {
+    // Use Zod 4's toJSONSchema with unrepresentable: 'any' to handle Date types
+    const jsonSchema = z.toJSONSchema(schema, { unrepresentable: 'any' }) as Record<string, unknown>
+
+    // Convert back to a simple Zod schema without Date types
+    const safeSchema = jsonSchemaToZod(jsonSchema)
+
+    // Cache the result
+    safeSchemaCache.set(schema, safeSchema)
+
+    return safeSchema
+  } catch (error) {
+    console.error('[Schema Utils] Error converting schema:', error)
+    // Fallback to the original schema if conversion fails
+    return schema
+  }
+}

package/src/modules/ai_assistant/lib/tool-executor.ts

@@ -0,0 +1,71 @@
+import type { McpToolContext, ToolExecutionResult } from './types'
+import { getToolRegistry } from './tool-registry'
+import { hasRequiredFeatures } from './auth'
+
+/**
+ * Execute a tool with full context and ACL checks.
+ */
+export async function executeTool(
+  toolName: string,
+  input: unknown,
+  context: McpToolContext
+): Promise<ToolExecutionResult> {
+  const registry = getToolRegistry()
+  const tool = registry.getTool(toolName)
+
+  if (!tool) {
+    return {
+      success: false,
+      error: `Tool "${toolName}" not found`,
+      errorCode: 'NOT_FOUND',
+    }
+  }
+
+  // ACL check
+  if (tool.requiredFeatures?.length) {
+    const hasAccess = hasRequiredFeatures(
+      tool.requiredFeatures,
+      context.userFeatures,
+      context.isSuperAdmin
+    )
+
+    if (!hasAccess) {
+      return {
+        success: false,
+        error: `Insufficient permissions for tool "${toolName}". Required: ${tool.requiredFeatures.join(', ')}`,
+        errorCode: 'UNAUTHORIZED',
+      }
+    }
+  }
+
+  // Input validation
+  const parseResult = tool.inputSchema.safeParse(input)
+  if (!parseResult.success) {
+    // Use any cast for Zod v4 compatibility
+    const issues = (parseResult.error as any).issues ?? []
+    const errorMessages = issues
+      .map((issue: { path: PropertyKey[]; message: string }) =>
+        `${issue.path.join('.')}: ${issue.message}`
+      )
+      .join('; ')
+    return {
+      success: false,
+      error: `Invalid input: ${errorMessages || 'Validation failed'}`,
+      errorCode: 'VALIDATION_ERROR',
+    }
+  }
+
+  // Execute tool
+  try {
+    const result = await tool.handler(parseResult.data, context)
+    return { success: true, result }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(`[MCP Tool] Error executing "${toolName}":`, error)
+    return {
+      success: false,
+      error: message,
+      errorCode: 'EXECUTION_ERROR',
+    }
+  }
+}

package/src/modules/ai_assistant/lib/tool-index-config.ts

@@ -0,0 +1,178 @@
+import type {
+  SearchEntityConfig,
+  SearchResultPresenter,
+  IndexableRecord,
+} from '@open-mercato/search/types'
+import type { McpToolDefinition } from './types'
+
+/**
+ * Entity ID for MCP tools in the search index.
+ * Following the module:entity naming convention.
+ */
+export const TOOL_ENTITY_ID = 'ai_assistant:mcp_tool' as const
+
+/**
+ * Tenant ID for global tools.
+ * Tools are not tenant-scoped, so we use a special "system" UUID.
+ * This is the nil UUID (all zeros) reserved for system-wide resources.
+ */
+export const GLOBAL_TENANT_ID = '00000000-0000-0000-0000-000000000000'
+
+/**
+ * Essential tools that should always be available regardless of search results.
+ * These provide fundamental functionality for the AI assistant.
+ */
+export const ESSENTIAL_TOOLS = [
+  'context_whoami', // Auth context awareness
+  'search_query', // Universal search
+  'search_schema', // Entity discovery
+  'search_status', // Check integrations
+] as const
+
+/**
+ * Default configuration for tool search.
+ */
+export const TOOL_SEARCH_CONFIG = {
+  /** Maximum tools to return from search */
+  defaultLimit: 12,
+  /** Minimum relevance score (0-1) */
+  minScore: 0.2,
+  /** Strategies to use (in priority order) */
+  strategies: ['fulltext', 'vector', 'tokens'] as const,
+} as const
+
+/**
+ * Search entity configuration for MCP tools.
+ * This configures how tools are indexed and searched.
+ */
+export const toolSearchEntityConfig: SearchEntityConfig = {
+  entityId: TOOL_ENTITY_ID,
+  enabled: true,
+  priority: 100, // High priority for tool results
+
+  /**
+   * Build searchable content from a tool definition.
+   */
+  buildSource: (ctx) => {
+    const tool = ctx.record as unknown as McpToolDefinition
+    const name = tool.name || ''
+    const description = tool.description || ''
+    const moduleId = (ctx.record as Record<string, unknown>).moduleId as string | undefined
+
+    // Normalize name: replace underscores/dots with spaces for better search
+    const normalizedName = name.replace(/[_.-]/g, ' ')
+
+    // Build text content for embedding and fulltext search
+    const textContent = [
+      normalizedName,
+      description,
+      moduleId ? `module ${moduleId}` : '',
+    ]
+      .filter(Boolean)
+      .join(' | ')
+
+    return {
+      text: textContent,
+      fields: {
+        name: normalizedName,
+        originalName: name,
+        description,
+        moduleId: moduleId ?? null,
+        requiredFeatures: tool.requiredFeatures ?? [],
+      },
+      presenter: {
+        title: name,
+        subtitle: description.slice(0, 100),
+        icon: 'tool',
+      },
+      checksumSource: { name, description, moduleId },
+    }
+  },
+
+  /**
+   * Format result for display in search UI.
+   */
+  formatResult: (ctx) => {
+    const tool = ctx.record as unknown as McpToolDefinition
+    return {
+      title: tool.name || 'Unknown Tool',
+      subtitle: (tool.description || '').slice(0, 100),
+      icon: 'tool',
+    }
+  },
+
+  /**
+   * Field policy for search strategies.
+   */
+  fieldPolicy: {
+    searchable: ['name', 'description', 'moduleId'],
+    hashOnly: [],
+    excluded: ['requiredFeatures', 'inputSchema', 'handler'],
+  },
+}
+
+/**
+ * Convert an MCP tool definition to an indexable record for search.
+ *
+ * @param tool - The tool definition to index
+ * @param moduleId - The module that registered this tool
+ * @returns IndexableRecord ready for search indexing
+ */
+export function toolToIndexableRecord(
+  tool: McpToolDefinition,
+  moduleId?: string
+): IndexableRecord {
+  const normalizedName = tool.name.replace(/[_.-]/g, ' ')
+  const description = tool.description || ''
+
+  // Build text for vector embedding
+  const embeddingText = `${normalizedName} | ${description}`
+
+  const presenter: SearchResultPresenter = {
+    title: tool.name,
+    subtitle: description.slice(0, 100),
+    icon: 'tool',
+  }
+
+  return {
+    entityId: TOOL_ENTITY_ID,
+    recordId: tool.name,
+    tenantId: GLOBAL_TENANT_ID,
+    organizationId: null,
+    fields: {
+      name: normalizedName,
+      originalName: tool.name,
+      description,
+      moduleId: moduleId ?? null,
+      requiredFeatures: tool.requiredFeatures ?? [],
+    },
+    presenter,
+    text: embeddingText,
+    checksumSource: {
+      name: tool.name,
+      description,
+      moduleId,
+    },
+  }
+}
+
+/**
+ * Compute a simple checksum for tool definitions.
+ * Used to detect changes and avoid unnecessary re-indexing.
+ */
+export function computeToolsChecksum(
+  tools: Array<{ name: string; description: string }>
+): string {
+  const content = tools
+    .map((t) => `${t.name}:${t.description}`)
+    .sort()
+    .join('|')
+
+  // Simple hash using string code points
+  let hash = 0
+  for (let i = 0; i < content.length; i++) {
+    const char = content.charCodeAt(i)
+    hash = ((hash << 5) - hash + char) | 0
+  }
+  return hash.toString(16)
+}

package/src/modules/ai_assistant/lib/tool-loader.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod'
+import type { SearchService } from '@open-mercato/search/service'
+import { registerMcpTool, getToolRegistry } from './tool-registry'
+import type { McpToolDefinition, McpToolContext } from './types'
+import { ToolSearchService } from './tool-search'
+import { loadApiDiscoveryTools } from './api-discovery-tools'
+
+/**
+ * Module tool definition as exported from ai-tools.ts files.
+ */
+type ModuleAiTool = {
+  name: string
+  description: string
+  inputSchema: any
+  requiredFeatures?: string[]
+  handler: (input: any, ctx: any) => Promise<unknown>
+}
+
+/**
+ * Built-in context.whoami tool that returns the current authentication context.
+ * This is useful for AI to understand its current tenant/org scope.
+ */
+const contextWhoamiTool: McpToolDefinition = {
+  name: 'context_whoami',
+  description:
+    'Get the current authentication context including tenant ID, organization ID, user ID, and available features. Use this to understand your current scope before performing operations.',
+  inputSchema: z.object({}),
+  requiredFeatures: [], // No specific feature required - available to all authenticated users
+  handler: async (_input: unknown, ctx: McpToolContext) => {
+    return {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      userId: ctx.userId,
+      isSuperAdmin: ctx.isSuperAdmin,
+      features: ctx.userFeatures,
+      featureCount: ctx.userFeatures.length,
+    }
+  },
+}
+
+/**
+ * Load and register AI tools from a module's ai-tools.ts export.
+ *
+ * @param moduleId - The module identifier (e.g., 'search', 'customers')
+ * @param tools - Array of tool definitions from the module
+ */
+export function loadModuleTools(moduleId: string, tools: ModuleAiTool[]): void {
+  for (const tool of tools) {
+    registerMcpTool(
+      {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        requiredFeatures: tool.requiredFeatures,
+        handler: tool.handler,
+      } as McpToolDefinition,
+      { moduleId }
+    )
+  }
+}
+
+/**
+ * Dynamically load tools from known module paths.
+ * This is called during MCP server startup.
+ */
+export async function loadAllModuleTools(): Promise<void> {
+  // 1. Register built-in tools
+  registerMcpTool(contextWhoamiTool, { moduleId: 'context' })
+  console.error('[MCP Tools] Registered built-in context_whoami tool')
+
+  // 2. Load manual ai-tools.ts files from modules
+  const moduleToolPaths = [
+    { moduleId: 'search', importPath: '@open-mercato/search/modules/search/ai-tools' },
+    // Add more modules here as they define ai-tools.ts
+  ]
+
+  for (const { moduleId, importPath } of moduleToolPaths) {
+    try {
+      const module = await import(importPath)
+      const tools = module.aiTools ?? module.default ?? []
+
+      if (Array.isArray(tools) && tools.length > 0) {
+        loadModuleTools(moduleId, tools)
+        console.error(`[MCP Tools] Loaded ${tools.length} tools from ${moduleId}`)
+      }
+    } catch (error) {
+      // Module might not have ai-tools.ts or import failed
+      // This is not an error - modules can optionally provide tools
+      console.error(`[MCP Tools] Could not load tools from ${moduleId}:`, error)
+    }
+  }
+
+  // 3. Load API discovery tools (api_discover, api_execute, api_schema)
+  try {
+    const apiToolCount = await loadApiDiscoveryTools()
+    console.error(`[MCP Tools] Loaded ${apiToolCount} API discovery tools`)
+  } catch (error) {
+    console.error('[MCP Tools] Could not load API discovery tools:', error)
+  }
+}
+
+/**
+ * Index all registered tools for hybrid search discovery.
+ * This should be called after loadAllModuleTools() when the search service is available.
+ *
+ * @param searchService - The search service from DI container
+ * @param force - Force re-indexing even if checksums match
+ * @returns Indexing result with statistics
+ */
+export async function indexToolsForSearch(
+  searchService: SearchService,
+  force = false
+): Promise<{
+  indexed: number
+  skipped: number
+  strategies: string[]
+  checksum: string
+}> {
+  const registry = getToolRegistry()
+  const toolSearchService = new ToolSearchService(searchService, registry)
+
+  try {
+    const result = await toolSearchService.indexTools(force)
+
+    console.error(`[MCP Tools] Indexed ${result.indexed} tools for search`)
+    console.error(`[MCP Tools] Search strategies available: ${result.strategies.join(', ')}`)
+
+    if (result.skipped > 0) {
+      console.error(`[MCP Tools] Skipped ${result.skipped} tools (unchanged)`)
+    }
+
+    return result
+  } catch (error) {
+    console.error('[MCP Tools] Failed to index tools for search:', error)
+    throw error
+  }
+}
+
+/**
+ * Create a ToolSearchService instance for tool discovery.
+ * Use this to get a configured service for discovering relevant tools.
+ *
+ * @param searchService - The search service from DI container
+ * @returns Configured ToolSearchService
+ */
+export function createToolSearchService(searchService: SearchService): ToolSearchService {
+  const registry = getToolRegistry()
+  return new ToolSearchService(searchService, registry)
+}

package/src/modules/ai_assistant/lib/tool-registry.ts

@@ -0,0 +1,114 @@
+import type { McpToolDefinition, McpToolRegistry, ToolRegistrationOptions } from './types'
+
+/**
+ * Global tool registry singleton.
+ * Modules call registerMcpTool() to add their tools.
+ */
+class ToolRegistryImpl implements McpToolRegistry {
+  private tools = new Map<string, McpToolDefinition>()
+  private moduleMap = new Map<string, string[]>()
+
+  registerTool<TInput, TOutput>(
+    tool: McpToolDefinition<TInput, TOutput>,
+    options?: ToolRegistrationOptions
+  ): void {
+    if (!tool?.name) {
+      throw new Error('MCP tool must define a name')
+    }
+
+    if (this.tools.has(tool.name)) {
+      console.warn(`[McpToolRegistry] Tool "${tool.name}" already registered, overwriting`)
+    }
+
+    this.tools.set(tool.name, tool as McpToolDefinition)
+
+    if (options?.moduleId) {
+      const existing = this.moduleMap.get(options.moduleId) ?? []
+      if (!existing.includes(tool.name)) {
+        existing.push(tool.name)
+      }
+      this.moduleMap.set(options.moduleId, existing)
+    }
+  }
+
+  getTools(): Map<string, McpToolDefinition> {
+    return new Map(this.tools)
+  }
+
+  getTool(name: string): McpToolDefinition | undefined {
+    return this.tools.get(name)
+  }
+
+  listToolNames(): string[] {
+    return Array.from(this.tools.keys())
+  }
+
+  listToolsByModule(moduleId: string): string[] {
+    return this.moduleMap.get(moduleId) ?? []
+  }
+
+  unregisterTool(name: string): void {
+    this.tools.delete(name)
+    for (const [moduleId, tools] of this.moduleMap.entries()) {
+      const index = tools.indexOf(name)
+      if (index !== -1) {
+        tools.splice(index, 1)
+        this.moduleMap.set(moduleId, tools)
+      }
+    }
+  }
+
+  clear(): void {
+    this.tools.clear()
+    this.moduleMap.clear()
+  }
+}
+
+export const toolRegistry = new ToolRegistryImpl()
+
+/**
+ * Register an MCP tool from any module.
+ *
+ * Note: Tool names must match the pattern ^[a-zA-Z0-9_-]{1,128}$
+ * (no dots allowed - use underscores instead).
+ *
+ * @example
+ * ```typescript
+ * import { registerMcpTool } from '@open-mercato/ai-assistant/tools'
+ * import { z } from 'zod'
+ *
+ * registerMcpTool({
+ *   name: 'customers_search',
+ *   description: 'Search for customers by name or email',
+ *   inputSchema: z.object({
+ *     query: z.string(),
+ *     limit: z.number().optional().default(10),
+ *   }),
+ *   requiredFeatures: ['customers.people.view'],
+ *   handler: async (input, ctx) => {
+ *     const queryEngine = ctx.container.resolve('queryEngine')
+ *     // ... implementation
+ *   }
+ * }, { moduleId: 'customers' })
+ * ```
+ */
+export function registerMcpTool<TInput, TOutput>(
+  tool: McpToolDefinition<TInput, TOutput>,
+  options?: ToolRegistrationOptions
+): void {
+  toolRegistry.registerTool(tool, options)
+}
+
+/**
+ * Get the global tool registry instance.
+ */
+export function getToolRegistry(): McpToolRegistry {
+  return toolRegistry
+}
+
+/**
+ * Unregister an MCP tool by name.
+ */
+export function unregisterMcpTool(name: string): void {
+  toolRegistry.unregisterTool(name)
+}