@opensaas/stack-core 0.39.2 → 0.40.0

package/src/mcp/handler.ts

@@ -1,8 +1,18 @@
 import * as z from 'zod'
-import type { OpenSaasConfig, FieldConfig, McpCustomTool } from '../config/types.js'
+import type { OpenSaasConfig, McpCustomTool } from '../config/types.js'
 import type { AccessContext } from '../access/types.js'
+import { checkAccess } from '../access/engine.js'
+import { AccessScopeDepthExceededError, RelationFilterAccessDeniedError } from '../access/errors.js'
+import { ValidationError } from '../hooks/index.js'
 import { getDbKey } from '../lib/case-utils.js'
 import type { McpSession, McpSessionProvider } from './types.js'
+import { generateFieldSchemas } from './field-schema.js'
+import {
+  McpProjectionRefusedError,
+  generateFieldsProjectionSchema,
+  projectMcpResult,
+  resolveFieldsProjection,
+} from './projection.js'
 
 /**
  * Context session type accepted by the generated getContext factory.
@@ -119,7 +129,8 @@ export function createMcpHandlers(options: {
       }
 
       if (body.method === 'tools/list') {
-        return handleToolsList(config, body.id)
+        const context = await getContext(toContextSession(session))
+        return await handleToolsList(config, context, body.id)
       }
 
       if (body.method === 'tools/call') {
@@ -194,91 +205,24 @@ function handleInitialize(_params?: any, id?: number | string): Response {
   )
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field configs have varying structures
-function fieldToJsonSchema(fieldName: string, fieldConfig: any): Record<string, unknown> {
-  const baseSchema: Record<string, unknown> = {}
-
-  switch (fieldConfig.type) {
-    case 'text':
-    case 'password':
-      baseSchema.type = 'string'
-      if (fieldConfig.validation?.length) {
-        if (fieldConfig.validation.length.min)
-          baseSchema.minLength = fieldConfig.validation.length.min
-        if (fieldConfig.validation.length.max)
-          baseSchema.maxLength = fieldConfig.validation.length.max
-      }
-      break
-    case 'integer':
-      baseSchema.type = 'number'
-      if (fieldConfig.validation?.min !== undefined) baseSchema.minimum = fieldConfig.validation.min
-      if (fieldConfig.validation?.max !== undefined) baseSchema.maximum = fieldConfig.validation.max
-      break
-    case 'checkbox':
-      baseSchema.type = 'boolean'
-      break
-    case 'timestamp':
-      baseSchema.type = 'string'
-      baseSchema.format = 'date-time'
-      break
-    case 'select':
-      baseSchema.type = 'string'
-      if (fieldConfig.options) {
-        baseSchema.enum = fieldConfig.options.map((opt: { value: string }) => opt.value)
-      }
-      break
-    case 'relationship':
-      baseSchema.type = 'object'
-      baseSchema.properties = {
-        connect: {
-          type: 'object',
-          properties: {
-            id: { type: 'string' },
-          },
-        },
-      }
-      break
-    default:
-      baseSchema.type = 'string'
-  }
-
-  return baseSchema
-}
-
-function generateFieldSchemas(
-  fields: Record<string, FieldConfig>,
-  operation: 'create' | 'update',
-): {
-  properties: Record<string, unknown>
-  required: string[]
-} {
-  const properties: Record<string, unknown> = {}
-  const required: string[] = []
-
-  for (const [fieldName, fieldConfig] of Object.entries(fields)) {
-    if (['id', 'createdAt', 'updatedAt'].includes(fieldName)) continue
-
-    properties[fieldName] = fieldToJsonSchema(fieldName, fieldConfig)
-
-    if (
-      operation === 'create' &&
-      'validation' in fieldConfig &&
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Validation property varies by field type
-      (fieldConfig.validation as any)?.isRequired
-    ) {
-      required.push(fieldName)
-    }
-  }
-
-  return { properties, required }
-}
-
-function handleToolsList(config: OpenSaasConfig, id?: number | string): Response {
+async function handleToolsList(
+  config: OpenSaasConfig,
+  context: AccessContext,
+  id?: number | string,
+): Promise<Response> {
   const tools: McpTool[] = []
 
   for (const [listKey, listConfig] of Object.entries(config.lists)) {
     if (listConfig.mcp?.enabled === false) continue
 
+    // A session denied operation-level `query` outright sees none of this
+    // list's tools, nor any relation entry elsewhere pointing at it as a
+    // target (`relatedListIfVisible` in projection.ts applies the identical
+    // check there) — ADR-0033.
+    const queryAccess = listConfig.access?.operation?.query
+    const accessResult = await checkAccess(queryAccess, { session: context.session, context })
+    if (accessResult === false) continue
+
     const dbKey = getDbKey(listKey)
     const defaultTools = config.mcp?.defaultTools || {
       read: true,
@@ -295,6 +239,12 @@ function handleToolsList(config: OpenSaasConfig, id?: number | string): Response
     }
 
     if (enabledTools.read) {
+      const fieldsSchema = await generateFieldsProjectionSchema(
+        listConfig,
+        config,
+        context.session,
+        context,
+      )
       tools.push({
         name: `list_${dbKey}_query`,
         description: `Query ${listKey} records with optional filters`,
@@ -305,6 +255,7 @@ function handleToolsList(config: OpenSaasConfig, id?: number | string): Response
             take: { type: 'number', description: 'Number of records to return (max 100)' },
             skip: { type: 'number', description: 'Number of records to skip' },
             orderBy: { type: 'object', description: 'Sort order' },
+            fields: fieldsSchema,
           },
         },
       })
@@ -462,27 +413,60 @@ async function handleCrudTool(
     let result: any
 
     switch (operation) {
-      case 'query':
+      case 'query': {
+        let projection: Awaited<ReturnType<typeof resolveFieldsProjection>> | undefined
+        if (args.fields !== undefined) {
+          const listEntry = Object.entries(config.lists).find(
+            ([listKey]) => getDbKey(listKey) === dbKey,
+          )
+          if (!listEntry) {
+            return createErrorResponse(`Unknown list for tool: ${dbKey}`, id)
+          }
+          const [listKey, listConfig] = listEntry
+          try {
+            projection = await resolveFieldsProjection(
+              args.fields,
+              listKey,
+              listConfig,
+              config,
+              context.session,
+              context,
+            )
+          } catch (error) {
+            if (error instanceof McpProjectionRefusedError || error instanceof ValidationError) {
+              return createErrorResultResponse(error.message, id)
+            }
+            throw error
+          }
+        }
+
         result = await context.db[dbKey].findMany({
           where: args.where,
           take: Math.min(args.take || 10, 100),
           skip: args.skip,
           orderBy: args.orderBy,
+          ...(projection?.include ? { include: projection.include } : {}),
         })
+
+        const items = projection
+          ? result.map((item: Record<string, unknown>) => projectMcpResult(item, projection))
+          : result
+
         return createSuccessResponse(
           {
-            items: result,
-            count: result.length,
+            items,
+            count: items.length,
           },
           id,
         )
+      }
 
       case 'create':
         result = await context.db[dbKey].create({
           data: args.data,
         })
         if (!result) {
-          return createErrorResponse(
+          return createErrorResultResponse(
             'Failed to create record. Access denied or validation failed.',
             id,
           )
@@ -495,7 +479,7 @@ async function handleCrudTool(
           data: args.data,
         })
         if (!result) {
-          return createErrorResponse(
+          return createErrorResultResponse(
             'Failed to update record. Access denied or record not found.',
             id,
           )
@@ -507,7 +491,7 @@ async function handleCrudTool(
           where: args.where,
         })
         if (!result) {
-          return createErrorResponse(
+          return createErrorResultResponse(
             'Failed to delete record. Access denied or record not found.',
             id,
           )
@@ -518,7 +502,13 @@ async function handleCrudTool(
         return createErrorResponse(`Unknown operation: ${operation}`, id)
     }
   } catch (error) {
-    return createErrorResponse(
+    if (
+      error instanceof AccessScopeDepthExceededError ||
+      error instanceof RelationFilterAccessDeniedError
+    ) {
+      return createErrorResultResponse(error.message, id)
+    }
+    return createErrorResultResponse(
       'Operation failed: ' + (error instanceof Error ? error.message : 'Unknown error'),
       id,
     )
@@ -550,20 +540,7 @@ async function handleCustomTool(
   if (isZodSchema(customTool.inputSchema)) {
     const parsed = customTool.inputSchema.safeParse(args)
     if (!parsed.success) {
-      return new Response(
-        JSON.stringify({
-          jsonrpc: '2.0',
-          id: id ?? null,
-          error: {
-            code: -32602,
-            message: `Invalid params: ${parsed.error.message}`,
-          },
-        }),
-        {
-          status: 400,
-          headers: { 'Content-Type': 'application/json' },
-        },
-      )
+      return createErrorResultResponse(`Invalid params: ${parsed.error.message}`, id)
     }
     input = parsed.data
   }
@@ -578,7 +555,7 @@ async function handleCustomTool(
 
     return createSuccessResponse(result, id)
   } catch (error) {
-    return createErrorResponse(
+    return createErrorResultResponse(
       'Custom tool execution failed: ' + (error instanceof Error ? error.message : 'Unknown error'),
       id,
     )
@@ -597,15 +574,39 @@ function mcpJsonReplacer(_key: string, value: unknown): unknown {
   return typeof value === 'bigint' ? value.toString() : value
 }
 
+function toToolContent(data: unknown): { type: 'text'; text: string }[] {
+  const text = typeof data === 'string' ? data : JSON.stringify(data, mcpJsonReplacer, 2)
+  return [{ type: 'text', text }]
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Response data structure is flexible per MCP protocol
 function createSuccessResponse(data: any, id?: number | string): Response {
   return new Response(
     JSON.stringify({
       jsonrpc: '2.0',
       id: id ?? null,
-      result: {
-        content: [{ type: 'text', text: JSON.stringify(data, mcpJsonReplacer, 2) }],
-      },
+      result: { content: toToolContent(data) },
+    }),
+    {
+      headers: { 'Content-Type': 'application/json' },
+    },
+  )
+}
+
+/**
+ * A dispatched tool that failed — access denial, a thrown engine/database
+ * error, or custom-tool input validation. This is a successful JSON-RPC
+ * response (HTTP 200, no `error` member): the model that called the tool
+ * needs to see the failure in `result` to have any chance of correcting its
+ * request, whereas a JSON-RPC `error` object is a protocol-level failure a
+ * host may never surface back to it.
+ */
+function createErrorResultResponse(message: string, id?: number | string): Response {
+  return new Response(
+    JSON.stringify({
+      jsonrpc: '2.0',
+      id: id ?? null,
+      result: { content: toToolContent(message), isError: true },
     }),
     {
       headers: { 'Content-Type': 'application/json' },
@@ -613,6 +614,7 @@ function createSuccessResponse(data: any, id?: number | string): Response {
   )
 }
 
+/** Genuine JSON-RPC protocol failures — unknown method, malformed request, unknown tool name. */
 function createErrorResponse(message: string, id?: number | string): Response {
   return new Response(
     JSON.stringify({