release: 0.1.0-alpha.17

.github/workflows/release-doctor.yml

@@ -20,3 +20,4 @@ jobs:
         env:
           NPM_TOKEN: ${{ secrets.STAINLESS_NPM_TOKEN || secrets.NPM_TOKEN }}
           DOCKERHUB_TOKEN: ${{ secrets.STAINLESS_DOCKERHUB_TOKEN || secrets.DOCKERHUB_TOKEN }}
+

.gitignore

@@ -7,5 +7,6 @@ dist
 dist-deno
 /*.tgz
 .idea/
+.eslintcache
 dist-bundle
 *.mcpb

.release-please-manifest.json

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

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 19
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/stainless%2Fstainless-v0-5c1008fd27f64bcde1a146a4158f1c3113b4e13437a4d880bd6811fb063cfcd6.yml
-openapi_spec_hash: 9583f62164b5dc15b10051dad6a7fca4
-config_hash: e895f7992a607a15865ed026cbe5470d
+configured_endpoints: 20
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/stainless%2Fstainless-v0-030e47a1bfd79a657974f5beddd685940ec04b1aa1786c3b2cb0f4610ad2b42c.yml
+openapi_spec_hash: 33b337af28bcc1c9aa1a5218acf2a7fe
+config_hash: 6b235571b537b4814a33a1008b443e36

CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.1.0-alpha.17 (2025-11-12)
+
+Full Changelog: [v0.1.0-alpha.16...v0.1.0-alpha.17](https://github.com/stainless-api/stainless-api-typescript/compare/v0.1.0-alpha.16...v0.1.0-alpha.17)
+
+### Features
+
+* Expose connection-specific decorated OAS ([f5bf0d1](https://github.com/stainless-api/stainless-api-typescript/commit/f5bf0d19f2aa16e2725268f09723437707eaa398))
+* **mcp:** enable optional code execution tool on http mcp servers ([4672381](https://github.com/stainless-api/stainless-api-typescript/commit/46723815835990f657488a48c95e57450fbd6956))
+
+
+### Bug Fixes
+
+* **mcpb:** pin @anthropic-ai/mcpb version ([6128a17](https://github.com/stainless-api/stainless-api-typescript/commit/6128a17ea4d7769d69d32776e971841d88c8b6b2))
+* **mcp:** fix cli argument parsing logic ([6f51296](https://github.com/stainless-api/stainless-api-typescript/commit/6f5129610f26504aa48d94375dbff726406aef51))
+* **mcp:** resolve a linting issue in server code ([3695b9c](https://github.com/stainless-api/stainless-api-typescript/commit/3695b9cf8da2c80a10e0164ea689cee3e8e05b4d))
+
+
+### Chores
+
+* extract some types in mcp docs ([6953e19](https://github.com/stainless-api/stainless-api-typescript/commit/6953e19081e6fd162450cb352745829803870036))
+* fix dockerfile ([a8620b9](https://github.com/stainless-api/stainless-api-typescript/commit/a8620b9e901e80a509217c0afdcfde3ca7db2594))
+* **internal:** codegen related update ([f5c0a4d](https://github.com/stainless-api/stainless-api-typescript/commit/f5c0a4d3c7a8d6f2ecee1cfe6a49b6d7207e2698))
+* **internal:** codegen related update ([6de1b6d](https://github.com/stainless-api/stainless-api-typescript/commit/6de1b6d21a332a82139fc62a09a339cc3e2deb34))
+* **internal:** codegen related update ([3dac6b5](https://github.com/stainless-api/stainless-api-typescript/commit/3dac6b5b9b954b7342a59da26bc3e0c7ac939a0e))
+* **internal:** codegen related update ([11cb6bd](https://github.com/stainless-api/stainless-api-typescript/commit/11cb6bd7fa124295e059111bab3f8c31a821fc73))
+* **internal:** codegen related update ([8d5c4c8](https://github.com/stainless-api/stainless-api-typescript/commit/8d5c4c8a196d731f6794b4d94a0eb844adecd395))
+* **internal:** codegen related update ([31e06ee](https://github.com/stainless-api/stainless-api-typescript/commit/31e06eeef3fe4c186ce2f9b84ae125fff6a2d16a))
+* **internal:** codegen related update ([692e4f4](https://github.com/stainless-api/stainless-api-typescript/commit/692e4f42982d3eedb78719ea10a44474756f7d5e))
+* **internal:** codegen related update ([c9bda4f](https://github.com/stainless-api/stainless-api-typescript/commit/c9bda4fc8d89ea78eb94ef8f8a759aa8c4ea1988))
+* **internal:** codegen related update ([be77a0b](https://github.com/stainless-api/stainless-api-typescript/commit/be77a0b78be435dee9aa3093d0fef7b023fac3c4))
+* **internal:** codegen related update ([72f8a2a](https://github.com/stainless-api/stainless-api-typescript/commit/72f8a2ab5ea125c3731fe33c73b18b3875184c7f))
+* **internal:** codegen related update ([31e3903](https://github.com/stainless-api/stainless-api-typescript/commit/31e390345ee472e95a30bc6c95d261499419772c))
+* **internal:** codegen related update ([ac32221](https://github.com/stainless-api/stainless-api-typescript/commit/ac322213ce1d438055c5b15834cceb36634155ab))
+* **internal:** codegen related update ([d8d72b0](https://github.com/stainless-api/stainless-api-typescript/commit/d8d72b0c940d6f71d93a93e657226cc49ac7e65b))
+* **internal:** codegen related update ([8be59d8](https://github.com/stainless-api/stainless-api-typescript/commit/8be59d8d750c483fcf89e09f8c115ce55b3c7e04))
+* **internal:** codegen related update ([0f35c17](https://github.com/stainless-api/stainless-api-typescript/commit/0f35c1778e16bc0f8c6542624d6325f34305d758))
+* **internal:** codegen related update ([a4f392b](https://github.com/stainless-api/stainless-api-typescript/commit/a4f392b24af3b8edd027a2519cbc79ac362669b0))
+* **internal:** codegen related update ([4aab75e](https://github.com/stainless-api/stainless-api-typescript/commit/4aab75e95c6be99f8340a16d0e415615db4bded8))
+* **internal:** fix incremental formatting in some cases ([5906dba](https://github.com/stainless-api/stainless-api-typescript/commit/5906dba834a1abec5399fd3cd27459b213a5d301))
+* **internal:** grammar fix (it's -> its) ([26f73e0](https://github.com/stainless-api/stainless-api-typescript/commit/26f73e01ba9f1e7a827ea482adb6654b8c98714c))
+* **internal:** ignore .eslintcache ([c1fe619](https://github.com/stainless-api/stainless-api-typescript/commit/c1fe61994b503fbd898b01feda816845436045a6))
+* **internal:** remove .eslintcache ([80c9762](https://github.com/stainless-api/stainless-api-typescript/commit/80c9762d8834f3fd1ad9ec8a4f8639a6732c8c43))
+* **internal:** use npm pack for build uploads ([64381d5](https://github.com/stainless-api/stainless-api-typescript/commit/64381d5bda0c0469711d936b76bf728965b6c5de))
+* **jsdoc:** fix [@link](https://github.com/link) annotations to refer only to parts of the package‘s public interface ([d443db2](https://github.com/stainless-api/stainless-api-typescript/commit/d443db20c8a895993c651a0d8681f526f970e028))
+* mcp code tool explicit error message when missing a run function ([15e25b5](https://github.com/stainless-api/stainless-api-typescript/commit/15e25b504f097d09eadf6ba2a2587dbec407182a))
+* **mcp:** add friendlier MCP code tool errors on incorrect method invocations ([41d7085](https://github.com/stainless-api/stainless-api-typescript/commit/41d708546062afff0b5be01a91f3e4b7f148e589))
+* **mcp:** add line numbers to code tool errors ([f251424](https://github.com/stainless-api/stainless-api-typescript/commit/f2514246e9ed694632eb18b67ffe90730948353e))
+* **mcp:** allow pointing `docs_search` tool at other URLs ([b8df387](https://github.com/stainless-api/stainless-api-typescript/commit/b8df387d55a125f19cc419605b349c910c8373fe))
+* **mcp:** clarify http auth error ([ffad929](https://github.com/stainless-api/stainless-api-typescript/commit/ffad92904ee9cb02d76603d8719529f362f83228))
+* update docstrings ([c4f88d9](https://github.com/stainless-api/stainless-api-typescript/commit/c4f88d941696d5f25dd449c33ffe71a46f9a2b2a))
+* update lockfile ([3972fce](https://github.com/stainless-api/stainless-api-typescript/commit/3972fce8d4d77f2cc734c3bc6e8812d1941d41ce))
+* update mcp dockerfile ([d531f3f](https://github.com/stainless-api/stainless-api-typescript/commit/d531f3f03874c84bba354b3a1a2a210946b0658c))
+* use structured error when code execution tool errors ([4b5b5ea](https://github.com/stainless-api/stainless-api-typescript/commit/4b5b5ea49614cdaea1a65680c2235827f775490e))
+
+
+### Documentation
+
+* **mcp:** add a README button for one-click add to Cursor ([266a273](https://github.com/stainless-api/stainless-api-typescript/commit/266a2739341ece77d84c2ff128c9b2aa5d65add7))
+* **mcp:** add a README link to add server to VS Code or Claude Code ([25ed318](https://github.com/stainless-api/stainless-api-typescript/commit/25ed318337f817f1e12b4d8f6760ef76d74dcb4b))
+
 ## 0.1.0-alpha.16 (2025-09-26)
 
 Full Changelog: [v0.1.0-alpha.15...v0.1.0-alpha.16](https://github.com/stainless-api/stainless-api-typescript/compare/v0.1.0-alpha.15...v0.1.0-alpha.16)

api.md

@@ -95,3 +95,13 @@ Methods:
 
 - <code title="get /v0/orgs/{org}">client.orgs.<a href="./src/resources/orgs.ts">retrieve</a>(org) -> Org</code>
 - <code title="get /v0/orgs">client.orgs.<a href="./src/resources/orgs.ts">list</a>() -> OrgListResponse</code>
+
+# Spec
+
+Types:
+
+- <code><a href="./src/resources/spec.ts">SpecRetrieveDecoratedSpecResponse</a></code>
+
+Methods:
+
+- <code title="get /v0/spec/application/{clientId}/{projectName}">client.spec.<a href="./src/resources/spec.ts">retrieveDecoratedSpec</a>(projectName, { ...params }) -> unknown</code>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/sdk",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.17",
   "description": "The official TypeScript library for the Stainless API",
   "author": "Stainless <[email protected]>",
   "types": "dist/index.d.ts",

packages/mcp-server/Dockerfile

@@ -1,48 +1,81 @@
-# Build stage
-FROM node:20-alpine AS builder
+# Dockerfile for Stainless MCP Server
+    #
+    # This Dockerfile builds a Docker image for the MCP Server.
+    #
+    # To build the image locally:
+    #   docker build -f packages/mcp-server/Dockerfile -t stainlessapi/stainless-mcp:local .
+    #
+    # To run the image:
+    #   docker run -i stainlessapi/stainless-mcp:local [OPTIONS]
+    #
+    # Common options:
+    #   --tool=<name>              Include specific tools
+    #   --resource=<name>          Include tools for specific resources
+    #   --operation=read|write     Filter by operation type
+    #   --client=<type>            Set client compatibility (e.g., claude, cursor)
+    #   --transport=<type>         Set transport type (stdio or http)
+    #
+    # For a full list of options:
+    #   docker run -i stainlessapi/stainless-mcp:local --help
+    #
+    # Note: The MCP server uses stdio transport by default. Docker's -i flag
+    # enables interactive mode, allowing the container to communicate over stdin/stdout.
 
-# Install bash for build script
-RUN apk add --no-cache bash openssl
+    # Build stage
+    FROM node:20-alpine AS builder
 
-# Set working directory
-WORKDIR /build
+# Enable corepack to use pnpm
+RUN corepack enable && corepack prepare pnpm@latest --activate
 
-# Copy entire repository
-COPY . .
+    # Install bash for build script
+    RUN apk add --no-cache bash openssl
 
-# Install all dependencies and build everything
-RUN pnpm install --frozen-lockfile && \
-    pnpm build
+    # Set working directory
+    WORKDIR /build
 
-# Production stage
-FROM node:20-alpine
+    # Copy entire repository
+    COPY . .
 
-# Add non-root user
-RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
+    # Install all dependencies and build everything
+    RUN pnpm install --frozen-lockfile && \
+        pnpm build
 
-# Set working directory
-WORKDIR /app
+    # Production stage
 
-# Copy the built mcp-server dist directory
-COPY --from=builder /build/packages/mcp-server/dist ./
+            FROM denoland/deno:alpine
+            RUN apk add --no-cache npm
 
-# Copy node_modules from mcp-server (includes all production deps)
-COPY --from=builder /build/packages/mcp-server/node_modules ./node_modules
+    # Add non-root user
+    RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
 
-# Copy the built @stainless-api/sdk into node_modules
-COPY --from=builder /build/dist ./node_modules/@stainless-api/sdk
+    # Set working directory
+    WORKDIR /app
 
-# Change ownership to nodejs user
-RUN chown -R nodejs:nodejs /app
+# Copy the built mcp-server preserving directory structure
+COPY --from=builder /build/packages/mcp-server/dist ./packages/mcp-server/dist
+COPY --from=builder /build/packages/mcp-server/node_modules ./packages/mcp-server/node_modules
 
-# Switch to non-root user
-USER nodejs
+# Copy node_modules from root (pnpm hoists dependencies here)
+COPY --from=builder /build/node_modules ./node_modules
 
-# The MCP server uses stdio transport by default
-# No exposed ports needed for stdio communication
+    # Copy the built @stainless-api/sdk into node_modules
+    COPY --from=builder /build/dist ./node_modules/@stainless-api/sdk
 
-# Set the entrypoint to the MCP server
-ENTRYPOINT ["node", "index.js"]
+    # Change ownership to nodejs user
+    RUN chown -R nodejs:nodejs /app
 
-# Allow passing arguments to the MCP server
-CMD []
+    # Switch to non-root user
+    USER nodejs
+
+    # The MCP server uses stdio transport by default
+    # No exposed ports needed for stdio communication
+
+    # This is needed for node to run on the deno:alpine image.
+    # See <https://github.com/denoland/deno_docker/issues/373>.
+    ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib
+
+    # Set the entrypoint to the MCP server
+    ENTRYPOINT ["node", "packages/mcp-server/dist/index.js"]
+
+    # Allow passing arguments to the MCP server
+    CMD []

packages/mcp-server/README.md

@@ -49,12 +49,36 @@ For clients with a configuration JSON, it might look something like this:
 }
 ```
 
+### Cursor
+
+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.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=@stainless-api/sdk-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzdGFpbmxlc3MtYXBpL3Nkay1tY3AiXSwiZW52Ijp7IlNUQUlOTEVTU19BUElfS0VZIjoiU2V0IHlvdXIgU1RBSU5MRVNTX0FQSV9LRVkgaGVyZS4iLCJTVEFJTkxFU1NfUFJPSkVDVCI6IlNldCB5b3VyIFNUQUlOTEVTU19QUk9KRUNUIGhlcmUuIn19)
+
+### VS Code
+
+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.
+
+[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40stainless-api%2Fsdk-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40stainless-api%2Fsdk-mcp%22%5D%2C%22env%22%3A%7B%22STAINLESS_API_KEY%22%3A%22Set%20your%20STAINLESS_API_KEY%20here.%22%2C%22STAINLESS_PROJECT%22%3A%22Set%20your%20STAINLESS_PROJECT%20here.%22%7D%7D)
+
+### Claude Code
+
+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.
+
+```
+claude mcp add --transport stdio stainless_api_sdk_api --env STAINLESS_API_KEY="Your STAINLESS_API_KEY here." STAINLESS_PROJECT="Your STAINLESS_PROJECT here." -- npx -y @stainless-api/sdk-mcp
+```
+
 ## Exposing endpoints to your MCP Client
 
-There are two ways to expose endpoints as tools in the MCP server:
+There are three 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
+3. Exposing a docs search tool and a code execution tool, allowing the client to write code to be executed against the TypeScript client
 
 ### Filtering endpoints and tools
 
@@ -89,6 +113,18 @@ All of these command-line options can be repeated, combined together, and have c
 
 Use `--list` to see the list of available tools, or see below.
 
+### Code execution
+
+If you specify `--tools=code` to the MCP server, it will expose just two tools:
+
+- `search_docs` - Searches the API documentation and returns a list of markdown results
+- `execute` - Runs code against the TypeScript client
+
+This allows the LLM to implement more complex logic by chaining together many API calls without loading
+intermediary results into its context window.
+
+The code execution itself happens in a Deno sandbox that has network access only to the base URL for the API.
+
 ### Specifying the MCP Client
 
 Different clients have varying abilities to handle arbitrary tools and schemas.
@@ -285,3 +321,8 @@ The following tools are available in this MCP server.
 
 - `retrieve_orgs` (`read`): Retrieve an organization by name.
 - `list_orgs` (`read`): List organizations accessible to the current authentication method.
+
+### Resource `spec`:
+
+- `retrieve_decorated_spec_spec` (`read`):
+  Retrieve the decorated spec for a given application and project.

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/sdk-mcp",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.17",
   "description": "The official MCP Server for the Stainless API",
   "author": "Stainless <[email protected]>",
   "types": "dist/index.d.ts",
@@ -35,8 +35,10 @@
     "@valtown/deno-http-worker": "^0.0.21",
     "cors": "^2.8.5",
     "express": "^5.1.0",
+    "fuse.js": "^7.1.0",
     "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.6/jq-web.tar.gz",
     "qs": "^6.14.0",
+    "typescript": "5.8.3",
     "yargs": "^17.7.2",
     "zod": "^3.25.20",
     "zod-to-json-schema": "^3.24.5",
@@ -46,7 +48,7 @@
     "mcp-server": "dist/index.js"
   },
   "devDependencies": {
-    "@anthropic-ai/mcpb": "^1.1.0",
+    "@anthropic-ai/mcpb": "1.1.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^29.4.0",
@@ -63,8 +65,7 @@
     "ts-morph": "^19.0.0",
     "ts-node": "^10.5.0",
     "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"
+    "tsconfig-paths": "^4.0.0"
   },
   "imports": {
     "@stainless-api/sdk-mcp": ".",