writer · sarahcstringer · Dec 1, 2025 · Oct 3, 2025 · Oct 3, 2025 · Oct 6, 2025
diff --git a/.eslintcache b/.eslintcache
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "2.3.2"
+  ".": "2.3.3-rc.1"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 33
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-4ec783072dd7f57c6e021a746df7650fb8d7a164d8ec25c7d5cab06c33bc114f.yml
-openapi_spec_hash: ceab065d515f3681b0c33137da308968
-config_hash: 089fd5502b9cf91247887b19117f1ca2
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-ea6ec4b34f6b7fdecc564f59b2e31482eee05830bf8dc1f389461b158de1548e.yml
+openapi_spec_hash: ea89c1faed473908be2740efe6da255f
+config_hash: 886645f89dc98f04b8931eaf02854e5f
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,49 @@
 # Changelog
 
+## 2.3.3-rc.1 (2025-12-01)
+
+Full Changelog: [v2.3.2...v2.3.3-rc.1](https://github.com/writer/writer-node/compare/v2.3.2...v2.3.3-rc.1)
+
+### Features
+
+* **api:** Improve MCP tool descriptions ([95aa714](https://github.com/writer/writer-node/commit/95aa71460549717420896fd47fcebbd603739743))
+* **mcp:** add detail field to docs search tool ([0c975f7](https://github.com/writer/writer-node/commit/0c975f793c10f8f047c477ecde35f8e358b95e91))
+* **mcp:** enable optional code execution tool on http mcp servers ([cad37b7](https://github.com/writer/writer-node/commit/cad37b70c93d26bdafdfdf6047e9591a1b27376e))
+
+
+### Bug Fixes
+
+* **client:** incorrect offset pagination check ([b7847ab](https://github.com/writer/writer-node/commit/b7847abd4a65c07090855fd674c6bd4ff15b9760))
+* Fix linting errors. ([#238](https://github.com/writer/writer-node/issues/238)) ([12f49e6](https://github.com/writer/writer-node/commit/12f49e62a666d57a934537bf8f25cef1338b3e27))
+* **mcpb:** pin @anthropic-ai/mcpb version ([43acbce](https://github.com/writer/writer-node/commit/43acbcefa5cdbabe670ef4a5687ef871a3acf9f6))
+* **mcp:** return tool execution error on jq failure ([f833b8f](https://github.com/writer/writer-node/commit/f833b8ffb35c9921f66939cafab7ddc1a6948096))
+* **mcp:** use raw responses for binary content ([54da4f9](https://github.com/writer/writer-node/commit/54da4f964cae97a224763a29e851c4c63273953e))
+
+
+### Chores
+
+* **client:** fix logger property type ([20209b8](https://github.com/writer/writer-node/commit/20209b8c6037de89117b4f9b0e690721380e2dbc))
+* extract some types in mcp docs ([de1e150](https://github.com/writer/writer-node/commit/de1e15096bb097df00cdee211b752487d364d977))
+* **internal:** codegen related update ([35b1a8f](https://github.com/writer/writer-node/commit/35b1a8fd3128b36cb3a99025547b3484e57ae318))
+* **internal:** codegen related update ([5e30270](https://github.com/writer/writer-node/commit/5e3027034d15d23909742ac7a65d5e1db6709631))
+* **internal:** grammar fix (it's -&gt; its) ([7dfbe17](https://github.com/writer/writer-node/commit/7dfbe171aa29752dd3e42e15d045fde008d6e96c))
+* **internal:** remove .eslintcache ([f75e301](https://github.com/writer/writer-node/commit/f75e3010fb346dde47038f0e876549bc6eba301f))
+* **internal:** use npm pack for build uploads ([38c37a1](https://github.com/writer/writer-node/commit/38c37a1cfc2af919b9833344716ff5172a5076b3))
+* **jsdoc:** fix [@link](https://github.com/link) annotations to refer only to parts of the package‘s public interface ([d227de6](https://github.com/writer/writer-node/commit/d227de61034910da49481c6ff488436fcfed61fd))
+* mcp code tool explicit error message when missing a run function ([16c1a44](https://github.com/writer/writer-node/commit/16c1a446e5f1cf853582afe76bbc21739855ca70))
+* **mcp:** add friendlier MCP code tool errors on incorrect method invocations ([e6a4a0c](https://github.com/writer/writer-node/commit/e6a4a0c0936a215c9aed87365108b3bcf59303fd))
+* **mcp:** add line numbers to code tool errors ([00af445](https://github.com/writer/writer-node/commit/00af445b63b9a0db2fb59202f7ed3c4d34887990))
+* **mcp:** clarify http auth error ([bd123e0](https://github.com/writer/writer-node/commit/bd123e075e8bd0b179f95d8f8513a53414f86ac6))
+* **mcp:** upgrade jq-web ([9a0ac58](https://github.com/writer/writer-node/commit/9a0ac581162b2c59792d493e17cbe9d9cb0b5f60))
+* use structured error when code execution tool errors ([e140047](https://github.com/writer/writer-node/commit/e140047e470588b4c18bccbdb752078f198d8374))
+
+
+### Documentation
+
+* **api:** updates to API spec ([69b36c9](https://github.com/writer/writer-node/commit/69b36c97a708452f05522c9b81f0855fea0daadb))
+* **mcp:** add a README button for one-click add to Cursor ([062b7d7](https://github.com/writer/writer-node/commit/062b7d73c91530ea083872b67036a77265db9a8d))
+* **mcp:** add a README link to add server to VS Code or Claude Code ([bb1991a](https://github.com/writer/writer-node/commit/bb1991af52bb810f9b69ec7d9d761d8b79aa6b15))
+
 ## 2.3.2 (2025-10-03)
 
 Full Changelog: [v2.3.2-rc.2...v2.3.2](https://github.com/writer/writer-node/compare/v2.3.2-rc.2...v2.3.2)

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "writer-sdk",
-  "version": "2.3.2",
+  "version": "2.3.3-rc.1",
   "description": "The official TypeScript library for the Writer API",
   "author": "Writer <dev-feedback@writer.com>",
   "types": "dist/index.d.ts",

diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md
@@ -34,12 +34,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=writer-sdk-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIndyaXRlci1zZGstbWNwIl0sImVudiI6eyJXUklURVJfQVBJX0tFWSI6IlNldCB5b3VyIFdSSVRFUl9BUElfS0VZIGhlcmUuIn19)
+
+### 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%22writer-sdk-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22writer-sdk-mcp%22%5D%2C%22env%22%3A%7B%22WRITER_API_KEY%22%3A%22Set%20your%20WRITER_API_KEY%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 writer_sdk_api --env WRITER_API_KEY="Your WRITER_API_KEY here." -- npx -y writer-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
 
@@ -74,6 +98,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.
@@ -207,8 +243,8 @@ The following tools are available in this MCP server.
 ### Resource `applications`:
 
 - `retrieve_applications` (`read`): Retrieves detailed information for a specific no-code agent (formerly called no-code applications), including its configuration and current status.
-- `list_applications` (`read`): Retrieves a paginated list of no-code agents (formerly called no-code applications) with optional filtering and sorting capabilities.
-- `generate_content_applications` (`write`): Generate content from an existing no-code agent (formerly called no-code applications) with inputs.
+- `list_applications` (`read`): Get all available no-code agents (applications) in your account. No-code agents are pre-configured AI workflows built in Writer's AI Studio. Use this to discover which agents are available before generating content from them.
+- `generate_content_applications` (`write`): Generate content using a pre-configured no-code agent. No-code agents are custom AI workflows you've built in AI Studio with specific prompts, models, and settings. Provide the application ID and required inputs to get tailored content. Useful for consistent, repeatable AI tasks like content generation, data extraction, or custom workflows.
 
 ### Resource `applications.jobs`:
 
@@ -224,35 +260,35 @@ The following tools are available in this MCP server.
 
 ### Resource `chat`:
 
-- `chat_chat` (`write`): Generate a chat completion based on the provided messages. The response shown below is for non-streaming. To learn about streaming responses, see the [chat completion guide](https://dev.writer.com/home/chat-completion).
+- `chat_chat` (`write`): Generate AI responses for conversational interactions. Use this for chat-based tasks, Q&A, content generation, and any natural language processing. Supports tools like Knowledge Graphs, web search, translation, and vision. Choose from models like palmyra-x5, palmyra-x4, palmyra-creative, palmyra-med, or palmyra-fin depending on the task.
 
 ### Resource `completions`:
 
-- `create_completions` (`write`): Generate text completions using the specified model and prompt. This endpoint is useful for text generation tasks that don't require conversational context.
+- `create_completions` (`write`): Generate text completions from a single prompt without conversational context. Best for straightforward text generation tasks like article writing, summaries, or creative content. For interactive conversations or multi-turn dialogues, use generate-chat-completion instead.
 
 ### Resource `models`:
 
 - `list_models` (`read`): Retrieve a list of available models that can be used for text generation, chat completions, and other AI tasks.
 
 ### Resource `graphs`:
 
-- `create_graphs` (`write`): Create a new Knowledge Graph.
-- `retrieve_graphs` (`read`): Retrieve a Knowledge Graph.
+- `create_graphs` (`write`): Create a new Knowledge Graph to organize and query documents. Knowledge Graphs are containers for files that enable AI-powered search and question answering. After creation, add files to the graph using add-file-to-graph, then query it using query-knowledge-graph.
+- `retrieve_graphs` (`read`): Get detailed information about a specific Knowledge Graph by its ID. Returns the graph name, description, creation date, file processing status, and associated URLs (for web-based graphs). Use this to check processing status or get graph metadata.
 - `update_graphs` (`write`): Update the name and description of a Knowledge Graph.
-- `list_graphs` (`read`): Retrieve a list of Knowledge Graphs.
+- `list_graphs` (`read`): Get all available Knowledge Graphs in your account. Knowledge Graphs are collections of documents and files that can be queried using AI. Use this to discover which knowledge bases are available before querying them.
 - `delete_graphs` (`write`): Delete a Knowledge Graph.
-- `add_file_to_graph_graphs` (`write`): Add a file to a Knowledge Graph.
-- `question_graphs` (`write`): Ask a question to specified Knowledge Graphs.
+- `add_file_to_graph_graphs` (`write`): Add an uploaded file to a Knowledge Graph to make it queryable. The file must already be uploaded using upload-file. Once added, the file's content becomes searchable when querying the Knowledge Graph. Files are processed asynchronously - check status using get-file-info.
+- `question_graphs` (`write`): Ask questions and get AI-generated answers based on your Knowledge Graph content. Queries your uploaded documents, PDFs, and files to retrieve accurate, source-cited information. Returns answers with supporting snippets and file references. Ideal for RAG (Retrieval-Augmented Generation) applications and knowledge base queries.
 - `remove_file_from_graph_graphs` (`write`): Remove a file from a Knowledge Graph.
 
 ### Resource `files`:
 
-- `retrieve_files` (`read`): Retrieve detailed information about a specific file, including its metadata, status, and associated graphs.
-- `list_files` (`read`): Retrieve a paginated list of files with optional filtering by status, graph association, and file type.
+- `retrieve_files` (`read`): Get metadata and status information for a specific file by its ID. Returns file name, creation date, processing status, and associated Knowledge Graph IDs. Use this to check if a file has finished processing or to find which Knowledge Graphs contain a specific file.
+- `list_files` (`read`): Get a paginated list of all uploaded files. Filter by processing status (in_progress, completed, failed), Knowledge Graph association, or file type. Use this to discover available files, monitor processing status, or find files to add to Knowledge Graphs.
 - `delete_files` (`write`): Permanently delete a file from the system. This action cannot be undone.
 - `download_files` (`read`): Download the binary content of a file. The response will contain the file data in the appropriate MIME type.
 - `retry_files` (`write`): Retry processing of files that previously failed to process. This will re-attempt the processing of the specified files.
-- `upload_files` (`write`): Upload a new file to the system. Supports various file formats including PDF, DOC, DOCX, PPT, PPTX, JPG, PNG, EML, HTML, SRT, CSV, XLS, and XLSX.
+- `upload_files` (`write`): Upload documents and files to Writer. Supports PDF, DOC, DOCX, PPT, PPTX, JPG, PNG, EML, HTML, SRT, CSV, XLS, XLSX, MP3, and MP4 formats. Once uploaded, files can be added to Knowledge Graphs for querying or used with Vision API for image analysis. Returns a file ID for subsequent operations.
 
 ### Resource `tools`:
 
@@ -271,4 +307,4 @@ The following tools are available in this MCP server.
 
 ### Resource `vision`:
 
-- `analyze_vision` (`write`): Submit images and a prompt to generate an analysis of the images.
+- `analyze_vision` (`write`): Submit images and documents with a prompt to generate an analysis. Supports JPG, PNG, PDF, and TXT files up to 7MB each.
diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "writer-sdk-mcp",
-  "version": "2.3.2",
+  "version": "2.3.3-rc.1",
   "description": "The official MCP Server for the Writer API",
   "author": "Writer <dev-feedback@writer.com>",
   "types": "dist/index.d.ts",
@@ -36,8 +36,10 @@
     "@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",
+    "fuse.js": "^7.1.0",
+    "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/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",
@@ -47,7 +49,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",
@@ -64,8 +66,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": {
     "writer-sdk-mcp": ".",