@tryfinch/finch-api-mcp 6.30.0 → 7.0.0

package/src/tools/sandbox/directory/create-sandbox-directory.ts

@@ -1,18 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'sandbox.directory',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/sandbox/directory',
+  operationId: 'post-sandbox-directory',
 };
 
 export const tool: Tool = {
   name: 'create_sandbox_directory',
-  description: 'Add new individuals to a sandbox company',
+  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\nAdd new individuals to a sandbox company\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/directory_create_response',\n  $defs: {\n    directory_create_response: {\n      type: 'array',\n      description: 'The individuals which were created',\n      items: {\n        type: 'object',\n        additionalProperties: true\n      }\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -39,9 +45,9 @@ export const tool: Tool = {
                   },
                   value: {
                     type: 'object',
+                    additionalProperties: true,
                   },
                 },
-                required: [],
               },
             },
             department: {
@@ -53,7 +59,6 @@ export const tool: Tool = {
                   description: 'The name of the department associated with the individual.',
                 },
               },
-              required: [],
             },
             dob: {
               type: 'string',
@@ -72,7 +77,6 @@ export const tool: Tool = {
                     enum: ['work', 'personal'],
                   },
                 },
-                required: [],
               },
             },
             employment: {
@@ -82,7 +86,7 @@ export const tool: Tool = {
                 subtype: {
                   type: 'string',
                   description:
-                    '\tThe secondary employment type of the individual. Options: `full_time`, `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`.',
+                    'The secondary employment type of the individual. Options: `full_time`, `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`.',
                   enum: ['full_time', 'intern', 'part_time', 'temp', 'seasonal', 'individual_contractor'],
                 },
                 type: {
@@ -91,11 +95,11 @@ export const tool: Tool = {
                   enum: ['employee', 'contractor'],
                 },
               },
-              required: [],
             },
             employment_status: {
               type: 'string',
-              description: 'The detailed employment status of the individual.',
+              description:
+                'The detailed employment status of the individual. Available options: `active`, `deceased`, `leave`, `onboarding`, `prehire`, `retired`, `terminated`.',
               enum: ['active', 'deceased', 'leave', 'onboarding', 'prehire', 'retired', 'terminated'],
             },
             encrypted_ssn: {
@@ -164,7 +168,6 @@ export const tool: Tool = {
                   description: 'A stable Finch `id` (UUID v4) for an individual in the company.',
                 },
               },
-              required: [],
             },
             middle_name: {
               type: 'string',
@@ -183,7 +186,6 @@ export const tool: Tool = {
                     enum: ['work', 'personal'],
                   },
                 },
-                required: [],
               },
             },
             preferred_name: {
@@ -211,10 +213,16 @@ export const tool: Tool = {
               description: 'The current title of the individual.',
             },
           },
-          required: [],
         },
       },
+      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/).',
+      },
     },
+    required: [],
     $defs: {
       income: {
         type: 'object',
@@ -233,6 +241,7 @@ export const tool: Tool = {
           effective_date: {
             type: 'string',
             description: 'The date the income amount went into effect.',
+            format: 'date',
           },
           unit: {
             type: 'string',
@@ -292,11 +301,19 @@ export const tool: Tool = {
       },
     },
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.directory.create(body['body']);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await client.sandbox.directory.create(body)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/sandbox/employment/update-sandbox-employment.ts

@@ -1,13 +1,17 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'sandbox.employment',
   operation: 'write',
   tags: [],
+  httpMethod: 'put',
+  httpPath: '/sandbox/employment/{individual_id}',
+  operationId: 'put-sandbox-employment-individual_id',
 };
 
 export const tool: Tool = {
@@ -35,9 +39,9 @@ export const tool: Tool = {
             },
             value: {
               type: 'object',
+              additionalProperties: true,
             },
           },
-          required: [],
         },
       },
       department: {
@@ -49,7 +53,6 @@ export const tool: Tool = {
             description: 'The name of the department associated with the individual.',
           },
         },
-        required: [],
       },
       employment: {
         type: 'object',
@@ -58,7 +61,7 @@ export const tool: Tool = {
           subtype: {
             type: 'string',
             description:
-              '\tThe secondary employment type of the individual. Options: `full_time`, `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`.',
+              'The secondary employment type of the individual. Options: `full_time`, `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`.',
             enum: ['full_time', 'intern', 'part_time', 'temp', 'seasonal', 'individual_contractor'],
           },
           type: {
@@ -67,11 +70,11 @@ export const tool: Tool = {
             enum: ['employee', 'contractor'],
           },
         },
-        required: [],
       },
       employment_status: {
         type: 'string',
-        description: 'The detailed employment status of the individual.',
+        description:
+          'The detailed employment status of the individual. Available options: `active`, `deceased`, `leave`, `onboarding`, `prehire`, `retired`, `terminated`.',
         enum: ['active', 'deceased', 'leave', 'onboarding', 'prehire', 'retired', 'terminated'],
       },
       end_date: {
@@ -116,7 +119,6 @@ export const tool: Tool = {
             description: 'A stable Finch `id` (UUID v4) for an individual in the company.',
           },
         },
-        required: [],
       },
       middle_name: {
         type: 'string',
@@ -135,6 +137,7 @@ export const tool: Tool = {
         description: 'The current title of the individual.',
       },
     },
+    required: ['individual_id'],
     $defs: {
       income: {
         type: 'object',
@@ -153,6 +156,7 @@ export const tool: Tool = {
           effective_date: {
             type: 'string',
             description: 'The date the income amount went into effect.',
+            format: 'date',
           },
           unit: {
             type: 'string',
@@ -212,11 +216,21 @@ export const tool: Tool = {
       },
     },
   },
+  annotations: {
+    idempotentHint: true,
+  },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
   const { individual_id, ...body } = args as any;
-  return client.sandbox.employment.update(individual_id, body);
+  try {
+    return asTextContentResult(await client.sandbox.employment.update(individual_id, body));
+  } catch (error) {
+    if (error instanceof Finch.APIError) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/sandbox/individual/update-sandbox-individual.ts

@@ -1,18 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'sandbox.individual',
   operation: 'write',
   tags: [],
+  httpMethod: 'put',
+  httpPath: '/sandbox/individual/{individual_id}',
+  operationId: 'put-sandbox-individual-individual_id',
 };
 
 export const tool: Tool = {
   name: 'update_sandbox_individual',
-  description: 'Update sandbox individual',
+  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 sandbox individual\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/individual_update_response',\n  $defs: {\n    individual_update_response: {\n      type: 'object',\n      title: 'Individual',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'A stable Finch `id` (UUID v4) for an individual in the company.'\n        },\n        dob: {\n          type: 'string',\n          title: 'Date'\n        },\n        emails: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              data: {\n                type: 'string'\n              },\n              type: {\n                type: 'string',\n                enum: [                  'work',\n                  'personal'\n                ]\n              }\n            }\n          }\n        },\n        encrypted_ssn: {\n          type: 'string',\n          description: 'Social Security Number of the individual in **encrypted** format. This field is only available with the `ssn` scope enabled and the `options: { include: [\\'ssn\\'] }` param set in the body.'\n        },\n        ethnicity: {\n          type: 'string',\n          description: 'The EEOC-defined ethnicity of the individual.',\n          enum: [            'asian',\n            'white',\n            'black_or_african_american',\n            'native_hawaiian_or_pacific_islander',\n            'american_indian_or_alaska_native',\n            'hispanic_or_latino',\n            'two_or_more_races',\n            'decline_to_specify'\n          ]\n        },\n        first_name: {\n          type: 'string',\n          description: 'The legal first name of the individual.'\n        },\n        gender: {\n          type: 'string',\n          description: 'The gender of the individual.',\n          enum: [            'female',\n            'male',\n            'other',\n            'decline_to_specify'\n          ]\n        },\n        last_name: {\n          type: 'string',\n          description: 'The legal last name of the individual.'\n        },\n        middle_name: {\n          type: 'string',\n          description: 'The legal middle name of the individual.'\n        },\n        phone_numbers: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              data: {\n                type: 'string'\n              },\n              type: {\n                type: 'string',\n                enum: [                  'work',\n                  'personal'\n                ]\n              }\n            }\n          }\n        },\n        preferred_name: {\n          type: 'string',\n          description: 'The preferred name of the individual.'\n        },\n        residence: {\n          $ref: '#/$defs/location'\n        },\n        ssn: {\n          type: 'string',\n          description: 'Social Security Number of the individual. This field is only available with the `ssn` scope enabled and the `options: { include: [\\'ssn\\'] }` param set in the body. [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field).'\n        }\n      }\n    },\n    location: {\n      type: 'object',\n      title: 'Location',\n      properties: {\n        city: {\n          type: 'string',\n          description: 'City, district, suburb, town, or village.'\n        },\n        country: {\n          type: 'string',\n          description: 'The 2-letter ISO 3166 country code.'\n        },\n        line1: {\n          type: 'string',\n          description: 'Street address or PO box.'\n        },\n        line2: {\n          type: 'string',\n          description: 'Apartment, suite, unit, or building.'\n        },\n        postal_code: {\n          type: 'string',\n          description: 'The postal code or zip code.'\n        },\n        state: {\n          type: 'string',\n          description: 'The state code.'\n        },\n        name: {\n          type: 'string'\n        },\n        source_id: {\n          type: 'string'\n        }\n      },\n      required: [        'city',\n        'country',\n        'line1',\n        'line2',\n        'postal_code',\n        'state'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -36,7 +42,6 @@ export const tool: Tool = {
               enum: ['work', 'personal'],
             },
           },
-          required: [],
         },
       },
       encrypted_ssn: {
@@ -88,7 +93,6 @@ export const tool: Tool = {
               enum: ['work', 'personal'],
             },
           },
-          required: [],
         },
       },
       preferred_name: {
@@ -103,7 +107,14 @@ export const tool: Tool = {
         description:
           "Social Security Number of the individual. This field is only available with the `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the body. [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field).",
       },
+      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/).',
+      },
     },
+    required: ['individual_id'],
     $defs: {
       location: {
         type: 'object',
@@ -144,11 +155,23 @@ export const tool: Tool = {
       },
     },
   },
+  annotations: {
+    idempotentHint: true,
+  },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { individual_id, ...body } = args as any;
-  return client.sandbox.individual.update(individual_id, body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { individual_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.sandbox.individual.update(individual_id, body)),
+    );
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/sandbox/jobs/configuration/retrieve-jobs-sandbox-configuration.ts

@@ -1,26 +1,53 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'sandbox.jobs.configuration',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/sandbox/jobs/configuration',
+  operationId: 'get-sandbox-jobs-configuration',
 };
 
 export const tool: Tool = {
   name: 'retrieve_jobs_sandbox_configuration',
-  description: 'Get configurations for sandbox jobs',
+  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 configurations for sandbox jobs\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/configuration_retrieve_response',\n  $defs: {\n    configuration_retrieve_response: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/sandbox_job_configuration'\n      }\n    },\n    sandbox_job_configuration: {\n      type: 'object',\n      title: 'SandboxJobConfiguration',\n      properties: {\n        completion_status: {\n          type: 'string',\n          enum: [            'complete',\n            'reauth_error',\n            'permissions_error',\n            'error'\n          ]\n        },\n        type: {\n          type: 'string',\n          enum: [            'data_sync_all'\n          ]\n        }\n      },\n      required: [        'completion_status',\n        'type'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
-    properties: {},
+    properties: {
+      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/).',
+      },
+    },
+    required: [],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  return client.sandbox.jobs.configuration.retrieve();
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.sandbox.jobs.configuration.retrieve()),
+    );
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/sandbox/jobs/configuration/update-jobs-sandbox-configuration.ts

@@ -1,18 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'sandbox.jobs.configuration',
   operation: 'write',
   tags: [],
+  httpMethod: 'put',
+  httpPath: '/sandbox/jobs/configuration',
+  operationId: 'put-sandbox-jobs-configuration',
 };
 
 export const tool: Tool = {
   name: 'update_jobs_sandbox_configuration',
-  description: 'Update configurations for sandbox jobs',
+  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 configurations for sandbox jobs\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/sandbox_job_configuration',\n  $defs: {\n    sandbox_job_configuration: {\n      type: 'object',\n      title: 'SandboxJobConfiguration',\n      properties: {\n        completion_status: {\n          type: 'string',\n          enum: [            'complete',\n            'reauth_error',\n            'permissions_error',\n            'error'\n          ]\n        },\n        type: {\n          type: 'string',\n          enum: [            'data_sync_all'\n          ]\n        }\n      },\n      required: [        'completion_status',\n        'type'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -24,13 +30,32 @@ export const tool: Tool = {
         type: 'string',
         enum: ['data_sync_all'],
       },
+      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/).',
+      },
     },
+    required: ['completion_status', 'type'],
+  },
+  annotations: {
+    idempotentHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.jobs.configuration.update(body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.sandbox.jobs.configuration.update(body)),
+    );
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/sandbox/jobs/create-sandbox-jobs.ts

@@ -1,18 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'sandbox.jobs',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/sandbox/jobs',
+  operationId: 'post-sandbox-job',
 };
 
 export const tool: Tool = {
   name: 'create_sandbox_jobs',
-  description: 'Enqueue a new sandbox job',
+  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\nEnqueue a new sandbox job\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/job_create_response',\n  $defs: {\n    job_create_response: {\n      type: 'object',\n      properties: {\n        allowed_refreshes: {\n          type: 'integer',\n          description: 'The number of allowed refreshes per hour (per hour, fixed window)'\n        },\n        job_id: {\n          type: 'string',\n          description: 'The id of the job that has been created.'\n        },\n        job_url: {\n          type: 'string',\n          description: 'The url that can be used to retrieve the job status'\n        },\n        remaining_refreshes: {\n          type: 'integer',\n          description: 'The number of remaining refreshes available (per hour, fixed window)'\n        }\n      },\n      required: [        'allowed_refreshes',\n        'job_id',\n        'job_url',\n        'remaining_refreshes'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -21,13 +27,28 @@ export const tool: Tool = {
         description: 'The type of job to start. Currently the only supported type is `data_sync_all`',
         enum: ['data_sync_all'],
       },
+      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/).',
+      },
     },
+    required: ['type'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.jobs.create(body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await client.sandbox.jobs.create(body)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };