Release

.github/workflows/release.yml

@@ -0,0 +1,100 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+      - "v*.*.*-alpha.*"
+      - "v*.*.*-beta.*"
+
+permissions:
+  contents: read
+  id-token: write # Required for npm provenance
+
+env:
+  NODE_VERSION: "22.x"
+
+jobs:
+  verify-version:
+    name: Verify version
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: tag
+        run: |
+          TAG=${GITHUB_REF#refs/tags/v}
+          echo "version=$TAG" >> $GITHUB_OUTPUT
+          echo "Tagged version: $TAG"
+
+      - name: Read package.json version
+        id: package
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Package version: $VERSION"
+
+      - name: Compare versions
+        run: |
+          if [ "${{ steps.tag.outputs.version }}" != "${{ steps.package.outputs.version }}" ]; then
+            echo "ERROR: Tag version (${{ steps.tag.outputs.version }}) does not match package.json version (${{ steps.package.outputs.version }})"
+            exit 1
+          fi
+          echo "Versions match: ${{ steps.tag.outputs.version }}"
+
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: verify-version
+    environment:
+      name: npm
+      url: https://www.npmjs.com/package/@ampersend_ai/fastmcp
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          package_json_file: package.json
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: "https://registry.npmjs.org"
+          cache: "pnpm"
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build package
+        run: pnpm build
+
+      - name: Determine publish tag
+        id: publish-tag
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          if [[ "$VERSION" == *"-alpha."* ]]; then
+            echo "tag=alpha" >> $GITHUB_OUTPUT
+            echo "Publishing with tag: alpha"
+          elif [[ "$VERSION" == *"-beta."* ]]; then
+            echo "tag=beta" >> $GITHUB_OUTPUT
+            echo "Publishing with tag: beta"
+          else
+            echo "tag=latest" >> $GITHUB_OUTPUT
+            echo "Publishing with tag: latest"
+          fi
+
+      - name: Publish to npm
+        run: npm publish --access public --tag ${{ steps.publish-tag.outputs.tag }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -771,7 +771,53 @@ The `log` object has the following methods:
 
 #### Errors
 
-The errors that are meant to be shown to the user should be thrown as `UserError` instances:
+FastMCP supports two ways to handle errors in tool execution:
+
+##### MCP Errors (Recommended)
+
+For standards-compliant error handling, throw `McpError` with appropriate error codes:
+
+```js
+import { ErrorCode, McpError } from "fastmcp";
+
+server.addTool({
+  name: "download",
+  description: "Download a file",
+  parameters: z.object({
+    url: z.string(),
+  }),
+  execute: async (args) => {
+    if (args.url.startsWith("https://example.com")) {
+      // Throw MCP error with InvalidParams code
+      throw new McpError(ErrorCode.InvalidParams, "This URL is not allowed");
+    }
+
+    // Throw MCP error with custom data
+    if (!urlExists(args.url)) {
+      throw new McpError(ErrorCode.InvalidRequest, "Resource not found", {
+        url: args.url,
+        statusCode: 404,
+      });
+    }
+
+    return "done";
+  },
+});
+```
+
+**Available Error Codes:**
+
+- `ErrorCode.InvalidParams` - Invalid parameters provided
+- `ErrorCode.InvalidRequest` - Invalid request
+- `ErrorCode.InternalError` - Internal server error
+- `ErrorCode.MethodNotFound` - Method/resource not found
+- And other standard JSON-RPC error codes
+
+When a tool throws `McpError`, it's propagated through the MCP protocol as a proper JSON-RPC error, allowing clients to handle different error types appropriately.
+
+##### User Errors (Legacy)
+
+For backward compatibility, you can still use `UserError` for simple error messages:
 
 ```js
 import { UserError } from "fastmcp";
@@ -792,6 +838,8 @@ server.addTool({
 });
 ```
 
+`UserError` errors are converted to tool responses with `isError: true` and are displayed to the user as text content.
+
 #### Progress
 
 Tools can report progress by calling `reportProgress` in the context object:
@@ -1316,9 +1364,9 @@ In this example, only clients authenticating with the `admin` role will be able
 FastMCP includes built-in support for OAuth discovery endpoints, supporting both **MCP Specification 2025-03-26** and **MCP Specification 2025-06-18** for OAuth integration. This makes it easy to integrate with OAuth authorization flows by providing standard discovery endpoints that comply with RFC 8414 (OAuth 2.0 Authorization Server Metadata) and RFC 9470 (OAuth 2.0 Protected Resource Metadata):
 
 ```ts
+import fastJwt from "fast-jwt";
 import { FastMCP } from "fastmcp";
 import { buildGetJwks } from "get-jwks";
-import fastJwt from "fast-jwt";
 
 const server = new FastMCP({
   name: "My Server",
@@ -1420,9 +1468,10 @@ For JWT token validation, you can use libraries like [`get-jwks`](https://github
 If you are exposing your MCP server via HTTP, you may wish to allow clients to supply sensitive keys via headers, which can then be passed along to APIs that your tools interact with, allowing each client to supply their own API keys. This can be done by capturing the HTTP headers in the `authenticate` section and storing them in the session to be referenced by the tools later.
 
 ```ts
-import { FastMCP } from "fastmcp";
 import { IncomingHttpHeaders } from "http";
 
+import { FastMCP } from "fastmcp";
+
 // Define the session data type
 interface SessionData {
   headers: IncomingHttpHeaders;
@@ -1470,8 +1519,8 @@ server.start({
 A client that would connect to this may look something like this:
 
 ```ts
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
 const transport = new StreamableHTTPClientTransport(
   new URL(`http://localhost:8080/mcp`),

jsr.json

@@ -2,6 +2,6 @@
   "exports": "./src/FastMCP.ts",
   "include": ["src/FastMCP.ts", "src/bin/fastmcp.ts"],
   "license": "MIT",
-  "name": "@punkpeye/fastmcp",
+  "name": "@ampersend_ai/fastmcp",
   "version": "1.0.0"
 }

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "fastmcp",
+  "name": "@ampersend_ai/fastmcp",
   "version": "1.0.0",
   "main": "dist/FastMCP.js",
   "scripts": {
@@ -22,7 +22,7 @@
   "module": "dist/FastMCP.js",
   "types": "dist/FastMCP.d.ts",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.17.2",
+    "@modelcontextprotocol/sdk": "npm:@ampersend_ai/modelcontextprotocol-sdk@^1.20.1",
     "@standard-schema/spec": "^1.0.0",
     "execa": "^9.6.0",
     "file-type": "^21.0.0",
@@ -37,7 +37,7 @@
     "zod-to-json-schema": "^3.24.6"
   },
   "repository": {
-    "url": "https://github.com/punkpeye/fastmcp"
+    "url": "https://github.com/edgeandnode/fastmcp"
   },
   "homepage": "https://glama.ai/mcp",
   "release": {