release: 0.1.0-alpha.6

.github/workflows/ci.yml

@@ -17,13 +17,14 @@ jobs:
     timeout-minutes: 10
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/scan-documents-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
       - uses: actions/checkout@v4
 
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Bootstrap
         run: ./scripts/bootstrap
@@ -35,6 +36,7 @@ jobs:
     timeout-minutes: 5
     name: build
     runs-on: ${{ github.repository == 'stainless-sdks/scan-documents-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     permissions:
       contents: read
       id-token: write
@@ -44,7 +46,7 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Bootstrap
         run: ./scripts/bootstrap
@@ -66,10 +68,20 @@ jobs:
           AUTH: ${{ steps.github-oidc.outputs.github_token }}
           SHA: ${{ github.sha }}
         run: ./scripts/utils/upload-artifact.sh
+
+      - name: Upload MCP Server tarball
+        if: github.repository == 'stainless-sdks/scan-documents-typescript'
+        env:
+          URL: https://pkg.stainless.com/s?subpackage=mcp-server
+          AUTH: ${{ steps.github-oidc.outputs.github_token }}
+          SHA: ${{ github.sha }}
+          BUILD_PATH: packages/mcp-server/dist
+        run: ./scripts/utils/upload-artifact.sh
   test:
     timeout-minutes: 10
     name: test
     runs-on: ${{ github.repository == 'stainless-sdks/scan-documents-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
       - uses: actions/checkout@v4
 

.release-please-manifest.json

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

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 17
+configured_endpoints: 18
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/scan-documents%2Fscan-documents-42f9aa9c3b2769584f60fa3742f3a004bdf2e3b5ba30a44535b0191654b1a51e.yml
 openapi_spec_hash: a0bab3e1411b24d8a662df98d227049a
-config_hash: 4f1180f734cbc7323ff2ed85a9cd510d
+config_hash: c1dd12e2ddf127e74f1b4981eef49e2b

CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 0.1.0-alpha.6 (2025-08-24)
+
+Full Changelog: [v0.1.0-alpha.5...v0.1.0-alpha.6](https://github.com/Scan-Documents/node-sdk/compare/v0.1.0-alpha.5...v0.1.0-alpha.6)
+
+### Features
+
+* **api:** update via SDK Studio ([29066c7](https://github.com/Scan-Documents/node-sdk/commit/29066c78a803d4eb260385bdf2a3e7748390b91d))
+* **mcp:** add code execution tool ([c36e7ab](https://github.com/Scan-Documents/node-sdk/commit/c36e7ab1ffe8f98f94603aa729b080bd16e034c4))
+* **mcp:** add logging when environment variable is set ([57fc795](https://github.com/Scan-Documents/node-sdk/commit/57fc7959d83c30d25152a60aeb8895df38ab15b8))
+* **mcp:** add option to infer mcp client ([149e514](https://github.com/Scan-Documents/node-sdk/commit/149e5145317a38b8acb37ec99948fc3aab8a2a2b))
+* **mcp:** add unix socket option for remote MCP ([72982bc](https://github.com/Scan-Documents/node-sdk/commit/72982bc112a6a5725956354b361944069cf92faa))
+* **mcp:** fallback for void-typed methods ([965b606](https://github.com/Scan-Documents/node-sdk/commit/965b6064ff025b992e21c9fd54edbe6963d27b6b))
+* **mcp:** parse query string as mcp client options in mcp server ([a72cd42](https://github.com/Scan-Documents/node-sdk/commit/a72cd4273cb2efc360656de84e17c94d2ba21c25))
+* **mcp:** remote server with passthru auth ([05f1022](https://github.com/Scan-Documents/node-sdk/commit/05f1022cf2d8897c5ca52bdac865fea951dabc39))
+* **mcp:** support filtering tool results by a jq expression ([436421e](https://github.com/Scan-Documents/node-sdk/commit/436421e66b382295d19149478a5cabb21bce12a6))
+
+
+### Bug Fixes
+
+* **ci:** release-doctor — report correct token name ([2430747](https://github.com/Scan-Documents/node-sdk/commit/2430747fe786df1a9e237b884c59082cfc21a2bf))
+* **client:** get fetchOptions type more reliably ([0a17458](https://github.com/Scan-Documents/node-sdk/commit/0a17458ddfe37d5b3e5c10f7e257fad3e2d08129))
+* **mcp:** avoid sending `jq_filter` to base API ([11b40cc](https://github.com/Scan-Documents/node-sdk/commit/11b40cca569792c127c204a6ca9c39e688b182be))
+* **mcp:** fix tool description of jq_filter ([33effa6](https://github.com/Scan-Documents/node-sdk/commit/33effa6ccb54e2da65a9aaad00bcbb7070e2bdd0))
+* **mcp:** generate additionalProperties=true for map schemas to avoid validation issues ([488ee1c](https://github.com/Scan-Documents/node-sdk/commit/488ee1c68366d5253d75565838c2c3447af525b1))
+* **mcp:** include required section for top-level properties and support naming transformations ([f7827a6](https://github.com/Scan-Documents/node-sdk/commit/f7827a6390ec0922cdc039344f47774cf588da14))
+* **mcp:** relax input type for asTextContextResult ([7f50ae3](https://github.com/Scan-Documents/node-sdk/commit/7f50ae35b174c4e7863bfc71c71ce70f71893ef7))
+* **mcp:** reverse validJson capability option and limit scope ([41bd333](https://github.com/Scan-Documents/node-sdk/commit/41bd333e563e4b23100f1f239928aa8c60fc223c))
+* **mcp:** support jq filtering on cloudflare workers ([d2bee12](https://github.com/Scan-Documents/node-sdk/commit/d2bee126b3794e12e7a66fd1df7600a89c7adf7a))
+
+
+### Chores
+
+* add docs to RequestOptions type ([26a2df1](https://github.com/Scan-Documents/node-sdk/commit/26a2df16f3133c6f3ebfa06a906ccbdb667b763c))
+* add package to package.json ([52c2226](https://github.com/Scan-Documents/node-sdk/commit/52c22269924c2992a427ce0136bf1f9effd4da8b))
+* **ci:** only run for pushes and fork pull requests ([fedf819](https://github.com/Scan-Documents/node-sdk/commit/fedf819df77819d08582e26bf2d768a0971684d0))
+* **client:** improve path param validation ([00bb123](https://github.com/Scan-Documents/node-sdk/commit/00bb1237344ad7b4d3cafb5ee3f8015033f581ad))
+* **client:** qualify global Blob ([b110292](https://github.com/Scan-Documents/node-sdk/commit/b110292d90aa445e9d73dd7cfa77d2bd57e46aa9))
+* **deps:** update dependency @types/node to v20.17.58 ([b435ab1](https://github.com/Scan-Documents/node-sdk/commit/b435ab1ef8e26e20a35842579846c87cd20ff4be))
+* **internal:** codegen related update ([5560f78](https://github.com/Scan-Documents/node-sdk/commit/5560f78a373d434a2b1a86f57fd14da284581bc0))
+* **internal:** codegen related update ([3554f3c](https://github.com/Scan-Documents/node-sdk/commit/3554f3cab5ce7969889c889bb833e8aa45740159))
+* **internal:** codegen related update ([4d9ab35](https://github.com/Scan-Documents/node-sdk/commit/4d9ab3563cfe93b7a61097a484e9f37f7604c5b7))
+* **internal:** codegen related update ([b47458d](https://github.com/Scan-Documents/node-sdk/commit/b47458d7c6269e4acbfc6fb4b469597581633e49))
+* **internal:** formatting change ([5a0343c](https://github.com/Scan-Documents/node-sdk/commit/5a0343c3751c96f3637abfd0ea84df271abf70a2))
+* **internal:** make mcp-server publishing public by defaut ([cb532ff](https://github.com/Scan-Documents/node-sdk/commit/cb532ff281e968d46b3d5dd5710d36ac9bdd530e))
+* **internal:** move publish config ([1947212](https://github.com/Scan-Documents/node-sdk/commit/1947212b285dd090527c98fb607308003036e1e3))
+* **internal:** refactor array check ([39a25bf](https://github.com/Scan-Documents/node-sdk/commit/39a25bf20d4cafdca951e6aa0fa0bf74a00b378f))
+* **internal:** remove redundant imports config ([cfe049c](https://github.com/Scan-Documents/node-sdk/commit/cfe049c407230ed71a4216f893cedb1c85ba856e))
+* **internal:** update comment in script ([3be780c](https://github.com/Scan-Documents/node-sdk/commit/3be780cb1d9bc7136a79a2f130617a42bd38b081))
+* make some internal functions async ([064caed](https://github.com/Scan-Documents/node-sdk/commit/064caed6799b56c06d441e02319f31ca79f0549f))
+* **mcp:** add cors to oauth metadata route ([e47261c](https://github.com/Scan-Documents/node-sdk/commit/e47261c644a962bc76c7ad5afb92ded38034098d))
+* **mcp:** document remote server in README.md ([64f8b3a](https://github.com/Scan-Documents/node-sdk/commit/64f8b3a076b881b43878aa2e78c2942a6b53d98d))
+* **mcp:** formatting ([32923a2](https://github.com/Scan-Documents/node-sdk/commit/32923a200bbe8c6ba2658428be044bd14e5f09cb))
+* **mcp:** minor cleanup of types and package.json ([938a40b](https://github.com/Scan-Documents/node-sdk/commit/938a40bc3dc1b8f4cacdea781c23dea0680ac1eb))
+* **mcp:** refactor streamable http transport ([8a955ea](https://github.com/Scan-Documents/node-sdk/commit/8a955eaa7bb01a0a85817567cd0000a15cdca487))
+* **mcp:** rework imports in tools ([df24a2f](https://github.com/Scan-Documents/node-sdk/commit/df24a2f821d16e2ef006bf6715be5d87b1179a83))
+* **mcp:** update package.json ([261f3f5](https://github.com/Scan-Documents/node-sdk/commit/261f3f5cef6e12b4d435264bc11ce5cc52f6ec6b))
+* **mcp:** update README ([b821690](https://github.com/Scan-Documents/node-sdk/commit/b821690f1b0a2494dcb6b2ab0643a212b4a040dc))
+* **mcp:** update types ([079839c](https://github.com/Scan-Documents/node-sdk/commit/079839c4089e8cf828d49a36339dc8764e1b6e71))
+* **ts:** reorder package.json imports ([596fc4f](https://github.com/Scan-Documents/node-sdk/commit/596fc4f6d1323ceeecf8eef62cc165d5430f9069))
+* update @stainless-api/prism-cli to v5.15.0 ([b609b33](https://github.com/Scan-Documents/node-sdk/commit/b609b338d3f8db485a3ede5f4fe920db21c79149))
+* update CI script ([2ace297](https://github.com/Scan-Documents/node-sdk/commit/2ace29730fa8c3b74531c0945e955b1339fafc6c))
+
 ## 0.1.0-alpha.5 (2025-06-24)
 
 Full Changelog: [v0.1.0-alpha.4...v0.1.0-alpha.5](https://github.com/Scan-Documents/node-sdk/compare/v0.1.0-alpha.4...v0.1.0-alpha.5)

README.md

@@ -79,7 +79,6 @@ await client.files.upload({ file: await toFile(Buffer.from('my bytes'), 'file'),
 await client.files.upload({ file: await toFile(new Uint8Array([0, 1, 2]), 'file'), name: 'File Name' });
 ```
 
-
 ## Task operations
 
 Operations can be found under the `imageOperations` and `pdfOperations` resources.

api.md

@@ -54,6 +54,7 @@ Types:
 - <code><a href="./src/resources/image-operations.ts">ExtractTextRequest</a></code>
 - <code><a href="./src/resources/image-operations.ts">ExtractTextResponse</a></code>
 - <code><a href="./src/resources/image-operations.ts">ImageFromTaskResponse</a></code>
+- <code><a href="./src/resources/image-operations.ts">ScanResponse</a></code>
 - <code><a href="./src/resources/image-operations.ts">WarpRequest</a></code>
 - <code><a href="./src/resources/image-operations.ts">WarpResponse</a></code>
 
@@ -63,6 +64,7 @@ Methods:
 - <code title="post /v1/image-operations/convert">client.imageOperations.<a href="./src/resources/image-operations.ts">convert</a>({ ...params }) -> ConvertResponse</code>
 - <code title="post /v1/image-operations/detect-documents">client.imageOperations.<a href="./src/resources/image-operations.ts">detectDocuments</a>({ ...params }) -> DetectDocumentsResponse</code>
 - <code title="post /v1/image-operations/extract-text">client.imageOperations.<a href="./src/resources/image-operations.ts">extractText</a>({ ...params }) -> ExtractTextResponse</code>
+- <code title="post /v1/image-operations/scan">client.imageOperations.<a href="./src/resources/image-operations.ts">scan</a>({ ...params }) -> ScanResponse</code>
 - <code title="post /v1/image-operations/warp">client.imageOperations.<a href="./src/resources/image-operations.ts">warp</a>({ ...params }) -> WarpResponse</code>
 
 # PdfOperations

bin/check-release-environment

@@ -3,7 +3,7 @@
 errors=()
 
 if [ -z "${NPM_TOKEN}" ]; then
-  errors+=("The SCAN_DOCUMENTS_NPM_TOKEN secret has not been set. Please set it in either this repository's secrets or your organization secrets")
+  errors+=("The NPM_TOKEN secret has not been set. Please set it in either this repository's secrets or your organization secrets")
 fi
 
 lenErrors=${#errors[@]}

bin/publish-npm

@@ -58,4 +58,4 @@ else
 fi
 
 # Publish with the appropriate tag
-yarn publish --access public --tag "$TAG"
+yarn publish --tag "$TAG"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "scan-documents",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "The official TypeScript library for the Scan Documents API",
   "author": "Scan Documents <support@scan-documents.com>",
   "types": "dist/index.d.ts",
@@ -13,6 +13,9 @@
     "**/*"
   ],
   "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "test": "./scripts/test",
     "build": "./scripts/build",
@@ -30,7 +33,6 @@
     "@swc/jest": "^0.2.29",
     "@types/jest": "^29.4.0",
     "@types/node": "^20.17.6",
-    "typescript-eslint": "8.31.1",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
     "eslint": "^9.20.1",
@@ -42,13 +44,11 @@
     "publint": "^0.2.12",
     "ts-jest": "^29.1.0",
     "ts-node": "^10.5.0",
-    "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.8/tsc-multi.tgz",
+    "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.9/tsc-multi.tgz",
     "tsconfig-paths": "^4.0.0",
-    "typescript": "5.8.3"
-  },
-  "imports": {
-    "scan-documents": ".",
-    "scan-documents/*": "./src/*"
+    "tslib": "^2.8.1",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.31.1"
   },
   "exports": {
     ".": {

packages/mcp-server/README.md

@@ -126,6 +126,43 @@ over time, you can manually enable or disable certain capabilities:
 --resource=cards,accounts --operation=read --tag=kyc --no-tool=create_cards
 ```
 
+## Running remotely
+
+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.
+
+Authorization can be provided via the following headers:
+| Header | Equivalent client option | Security scheme |
+| ----------- | ------------------------ | --------------- |
+| `x-api-key` | `apiKey` | ApiKeyAuth |
+
+A configuration JSON for this server might look like this, assuming the server is hosted at `http://localhost:3000`:
+
+```json
+{
+  "mcpServers": {
+    "scan_documents_api": {
+      "url": "http://localhost:3000",
+      "headers": {
+        "x-api-key": "My API Key"
+      }
+    }
+  }
+}
+```
+
+The command-line arguments for filtering tools and specifying clients can also be used as query parameters in the URL.
+For example, to exclude specific tools while including others, use the URL:
+
+```
+http://localhost:3000?resource=cards&resource=accounts&no_tool=create_cards
+```
+
+Or, to configure for the Cursor client, with a custom max tool name length, use the URL:
+
+```
+http://localhost:3000?client=cursor&capability=tool-name-length%3D40
+```
+
 ## Importing the tools and server individually
 
 ```js
@@ -188,6 +225,8 @@ The following tools are available in this MCP server.
 - `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.
+- `scan_image_operations` (`write`): Creates a task to scan an image file.
+  This is an equivalent operation for `detect-documents` and `warp` combined, additionally it can apply effects to the scanned image.
 - `warp_image_operations` (`write`): Creates a task to apply perspective correction (warp) to an image based on detected document boundaries.
 
 ### Resource `pdf_operations`:

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scan-documents-mcp",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "The official MCP Server for the Scan Documents API",
   "author": "Scan Documents <support@scan-documents.com>",
   "types": "dist/index.d.ts",
@@ -15,6 +15,9 @@
   "license": "Apache-2.0",
   "packageManager": "yarn@1.22.22",
   "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "test": "jest",
     "build": "bash ./build",
@@ -28,17 +31,27 @@
   },
   "dependencies": {
     "scan-documents": "file:../../dist/",
+    "@cloudflare/cabidela": "^0.2.4",
     "@modelcontextprotocol/sdk": "^1.11.5",
+    "@valtown/deno-http-worker": "^0.0.21",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.6/jq-web.tar.gz",
+    "qs": "^6.14.0",
     "yargs": "^17.7.2",
-    "@cloudflare/cabidela": "^0.2.4",
     "zod": "^3.25.20",
-    "zod-to-json-schema": "^3.24.5"
+    "zod-to-json-schema": "^3.24.5",
+    "zod-validation-error": "^4.0.1"
   },
   "bin": {
     "mcp-server": "dist/index.js"
   },
   "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
     "@types/jest": "^29.4.0",
+    "@types/qs": "^6.14.0",
+    "@types/yargs": "^17.0.8",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
     "eslint": "^8.49.0",
@@ -49,7 +62,7 @@
     "ts-jest": "^29.1.0",
     "ts-morph": "^19.0.0",
     "ts-node": "^10.5.0",
-    "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.8/tsc-multi.tgz",
+    "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.9/tsc-multi.tgz",
     "tsconfig-paths": "^4.0.0",
     "typescript": "5.8.3"
   },

packages/mcp-server/src/code-tool-paths.cts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export const workerPath = require.resolve('./code-tool-worker.mjs');

packages/mcp-server/src/code-tool-types.ts

@@ -0,0 +1,14 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { ClientOptions } from 'scan-documents';
+
+export type WorkerInput = {
+  opts: ClientOptions;
+  code: string;
+};
+export type WorkerSuccess = {
+  result: unknown | null;
+  logLines: string[];
+  errLines: string[];
+};
+export type WorkerError = { message: string | undefined };

packages/mcp-server/src/code-tool-worker.ts

@@ -0,0 +1,46 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import util from 'node:util';
+import { WorkerInput, WorkerSuccess, WorkerError } from './code-tool-types';
+import { ScanDocuments } from 'scan-documents';
+
+const fetch = async (req: Request): Promise<Response> => {
+  const { opts, code } = (await req.json()) as WorkerInput;
+  const client = new ScanDocuments({
+    ...opts,
+  });
+
+  const logLines: string[] = [];
+  const errLines: string[] = [];
+  const console = {
+    log: (...args: unknown[]) => {
+      logLines.push(util.format(...args));
+    },
+    error: (...args: unknown[]) => {
+      errLines.push(util.format(...args));
+    },
+  };
+  try {
+    let run_ = async (client: any) => {};
+    eval(`
+      ${code}
+      run_ = run;
+    `);
+    const result = await run_(client);
+    return Response.json({
+      result,
+      logLines,
+      errLines,
+    } satisfies WorkerSuccess);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : undefined;
+    return Response.json(
+      {
+        message,
+      } satisfies WorkerError,
+      { status: 400, statusText: 'Code execution error' },
+    );
+  }
+};
+
+export default { fetch };