@shipfox/api-integration-core 12.4.0 → 12.6.0

package/src/presentation/routes/agent-tools-gateway/mcp-server.test.ts

@@ -54,6 +54,7 @@ describe('buildAgentToolsMcpServer', () => {
         }),
         method: 'get',
         outcome: 'success',
+        errorCode: 'none',
       },
     ]);
   });
@@ -93,6 +94,7 @@ describe('buildAgentToolsMcpServer', () => {
       {
         method: expectedMethod,
         outcome: 'invalid-request',
+        errorCode: 'invalid-request',
       },
     ]);
     if (expectedToolId) {
@@ -128,7 +130,9 @@ describe('buildAgentToolsMcpServer', () => {
         arguments: {method: 'ignored'},
       }),
     );
-    expect(records).toMatchObject([{method: NO_METHOD_LABEL, outcome: 'success'}]);
+    expect(records).toMatchObject([
+      {method: NO_METHOD_LABEL, outcome: 'success', errorCode: 'none'},
+    ]);
   });
 
   it('defaults omitted arguments to an empty object for optional-argument tools', async () => {
@@ -179,7 +183,7 @@ describe('buildAgentToolsMcpServer', () => {
         arguments: expect.objectContaining({issue_number: 'not-an-integer'}),
       }),
     );
-    expect(records).toMatchObject([{method: 'get', outcome: 'success'}]);
+    expect(records).toMatchObject([{method: 'get', outcome: 'success', errorCode: 'none'}]);
   });
 
   it('records tool-error when dispatch returns an error result', async () => {
@@ -204,7 +208,7 @@ describe('buildAgentToolsMcpServer', () => {
     await close();
 
     expect(result.isError).toBe(true);
-    expect(records).toMatchObject([{method: 'get', outcome: 'tool-error'}]);
+    expect(records).toMatchObject([{method: 'get', outcome: 'tool-error', errorCode: 'unknown'}]);
   });
 
   it('records exception before rethrowing dispatcher failures', async () => {
@@ -227,7 +231,40 @@ describe('buildAgentToolsMcpServer', () => {
     ).rejects.toThrow('MCP error -32603');
     await close();
 
-    expect(records).toMatchObject([{method: 'get', outcome: 'exception'}]);
+    expect(records).toMatchObject([{method: 'get', outcome: 'exception', errorCode: 'unknown'}]);
+  });
+
+  it('records bounded provider error details returned by the dispatcher', async () => {
+    const dispatch = vi.fn(async () => ({
+      isError: true,
+      content: [{type: 'text' as const, text: 'provider rejected call'}],
+      structuredContent: {code: 'provider-rejected', status: 422},
+    }));
+    const records: Parameters<
+      NonNullable<Parameters<typeof buildAgentToolsMcpServer>[0]['recordCall']>
+    >[0][] = [];
+    const {client, close} = await connectClient(dispatch, defaultAuthorizedTools(), (record) =>
+      records.push(record),
+    );
+
+    const result = await client.callTool(
+      {
+        name: 'github_main__issue_read',
+        arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      },
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(result.isError).toBe(true);
+    expect(records).toMatchObject([
+      {
+        method: 'get',
+        outcome: 'tool-error',
+        errorCode: 'provider-rejected',
+        providerStatus: 422,
+      },
+    ]);
   });
 });
 

package/src/presentation/routes/agent-tools-gateway/mcp-server.ts

@@ -6,7 +6,13 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import {reportError} from '@shipfox/node-error-monitoring';
 import {logger} from '@shipfox/node-opentelemetry';
-import {INVALID_METHOD_LABEL, type IntegrationToolCallRecorder, NO_METHOD_LABEL} from './audit.js';
+import {normalizeIntegrationAgentToolCallErrorCode} from '#metrics/index.js';
+import {
+  INVALID_METHOD_LABEL,
+  type IntegrationAgentToolCallErrorCode,
+  type IntegrationToolCallRecorder,
+  NO_METHOD_LABEL,
+} from './audit.js';
 import type {
   AuthorizedIntegrationTool,
   AuthorizedIntegrationToolMap,
@@ -61,6 +67,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: request.params.arguments ?? {},
         method: NO_METHOD_LABEL,
         outcome: 'invalid-request',
+        errorCode: 'invalid-request',
       });
       return toolError(`Unknown integration tool: ${request.params.name}`);
     }
@@ -72,6 +79,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: args,
         method: NO_METHOD_LABEL,
         outcome: 'invalid-request',
+        errorCode: 'invalid-request',
       });
       return toolError('Tool arguments must be an object');
     }
@@ -83,6 +91,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: args,
         method: INVALID_METHOD_LABEL,
         outcome: 'invalid-request',
+        errorCode: 'invalid-request',
       });
       return toolError(methodValidation.message);
     }
@@ -99,6 +108,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: args,
         method,
         outcome: result.isError === true ? 'tool-error' : 'success',
+        ...toolCallErrorDetails(result),
       });
       return result;
     } catch (error) {
@@ -107,6 +117,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: args,
         method,
         outcome: 'exception',
+        errorCode: 'unknown',
       });
       throw error;
     }
@@ -115,6 +126,23 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
   return server;
 }
 
+function toolCallErrorDetails(result: CallToolResult): {
+  errorCode: IntegrationAgentToolCallErrorCode | 'none';
+  providerStatus?: number | undefined;
+} {
+  if (result.isError !== true) return {errorCode: 'none'};
+
+  const structuredContent = isRecord(result.structuredContent)
+    ? result.structuredContent
+    : undefined;
+  const providerStatus = statusCode(structuredContent?.status);
+
+  return {
+    errorCode: normalizeIntegrationAgentToolCallErrorCode(structuredContent?.code),
+    ...(providerStatus === undefined ? {} : {providerStatus}),
+  };
+}
+
 function recordToolCall(
   recordCall: IntegrationToolCallRecorder | undefined,
   record: Parameters<IntegrationToolCallRecorder>[0],
@@ -157,3 +185,9 @@ function toolError(message: string): CallToolResult {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+
+function statusCode(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599
+    ? value
+    : undefined;
+}

package/src/presentation/routes/errors.ts

@@ -28,6 +28,7 @@ function isProviderError(error: unknown): error is IntegrationProviderError {
         error.reason === 'rate-limited' ||
         error.reason === 'timeout' ||
         error.reason === 'provider-unavailable' ||
+        error.reason === 'provider-rejected' ||
         error.reason === 'malformed-provider-response' ||
         error.reason === 'content-too-large' ||
         error.reason === 'too-many-files'))