@tryfinch/finch-api-mcp 6.31.0 → 7.0.0

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

@@ -1,137 +1,115 @@
 // 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.payment',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/sandbox/payment',
+  operationId: 'post-sandbox-payment',
 };
 
 export const tool: Tool = {
   name: 'create_sandbox_payment',
-  description: 'Add a new sandbox payment',
+  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 a new sandbox payment\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/payment_create_response',\n  $defs: {\n    payment_create_response: {\n      type: 'object',\n      properties: {\n        pay_date: {\n          type: 'string',\n          description: 'The date of the payment.'\n        },\n        payment_id: {\n          type: 'string',\n          description: 'The ID of the payment.'\n        }\n      },\n      required: [        'pay_date',\n        'payment_id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       end_date: {
         type: 'string',
+        format: 'date',
       },
       pay_statements: {
         type: 'array',
+        description: 'Array of pay statements to include in the payment.',
         items: {
           type: 'object',
-          title: 'Pay Statement',
           properties: {
+            individual_id: {
+              type: 'string',
+            },
             earnings: {
               type: 'array',
-              description: 'The array of earnings objects associated with this pay statement',
               items: {
                 type: 'object',
                 properties: {
                   amount: {
                     type: 'integer',
-                    description: 'The earnings amount in cents.',
-                  },
-                  attributes: {
-                    type: 'object',
-                    properties: {
-                      metadata: {
-                        type: 'object',
-                        properties: {
-                          metadata: {
-                            type: 'object',
-                            description:
-                              'The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).',
-                          },
-                        },
-                        required: [],
-                      },
-                    },
-                    required: [],
-                  },
-                  currency: {
-                    type: 'string',
-                    description: 'The earnings currency code.',
                   },
                   hours: {
                     type: 'number',
-                    description:
-                      'The number of hours associated with this earning. (For salaried employees, this could be hours per pay period, `0` or `null`, depending on the provider).',
                   },
                   name: {
                     type: 'string',
-                    description: 'The exact name of the deduction from the pay statement.',
                   },
                   type: {
                     type: 'string',
-                    description: 'The type of earning.',
                     enum: [
-                      'salary',
-                      'wage',
-                      'reimbursement',
-                      'overtime',
-                      'severance',
+                      'bonus',
+                      'commission',
                       'double_overtime',
+                      'other',
+                      'overtime',
                       'pto',
+                      'reimbursement',
+                      'salary',
+                      'severance',
                       'sick',
-                      'bonus',
-                      'commission',
                       'tips',
+                      'wage',
                       '1099',
-                      'other',
                     ],
                   },
                 },
-                required: [],
               },
             },
             employee_deductions: {
               type: 'array',
-              description: 'The array of deductions objects associated with this pay statement.',
               items: {
                 type: 'object',
                 properties: {
                   amount: {
                     type: 'integer',
-                    description: 'The deduction amount in cents.',
-                  },
-                  attributes: {
-                    type: 'object',
-                    properties: {
-                      metadata: {
-                        type: 'object',
-                        properties: {
-                          metadata: {
-                            type: 'object',
-                            description:
-                              'The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).',
-                          },
-                        },
-                        required: [],
-                      },
-                    },
-                    required: [],
-                  },
-                  currency: {
-                    type: 'string',
-                    description: 'The deduction currency.',
                   },
                   name: {
                     type: 'string',
-                    description: 'The deduction name from the pay statement.',
+                    description: 'The deduction name. Required when type is specified.',
                   },
                   pre_tax: {
                     type: 'boolean',
-                    description: 'Boolean indicating if the deduction is pre-tax.',
                   },
                   type: {
-                    $ref: '#/$defs/benefit_type',
+                    type: 'string',
+                    enum: [
+                      '457',
+                      '401k',
+                      '401k_roth',
+                      '401k_loan',
+                      '403b',
+                      '403b_roth',
+                      '457_roth',
+                      'commuter',
+                      'custom_post_tax',
+                      'custom_pre_tax',
+                      'fsa_dependent_care',
+                      'fsa_medical',
+                      'hsa_post',
+                      'hsa_pre',
+                      's125_dental',
+                      's125_medical',
+                      's125_vision',
+                      'simple',
+                      'simple_ira',
+                    ],
                   },
                 },
-                required: [],
               },
             },
             employer_contributions: {
@@ -141,168 +119,106 @@ export const tool: Tool = {
                 properties: {
                   amount: {
                     type: 'integer',
-                    description: 'The contribution amount in cents.',
-                  },
-                  attributes: {
-                    type: 'object',
-                    properties: {
-                      metadata: {
-                        type: 'object',
-                        properties: {
-                          metadata: {
-                            type: 'object',
-                            description:
-                              'The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).',
-                          },
-                        },
-                        required: [],
-                      },
-                    },
-                    required: [],
-                  },
-                  currency: {
-                    type: 'string',
-                    description: 'The contribution currency.',
                   },
                   name: {
                     type: 'string',
-                    description: 'The contribution name from the pay statement.',
+                    description: 'The contribution name. Required when type is specified.',
                   },
                   type: {
-                    $ref: '#/$defs/benefit_type',
+                    type: 'string',
+                    enum: [
+                      '457',
+                      '401k',
+                      '401k_roth',
+                      '401k_loan',
+                      '403b',
+                      '403b_roth',
+                      '457_roth',
+                      'commuter',
+                      'custom_post_tax',
+                      'custom_pre_tax',
+                      'fsa_dependent_care',
+                      'fsa_medical',
+                      'hsa_post',
+                      'hsa_pre',
+                      's125_dental',
+                      's125_medical',
+                      's125_vision',
+                      'simple',
+                      'simple_ira',
+                    ],
                   },
                 },
-                required: [],
               },
             },
             gross_pay: {
-              $ref: '#/$defs/money',
-            },
-            individual_id: {
-              type: 'string',
-              description: 'A stable Finch `id` (UUID v4) for an individual in the company',
+              type: 'integer',
             },
             net_pay: {
-              $ref: '#/$defs/money',
+              type: 'integer',
             },
             payment_method: {
               type: 'string',
-              description: 'The payment method.',
               enum: ['check', 'direct_deposit', 'other'],
             },
             taxes: {
               type: 'array',
-              description: 'The array of taxes objects associated with this pay statement.',
               items: {
                 type: 'object',
                 properties: {
                   amount: {
                     type: 'integer',
-                    description: 'The tax amount in cents.',
-                  },
-                  attributes: {
-                    type: 'object',
-                    properties: {
-                      metadata: {
-                        type: 'object',
-                        properties: {
-                          metadata: {
-                            type: 'object',
-                            description:
-                              'The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).',
-                          },
-                        },
-                        required: [],
-                      },
-                    },
-                    required: [],
-                  },
-                  currency: {
-                    type: 'string',
-                    description: 'The currency code.',
                   },
                   employer: {
                     type: 'boolean',
-                    description: '`true` if the amount is paid by the employers.',
                   },
                   name: {
                     type: 'string',
-                    description: 'The exact name of tax from the pay statement.',
                   },
                   type: {
                     type: 'string',
-                    description: 'The type of taxes.',
-                    enum: ['state', 'federal', 'local', 'fica'],
+                    enum: ['federal', 'fica', 'local', 'state'],
                   },
                 },
-                required: [],
               },
             },
             total_hours: {
               type: 'number',
-              description: 'The number of hours worked for this pay period',
             },
             type: {
               type: 'string',
-              description: 'The type of the payment associated with the pay statement.',
-              enum: ['regular_payroll', 'off_cycle_payroll', 'one_time_payment'],
+              enum: ['off_cycle_payroll', 'one_time_payment', 'regular_payroll'],
             },
           },
-          required: [],
+          required: ['individual_id'],
         },
       },
       start_date: {
         type: 'string',
+        format: 'date',
       },
-    },
-    $defs: {
-      benefit_type: {
+      jq_filter: {
         type: 'string',
-        title: 'BenefitType',
-        description: 'Type of benefit.',
-        enum: [
-          '401k',
-          '401k_roth',
-          '401k_loan',
-          '403b',
-          '403b_roth',
-          '457',
-          '457_roth',
-          's125_medical',
-          's125_dental',
-          's125_vision',
-          'hsa_pre',
-          'hsa_post',
-          'fsa_medical',
-          'fsa_dependent_care',
-          'simple_ira',
-          'simple',
-          'commuter',
-          'custom_post_tax',
-          'custom_pre_tax',
-        ],
-      },
-      money: {
-        type: 'object',
-        title: 'Money',
-        properties: {
-          amount: {
-            type: 'integer',
-            description: 'Amount for money object (in cents)',
-          },
-          currency: {
-            type: 'string',
-          },
-        },
-        required: [],
+        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: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.payment.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.payment.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/types.ts

@@ -0,0 +1,115 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import Finch from '@tryfinch/finch-api';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+type TextContentBlock = {
+  type: 'text';
+  text: string;
+};
+
+type ImageContentBlock = {
+  type: 'image';
+  data: string;
+  mimeType: string;
+};
+
+type AudioContentBlock = {
+  type: 'audio';
+  data: string;
+  mimeType: string;
+};
+
+type ResourceContentBlock = {
+  type: 'resource';
+  resource:
+    | {
+        uri: string;
+        mimeType: string;
+        text: string;
+      }
+    | {
+        uri: string;
+        mimeType: string;
+        blob: string;
+      };
+};
+
+export type ContentBlock = TextContentBlock | ImageContentBlock | AudioContentBlock | ResourceContentBlock;
+
+export type ToolCallResult = {
+  content: ContentBlock[];
+  isError?: boolean;
+};
+
+export type HandlerFunction = (
+  client: Finch,
+  args: Record<string, unknown> | undefined,
+) => Promise<ToolCallResult>;
+
+export function asTextContentResult(result: unknown): ToolCallResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+  };
+}
+
+export async function asBinaryContentResult(response: Response): Promise<ToolCallResult> {
+  const blob = await response.blob();
+  const mimeType = blob.type;
+  const data = Buffer.from(await blob.arrayBuffer()).toString('base64');
+  if (mimeType.startsWith('image/')) {
+    return {
+      content: [{ type: 'image', mimeType, data }],
+    };
+  } else if (mimeType.startsWith('audio/')) {
+    return {
+      content: [{ type: 'audio', mimeType, data }],
+    };
+  } else {
+    return {
+      content: [
+        {
+          type: 'resource',
+          resource: {
+            // We must give a URI, even though this isn't actually an MCP resource.
+            uri: 'resource://tool-response',
+            mimeType,
+            blob: data,
+          },
+        },
+      ],
+    };
+  }
+}
+
+export function asErrorResult(message: string): ToolCallResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: message,
+      },
+    ],
+    isError: true,
+  };
+}
+
+export type Metadata = {
+  resource: string;
+  operation: 'read' | 'write';
+  tags: string[];
+  httpMethod?: string;
+  httpPath?: string;
+  operationId?: string;
+};
+
+export type Endpoint = {
+  metadata: Metadata;
+  tool: Tool;
+  handler: HandlerFunction;
+};

package/stdio.d.mts

@@ -0,0 +1,3 @@
+import { McpOptions } from "./options.mjs";
+export declare const launchStdioServer: (options: McpOptions) => Promise<void>;
+//# sourceMappingURL=stdio.d.mts.map

package/stdio.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.mts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OAEO,EAAE,UAAU,EAAE;AAErB,eAAO,MAAM,iBAAiB,GAAU,SAAS,UAAU,kBAQ1D,CAAC"}

package/stdio.d.ts

@@ -0,0 +1,3 @@
+import { McpOptions } from "./options.js";
+export declare const launchStdioServer: (options: McpOptions) => Promise<void>;
+//# sourceMappingURL=stdio.d.ts.map

package/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OAEO,EAAE,UAAU,EAAE;AAErB,eAAO,MAAM,iBAAiB,GAAU,SAAS,UAAU,kBAQ1D,CAAC"}

package/stdio.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.launchStdioServer = void 0;
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const server_1 = require("./server.js");
+const launchStdioServer = async (options) => {
+    const server = (0, server_1.newMcpServer)();
+    (0, server_1.initMcpServer)({ server, mcpOptions: options });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('MCP Server running on stdio');
+};
+exports.launchStdioServer = launchStdioServer;
+//# sourceMappingURL=stdio.js.map

package/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AACjF,wCAAuD;AAGhD,MAAM,iBAAiB,GAAG,KAAK,EAAE,OAAmB,EAAE,EAAE;IAC7D,MAAM,MAAM,GAAG,IAAA,qBAAY,GAAE,CAAC;IAE9B,IAAA,sBAAa,EAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAE/C,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAC/C,CAAC,CAAC;AARW,QAAA,iBAAiB,qBAQ5B"}

package/stdio.mjs

@@ -0,0 +1,10 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { initMcpServer, newMcpServer } from "./server.mjs";
+export const launchStdioServer = async (options) => {
+    const server = newMcpServer();
+    initMcpServer({ server, mcpOptions: options });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('MCP Server running on stdio');
+};
+//# sourceMappingURL=stdio.mjs.map

package/stdio.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.mjs","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C;OACzE,EAAE,aAAa,EAAE,YAAY,EAAE;AAGtC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,OAAmB,EAAE,EAAE;IAC7D,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAE9B,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAE/C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAC/C,CAAC,CAAC"}

package/tools/access-tokens/create-access-tokens.d.mts

@@ -1,32 +1,51 @@
+import { Metadata } from '@tryfinch/finch-api-mcp/tools/types';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from "..//index.mjs";
 import Finch from '@tryfinch/finch-api';
 export declare const metadata: Metadata;
 export declare const tool: Tool;
-export declare const handler: (client: Finch, args: Record<string, unknown> | undefined) => import("@tryfinch/finch-api/core").APIPromise<Finch.AccessTokens.CreateAccessTokenResponse>;
+export declare const handler: (client: Finch, args: Record<string, unknown> | undefined) => Promise<import("@tryfinch/finch-api-mcp/tools/types").ToolCallResult>;
 declare const _default: {
     metadata: Metadata;
     tool: {
-        [x: string]: unknown;
-        name: string;
         inputSchema: {
             [x: string]: unknown;
             type: "object";
             properties?: {
-                [x: string]: unknown;
+                [x: string]: object;
             } | undefined;
+            required?: string[] | undefined;
         };
+        name: string;
         description?: string | undefined;
-        annotations?: {
+        outputSchema?: {
             [x: string]: unknown;
+            type: "object";
+            properties?: {
+                [x: string]: object;
+            } | undefined;
+            required?: string[] | undefined;
+        } | undefined;
+        annotations?: {
             title?: string | undefined;
             readOnlyHint?: boolean | undefined;
             destructiveHint?: boolean | undefined;
             idempotentHint?: boolean | undefined;
             openWorldHint?: boolean | undefined;
         } | undefined;
+        execution?: {
+            taskSupport?: "optional" | "required" | "forbidden" | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+        }[] | undefined;
+        title?: string | undefined;
     };
-    handler: (client: Finch, args: Record<string, unknown> | undefined) => import("@tryfinch/finch-api/core").APIPromise<Finch.AccessTokens.CreateAccessTokenResponse>;
+    handler: (client: Finch, args: Record<string, unknown> | undefined) => Promise<import("@tryfinch/finch-api-mcp/tools/types").ToolCallResult>;
 };
 export default _default;
 //# sourceMappingURL=create-access-tokens.d.mts.map

package/tools/access-tokens/create-access-tokens.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"create-access-tokens.d.mts","sourceRoot":"","sources":["../../src/tools/access-tokens/create-access-tokens.ts"],"names":[],"mappings":"OAEO,EAAE,IAAI,EAAE,MAAM,oCAAoC;OAClD,KAAK,EAAE,QAAQ,EAAE;OACjB,KAAK,MAAM,qBAAqB;AAEvC,eAAO,MAAM,QAAQ,EAAE,QAItB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,IAoBlB,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,QAAQ,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,gGAG/E,CAAC;;;;;;;;;;;;;;;;;;;;;;;sBAH8B,KAAK,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;;AAKhF,wBAA2C"}
+{"version":3,"file":"create-access-tokens.d.mts","sourceRoot":"","sources":["../../src/tools/access-tokens/create-access-tokens.ts"],"names":[],"mappings":"OAGO,EAAE,QAAQ,EAAsC,MAAM,qCAAqC;OAE3F,EAAE,IAAI,EAAE,MAAM,oCAAoC;OAClD,KAAK,MAAM,qBAAqB;AAEvC,eAAO,MAAM,QAAQ,EAAE,QAOtB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,IAiClB,CAAC;AAEF,eAAO,MAAM,OAAO,GAAU,QAAQ,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,0EAUrF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAVoC,KAAK,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;;AAYtF,wBAA2C"}