feat(mcp): support filtering tool results by a jq expression

Author: stainless-app[bot]

packages/mcp-server/package.json

@@ -29,6 +29,7 @@
   "dependencies": {
     "@flowglad/node": "file:../../dist/",
     "@modelcontextprotocol/sdk": "^1.11.5",
+    "jq-web": "^0.6.2",
     "yargs": "^17.7.2",
     "@cloudflare/cabidela": "^0.2.4",
     "zod": "^3.25.20",

packages/mcp-server/src/filtering.ts

@@ -0,0 +1,13 @@
+export async function maybeFilter(args: Record<string, unknown> | undefined, response: any): Promise<any> {
+  const jqFilter = args?.['jq_filter'];
+  if (jqFilter && typeof jqFilter === 'string') {
+    return await jq(response, jqFilter);
+  } else {
+    return response;
+  }
+}
+
+var jqWeb = require('jq-web');
+async function jq(json: any, jqFilter: string) {
+  return (await jqWeb).json(json, jqFilter);
+}

packages/mcp-server/src/tools/catalogs/clone-catalogs.ts

@@ -17,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'clone_catalogs',
-  description: 'Clone a Catalog',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nClone a Catalog",
   inputSchema: {
     type: 'object',
     properties: {

packages/mcp-server/src/tools/catalogs/create-catalogs.ts

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { maybeFilter } from '@flowglad/node-mcp/filtering';
 import { asTextContentResult } from '@flowglad/node-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
@@ -17,7 +18,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'create_catalogs',
-  description: 'Create Catalog',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nCreate Catalog\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    catalog: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        createdAt: {\n          anyOf: [            {\n              type: 'string',\n              format: 'date-time'\n            },\n            {\n              type: 'string'\n            }\n          ],\n          description: 'safeZodDate'\n        },\n        createdByCommit: {\n          type: 'string'\n        },\n        isDefault: {\n          type: 'boolean'\n        },\n        livemode: {\n          type: 'boolean'\n        },\n        name: {\n          type: 'string'\n        },\n        organizationId: {\n          type: 'string'\n        },\n        updatedAt: {\n          anyOf: [            {\n              type: 'string',\n              format: 'date-time'\n            },\n            {\n              type: 'string'\n            }\n          ],\n          description: 'safeZodDate'\n        },\n        updatedByCommit: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        'createdAt',\n        'createdByCommit',\n        'isDefault',\n        'livemode',\n        'name',\n        'organizationId',\n        'updatedAt',\n        'updatedByCommit'\n      ]\n    }\n  },\n  required: [    'catalog'\n  ]\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -33,13 +35,19 @@ export const tool: Tool = {
         },
         required: ['name'],
       },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
   },
 };
 
 export const handler = async (client: Flowglad, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return asTextContentResult(await client.catalogs.create(body));
+  return asTextContentResult(await maybeFilter(args, await client.catalogs.create(body)));
 };
 
 export default { metadata, tool, handler };

packages/mcp-server/src/tools/catalogs/list-catalogs.ts

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { maybeFilter } from '@flowglad/node-mcp/filtering';
 import { asTextContentResult } from '@flowglad/node-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
@@ -17,7 +18,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'list_catalogs',
-  description: 'List Catalogs',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nList Catalogs\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        type: 'object',\n        properties: {\n          id: {\n            type: 'string'\n          },\n          createdAt: {\n            anyOf: [              {\n                type: 'string',\n                format: 'date-time'\n              },\n              {\n                type: 'string'\n              }\n            ],\n            description: 'safeZodDate'\n          },\n          createdByCommit: {\n            type: 'string'\n          },\n          isDefault: {\n            type: 'boolean'\n          },\n          livemode: {\n            type: 'boolean'\n          },\n          name: {\n            type: 'string'\n          },\n          organizationId: {\n            type: 'string'\n          },\n          updatedAt: {\n            anyOf: [              {\n                type: 'string',\n                format: 'date-time'\n              },\n              {\n                type: 'string'\n              }\n            ],\n            description: 'safeZodDate'\n          },\n          updatedByCommit: {\n            type: 'string'\n          }\n        },\n        required: [          'id',\n          'createdAt',\n          'createdByCommit',\n          'isDefault',\n          'livemode',\n          'name',\n          'organizationId',\n          'updatedAt',\n          'updatedByCommit'\n        ]\n      }\n    },\n    hasMore: {\n      type: 'boolean'\n    },\n    total: {\n      type: 'number'\n    },\n    currentCursor: {\n      type: 'string'\n    },\n    nextCursor: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'hasMore',\n    'total'\n  ]\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -27,13 +29,19 @@ export const tool: Tool = {
       limit: {
         type: 'number',
       },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
   },
 };
 
 export const handler = async (client: Flowglad, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return asTextContentResult(await client.catalogs.list(body));
+  return asTextContentResult(await maybeFilter(args, await client.catalogs.list(body)));
 };
 
 export default { metadata, tool, handler };

packages/mcp-server/src/tools/catalogs/retrieve-catalogs.ts

@@ -17,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'retrieve_catalogs',
-  description: 'Get Catalog',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nGet Catalog",
   inputSchema: {
     type: 'object',
     properties: {

packages/mcp-server/src/tools/catalogs/retrieve-default-catalogs.ts

@@ -17,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'retrieve_default_catalogs',
-  description: 'Get Default Catalog for Organization',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nGet Default Catalog for Organization",
   inputSchema: {
     type: 'object',
     properties: {},

packages/mcp-server/src/tools/catalogs/update-catalogs.ts

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { maybeFilter } from '@flowglad/node-mcp/filtering';
 import { asTextContentResult } from '@flowglad/node-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
@@ -17,7 +18,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'update_catalogs',
-  description: 'Update Catalog',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nUpdate Catalog\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    catalog: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        createdAt: {\n          anyOf: [            {\n              type: 'string',\n              format: 'date-time'\n            },\n            {\n              type: 'string'\n            }\n          ],\n          description: 'safeZodDate'\n        },\n        createdByCommit: {\n          type: 'string'\n        },\n        isDefault: {\n          type: 'boolean'\n        },\n        livemode: {\n          type: 'boolean'\n        },\n        name: {\n          type: 'string'\n        },\n        organizationId: {\n          type: 'string'\n        },\n        updatedAt: {\n          anyOf: [            {\n              type: 'string',\n              format: 'date-time'\n            },\n            {\n              type: 'string'\n            }\n          ],\n          description: 'safeZodDate'\n        },\n        updatedByCommit: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        'createdAt',\n        'createdByCommit',\n        'isDefault',\n        'livemode',\n        'name',\n        'organizationId',\n        'updatedAt',\n        'updatedByCommit'\n      ]\n    }\n  },\n  required: [    'catalog'\n  ]\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -39,13 +41,19 @@ export const tool: Tool = {
         },
         required: ['id'],
       },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
   },
 };
 
 export const handler = async (client: Flowglad, args: Record<string, unknown> | undefined) => {
   const { id, ...body } = args as any;
-  return asTextContentResult(await client.catalogs.update(id, body));
+  return asTextContentResult(await maybeFilter(args, await client.catalogs.update(id, body)));
 };
 
 export default { metadata, tool, handler };

packages/mcp-server/src/tools/checkout-sessions/create-checkout-sessions.ts

@@ -17,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'create_checkout_sessions',
-  description: 'Create Checkout Session',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nCreate Checkout Session",
   inputSchema: {
     type: 'object',
     properties: {

packages/mcp-server/src/tools/checkout-sessions/list-checkout-sessions.ts

@@ -17,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'list_checkout_sessions',
-  description: 'List Checkout Sessions',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nList Checkout Sessions",
   inputSchema: {
     type: 'object',
     properties: {