@open-mercato/ai-assistant 0.7.0 → 0.7.1-develop.7103.1.41ff100d93

package/src/modules/ai_assistant/lib/__tests__/mcp-server-tool-annotations.test.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod'
+import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { createMcpServer } from '../mcp-server'
+import type { AiToolDefinition, McpServerOptions, McpToolDefinition } from '../types'
+
+const mockCapturedHandlers = new Map<unknown, (request: unknown) => Promise<unknown>>()
+const mockRegisteredTools = new Map<string, McpToolDefinition>()
+
+jest.mock('@modelcontextprotocol/sdk/server/index.js', () => ({
+  Server: class {
+    setRequestHandler(schema: unknown, handler: (request: unknown) => Promise<unknown>) {
+      mockCapturedHandlers.set(schema, handler)
+    }
+  },
+}))
+jest.mock('@modelcontextprotocol/sdk/server/stdio.js', () => ({
+  StdioServerTransport: class {},
+}))
+jest.mock('@modelcontextprotocol/sdk/types.js', () => ({
+  ListToolsRequestSchema: { id: 'tools/list' },
+  CallToolRequestSchema: { id: 'tools/call' },
+}))
+jest.mock('../tool-registry', () => ({
+  getToolRegistry: () => ({
+    getTools: () => mockRegisteredTools,
+    listToolNames: () => Array.from(mockRegisteredTools.keys()),
+  }),
+}))
+jest.mock('../tool-executor', () => ({ executeTool: jest.fn() }))
+jest.mock('../tool-loader', () => ({
+  loadAllModuleTools: jest.fn(),
+  indexToolsForSearch: jest.fn(),
+}))
+jest.mock('../auth', () => ({
+  authenticateMcpRequest: jest.fn(),
+  hasRequiredFeatures: jest.fn(() => true),
+}))
+
+function registerTool(overrides: Partial<AiToolDefinition> & { name: string }): void {
+  mockRegisteredTools.set(overrides.name, {
+    description: `${overrides.name} description`,
+    inputSchema: z.object({ id: z.string() }),
+    handler: async () => ({}),
+    ...overrides,
+  } as McpToolDefinition)
+}
+
+function makeContainer(): McpServerOptions['container'] {
+  return {
+    resolve: () => ({ loadAcl: jest.fn() }),
+  } as unknown as McpServerOptions['container']
+}
+
+type ListedTool = {
+  name: string
+  description: string
+  inputSchema: unknown
+  annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean }
+}
+
+async function listTools(): Promise<ListedTool[]> {
+  await createMcpServer({
+    config: { name: 'test-mcp', version: '0.0.0' },
+    container: makeContainer(),
+    allowUnauthenticatedSuperadmin: true,
+  })
+  const handler = mockCapturedHandlers.get(ListToolsRequestSchema)
+  if (!handler) throw new Error('[internal] tools/list handler was not registered')
+  const response = (await handler({})) as { tools: ListedTool[] }
+  return response.tools
+}
+
+describe('issue #5283 — MCP tools/list publishes readOnlyHint annotations', () => {
+  beforeEach(() => {
+    mockRegisteredTools.clear()
+    mockCapturedHandlers.clear()
+    jest.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  it('marks read operations as read-only so clients can skip approval', async () => {
+    registerTool({ name: 'customers.get_company' })
+    registerTool({ name: 'customers.list_people' })
+    registerTool({ name: 'search_status', isMutation: false })
+
+    const tools = await listTools()
+
+    expect(tools).toHaveLength(3)
+    for (const tool of tools) {
+      expect(tool.annotations?.readOnlyHint).toBe(true)
+    }
+  })
+
+  it('never marks mutating operations as read-only', async () => {
+    registerTool({ name: 'catalog.update_product', isMutation: true })
+    registerTool({ name: 'customers.manage_deal_comment', isMutation: true, isDestructive: true })
+
+    const tools = await listTools()
+
+    const byName = new Map(tools.map((tool) => [tool.name, tool]))
+    expect(byName.get('catalog.update_product')?.annotations?.readOnlyHint).toBe(false)
+    expect(byName.get('customers.manage_deal_comment')?.annotations).toEqual({
+      readOnlyHint: false,
+      destructiveHint: true,
+    })
+  })
+
+  it('keeps the existing name / description / inputSchema fields intact', async () => {
+    registerTool({ name: 'customers.get_company' })
+
+    const [tool] = await listTools()
+
+    expect(tool.name).toBe('customers.get_company')
+    expect(tool.description).toBe('customers.get_company description')
+    expect(tool.inputSchema).toBeDefined()
+  })
+})

package/src/modules/ai_assistant/lib/__tests__/mcp-tool-annotations.test.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod'
+import { buildMcpToolAnnotations } from '../mcp-tool-annotations'
+import type { AiToolDefinition } from '../types'
+
+function makeTool(overrides: Partial<AiToolDefinition> = {}): AiToolDefinition {
+  return {
+    name: 'customers.get_company',
+    description: 'Fetch a single company record.',
+    inputSchema: z.object({ id: z.string() }),
+    handler: async () => ({}),
+    ...overrides,
+  } as AiToolDefinition
+}
+
+describe('buildMcpToolAnnotations', () => {
+  it('advertises readOnlyHint for tools that do not declare a mutation', () => {
+    expect(buildMcpToolAnnotations(makeTool())).toEqual({ readOnlyHint: true })
+  })
+
+  it('advertises readOnlyHint for tools that explicitly declare isMutation: false', () => {
+    expect(buildMcpToolAnnotations(makeTool({ isMutation: false }))).toEqual({ readOnlyHint: true })
+  })
+
+  it('never advertises readOnlyHint for mutating tools', () => {
+    expect(buildMcpToolAnnotations(makeTool({ isMutation: true }))).toEqual({ readOnlyHint: false })
+  })
+
+  it('advertises destructiveHint when the mutation declares isDestructive', () => {
+    expect(buildMcpToolAnnotations(makeTool({ isMutation: true, isDestructive: true }))).toEqual({
+      readOnlyHint: false,
+      destructiveHint: true,
+    })
+  })
+
+  it('carries an explicit non-destructive declaration through', () => {
+    expect(buildMcpToolAnnotations(makeTool({ isMutation: true, isDestructive: false }))).toEqual({
+      readOnlyHint: false,
+      destructiveHint: false,
+    })
+  })
+
+  it('resolves a per-input isDestructive predicate to true rather than under-warning', () => {
+    const annotations = buildMcpToolAnnotations(
+      makeTool({ isMutation: true, isDestructive: (input: unknown) => (input as { op: string }).op === 'delete' }),
+    )
+    expect(annotations).toEqual({ readOnlyHint: false, destructiveHint: true })
+  })
+
+  it('omits destructiveHint when a mutation does not declare isDestructive', () => {
+    expect(buildMcpToolAnnotations(makeTool({ isMutation: true }))).not.toHaveProperty('destructiveHint')
+  })
+
+  it('never advertises idempotentHint, which no tool definition carries', () => {
+    expect(buildMcpToolAnnotations(makeTool())).not.toHaveProperty('idempotentHint')
+    expect(buildMcpToolAnnotations(makeTool({ isMutation: true }))).not.toHaveProperty('idempotentHint')
+  })
+})

package/src/modules/ai_assistant/lib/codemode-tools.ts

@@ -13,7 +13,7 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 import { z } from 'zod'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 import { registerMcpTool } from './tool-registry'
-import type { McpToolContext } from './types'
+import type { AiToolDefinition, McpToolContext } from './types'
 import { createSandbox } from './sandbox'
 import { truncateResult } from './truncate'
 import { applyContextScopeToQuery, applyContextScopeToBody } from './scope-injection'
@@ -560,6 +560,15 @@ export const CODE_MODE_MAX_API_CALLS = 50
 /** Maximum mutation (non-GET/HEAD/OPTIONS) api.request() calls allowed per execute() run. */
 export const CODE_MODE_MAX_MUTATION_CALLS = 20
 
+/**
+ * Register a Code Mode tool through the typed definition so the optional
+ * metadata (`isMutation`, `isDestructive`) survives registration — the MCP
+ * `tools/list` annotations are derived from those flags.
+ */
+function registerCodeModeTool(tool: AiToolDefinition<{ code: string }>): void {
+  registerMcpTool(tool, { moduleId: 'codemode' })
+}
+
 /**
  * Load and register the two Code Mode tools.
  * Generates TypeScript type stubs for common endpoints at startup.
@@ -576,9 +585,10 @@ export async function loadCodeModeTools(): Promise<number> {
  * search — Query the OpenAPI spec and entity graph programmatically.
  */
 function registerSearchTool(): void {
-  registerMcpTool(
+  registerCodeModeTool(
     {
       name: 'search',
+      isMutation: false,
       description: `Query the OpenAPI spec and entity schemas. READ-ONLY, no side effects.
 Globals: spec.findEndpoints(keyword), spec.describeEndpoint(path, method), spec.describeEntity(keyword), spec.paths, spec.entitySchemas.
 Use BEFORE execute to learn endpoint schemas for CREATE/UPDATE. Skip for common paths (companies, people, orders, quotes, products).`,
@@ -650,8 +660,7 @@ Use BEFORE execute to learn endpoint schemas for CREATE/UPDATE. Skip for common
           _memoryContext: memoryContext,
         }
       },
-    },
-    { moduleId: 'codemode' }
+    }
   )
 }
 
@@ -663,9 +672,15 @@ function registerExecuteTool(commonTypes: string): void {
     ? `\n\n${commonTypes}`
     : ''
 
-  registerMcpTool(
+  registerCodeModeTool(
     {
       name: 'execute',
+      // api.request() reaches every documented endpoint, including POST/PUT/DELETE,
+      // so the tool is neither read-only nor guaranteed non-destructive. It is
+      // intentionally exempt from prepareMutation: arbitrary sandbox code cannot
+      // provide the structured before/after preview that approval flow requires.
+      isMutation: true,
+      isDestructive: true,
       description: `Make API calls. Returns JSON.
 Globals: api.request({ method, path, query?, body? }) → { success, statusCode, data }, context { tenantId, organizationId, userId }.
 RULES: For FIND/LIST → GET only (1 call). For UPDATE → PUT to collection path with id in BODY. NEVER PUT/POST/DELETE unless user explicitly asked to change data. Before ANY write operation (POST/PUT/DELETE), you MUST use the AskUserQuestion tool to get explicit user confirmation. Do NOT just ask in text — use the tool so execution pauses until the user responds.${typesBlock}`,
@@ -749,8 +764,7 @@ RULES: For FIND/LIST → GET only (1 call). For UPDATE → PUT to collection pat
           _memoryContext: memoryContext,
         }
       },
-    },
-    { moduleId: 'codemode' }
+    }
   )
 }
 

package/src/modules/ai_assistant/lib/generated-registry-loader.ts

@@ -121,7 +121,11 @@ export async function compileAndImportGenerated(tsPath: string): Promise<Record<
   if (useJestCjsArtifact) {
     return requireFromHere(jsPath) as Record<string, unknown>
   }
-  return (await import(pathToFileURL(jsPath).href)) as Record<string, unknown>
+  return (await import(
+    /* webpackIgnore: true */
+    /* turbopackIgnore: true */
+    pathToFileURL(jsPath).href
+  )) as Record<string, unknown>
 }
 
 function isJestRuntime(): boolean {
@@ -169,7 +173,11 @@ async function compileAppLocalModuleEntries(
   if (specifiers.length === 0) return artifacts
 
   const generatedDir = path.join(appRoot, '.mercato', 'generated')
-  const { compileAppSourceFile } = await import('@open-mercato/shared/lib/bootstrap/dynamicLoader')
+  const { compileAppSourceFile } = await import(
+    /* webpackIgnore: true */
+    /* turbopackIgnore: true */
+    '@open-mercato/shared/lib/bootstrap/dynamicLoader'
+  )
 
   for (const specifier of specifiers) {
     const target = path.resolve(generatedDir, specifier)

package/src/modules/ai_assistant/lib/http-server.ts

@@ -10,6 +10,7 @@ import { executeTool } from './tool-executor'
 import { loadAllModuleTools, indexToolsForSearch } from './tool-loader'
 import { authenticateMcpRequest, extractApiKeyFromHeaders, hasRequiredFeatures } from './auth'
 import { jsonSchemaToZod, toSafeZodSchema } from './schema-utils'
+import { buildMcpToolAnnotations } from './mcp-tool-annotations'
 import { redactSecretForLog, deriveApiKeySessionId } from './log-redaction'
 import type { McpServerConfig, McpToolContext } from './types'
 import type { SearchService } from '@open-mercato/search/service'
@@ -219,6 +220,7 @@ function createMcpServerForRequest(
         {
           description: tool.description,
           inputSchema: safeSchema,
+          annotations: buildMcpToolAnnotations(tool),
         },
         async (args: unknown) => {
           const toolArgs = (args ?? {}) as Record<string, unknown>

package/src/modules/ai_assistant/lib/in-process-client.ts

@@ -1,6 +1,7 @@
 import type { AwilixContainer } from 'awilix'
 import type { z } from 'zod'
 import { toolInputJsonSchema } from './tool-input-schema'
+import { buildMcpToolAnnotations } from './mcp-tool-annotations'
 import { getToolRegistry } from './tool-registry'
 import { executeTool } from './tool-executor'
 import { loadAllModuleTools } from './tool-loader'
@@ -138,6 +139,7 @@ export class InProcessMcpClient implements McpClientInterface {
       name: tool.name,
       description: tool.description,
       inputSchema: toolInputJsonSchema(tool.inputSchema),
+      annotations: buildMcpToolAnnotations(tool),
     }))
   }
 

package/src/modules/ai_assistant/lib/mcp-client.ts

@@ -147,6 +147,7 @@ export class McpClient implements McpClientInterface {
       name: tool.name,
       description: tool.description ?? '',
       inputSchema: (tool.inputSchema ?? {}) as Record<string, unknown>,
+      annotations: tool.annotations,
     }))
   }
 

package/src/modules/ai_assistant/lib/mcp-dev-server.ts

@@ -8,6 +8,7 @@ import { executeTool } from './tool-executor'
 import { loadAllModuleTools, indexToolsForSearch } from './tool-loader'
 import { authenticateMcpRequest, extractApiKeyFromHeaders, hasRequiredFeatures } from './auth'
 import { jsonSchemaToZod } from './schema-utils'
+import { buildMcpToolAnnotations } from './mcp-tool-annotations'
 import { getApiKeyFromMcpJson } from './mcp-dev-key-resolution'
 import type { McpToolContext } from './types'
 import type { SearchService } from '@open-mercato/search/service'
@@ -111,6 +112,7 @@ function createDevMcpServer(
         {
           description: tool.description,
           inputSchema: safeSchema,
+          annotations: buildMcpToolAnnotations(tool),
         },
         async (args: unknown) => {
           const toolArgs = (args ?? {}) as Record<string, unknown>

package/src/modules/ai_assistant/lib/mcp-server.ts

@@ -5,6 +5,7 @@ import {
   CallToolRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
 import { toolInputJsonSchema } from './tool-input-schema'
+import { buildMcpToolAnnotations } from './mcp-tool-annotations'
 import { getToolRegistry } from './tool-registry'
 import { executeTool } from './tool-executor'
 import { loadAllModuleTools, indexToolsForSearch } from './tool-loader'
@@ -133,6 +134,7 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
         name: tool.name,
         description: tool.description,
         inputSchema: toolInputJsonSchema(tool.inputSchema),
+        annotations: buildMcpToolAnnotations(tool),
       })),
     }
   })

package/src/modules/ai_assistant/lib/mcp-tool-annotations.ts

@@ -0,0 +1,35 @@
+import type { AiToolDefinition, McpToolAnnotations, McpToolDefinition } from './types'
+
+/**
+ * Build the MCP annotations advertised for a registered tool.
+ *
+ * `readOnlyHint` follows the registry's existing mutation contract: a tool is
+ * read-only unless it declares `isMutation: true`. Every write tool is required
+ * to set that flag (see the module AGENTS.md) and the agent mutation-policy gate
+ * already reads it the same way.
+ *
+ * `destructiveHint` only carries meaning for mutating tools. A predicate
+ * `isDestructive` cannot be evaluated without call input, so it resolves to
+ * `true` rather than under-warning the client. When the flag is absent the hint
+ * is omitted so clients fall back to the conservative MCP default (`true`).
+ *
+ * `idempotentHint` is deliberately not emitted: no tool-definition field
+ * carries that information, so clients keep the MCP default (`false`).
+ */
+export function buildMcpToolAnnotations(tool: McpToolDefinition): McpToolAnnotations {
+  const definition = tool as AiToolDefinition
+
+  if (definition.isMutation !== true) {
+    return { readOnlyHint: true }
+  }
+
+  const { isDestructive } = definition
+  if (isDestructive === undefined) {
+    return { readOnlyHint: false }
+  }
+
+  return {
+    readOnlyHint: false,
+    destructiveHint: typeof isDestructive === 'function' ? true : isDestructive,
+  }
+}

package/src/modules/ai_assistant/lib/types.ts

@@ -249,6 +249,17 @@ export type ToolInfo = {
   name: string
   description: string
   inputSchema: Record<string, unknown>
+  /** MCP capability hints advertised for the tool (see `buildMcpToolAnnotations`). */
+  annotations?: McpToolAnnotations
+}
+
+/** MCP `ToolAnnotations` values carried through remote and in-process clients. */
+export type McpToolAnnotations = {
+  title?: string
+  readOnlyHint?: boolean
+  destructiveHint?: boolean
+  idempotentHint?: boolean
+  openWorldHint?: boolean
 }
 
 /**