[CPL-20880] Provide guidance for errors

src/tools/get-dataflow/handler.test.ts

@@ -23,6 +23,10 @@ const mockGetDataflowError = createMockResponse(
   async () => new Response('Error when getting dataflow', { status: 500 })
 )
 
+const mockGetDataflowErrorWithDetails = createMockResponse(
+  async () => new Response(JSON.stringify({ error: { message: 'Test error message' } }), { status: 500 })
+) 
+
 const mockFetch = vi.spyOn(globalThis, 'fetch')
 
 describe('get-dataflow', () => {
@@ -63,7 +67,22 @@ describe('get-dataflow', () => {
         isError: true,
         content: [{
           type: 'text',
-          text: 'Failed to get data flow gsheet_dataflow. Response status: 500',
+          text: 'Failed to get data flow gsheet_dataflow. Response status: 500.',
+        }]
+      })
+    })
+
+    it('includes error details when present', async () => {
+      mockFetch
+        .mockImplementationOnce(mockGetDataflowErrorWithDetails)
+
+      const toolResult = await handler({ dataflowId: 'gsheet_dataflow' })
+
+      expect(toolResult).toEqual({
+        isError: true,
+        content: [{
+          type: 'text',
+          text: 'Failed to get data flow gsheet_dataflow. Response status: 500. Error details: Test error message',
         }]
       })
     })

src/tools/get-dataflow/handler.ts

@@ -3,7 +3,7 @@ import { fromError } from 'zod-validation-error'
 
 import { zodInputSchema } from './schema.js'
 
-import { textResponse } from '../../util/tool-response.js'
+import { textResponse, buildErrorMessage } from '../../util/tool-response.js'
 import { COUPLER_ACCESS_TOKEN } from '../../env.js'
 import { CouplerioClient } from '../../lib/couplerio-client/index.js'
 import { logger } from '../../logger/index.js'
@@ -33,10 +33,12 @@ export const handler = async (params?: Record<string, unknown>): Promise<CallToo
   })
 
   if (!response.ok) {
-    logger.error(`Failed to get data flow ${validationResult.data.dataflowId}. Response status: ${response.status}`)
+    const errorText = await buildErrorMessage( { response, customText: `Failed to get data flow ${validationResult.data.dataflowId}.`})
+
+    logger.error(errorText)
     return textResponse({
       isError: true,
-      text: `Failed to get data flow ${validationResult.data.dataflowId}. Response status: ${response.status}`
+      text: errorText
     })
   }
 

src/tools/list-dataflows/handler.test.ts

@@ -23,6 +23,12 @@ const mockListDataflowsError = createMockResponse(
   async () => new Response('Error listing dataflows', { status: 500 })
 )
 
+const mockGetDataflowErrorWithDetails = createMockResponse(
+  async () => new Response(
+    JSON.stringify({ error: { message: 'Test error message' } }), { status: 500 }
+  )
+)
+
 const mockFetch = vi.spyOn(globalThis, 'fetch')
 
 describe('listDataflows', () => {
@@ -63,7 +69,22 @@ describe('listDataflows', () => {
         isError: true,
         content: [{
           type: 'text',
-          text: 'Failed to list data flows. Response status: 500',
+          text: 'Failed to list data flows. Response status: 500.',
+        }]
+      })
+    })
+
+    it('includes error details when present', async () => {
+      mockFetch
+        .mockImplementationOnce(mockGetDataflowErrorWithDetails)
+
+      const toolResult = await handler()
+
+      expect(toolResult).toEqual({
+        isError: true,
+        content: [{
+          type: 'text',
+          text: 'Failed to list data flows. Response status: 500. Error details: Test error message',
         }]
       })
     })

src/tools/list-dataflows/handler.ts

@@ -1,6 +1,6 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 
-import { textResponse } from '../../util/tool-response.js'
+import { textResponse, buildErrorMessage } from '../../util/tool-response.js'
 import { COUPLER_ACCESS_TOKEN } from '../../env.js'
 import { CouplerioClient } from '../../lib/couplerio-client/index.js'
 import { logger } from '../../logger/index.js'
@@ -12,10 +12,12 @@ export const handler = async (): Promise<CallToolResult> => {
   const response = await coupler.request(`/dataflows?${query}{?type}`)
 
   if (!response.ok) {
-    logger.error(`Failed to list dataflows. Response status: ${response.status}`)
+    const errorText = await buildErrorMessage({ response, customText: 'Failed to list data flows.'})
+
+    logger.error(errorText)
     return textResponse({
       isError: true,
-      text: `Failed to list data flows. Response status: ${response.status}`
+      text: errorText
     })
   }
 

src/util/tool-response.ts

@@ -1,4 +1,5 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import { logger } from '../logger/index.js'
 
 export const textResponse = ({ text, isError = false, structuredContent }: { text: string, isError?: boolean, structuredContent?: Record<string, unknown> }) => {
   const callToolResult: CallToolResult = {
@@ -17,3 +18,24 @@ export const textResponse = ({ text, isError = false, structuredContent }: { tex
 
   return callToolResult
 }
+
+export const buildErrorMessage = async ({
+  response,
+  customText = 'An unexpected error occurred.',
+}: {
+  response: Response,
+  customText: string,
+}): Promise<string> => {
+  let errorDetails = ''
+
+  try {
+    const { error } = await response.json() as { error?: { message?: string } }
+    errorDetails = error?.message ?? ''
+  } catch (err){
+    // Does not update for JSON parse errors
+    logger.error('Failed to parse JSON response', err)
+  }
+
+  return `${customText} Response status: ${response.status}.` +
+         (errorDetails ? ` Error details: ${errorDetails}` : '')
+}