@tryfinch/finch-api-mcp 6.22.1

package/src/server.ts

@@ -0,0 +1,89 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { endpoints, HandlerFunction } from './tools';
+import { CallToolRequestSchema, ListToolsRequestSchema, Tool } from '@modelcontextprotocol/sdk/types.js';
+import Finch from '@tryfinch/finch-api';
+export { endpoints } from './tools';
+
+// Create server instance
+export const server = new McpServer(
+  {
+    name: 'tryfinch_finch_api_api',
+    version: '6.22.1',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+/**
+ * Initializes the provided MCP Server with the given tools and handlers.
+ * If not provided, the default client, tools and handlers will be used.
+ */
+export function init(params: {
+  server: Server | McpServer;
+  client?: Finch;
+  endpoints?: { tool: Tool; handler: HandlerFunction }[];
+}) {
+  const server = params.server instanceof McpServer ? params.server.server : params.server;
+  const providedEndpoints = params.endpoints || endpoints;
+  const tools = providedEndpoints.map((endpoint) => endpoint.tool);
+  const handlers = Object.fromEntries(
+    providedEndpoints.map((endpoint) => [endpoint.tool.name, endpoint.handler]),
+  );
+
+  const client = params.client || new Finch({});
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools,
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    const handler = handlers[name];
+    if (!handler) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return executeHandler(handler, client, args);
+  });
+}
+
+/**
+ * Runs the provided handler with the given client and arguments.
+ */
+export async function executeHandler(
+  handler: HandlerFunction,
+  client: Finch,
+  args: Record<string, unknown> | undefined,
+) {
+  const result = await handler(client, args || {});
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+  };
+}
+
+export const readEnv = (env: string): string => {
+  let envValue = undefined;
+  if (typeof (globalThis as any).process !== 'undefined') {
+    envValue = (globalThis as any).process.env?.[env]?.trim();
+  } else if (typeof (globalThis as any).Deno !== 'undefined') {
+    envValue = (globalThis as any).Deno.env?.get?.(env)?.trim();
+  }
+  if (envValue === undefined) {
+    throw new Error(`Environment variable ${env} is not set`);
+  }
+  return envValue;
+};

package/src/tools/access-tokens/create-access-tokens.ts

@@ -0,0 +1,40 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'access_tokens',
+  operation: 'write',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'create_access_tokens',
+  description: 'Exchange the authorization code for an access token',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      code: {
+        type: 'string',
+      },
+      client_id: {
+        type: 'string',
+      },
+      client_secret: {
+        type: 'string',
+      },
+      redirect_uri: {
+        type: 'string',
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { ...body } = args;
+  return client.accessTokens.create(body);
+};
+
+export default { metadata, tool, handler };

package/src/tools/account/disconnect-account.ts

@@ -0,0 +1,27 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'account',
+  operation: 'write',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'disconnect_account',
+  description: 'Disconnect one or more `access_token`s from your application.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const {} = args;
+  return client.account.disconnect();
+};
+
+export default { metadata, tool, handler };

package/src/tools/account/introspect-account.ts

@@ -0,0 +1,27 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'account',
+  operation: 'read',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'introspect_account',
+  description: 'Read account information associated with an `access_token`',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const {} = args;
+  return client.account.introspect();
+};
+
+export default { metadata, tool, handler };

package/src/tools/connect/sessions/new-connect-sessions.ts

@@ -0,0 +1,81 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'connect.sessions',
+  operation: 'write',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'new_connect_sessions',
+  description: 'Create a new connect session for an employer',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      customer_id: {
+        type: 'string',
+      },
+      customer_name: {
+        type: 'string',
+      },
+      products: {
+        type: 'array',
+        items: {
+          type: 'string',
+          description: 'The Finch products that can be requested during the Connect flow.',
+          enum: [
+            'company',
+            'directory',
+            'individual',
+            'employment',
+            'payment',
+            'pay_statement',
+            'benefits',
+            'ssn',
+          ],
+        },
+      },
+      customer_email: {
+        type: 'string',
+      },
+      integration: {
+        type: 'object',
+        properties: {
+          auth_method: {
+            type: 'string',
+            enum: ['assisted', 'credential', 'oauth', 'api_token'],
+          },
+          provider: {
+            type: 'string',
+          },
+        },
+        required: [],
+      },
+      manual: {
+        type: 'boolean',
+      },
+      minutes_to_expire: {
+        type: 'number',
+        description: 'The number of minutes until the session expires (defaults to 43,200, which is 30 days)',
+      },
+      redirect_uri: {
+        type: 'string',
+      },
+      sandbox: {
+        type: 'string',
+        enum: ['finch', 'provider'],
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { ...body } = args;
+  return client.connect.sessions.new(body);
+};
+
+export default { metadata, tool, handler };

package/src/tools/connect/sessions/reauthenticate-connect-sessions.ts

@@ -0,0 +1,58 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'connect.sessions',
+  operation: 'write',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'reauthenticate_connect_sessions',
+  description: 'Create a new Connect session for reauthenticating an existing connection',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      connection_id: {
+        type: 'string',
+        description: 'The ID of the existing connection to reauthenticate',
+      },
+      minutes_to_expire: {
+        type: 'integer',
+        description: 'The number of minutes until the session expires (defaults to 43,200, which is 30 days)',
+      },
+      products: {
+        type: 'array',
+        description: 'The products to request access to (optional for reauthentication)',
+        items: {
+          type: 'string',
+          description: 'The Finch products that can be requested during the Connect flow.',
+          enum: [
+            'company',
+            'directory',
+            'individual',
+            'employment',
+            'payment',
+            'pay_statement',
+            'benefits',
+            'ssn',
+          ],
+        },
+      },
+      redirect_uri: {
+        type: 'string',
+        description: 'The URI to redirect to after the Connect flow is completed',
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { ...body } = args;
+  return client.connect.sessions.reauthenticate(body);
+};
+
+export default { metadata, tool, handler };

package/src/tools/hris/benefits/create-hris-benefits.ts

@@ -0,0 +1,67 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'hris.benefits',
+  operation: 'write',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'create_hris_benefits',
+  description:
+    'Creates a new company-wide deduction or contribution. Please use the `/providers` endpoint to view available types for each provider.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      description: {
+        type: 'string',
+        title: 'BenefitDescription',
+        description:
+          'Name of the benefit as it appears in the provider and pay statements. Recommend limiting this to <30 characters due to limitations in specific providers (e.g. Justworks).',
+      },
+      frequency: {
+        type: 'string',
+        title: 'BenefitFrequency',
+        description: 'The frequency of the benefit deduction/contribution.',
+        enum: ['one_time', 'every_paycheck', 'monthly'],
+      },
+      type: {
+        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',
+        ],
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { ...body } = args;
+  return client.hris.benefits.create(body);
+};
+
+export default { metadata, tool, handler };

package/src/tools/hris/benefits/individuals/enroll-many-benefits-hris-individuals.ts

@@ -0,0 +1,101 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'hris.benefits.individuals',
+  operation: 'write',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'enroll_many_benefits_hris_individuals',
+  description:
+    'Enroll an individual into a deduction or contribution. This is an overwrite operation. If the employee is already enrolled, the enrollment amounts will be adjusted. Making the same request multiple times will not create new enrollments, but will continue to set the state of the existing enrollment.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      benefit_id: {
+        type: 'string',
+      },
+      individuals: {
+        type: 'array',
+        description: 'Array of the individual_id to enroll and a configuration object.',
+        items: {
+          type: 'object',
+          properties: {
+            configuration: {
+              type: 'object',
+              properties: {
+                annual_contribution_limit: {
+                  type: 'string',
+                  description:
+                    'For HSA benefits only - whether the contribution limit is for an individual or family',
+                  enum: ['individual', 'family'],
+                },
+                annual_maximum: {
+                  type: 'integer',
+                  description: 'Maximum annual amount in cents',
+                },
+                catch_up: {
+                  type: 'boolean',
+                  description: 'For retirement benefits only - whether catch up contributions are enabled',
+                },
+                company_contribution: {
+                  type: 'object',
+                  properties: {
+                    amount: {
+                      type: 'integer',
+                      description:
+                        'Amount in cents for fixed type or basis points (1/100th of a percent) for percent type',
+                    },
+                    type: {
+                      type: 'string',
+                      enum: ['fixed', 'percent'],
+                    },
+                  },
+                  required: [],
+                },
+                effective_date: {
+                  type: 'string',
+                  description: 'The date the enrollment will take effect',
+                  format: 'date',
+                },
+                employee_deduction: {
+                  type: 'object',
+                  properties: {
+                    amount: {
+                      type: 'integer',
+                      description:
+                        'Amount in cents for fixed type or basis points (1/100th of a percent) for percent type',
+                    },
+                    type: {
+                      type: 'string',
+                      enum: ['fixed', 'percent'],
+                    },
+                  },
+                  required: [],
+                },
+              },
+              required: [],
+            },
+            individual_id: {
+              type: 'string',
+              description: 'Finch id (uuidv4) for the individual to enroll',
+            },
+          },
+          required: [],
+        },
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { benefit_id, ...body } = args;
+  return client.hris.benefits.individuals.enrollMany(benefit_id, body);
+};
+
+export default { metadata, tool, handler };

package/src/tools/hris/benefits/individuals/enrolled-ids-benefits-hris-individuals.ts

@@ -0,0 +1,31 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'hris.benefits.individuals',
+  operation: 'read',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'enrolled_ids_benefits_hris_individuals',
+  description: 'Lists individuals currently enrolled in a given deduction.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      benefit_id: {
+        type: 'string',
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { benefit_id } = args;
+  return client.hris.benefits.individuals.enrolledIds(benefit_id);
+};
+
+export default { metadata, tool, handler };

package/src/tools/hris/benefits/individuals/retrieve-many-benefits-benefits-hris-individuals.ts

@@ -0,0 +1,36 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'hris.benefits.individuals',
+  operation: 'read',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'retrieve_many_benefits_benefits_hris_individuals',
+  description: 'Get enrollment information for the given individuals.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      benefit_id: {
+        type: 'string',
+      },
+      individual_ids: {
+        type: 'string',
+        description:
+          'comma-delimited list of stable Finch uuids for each individual. If empty, defaults to all individuals',
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { benefit_id, ...body } = args;
+  return client.hris.benefits.individuals.retrieveManyBenefits(benefit_id, body);
+};
+
+export default { metadata, tool, handler };

package/src/tools/hris/benefits/individuals/unenroll-many-benefits-hris-individuals.ts

@@ -0,0 +1,38 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'hris.benefits.individuals',
+  operation: 'write',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'unenroll_many_benefits_hris_individuals',
+  description: 'Unenroll individuals from a deduction or contribution',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      benefit_id: {
+        type: 'string',
+      },
+      individual_ids: {
+        type: 'array',
+        description: 'Array of individual_ids to unenroll.',
+        items: {
+          type: 'string',
+        },
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { benefit_id, ...body } = args;
+  return client.hris.benefits.individuals.unenrollMany(benefit_id, body);
+};
+
+export default { metadata, tool, handler };

package/src/tools/hris/benefits/list-hris-benefits.ts

@@ -0,0 +1,27 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'hris.benefits',
+  operation: 'read',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'list_hris_benefits',
+  description: 'List all company-wide deductions and contributions.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const {} = args;
+  return client.hris.benefits.list();
+};
+
+export default { metadata, tool, handler };

package/src/tools/hris/benefits/list-supported-benefits-hris-benefits.ts

@@ -0,0 +1,27 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'hris.benefits',
+  operation: 'read',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'list_supported_benefits_hris_benefits',
+  description: 'Get deductions metadata',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const {} = args;
+  return client.hris.benefits.listSupportedBenefits();
+};
+
+export default { metadata, tool, handler };

package/src/tools/hris/benefits/retrieve-hris-benefits.ts

@@ -0,0 +1,31 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Metadata } from '../../';
+import Finch from '@tryfinch/finch-api';
+
+export const metadata: Metadata = {
+  resource: 'hris.benefits',
+  operation: 'read',
+  tags: [],
+};
+
+export const tool: Tool = {
+  name: 'retrieve_hris_benefits',
+  description: 'Lists deductions and contributions information for a given item',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      benefit_id: {
+        type: 'string',
+      },
+    },
+  },
+};
+
+export const handler = (client: Finch, args: any) => {
+  const { benefit_id } = args;
+  return client.hris.benefits.retrieve(benefit_id);
+};
+
+export default { metadata, tool, handler };