release: 0.1.0-alpha.2

.github/workflows/ci.yml

@@ -72,10 +72,13 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Bootstrap
         run: ./scripts/bootstrap
 
+      - name: Build
+        run: ./scripts/build
+
       - name: Run tests
         run: ./scripts/test

.github/workflows/publish-npm.yml

@@ -4,6 +4,10 @@
 name: Publish NPM
 on:
   workflow_dispatch:
+    inputs:
+      path:
+        description: The path to run the release in, e.g. '.' or 'packages/mcp-server'
+        required: true
 
   release:
     types: [published]
@@ -27,6 +31,11 @@ jobs:
 
       - name: Publish to NPM
         run: |
-          bash ./bin/publish-npm
+          if [ -n "${{ github.event.inputs.path }}" ]; then
+            PATHS_RELEASED='[\"${{ github.event.inputs.path }}\"]'
+          else
+            PATHS_RELEASED='[\".\", \"packages/mcp-server\"]'
+          fi
+          yarn tsn scripts/publish-packages.ts "{ \"paths_released\": \"$PATHS_RELEASED\" }"
         env:
           NPM_TOKEN: ${{ secrets.SCAN_DOCUMENTS_NPM_TOKEN || secrets.NPM_TOKEN }}

.prettierignore

@@ -4,4 +4,4 @@ CHANGELOG.md
 /deno
 
 # don't format tsc output, will break source maps
-/dist
+dist

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.1"
+  ".": "0.1.0-alpha.2"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 17
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/scan-documents%2Fscan-documents-04f736d0a9ae5151fec360201288ee49dc02cc4f60adf1ff17c5e3a0bbb639b4.yml
 openapi_spec_hash: e9d1be2b0eae296e605a9a79af48ab63
-config_hash: 277743e0fb95d030cf82282dc09bf31a
+config_hash: 242faa43d2cdcb84a3ac26da983e34c6

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.0-alpha.2 (2025-05-21)
+
+Full Changelog: [v0.1.0-alpha.1...v0.1.0-alpha.2](https://github.com/Scan-Documents/node-sdk/compare/v0.1.0-alpha.1...v0.1.0-alpha.2)
+
+### Chores
+
+* configure new SDK language ([c67054f](https://github.com/Scan-Documents/node-sdk/commit/c67054fbb0ddd462c28710624f704049361cabb4))
+
 ## 0.1.0-alpha.1 (2025-05-21)
 
 Full Changelog: [v0.0.1-alpha.0...v0.1.0-alpha.1](https://github.com/Scan-Documents/node-sdk/compare/v0.0.1-alpha.0...v0.1.0-alpha.1)

eslint.config.mjs

@@ -34,7 +34,7 @@ export default tseslint.config(
     },
   },
   {
-    files: ['tests/**', 'examples/**'],
+    files: ['tests/**', 'examples/**', 'packages/**'],
     rules: {
       'no-restricted-imports': 'off',
     },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "scan-documents",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "The official TypeScript library for the Scan Documents API",
   "author": "Scan Documents <>",
   "types": "dist/index.d.ts",

packages/mcp-server/README.md

@@ -0,0 +1,198 @@
+# Scan Documents TypeScript MCP Server
+
+It is generated with [Stainless](https://www.stainless.com/).
+
+## Installation
+
+### Direct invocation
+
+You can run the MCP Server directly via `npx`:
+
+```sh
+export SCAN_DOCUMENTS_API_KEY="My API Key"
+npx -y scan-documents-mcp@latest
+```
+
+### Via MCP Client
+
+There is a partial list of existing clients at [modelcontextprotocol.io](https://modelcontextprotocol.io/clients). If you already
+have a client, consult their documentation to install the MCP server.
+
+For clients with a configuration JSON, it might look something like this:
+
+```json
+{
+  "mcpServers": {
+    "scan_documents_api": {
+      "command": "npx",
+      "args": ["-y", "scan-documents-mcp", "--client=claude", "--tools=all"],
+      "env": {
+        "SCAN_DOCUMENTS_API_KEY": "My API Key"
+      }
+    }
+  }
+}
+```
+
+## Exposing endpoints to your MCP Client
+
+There are two ways to expose endpoints as tools in the 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
+
+### Filtering endpoints and tools
+
+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.
+
+You can filter by multiple aspects:
+
+- `--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
+
+### Dynamic tools
+
+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
+```
+
+3. Configure for Cursor client with custom max tool name length:
+
+```bash
+--client=cursor --capability=tool-name-length=40
+```
+
+4. Complex filtering with multiple criteria:
+
+```bash
+--resource=cards,accounts --operation=read --tag=kyc --no-tool=create_cards
+```
+
+## Importing the tools and server individually
+
+```js
+// Import the server, generated endpoints, or the init function
+import { server, endpoints, init } from "scan-documents-mcp/server";
+
+// import a specific tool
+import retrieveFiles from "scan-documents-mcp/tools/files/retrieve-files";
+
+// initialize the server and all endpoints
+init({ server, endpoints });
+
+// manually start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// or initialize your own server with specific tools
+const myServer = new McpServer(...);
+
+// 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!' };
+  })
+};
+
+// initialize the server with your custom endpoints
+init({ server: myServer, endpoints: [retrieveFiles, myCustomEndpoint] });
+```
+
+## Available Tools
+
+The following tools are available in this MCP server.
+
+### Resource `files`:
+
+- `retrieve_files` (`read`): Retrieves the data for a specific file by its ID.
+- `list_files` (`read`): Retrieves a paginated list of files belonging to the authenticated user.
+- `delete_files` (`write`): Deletes a specific file by its ID.
+- `download_files` (`read`): Downloads the content of a specific file by its ID.
+- `upload_files` (`write`): Uploads a file to the user's storage. The file size is limited to 10MB.
+
+### Resource `tasks`:
+
+- `retrieve_tasks` (`read`): Retrieves the data for a specific task by its ID.
+- `list_tasks` (`read`): Retrieves a paginated list of tasks belonging to the authenticated user.
+
+### Resource `events`:
+
+- `list_events` (`read`): Retrieves a paginated list of events belonging to the authenticated user.
+
+### Resource `image_operations`:
+
+- `apply_effect_image_operations` (`write`): Creates a task to apply a specified visual effect to an image.
+- `convert_image_operations` (`write`): Creates a task to convert an image file to a different format.
+- `detect_documents_image_operations` (`write`): Creates a task to detect document boundaries within an image.
+- `extract_text_image_operations` (`write`): Creates a task to extract text from a specified image file.
+- `warp_image_operations` (`write`): Creates a task to apply perspective correction (warp) to an image based on detected document boundaries.
+
+### Resource `pdf_operations`:
+
+- `extract_pages_pdf_operations` (`write`): Creates a task to extract specific pages from a PDF file into a new PDF file.
+- `merge_pdf_operations` (`write`): Creates a task to merge multiple PDF and/or image files into a single PDF file.
+- `render_pdf_operations` (`write`): Creates a task to render specified pages of a PDF file as images.
+- `split_pdf_operations` (`write`): Creates a task to split a PDF file into multiple single-page PDF files.

packages/mcp-server/build

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -exuo pipefail
+
+rm -rf dist; mkdir dist
+
+# Copy src to dist/src and build from dist/src into dist, so that
+# the source map for index.js.map will refer to ./src/index.ts etc
+cp -rp src README.md dist
+
+for file in LICENSE; do
+  if [ -e "../../${file}" ]; then cp "../../${file}" dist; fi
+done
+
+for file in CHANGELOG.md; do
+  if [ -e "${file}" ]; then cp "${file}" dist; fi
+done
+
+# this converts the export map paths for the dist directory
+# and does a few other minor things
+PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist/package.json
+
+# updates the `scan-documents` dependency to point to NPM
+node scripts/postprocess-dist-package-json.cjs
+
+# build to .js/.mjs/.d.ts files
+npm exec tsc-multi
+
+cp tsconfig.dist-src.json dist/src/tsconfig.json
+
+# Add proper Node.js shebang to the top of the file
+sed -i.bak '1s;^;#!/usr/bin/env node\n;' dist/index.js
+rm dist/index.js.bak
+
+chmod +x dist/index.js
+
+DIST_PATH=./dist PKG_IMPORT_PATH=scan-documents-mcp/ node ../../scripts/utils/postprocess-files.cjs

packages/mcp-server/jest.config.ts

@@ -0,0 +1,17 @@
+import type { JestConfigWithTsJest } from 'ts-jest';
+
+const config: JestConfigWithTsJest = {
+  preset: 'ts-jest/presets/default-esm',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.(t|j)sx?$': ['@swc/jest', { sourceMaps: 'inline' }],
+  },
+  moduleNameMapper: {
+    '^scan-documents-mcp$': '<rootDir>/src/index.ts',
+    '^scan-documents-mcp/(.*)$': '<rootDir>/src/$1',
+  },
+  modulePathIgnorePatterns: ['<rootDir>/dist/'],
+  testPathIgnorePatterns: ['scripts'],
+};
+
+export default config;