tmcp 1.20.0 → 1.20.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "tmcp",
-  "version": "1.20.0",
+  "version": "1.20.1",
   "description": "The main tmcp library",
   "main": "src/index.js",
   "type": "module",
-  "types": "src/types/index.d.ts",
+  "types": "./types/index.d.ts",
   "keywords": [],
   "repository": {
     "type": "git",
@@ -14,61 +14,88 @@
   "author": "Paolo Ricciuti",
   "license": "MIT",
   "files": [
-    "src/"
+    "src/",
+    "types/",
+    "!src/**/*.d.ts"
   ],
   "exports": {
     ".": {
-      "types": "./src/types/index.d.ts",
+      "types": "./types/index.d.ts",
       "default": "./src/index.js"
     },
     "./tool": {
-      "types": "./src/types/index.d.ts",
+      "types": "./types/tool.d.ts",
       "default": "./src/tool.js"
     },
     "./prompt": {
-      "types": "./src/types/index.d.ts",
+      "types": "./types/prompt.d.ts",
       "default": "./src/prompt.js"
     },
     "./resource": {
-      "types": "./src/types/index.d.ts",
+      "types": "./types/resource.d.ts",
       "default": "./src/resource.js"
     },
     "./template": {
-      "types": "./src/types/index.d.ts",
+      "types": "./types/template.d.ts",
       "default": "./src/template.js"
     },
     "./adapter": {
-      "types": "./src/types/index.d.ts",
+      "types": "./types/adapter.d.ts",
       "default": "./src/adapter.js"
     },
     "./method-policy": {
-      "types": "./src/types/index.d.ts",
+      "types": "./types/method-policy.d.ts",
       "default": "./src/method-policy.js"
     },
     "./utils": {
-      "types": "./src/types/index.d.ts",
+      "types": "./types/utils/index.d.ts",
       "default": "./src/utils/index.js"
     },
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "tool": [
+        "./types/tool.d.ts"
+      ],
+      "prompt": [
+        "./types/prompt.d.ts"
+      ],
+      "resource": [
+        "./types/resource.d.ts"
+      ],
+      "template": [
+        "./types/template.d.ts"
+      ],
+      "adapter": [
+        "./types/adapter.d.ts"
+      ],
+      "method-policy": [
+        "./types/method-policy.d.ts"
+      ],
+      "utils": [
+        "./types/utils/index.d.ts"
+      ]
+    }
+  },
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
+    "@types/json-schema": "^7.0.15",
     "json-rpc-2.0": "^1.7.1",
     "sqids": "^0.3.0",
     "uri-template-matcher": "^1.1.1",
     "valibot": "^1.1.0"
   },
   "devDependencies": {
-    "@types/json-schema": "^7.0.15",
     "@types/node": "^24.0.13",
-    "dts-buddy": "^0.6.2",
     "publint": "^0.3.12",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@tmcp/internal-ts-helpers": "^1.0.0"
   },
   "scripts": {
     "test": "vitest",
     "typecheck": "tsc --noEmit",
-    "generate:types": "dts-buddy && node ./scripts/fix-unique-symbol.ts && publint",
+    "generate:types": "generate-types && publint",
     "prepublish": "pnpm generate:types"
   }
 }

package/src/index.js

@@ -2,11 +2,15 @@
 /**
  * @import { StandardSchemaV1 } from "@standard-schema/spec";
  * @import SqidsType from "sqids";
- * @import { JSONRPCRequest, JSONRPCParams } from "json-rpc-2.0";
+ * @import { JSONRPCRequest, JSONRPCParams, JSONRPCErrorResponse } from "json-rpc-2.0";
  * @import { ExtractURITemplateVariables } from "./internal/uri-template.js";
  * @import { CallToolResult as CallToolResultType, ReadResourceResult as ReadResourceResultType, GetPromptResult as GetPromptResultType, ServerInfo as ServerInfoType, ClientCapabilities as ClientCapabilitiesType, JSONRPCRequest as JSONRPCRequestType, JSONRPCResponse, CreateMessageRequestParams as CreateMessageRequestParamsType, CreateMessageResult as CreateMessageResultType, Resource as ResourceType, LoggingLevel as LoggingLevelType, ToolAnnotations, ClientInfo as ClientInfoType, ElicitResult as ElicitResultType, Icons as IconsType, JSONRPCMessage, InitializeResult as InitializeResultType, ListToolsResult as ListToolsResultType, ListPromptsResult as ListPromptsResultType, ListResourceTemplatesResult as ListResourceTemplatesResultType, ListResourcesResult as ListResourcesResultType, CompleteResult as CompleteResultType, SubscriptionFilter as SubscriptionFilterType, SubscriptionsListenRequest as SubscriptionsListenRequestType, SubscriptionsListenResult as SubscriptionsListenResultType, SubscriptionsAcknowledgedNotification as SubscriptionsAcknowledgedNotificationType, DiscoverRequestParams } from "./validation/index.js";
- * @import { Tool, Completion, Prompt, StoredResource, ServerOptions, SubscriptionsKeys, ChangedArgs, McpEvents, AllSame, TemplateOptions, MrtrState, Subscription as SubscriptionType, SubscriptionCallbacks as SubscriptionCallbacksType, SubscriptionManager as SubscriptionManagerType, SubscriptionOrigin as SubscriptionOriginType } from "./internal/internal.js";
- * @import { CreatedTool, ToolOptions, CreatedPrompt, PromptOptions, CreatedResource, CreatedTemplate, ResourceOptions } from "./internal/internal.js";
+ * @import { Tool, Completion, Prompt, StoredResource, ServerOptions, SubscriptionsKeys, McpEvents as McpEventsType, AllSame, TemplateOptions, MrtrState, Subscription as SubscriptionType, SubscriptionCallbacks as SubscriptionCallbacksType, SubscriptionManager as SubscriptionManagerType, SubscriptionOrigin as SubscriptionOriginType } from "./internal/internal.js";
+ * @import { ToolOptions, PromptOptions, ResourceOptions } from "./internal/internal.js";
+ * @import { CreatedTool } from "./tool.js";
+ * @import { CreatedPrompt } from "./prompt.js";
+ * @import { CreatedResource } from "./resource.js";
+ * @import { CreatedTemplate } from "./template.js";
  */
 import {
 	createJSONRPCErrorResponse,
@@ -153,6 +157,11 @@ export function getPerRequestProtocolVersions() {
  * @typedef {Context<TCustom> & { subscriptionOrigin?: SubscriptionOriginType, subscriptionManager?: SubscriptionManagerType }} ReceiveContext
  */
 
+/** @typedef {McpEventsType} McpEvents */
+/**
+ * The arguments of `McpServer.changed` for each kind of change.
+ * @typedef {{ resource: [id: string], tools: [], prompts: [], resources: [] }} ChangedArgs
+ */
 /** @typedef {SubscriptionFilterType} SubscriptionFilter */
 /** @typedef {SubscriptionOriginType} SubscriptionOrigin */
 /** @typedef {SubscriptionType} Subscription */
@@ -399,13 +408,14 @@ export class McpServer {
 					event('initialize', validated_initialize),
 				);
 
-				// Return server response with negotiated version and capabilities
-				// (per-request protocol options are not part of the legacy initialize result)
-				// eslint-disable-next-line no-unused-vars
-				const { cache, ...legacy_options } = options;
+				// Return server response with negotiated version and capabilities;
+				// the rest of the options (adapter, pagination, cache...) is server-side only
 				return {
 					protocolVersion: negotiated_version,
-					...legacy_options,
+					capabilities: options.capabilities,
+					...(options.instructions != null
+						? { instructions: options.instructions }
+						: {}),
 					serverInfo: server_info,
 				};
 			} catch (error) {
@@ -1620,6 +1630,7 @@ export class McpServer {
 	 * notification (which cannot receive a response).
 	 * @param {string | number | undefined} id
 	 * @param {McpError} error
+	 * @returns {Promise<JSONRPCErrorResponse | null>}
 	 */
 	#error_response(id, error) {
 		if (id === undefined) return Promise.resolve(null);
@@ -1634,12 +1645,16 @@ export class McpServer {
 		});
 	}
 
+	// TODO: on the next major remove `@returns {any}` so the real return type is
+	// inferred. Since 1.5.0 a misplaced `| undefined` in the annotation
+	// (`ReturnType<JSONRPCClient['receive'] | undefined>`) made it `any`, and
+	// changing it now would break users that rely on it.
 	/**
 	 * The main function that receive a JSONRpc message and either dispatch a `send` event or process the request.
 	 *
 	 * @param {JSONRPCMessage} message
 	 * @param {ReceiveContext<CustomContext>} [ctx]
-	 * @returns {ReturnType<JSONRPCServer['receive']> | ReturnType<JSONRPCClient['receive'] | undefined>}
+	 * @returns {any}
 	 */
 	receive(message, ctx) {
 		// Validate the message first

package/src/prompt.js

@@ -1,9 +1,15 @@
 /**
  * @import { StandardSchemaV1 } from "@standard-schema/spec";
- * @import { PromptOptions, CreatedPrompt } from "./internal/internal.js";
+ * @import { PromptOptions } from "./internal/internal.js";
  * @import { GetPromptResult } from "./validation/index.js"
  */
 
+/**
+ * A prompt created with `definePrompt`.
+ * @template {StandardSchemaV1 | undefined} [TSchema=undefined]
+ * @typedef {PromptOptions<TSchema> & { [created_prompt]: typeof created_prompt }} CreatedPrompt
+ */
+
 /**
  * Add a tool to the server. If you want to receive any input you need to provide a schema. The schema needs to be a valid Standard Schema V1 schema and needs to be an Object with the properties you need,
  * Use the description and title to help the LLM to understand what the tool does and when to use it. If you provide an outputSchema, you need to return a structuredContent that matches the schema.

package/src/resource.js

@@ -1,8 +1,13 @@
 /**
- * @import { ResourceOptions, CreatedResource } from "./internal/internal.js";
+ * @import { ResourceOptions } from "./internal/internal.js";
  * @import { ReadResourceResult } from "./validation/index.js";
  */
 
+/**
+ * A resource created with `defineResource`.
+ * @typedef {ResourceOptions & { [created_resource]: typeof created_resource }} CreatedResource
+ */
+
 /**
  * Add a resource to the server. Resources are added manually to the context by the user to provide the LLM with additional context.
  * Use the description and title to help the user to understand what the resource is. The mimeType can be used to indicate the type of content.

package/src/template.js

@@ -1,10 +1,16 @@
 /* eslint-disable jsdoc/no-undefined-types */
 /**
  * @import { ExtractURITemplateVariables } from "./internal/uri-template.js";
- * @import { TemplateOptions, CreatedTemplate } from "./internal/internal.js";
+ * @import { TemplateOptions } from "./internal/internal.js";
  * @import { ReadResourceResult } from "./validation/index.js";
  */
 
+/**
+ * A resource template created with `defineTemplate`.
+ * @template {string} [TUri=string]
+ * @typedef {TemplateOptions<TUri> & { [created_template]: typeof created_template }} CreatedTemplate
+ */
+
 /**
  * Add a resource template to the server. Resources are added manually to the context by the user to provide the LLM with additional context.
  * Resource templates are used to create resources dynamically based on a URI template. The URI template should be a valid URI template as defined in RFC 6570.

package/src/tool.js

@@ -1,6 +1,13 @@
 /**
  * @import { StandardSchemaV1 } from "@standard-schema/spec";
- * @import { ToolOptions, CreatedTool } from "./internal/internal.js";
+ * @import { ToolOptions } from "./internal/internal.js";
+ */
+
+/**
+ * A tool created with `defineTool`.
+ * @template {StandardSchemaV1 | undefined} [TSchema=undefined]
+ * @template {StandardSchemaV1 | undefined} [TOutputSchema=undefined]
+ * @typedef {ToolOptions<TSchema, TOutputSchema> & { [created_tool]: typeof created_tool }} CreatedTool
  */
 
 /**

package/src/utils/index.js

@@ -1,5 +1,6 @@
 /**
- * @import { EmbeddedResource, ResourceLink, CallToolResult, ReadResourceResult, GetPromptResult,  CompleteResult } from "../validation/index.js";
+ * @import { EmbeddedResource, ResourceLink, ReadResourceResult, GetPromptResult,  CompleteResult } from "../validation/index.js";
+ * @import { CallToolResult } from "../index.js";
  */
 
 /**