feat: onToolCall callback (#146)

* feat: `onToolCall` in mcp-utils

* test: `onToolCall` in mcp-utils

* feat: forward `onToolCall` through mcp-server-supabase

* chore: cleanup

* test: rename with "and errors"

Co-authored-by: Greg Richardson <[email protected]>

* fix: make `onToolCall` non-blocking

* fix: no async `onToolCall`

* feat: re-export `ToolCallCallback` type

* feat: include arguments, data, error in tool call details

---------

Co-authored-by: Greg Richardson <[email protected]>

Author: mattrossman

packages/mcp-server-supabase/src/index.ts

@@ -1,5 +1,6 @@
 import packageJson from '../package.json' with { type: 'json' };
 
+export type { ToolCallCallback } from '@supabase/mcp-utils';
 export type { SupabasePlatform } from './platform/index.js';
 export {
   createSupabaseMcpServer,

packages/mcp-server-supabase/src/server.ts

@@ -1,4 +1,8 @@
-import { createMcpServer, type Tool } from '@supabase/mcp-utils';
+import {
+  createMcpServer,
+  type Tool,
+  type ToolCallCallback,
+} from '@supabase/mcp-utils';
 import packageJson from '../package.json' with { type: 'json' };
 import { createContentApiClient } from './content-api/index.js';
 import type { SupabasePlatform } from './platform/types.js';
@@ -44,6 +48,11 @@ export type SupabaseMcpServerOptions = {
    * Options: 'account', 'branching', 'database', 'debugging', 'development', 'docs', 'functions', 'storage'
    */
   features?: string[];
+
+  /**
+   * Callback for after a supabase tool is called.
+   */
+  onToolCall?: ToolCallCallback;
 };
 
 const DEFAULT_FEATURES: FeatureGroup[] = [
@@ -68,6 +77,7 @@ export function createSupabaseMcpServer(options: SupabaseMcpServerOptions) {
     readOnly,
     features,
     contentApiUrl = 'https://supabase.com/docs/api/graphql',
+    onToolCall,
   } = options;
 
   const contentApiClientPromise = createContentApiClient(contentApiUrl, {
@@ -104,6 +114,7 @@ export function createSupabaseMcpServer(options: SupabaseMcpServerOptions) {
         ),
       ]);
     },
+    onToolCall,
     tools: async () => {
       const contentApiClient = await contentApiClientPromise;
       const tools: Record<string, Tool> = {};

packages/mcp-utils/src/server.test.ts

@@ -4,7 +4,7 @@ import {
   CallToolResultSchema,
   type CallToolRequest,
 } from '@modelcontextprotocol/sdk/types.js';
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 import { z } from 'zod';
 import {
   createMcpServer,
@@ -114,6 +114,111 @@ describe('tools', () => {
       caseSensitive: false,
     });
   });
+
+  test('tool callback is called for success and errors', async () => {
+    const onToolCall = vi.fn();
+
+    const server = createMcpServer({
+      name: 'test-server',
+      version: '0.0.0',
+      onToolCall,
+      tools: {
+        good_tool: tool({
+          description: 'A tool that always succeeds',
+          annotations: {
+            title: 'Good tool',
+            readOnlyHint: true,
+          },
+          parameters: z.object({ foo: z.string() }),
+          execute: async ({ foo }) => {
+            return `Success: ${foo}`;
+          },
+        }),
+        bad_tool: tool({
+          description: 'A tool that always fails',
+          annotations: {
+            title: 'Bad tool',
+            readOnlyHint: true,
+          },
+          parameters: z.object({ foo: z.string() }),
+          execute: async ({ foo }) => {
+            throw new Error('Failure: ' + foo);
+          },
+        }),
+      },
+    });
+
+    const { callTool } = await setup({ server });
+
+    const goodToolPromise = callTool({
+      name: 'good_tool',
+      arguments: { foo: 'bar' },
+    });
+
+    await expect(goodToolPromise).resolves.toEqual('Success: bar');
+    expect(onToolCall).toHaveBeenLastCalledWith({
+      name: 'good_tool',
+      arguments: { foo: 'bar' },
+      annotations: {
+        title: 'Good tool',
+        readOnlyHint: true,
+      },
+      success: true,
+      data: 'Success: bar',
+    });
+
+    const badToolPromise = callTool({
+      name: 'bad_tool',
+      arguments: { foo: 'bar' },
+    });
+
+    await expect(badToolPromise).rejects.toThrow('Failure: bar');
+    expect(onToolCall).toHaveBeenLastCalledWith({
+      name: 'bad_tool',
+      arguments: { foo: 'bar' },
+      annotations: {
+        title: 'Bad tool',
+        readOnlyHint: true,
+      },
+      success: false,
+      error: expect.any(Error),
+    });
+  });
+
+  test("tool callback error doesn't fail the tool call", async () => {
+    const onToolCall = vi.fn(() => {
+      throw new Error('Tool callback failed');
+    });
+
+    const server = createMcpServer({
+      name: 'test-server',
+      version: '0.0.0',
+      onToolCall,
+      tools: {
+        good_tool: tool({
+          description: 'A tool that always succeeds',
+          annotations: {
+            title: 'Good tool',
+            readOnlyHint: true,
+          },
+          parameters: z.object({ foo: z.string() }),
+          execute: async ({ foo }) => {
+            return `Success: ${foo}`;
+          },
+        }),
+      },
+    });
+
+    const { callTool } = await setup({ server });
+
+    const goodToolPromise = callTool({
+      name: 'good_tool',
+      arguments: { foo: 'bar' },
+    });
+
+    await expect(goodToolPromise).resolves.toEqual('Success: bar');
+    expect(onToolCall.mock.results[0]?.type).toBe('throw');
+  });
 });
 
 describe('resources helper', () => {

packages/mcp-utils/src/server.ts

@@ -175,7 +175,26 @@ export type InitData = {
   clientCapabilities: ClientCapabilities;
 };
 
+type ToolCallBaseDetails = {
+  name: string;
+  arguments: Record<string, unknown>;
+  annotations?: Annotations;
+};
+
+type ToolCallSuccessDetails = ToolCallBaseDetails & {
+  success: true;
+  data: unknown;
+};
+
+type ToolCallErrorDetails = ToolCallBaseDetails & {
+  success: false;
+  error: unknown;
+};
+
+export type ToolCallDetails = ToolCallSuccessDetails | ToolCallErrorDetails;
+
 export type InitCallback = (initData: InitData) => void | Promise<void>;
+export type ToolCallCallback = (details: ToolCallDetails) => void;
 export type PropCallback<T> = () => T | Promise<T>;
 export type Prop<T> = T | PropCallback<T>;
 
@@ -205,6 +224,11 @@ export type McpServerOptions = {
    */
   onInitialize?: InitCallback;
 
+  /**
+   * Callback for after a tool is called.
+   */
+  onToolCall?: ToolCallCallback;
+
   /**
    * Resources to be served by the server. These can be defined as a static
    * object or as a function that dynamically returns the object synchronously
@@ -452,7 +476,34 @@ export function createMcpServer(options: McpServerOptions) {
           .strict()
           .parse(request.params.arguments ?? {});
 
-        const result = await tool.execute(args);
+        const executeWithCallback = async (tool: Tool) => {
+          // Wrap success or error in a result value
+          const res = await tool
+            .execute(args)
+            .then((data: unknown) => ({ success: true as const, data }))
+            .catch((error) => ({ success: false as const, error }));
+
+          try {
+            options.onToolCall?.({
+              name: toolName,
+              arguments: args,
+              annotations: tool.annotations,
+              ...res,
+            });
+          } catch (error) {
+            // Don't fail the tool call if the callback fails
+            console.error('Failed to run tool callback', error);
+          }
+
+          // Unwrap result
+          if (!res.success) {
+            throw res.error;
+          }
+          return res.data;
+        };
+
+        const result = await executeWithCallback(tool);
+
         const content = result
           ? [{ type: 'text', text: JSON.stringify(result) }]
           : [];