@tryfinch/finch-api-mcp 6.31.0 → 8.0.0

package/README.md

@@ -1,4 +1,4 @@
-# Finch Node MCP Server
+# Finch TypeScript MCP Server
 
 It is generated with [Stainless](https://www.stainless.com/).
 
@@ -28,7 +28,7 @@ For clients with a configuration JSON, it might look something like this:
   "mcpServers": {
     "tryfinch_finch_api_api": {
       "command": "npx",
-      "args": ["-y", "@tryfinch/finch-api-mcp", "--client=claude", "--tools=dynamic"],
+      "args": ["-y", "@tryfinch/finch-api-mcp"],
       "env": {
         "FINCH_ACCESS_TOKEN": "My Access Token",
         "FINCH_CLIENT_ID": "4ab15e51-11ad-49f4-acae-f343b7794375",
@@ -40,282 +40,69 @@ For clients with a configuration JSON, it might look something like this:
 }
 ```
 
-## Exposing endpoints to your MCP Client
+### Cursor
 
-There are two ways to expose endpoints as tools in the MCP server:
+If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables
+in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server.
 
-1. Exposing one tool per endpoint, and filtering as necessary
-2. Exposing a set of tools to dynamically discover and invoke endpoints from the API
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=@tryfinch/finch-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0cnlmaW5jaC9maW5jaC1hcGktbWNwIl0sImVudiI6eyJGSU5DSF9BQ0NFU1NfVE9LRU4iOiJTZXQgeW91ciBGSU5DSF9BQ0NFU1NfVE9LRU4gaGVyZS4iLCJGSU5DSF9DTElFTlRfSUQiOiJTZXQgeW91ciBGSU5DSF9DTElFTlRfSUQgaGVyZS4iLCJGSU5DSF9DTElFTlRfU0VDUkVUIjoiU2V0IHlvdXIgRklOQ0hfQ0xJRU5UX1NFQ1JFVCBoZXJlLiIsIkZJTkNIX1dFQkhPT0tfU0VDUkVUIjoiU2V0IHlvdXIgRklOQ0hfV0VCSE9PS19TRUNSRVQgaGVyZS4ifX0)
 
-### Filtering endpoints and tools
+### VS Code
 
-You can run the package on the command line to discover and filter the set of tools that are exposed by the
-MCP Server. This can be helpful for large APIs where including all endpoints at once is too much for your AI's
-context window.
+If you use MCP, you can install the MCP server by clicking the link below. You will need to set your environment variables
+in VS Code's `mcp.json`, which can be found via Command Palette > MCP: Open User Configuration.
 
-You can filter by multiple aspects:
+[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40tryfinch%2Ffinch-api-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40tryfinch%2Ffinch-api-mcp%22%5D%2C%22env%22%3A%7B%22FINCH_ACCESS_TOKEN%22%3A%22Set%20your%20FINCH_ACCESS_TOKEN%20here.%22%2C%22FINCH_CLIENT_ID%22%3A%22Set%20your%20FINCH_CLIENT_ID%20here.%22%2C%22FINCH_CLIENT_SECRET%22%3A%22Set%20your%20FINCH_CLIENT_SECRET%20here.%22%2C%22FINCH_WEBHOOK_SECRET%22%3A%22Set%20your%20FINCH_WEBHOOK_SECRET%20here.%22%7D%7D)
 
-- `--tool` includes a specific tool by name
-- `--resource` includes all tools under a specific resource, and can have wildcards, e.g. `my.resource*`
-- `--operation` includes just read (get/list) or just write operations
+### Claude Code
 
-### Dynamic tools
+If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your
+environment variables in Claude Code's `.claude.json`, which can be found in your home directory.
 
-If you specify `--tools=dynamic` to the MCP server, instead of exposing one tool per endpoint in the API, it will
-expose the following tools:
-
-1. `list_api_endpoints` - Discovers available endpoints, with optional filtering by search query
-2. `get_api_endpoint_schema` - Gets detailed schema information for a specific endpoint
-3. `invoke_api_endpoint` - Executes any endpoint with the appropriate parameters
-
-This allows you to have the full set of API endpoints available to your MCP Client, while not requiring that all
-of their schemas be loaded into context at once. Instead, the LLM will automatically use these tools together to
-search for, look up, and invoke endpoints dynamically. However, due to the indirect nature of the schemas, it
-can struggle to provide the correct properties a bit more than when tools are imported explicitly. Therefore,
-you can opt-in to explicit tools, the dynamic tools, or both.
-
-See more information with `--help`.
-
-All of these command-line options can be repeated, combined together, and have corresponding exclusion versions (e.g. `--no-tool`).
-
-Use `--list` to see the list of available tools, or see below.
-
-### Specifying the MCP Client
-
-Different clients have varying abilities to handle arbitrary tools and schemas.
-
-You can specify the client you are using with the `--client` argument, and the MCP server will automatically
-serve tools and schemas that are more compatible with that client.
-
-- `--client=<type>`: Set all capabilities based on a known MCP client
-
-  - Valid values: `openai-agents`, `claude`, `claude-code`, `cursor`
-  - Example: `--client=cursor`
-
-Additionally, if you have a client not on the above list, or the client has gotten better
-over time, you can manually enable or disable certain capabilities:
-
-- `--capability=<name>`: Specify individual client capabilities
-  - Available capabilities:
-    - `top-level-unions`: Enable support for top-level unions in tool schemas
-    - `valid-json`: Enable JSON string parsing for arguments
-    - `refs`: Enable support for $ref pointers in schemas
-    - `unions`: Enable support for union types (anyOf) in schemas
-    - `formats`: Enable support for format validations in schemas (e.g. date-time, email)
-    - `tool-name-length=N`: Set maximum tool name length to N characters
-  - Example: `--capability=top-level-unions --capability=tool-name-length=40`
-  - Example: `--capability=top-level-unions,tool-name-length=40`
-
-### Examples
-
-1. Filter for read operations on cards:
-
-```bash
---resource=cards --operation=read
 ```
-
-2. Exclude specific tools while including others:
-
-```bash
---resource=cards --no-tool=create_cards
+claude mcp add --transport stdio tryfinch_finch_api_api --env FINCH_ACCESS_TOKEN="Your FINCH_ACCESS_TOKEN here." FINCH_CLIENT_ID="Your FINCH_CLIENT_ID here." FINCH_CLIENT_SECRET="Your FINCH_CLIENT_SECRET here." FINCH_WEBHOOK_SECRET="Your FINCH_WEBHOOK_SECRET here." -- npx -y @tryfinch/finch-api-mcp
 ```
 
-3. Configure for Cursor client with custom max tool name length:
+## Code Mode
 
-```bash
---client=cursor --capability=tool-name-length=40
-```
+This MCP server is built on the "Code Mode" tool scheme. In this MCP Server,
+your agent will write code against the TypeScript SDK, which will then be executed in an
+isolated sandbox. To accomplish this, the server will expose two tools to your agent:
 
-4. Complex filtering with multiple criteria:
+- The first tool is a docs search tool, which can be used to generically query for
+  documentation about your API/SDK.
 
-```bash
---resource=cards,accounts --operation=read --tag=kyc --no-tool=create_cards
-```
-
-## Importing the tools and server individually
+- The second tool is a code tool, where the agent can write code against the TypeScript SDK.
+  The code will be executed in a sandbox environment without web or filesystem access. Then,
+  anything the code returns or prints will be returned to the agent as the result of the
+  tool call.
 
-```js
-// Import the server, generated endpoints, or the init function
-import { server, endpoints, init } from "@tryfinch/finch-api-mcp/server";
+Using this scheme, agents are capable of performing very complex tasks deterministically
+and repeatably.
 
-// import a specific tool
-import createAccessTokens from "@tryfinch/finch-api-mcp/tools/access-tokens/create-access-tokens";
+## Running remotely
 
-// initialize the server and all endpoints
-init({ server, endpoints });
+Launching the client with `--transport=http` launches the server as a remote server using Streamable HTTP transport. The `--port` setting can choose the port it will run on, and the `--socket` setting allows it to run on a Unix socket.
 
-// manually start server
-const transport = new StdioServerTransport();
-await server.connect(transport);
+Authorization can be provided via the `Authorization` header using the Bearer or Basic scheme.
 
-// or initialize your own server with specific tools
-const myServer = new McpServer(...);
+Additionally, authorization can be provided via the following headers:
+| Header | Equivalent client option | Security scheme |
+| ----------------------- | ------------------------ | --------------- |
+| `x-finch-client-id` | `clientID` | basicAuth |
+| `x-finch-client-secret` | `clientSecret` | basicAuth |
 
-// define your own endpoint
-const myCustomEndpoint = {
-  tool: {
-    name: 'my_custom_tool',
-    description: 'My custom tool',
-    inputSchema: zodToJsonSchema(z.object({ a_property: z.string() })),
-  },
-  handler: async (client: client, args: any) => {
-    return { myResponse: 'Hello world!' };
-  })
-};
+A configuration JSON for this server might look like this, assuming the server is hosted at `http://localhost:3000`:
 
-// initialize the server with your custom endpoints
-init({ server: myServer, endpoints: [createAccessTokens, myCustomEndpoint] });
+```json
+{
+  "mcpServers": {
+    "tryfinch_finch_api_api": {
+      "url": "http://localhost:3000",
+      "headers": {
+        "Authorization": "Bearer <auth value>"
+      }
+    }
+  }
+}
 ```
-
-## Available Tools
-
-The following tools are available in this MCP server.
-
-### Resource `access_tokens`:
-
-- `create_access_tokens` (`write`): Exchange the authorization code for an access token
-
-### Resource `hris.company`:
-
-- `retrieve_hris_company` (`read`): Read basic company data
-
-### Resource `hris.company.pay_statement_item`:
-
-- `list_company_hris_pay_statement_item` (`read`): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
-  Retrieve a list of detailed pay statement items for the access token's connection account.
-
-### Resource `hris.company.pay_statement_item.rules`:
-
-- `create_pay_statement_item_company_hris_rules` (`write`): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
-  Custom rules can be created to associate specific attributes to pay statement items depending on the use case. For example, pay statement items that meet certain conditions can be labeled as a pre-tax 401k. This metadata can be retrieved where pay statement item information is available.
-- `update_pay_statement_item_company_hris_rules` (`write`): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
-  Update a rule for a pay statement item.
-- `list_pay_statement_item_company_hris_rules` (`read`): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
-  List all rules of a connection account.
-- `delete_pay_statement_item_company_hris_rules` (`write`): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
-  Delete a rule for a pay statement item.
-
-### Resource `hris.directory`:
-
-- `list_hris_directory` (`read`): Read company directory and organization structure
-- `list_individuals_hris_directory` (`read`): Read company directory and organization structure
-
-### Resource `hris.individuals`:
-
-- `retrieve_many_hris_individuals` (`write`): Read individual data, excluding income and employment data
-
-### Resource `hris.employments`:
-
-- `retrieve_many_hris_employments` (`write`): Read individual employment and income data
-
-### Resource `hris.payments`:
-
-- `list_hris_payments` (`read`): Read payroll and contractor related payments by the company.
-
-### Resource `hris.pay_statements`:
-
-- `retrieve_many_hris_pay_statements` (`write`): Read detailed pay statements for each individual.
-
-Deduction and contribution types are supported by the payroll systems that supports Benefits.
-
-### Resource `hris.documents`:
-
-- `list_hris_documents` (`read`): **Beta:** This endpoint is in beta and may change.
-  Retrieve a list of company-wide documents.
-- `retreive_hris_documents` (`read`): **Beta:** This endpoint is in beta and may change.
-  Retrieve details of a specific document by its ID.
-
-### Resource `hris.benefits`:
-
-- `create_hris_benefits` (`write`): Creates a new company-wide deduction or contribution. Please use the `/providers` endpoint to view available types for each provider.
-- `retrieve_hris_benefits` (`read`): Lists deductions and contributions information for a given item
-- `update_hris_benefits` (`write`): Updates an existing company-wide deduction or contribution
-- `list_hris_benefits` (`read`): List all company-wide deductions and contributions.
-- `list_supported_benefits_hris_benefits` (`read`): Get deductions metadata
-
-### Resource `hris.benefits.individuals`:
-
-- `enroll_many_benefits_hris_individuals` (`write`): 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.
-- `enrolled_ids_benefits_hris_individuals` (`read`): Lists individuals currently enrolled in a given deduction.
-- `retrieve_many_benefits_benefits_hris_individuals` (`read`): Get enrollment information for the given individuals.
-- `unenroll_many_benefits_hris_individuals` (`write`): Unenroll individuals from a deduction or contribution
-
-### Resource `providers`:
-
-- `list_providers` (`read`): Return details on all available payroll and HR systems.
-
-### Resource `account`:
-
-- `disconnect_account` (`write`): Disconnect one or more `access_token`s from your application.
-- `introspect_account` (`read`): Read account information associated with an `access_token`
-
-### Resource `request_forwarding`:
-
-- `forward_request_forwarding` (`write`): The Forward API allows you to make direct requests to an employment system. If Finch’s unified API
-  doesn’t have a data model that cleanly fits your needs, then Forward allows you to push or pull
-  data models directly against an integration’s API.
-
-### Resource `jobs.automated`:
-
-- `create_jobs_automated` (`write`): Enqueue an automated job.
-
-`data_sync_all`: Enqueue a job to re-sync all data for a connection. `data_sync_all` has a concurrency limit of 1 job at a time per connection. This means that if this endpoint is called while a job is already in progress for this connection, Finch will return the `job_id` of the job that is currently in progress. Finch allows a fixed window rate limit of 1 forced refresh per hour per connection.
-
-`w4_form_employee_sync`: Enqueues a job for sync W-4 data for a particular individual, identified by `individual_id`. This feature is currently in beta.
-
-This endpoint is available for _Scale_ tier customers as an add-on. To request access to this endpoint, please contact your Finch account manager.
-
-- `retrieve_jobs_automated` (`read`): Get an automated job by `job_id`.
-- `list_jobs_automated` (`read`): Get all automated jobs. Automated jobs are completed by a machine. By default, jobs are sorted in descending order by submission time. For scheduled jobs such as data syncs, only the next scheduled job is shown.
-
-### Resource `jobs.manual`:
-
-- `retrieve_jobs_manual` (`read`): Get a manual job by `job_id`. Manual jobs are completed by a human and include Assisted Benefits jobs.
-
-### Resource `sandbox.connections`:
-
-- `create_sandbox_connections` (`write`): Create a new connection (new company/provider pair) with a new account
-
-### Resource `sandbox.connections.accounts`:
-
-- `create_connections_sandbox_accounts` (`write`): Create a new account for an existing connection (company/provider pair)
-- `update_connections_sandbox_accounts` (`write`): Update an existing sandbox account. Change the connection status to understand how the Finch API responds.
-
-### Resource `sandbox.company`:
-
-- `update_sandbox_company` (`write`): Update a sandbox company's data
-
-### Resource `sandbox.directory`:
-
-- `create_sandbox_directory` (`write`): Add new individuals to a sandbox company
-
-### Resource `sandbox.individual`:
-
-- `update_sandbox_individual` (`write`): Update sandbox individual
-
-### Resource `sandbox.employment`:
-
-- `update_sandbox_employment` (`write`): Update sandbox employment
-
-### Resource `sandbox.payment`:
-
-- `create_sandbox_payment` (`write`): Add a new sandbox payment
-
-### Resource `sandbox.jobs`:
-
-- `create_sandbox_jobs` (`write`): Enqueue a new sandbox job
-
-### Resource `sandbox.jobs.configuration`:
-
-- `retrieve_jobs_sandbox_configuration` (`read`): Get configurations for sandbox jobs
-- `update_jobs_sandbox_configuration` (`write`): Update configurations for sandbox jobs
-
-### Resource `payroll.pay_groups`:
-
-- `retrieve_payroll_pay_groups` (`read`): Read information from a single pay group
-- `list_payroll_pay_groups` (`read`): Read company pay groups and frequencies
-
-### Resource `connect.sessions`:
-
-- `new_connect_sessions` (`write`): Create a new connect session for an employer
-- `reauthenticate_connect_sessions` (`write`): Create a new Connect session for reauthenticating an existing connection

package/code-tool-types.d.mts

@@ -0,0 +1,16 @@
+import { ClientOptions } from '@tryfinch/finch-api';
+export type WorkerInput = {
+    opts: ClientOptions;
+    code: string;
+};
+export type WorkerSuccess = {
+    result: unknown | null;
+    logLines: string[];
+    errLines: string[];
+};
+export type WorkerError = {
+    message: string | undefined;
+    logLines: string[];
+    errLines: string[];
+};
+//# sourceMappingURL=code-tool-types.d.mts.map

package/code-tool-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tool-types.d.mts","sourceRoot":"","sources":["src/code-tool-types.ts"],"names":[],"mappings":"OAEO,EAAE,aAAa,EAAE,MAAM,qBAAqB;AAEnD,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AACF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC"}

package/code-tool-types.d.ts

@@ -0,0 +1,16 @@
+import { ClientOptions } from '@tryfinch/finch-api';
+export type WorkerInput = {
+    opts: ClientOptions;
+    code: string;
+};
+export type WorkerSuccess = {
+    result: unknown | null;
+    logLines: string[];
+    errLines: string[];
+};
+export type WorkerError = {
+    message: string | undefined;
+    logLines: string[];
+    errLines: string[];
+};
+//# sourceMappingURL=code-tool-types.d.ts.map

package/code-tool-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tool-types.d.ts","sourceRoot":"","sources":["src/code-tool-types.ts"],"names":[],"mappings":"OAEO,EAAE,aAAa,EAAE,MAAM,qBAAqB;AAEnD,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AACF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC"}

package/code-tool-types.js

@@ -0,0 +1,4 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=code-tool-types.js.map

package/code-tool-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tool-types.js","sourceRoot":"","sources":["src/code-tool-types.ts"],"names":[],"mappings":";AAAA,sFAAsF"}

package/code-tool-types.mjs

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+export {};
+//# sourceMappingURL=code-tool-types.mjs.map

package/code-tool-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tool-types.mjs","sourceRoot":"","sources":["src/code-tool-types.ts"],"names":[],"mappings":"AAAA,sFAAsF"}

package/code-tool.d.mts

@@ -0,0 +1,12 @@
+import { McpTool } from "./types.mjs";
+/**
+ * A tool that runs code against a copy of the SDK.
+ *
+ * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once,
+ * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then
+ * a generic endpoint that can be used to invoke any endpoint with the provided arguments.
+ *
+ * @param endpoints - The endpoints to include in the list.
+ */
+export declare function codeTool(): McpTool;
+//# sourceMappingURL=code-tool.d.mts.map

package/code-tool.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tool.d.mts","sourceRoot":"","sources":["src/code-tool.ts"],"names":[],"mappings":"OAEO,EAAE,OAAO,EAAiD;AAIjE;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAiDlC"}

package/code-tool.d.ts

@@ -0,0 +1,12 @@
+import { McpTool } from "./types.js";
+/**
+ * A tool that runs code against a copy of the SDK.
+ *
+ * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once,
+ * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then
+ * a generic endpoint that can be used to invoke any endpoint with the provided arguments.
+ *
+ * @param endpoints - The endpoints to include in the list.
+ */
+export declare function codeTool(): McpTool;
+//# sourceMappingURL=code-tool.d.ts.map

package/code-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tool.d.ts","sourceRoot":"","sources":["src/code-tool.ts"],"names":[],"mappings":"OAEO,EAAE,OAAO,EAAiD;AAIjE;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAiDlC"}

package/code-tool.js

@@ -0,0 +1,55 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codeTool = codeTool;
+const types_1 = require("./types.js");
+const server_1 = require("./server.js");
+/**
+ * A tool that runs code against a copy of the SDK.
+ *
+ * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once,
+ * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then
+ * a generic endpoint that can be used to invoke any endpoint with the provided arguments.
+ *
+ * @param endpoints - The endpoints to include in the list.
+ */
+function codeTool() {
+    const metadata = { resource: 'all', operation: 'write', tags: [] };
+    const tool = {
+        name: 'execute',
+        description: 'Runs JavaScript code to interact with the API.\n\nYou are a skilled programmer writing code to interface with the service.\nDefine an async function named "run" that takes a single parameter of an initialized SDK client and it will be run.\nWrite code within this template:\n\n```\nasync function run(client) {\n  // Fill this out\n}\n```\n\nYou will be returned anything that your function returns, plus the results of any console.log statements.\nIf any code triggers an error, the tool will return an error response, so you do not need to add error handling unless you want to output something more helpful than the raw error.\nIt is not necessary to add comments to code, unless by adding those comments you believe that you can generate better code.\nThis code will run in a container, and you will not be able to use fetch or otherwise interact with the network calls other than through the client you are given.\nAny variables you define won\'t live between successive uses of this call, so make sure to return or log any data you might need later.',
+        inputSchema: { type: 'object', properties: { code: { type: 'string' } } },
+    };
+    const handler = async (_, args) => {
+        const code = args.code;
+        // this is not required, but passing a Stainless API key for the matching project_name
+        // will allow you to run code-mode queries against non-published versions of your SDK.
+        const stainlessAPIKey = (0, server_1.readEnv)('STAINLESS_API_KEY');
+        const codeModeEndpoint = (0, server_1.readEnv)('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
+        const res = await fetch(codeModeEndpoint, {
+            method: 'POST',
+            headers: {
+                ...(stainlessAPIKey && { Authorization: stainlessAPIKey }),
+                'Content-Type': 'application/json',
+                client_envs: JSON.stringify({
+                    FINCH_ACCESS_TOKEN: (0, server_1.readEnv)('FINCH_ACCESS_TOKEN'),
+                    FINCH_CLIENT_ID: (0, server_1.readEnv)('FINCH_CLIENT_ID'),
+                    FINCH_CLIENT_SECRET: (0, server_1.readEnv)('FINCH_CLIENT_SECRET'),
+                    FINCH_WEBHOOK_SECRET: (0, server_1.readEnv)('FINCH_WEBHOOK_SECRET'),
+                    FINCH_BASE_URL: (0, server_1.readEnv)('FINCH_BASE_URL'),
+                }),
+            },
+            body: JSON.stringify({
+                project_name: 'finch',
+                client_opts: { accessToken: (0, server_1.readEnv)('FINCH_ACCESS_TOKEN') },
+                code,
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`${res.status}: ${res.statusText} error when trying to contact Code Tool server. Details: ${await res.text()}`);
+        }
+        return (0, types_1.asTextContentResult)((await res.json()));
+    };
+    return { metadata, tool, handler };
+}
+//# sourceMappingURL=code-tool.js.map

package/code-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tool.js","sourceRoot":"","sources":["src/code-tool.ts"],"names":[],"mappings":";AAAA,sFAAsF;;AAetF,4BAiDC;AA9DD,sCAAiF;AAEjF,wCAAmC;AAEnC;;;;;;;;GAQG;AACH,SAAgB,QAAQ;IACtB,MAAM,QAAQ,GAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC7E,MAAM,IAAI,GAAS;QACjB,IAAI,EAAE,SAAS;QACf,WAAW,EACT,iiCAAiiC;QACniC,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE;KAC1E,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,EAAE,CAAU,EAAE,IAAS,EAA2B,EAAE;QACvE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAc,CAAC;QAEjC,sFAAsF;QACtF,sFAAsF;QACtF,MAAM,eAAe,GAAG,IAAA,gBAAO,EAAC,mBAAmB,CAAC,CAAC;QACrD,MAAM,gBAAgB,GACpB,IAAA,gBAAO,EAAC,wBAAwB,CAAC,IAAI,4CAA4C,CAAC;QAEpF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,gBAAgB,EAAE;YACxC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,GAAG,CAAC,eAAe,IAAI,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;gBAC1D,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC;oBAC1B,kBAAkB,EAAE,IAAA,gBAAO,EAAC,oBAAoB,CAAC;oBACjD,eAAe,EAAE,IAAA,gBAAO,EAAC,iBAAiB,CAAC;oBAC3C,mBAAmB,EAAE,IAAA,gBAAO,EAAC,qBAAqB,CAAC;oBACnD,oBAAoB,EAAE,IAAA,gBAAO,EAAC,sBAAsB,CAAC;oBACrD,cAAc,EAAE,IAAA,gBAAO,EAAC,gBAAgB,CAAC;iBAC1C,CAAC;aACH;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,YAAY,EAAE,OAAO;gBACrB,WAAW,EAAE,EAAE,WAAW,EAAE,IAAA,gBAAO,EAAC,oBAAoB,CAAC,EAAE;gBAC3D,IAAI;aACL,CAAC;SACH,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,MAAM,KACX,GAAG,CAAC,UACN,4DAA4D,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAC/E,CAAC;QACJ,CAAC;QAED,OAAO,IAAA,2BAAmB,EAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAkB,CAAC,CAAC;IAClE,CAAC,CAAC;IAEF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACrC,CAAC"}

package/code-tool.mjs

@@ -0,0 +1,52 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { asTextContentResult } from "./types.mjs";
+import { readEnv } from "./server.mjs";
+/**
+ * A tool that runs code against a copy of the SDK.
+ *
+ * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once,
+ * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then
+ * a generic endpoint that can be used to invoke any endpoint with the provided arguments.
+ *
+ * @param endpoints - The endpoints to include in the list.
+ */
+export function codeTool() {
+    const metadata = { resource: 'all', operation: 'write', tags: [] };
+    const tool = {
+        name: 'execute',
+        description: 'Runs JavaScript code to interact with the API.\n\nYou are a skilled programmer writing code to interface with the service.\nDefine an async function named "run" that takes a single parameter of an initialized SDK client and it will be run.\nWrite code within this template:\n\n```\nasync function run(client) {\n  // Fill this out\n}\n```\n\nYou will be returned anything that your function returns, plus the results of any console.log statements.\nIf any code triggers an error, the tool will return an error response, so you do not need to add error handling unless you want to output something more helpful than the raw error.\nIt is not necessary to add comments to code, unless by adding those comments you believe that you can generate better code.\nThis code will run in a container, and you will not be able to use fetch or otherwise interact with the network calls other than through the client you are given.\nAny variables you define won\'t live between successive uses of this call, so make sure to return or log any data you might need later.',
+        inputSchema: { type: 'object', properties: { code: { type: 'string' } } },
+    };
+    const handler = async (_, args) => {
+        const code = args.code;
+        // this is not required, but passing a Stainless API key for the matching project_name
+        // will allow you to run code-mode queries against non-published versions of your SDK.
+        const stainlessAPIKey = readEnv('STAINLESS_API_KEY');
+        const codeModeEndpoint = readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
+        const res = await fetch(codeModeEndpoint, {
+            method: 'POST',
+            headers: {
+                ...(stainlessAPIKey && { Authorization: stainlessAPIKey }),
+                'Content-Type': 'application/json',
+                client_envs: JSON.stringify({
+                    FINCH_ACCESS_TOKEN: readEnv('FINCH_ACCESS_TOKEN'),
+                    FINCH_CLIENT_ID: readEnv('FINCH_CLIENT_ID'),
+                    FINCH_CLIENT_SECRET: readEnv('FINCH_CLIENT_SECRET'),
+                    FINCH_WEBHOOK_SECRET: readEnv('FINCH_WEBHOOK_SECRET'),
+                    FINCH_BASE_URL: readEnv('FINCH_BASE_URL'),
+                }),
+            },
+            body: JSON.stringify({
+                project_name: 'finch',
+                client_opts: { accessToken: readEnv('FINCH_ACCESS_TOKEN') },
+                code,
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`${res.status}: ${res.statusText} error when trying to contact Code Tool server. Details: ${await res.text()}`);
+        }
+        return asTextContentResult((await res.json()));
+    };
+    return { metadata, tool, handler };
+}
+//# sourceMappingURL=code-tool.mjs.map

package/code-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tool.mjs","sourceRoot":"","sources":["src/code-tool.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAqC,mBAAmB,EAAE;OAE1D,EAAE,OAAO,EAAE;AAElB;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,QAAQ,GAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC7E,MAAM,IAAI,GAAS;QACjB,IAAI,EAAE,SAAS;QACf,WAAW,EACT,iiCAAiiC;QACniC,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE;KAC1E,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,EAAE,CAAU,EAAE,IAAS,EAA2B,EAAE;QACvE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAc,CAAC;QAEjC,sFAAsF;QACtF,sFAAsF;QACtF,MAAM,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACrD,MAAM,gBAAgB,GACpB,OAAO,CAAC,wBAAwB,CAAC,IAAI,4CAA4C,CAAC;QAEpF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,gBAAgB,EAAE;YACxC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,GAAG,CAAC,eAAe,IAAI,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;gBAC1D,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC;oBAC1B,kBAAkB,EAAE,OAAO,CAAC,oBAAoB,CAAC;oBACjD,eAAe,EAAE,OAAO,CAAC,iBAAiB,CAAC;oBAC3C,mBAAmB,EAAE,OAAO,CAAC,qBAAqB,CAAC;oBACnD,oBAAoB,EAAE,OAAO,CAAC,sBAAsB,CAAC;oBACrD,cAAc,EAAE,OAAO,CAAC,gBAAgB,CAAC;iBAC1C,CAAC;aACH;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,YAAY,EAAE,OAAO;gBACrB,WAAW,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,oBAAoB,CAAC,EAAE;gBAC3D,IAAI;aACL,CAAC;SACH,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,MAAM,KACX,GAAG,CAAC,UACN,4DAA4D,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAC/E,CAAC;QACJ,CAAC;QAED,OAAO,mBAAmB,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAkB,CAAC,CAAC;IAClE,CAAC,CAAC;IAEF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACrC,CAAC"}

package/docs-search-tool.d.mts

@@ -0,0 +1,50 @@
+import { Metadata } from "./types.mjs";
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const metadata: Metadata;
+export declare const tool: Tool;
+export declare const handler: (_: unknown, args: Record<string, unknown> | undefined) => Promise<import("./types").ToolCallResult>;
+declare const _default: {
+    metadata: Metadata;
+    tool: {
+        inputSchema: {
+            [x: string]: unknown;
+            type: "object";
+            properties?: {
+                [x: string]: object;
+            } | undefined;
+            required?: string[] | undefined;
+        };
+        name: string;
+        description?: string | undefined;
+        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: (_: unknown, args: Record<string, unknown> | undefined) => Promise<import("./types").ToolCallResult>;
+};
+export default _default;
+//# sourceMappingURL=docs-search-tool.d.mts.map

package/docs-search-tool.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-search-tool.d.mts","sourceRoot":"","sources":["src/docs-search-tool.ts"],"names":[],"mappings":"OAEO,EAAE,QAAQ,EAAuB;OAEjC,EAAE,IAAI,EAAE,MAAM,oCAAoC;AAEzD,eAAO,MAAM,QAAQ,EAAE,QAKtB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,IA0BlB,CAAC;AAKF,eAAO,MAAM,OAAO,GAAU,GAAG,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,8CAYlF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAZ+B,OAAO,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;;AAcnF,wBAA2C"}