tmcp 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "The main tmcp library",
   "main": "src/index.js",
   "type": "module",
@@ -34,6 +34,7 @@
   "devDependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@types/json-schema": "^7.0.15",
+    "@types/node": "^24.0.13",
     "publint": "^0.3.12"
   },
   "scripts": {

package/src/index.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {ClientCapabilitiesType} ClientCapabilities
+ */
 /**
  * @template {StandardSchemaV1} StandardSchema
  */
@@ -7,6 +10,21 @@ export class McpServer<StandardSchema extends StandardSchemaV1> {
      * @param {ServerOptions<StandardSchema>} options
      */
     constructor(server_info: ServerInfo, options: ServerOptions<StandardSchema>);
+    currentClientCapabilities(): {
+        roots?: {
+            listChanged?: boolean;
+        } & {
+            [key: string]: unknown;
+        };
+        sampling?: {} & {
+            [key: string]: unknown;
+        };
+        elicitation?: {} & {
+            [key: string]: unknown;
+        };
+    } & {
+        [key: string]: unknown;
+    };
     /**
      * @template {keyof McpEvents} TEvent
      * @param {TEvent} event
@@ -58,17 +76,25 @@ export class McpServer<StandardSchema extends StandardSchemaV1> {
     }, execute: (uri: string, params: Record<TVariables, string | string[]>) => Promise<ReadResourceResult> | ReadResourceResult): void;
     /**
      * @param {JSONRPCRequest} request
+     * @param {string} [session_id]
      * @returns {ReturnType<JSONRPCServer['receive']>}
      */
-    receive(request: JSONRPCRequest): ReturnType<JSONRPCServer["receive"]>;
+    receive(request: JSONRPCRequest, session_id?: string): ReturnType<JSONRPCServer["receive"]>;
     /**
      * Send a notification for subscriptions
      * @param {SubscriptionsKeys} what
      * @param {string} id
      */
     changed(what: SubscriptionsKeys, id: string): void;
+    /**
+     * @template {StandardSchema} TSchema
+     * @param {TSchema} schema
+     * @returns {Promise<StandardSchemaV1.InferOutput<TSchema>>}
+     */
+    elicitation<TSchema extends StandardSchema>(schema: TSchema): Promise<StandardSchemaV1.InferOutput<TSchema>>;
     #private;
 }
+export type ClientCapabilities = ClientCapabilitiesType;
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { McpEvents } from "./internal/internal.js";
 import type { CallToolResult } from "./validation/index.js";
@@ -81,3 +107,4 @@ import { JSONRPCServer } from 'json-rpc-2.0';
 import type { SubscriptionsKeys } from "./internal/internal.js";
 import type { ServerInfo } from "./internal/internal.js";
 import type { ServerOptions } from "./internal/internal.js";
+import type { ClientCapabilities as ClientCapabilitiesType } from "./validation/index.js";

package/src/index.js

@@ -2,7 +2,7 @@
  * @import { StandardSchemaV1 } from "@standard-schema/spec";
  * @import { JSONRPCRequest, JSONRPCParams } from "json-rpc-2.0";
  * @import { ExtractURITemplateVariables } from "./internal/uri-template.js";
- * @import { CallToolResult, ReadResourceResult, GetPromptResult, CompleteResult } from "./validation/index.js";
+ * @import { CallToolResult, ReadResourceResult, GetPromptResult, ClientCapabilities as ClientCapabilitiesType } from "./validation/index.js";
  * @import { Tool, Completion, Prompt, Resource, ServerOptions, ServerInfo, SubscriptionsKeys, McpEvents } from "./internal/internal.js";
  */
 import { JSONRPCServer, JSONRPCClient } from 'json-rpc-2.0';
@@ -12,16 +12,22 @@ import {
 	ReadResourceResultSchema,
 	GetPromptResultSchema,
 	CompleteResultSchema,
+	InitializeRequestSchema,
 } from './validation/index.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import * as v from 'valibot';
 
+/**
+ * @typedef {ClientCapabilitiesType} ClientCapabilities
+ */
+
 /**
  * @template {StandardSchemaV1} StandardSchema
  */
 export class McpServer {
 	#server = new JSONRPCServer();
 	/**
-	 * @type {JSONRPCClient | undefined}
+	 * @type {JSONRPCClient<Record<string, any> | undefined> | undefined}
 	 */
 	#client;
 	#options;
@@ -49,24 +55,47 @@ export class McpServer {
 	#event_target = new EventTarget();
 
 	/**
-	 * @type {Record<SubscriptionsKeys, Set<string>>}
+	 * @type {Record<SubscriptionsKeys, Map<string, Set<string | undefined>>>}
 	 */
 	#subscriptions = {
 		/**
-		 * @type {Set<string>}
+		 * @type {Map<string, Set<string>>}
 		 */
-		resource: new Set(),
+		resource: new Map(),
 	};
 
+	/**
+	 * @type {AsyncLocalStorage<string | undefined>}
+	 */
+	#session_storage = new AsyncLocalStorage();
+
+	/**
+	 * @type {Map<string|undefined, ClientCapabilities>}
+	 */
+	#client_capabilities_map = new Map();
+
 	/**
 	 * @param {ServerInfo} server_info
 	 * @param {ServerOptions<StandardSchema>} options
 	 */
 	constructor(server_info, options) {
 		this.#options = options;
-		this.#server.addMethod('initialize', ({ protocolVersion }) => {
+		this.#server.addMethod('initialize', (initialize_request) => {
+			const validated_initialize = v.parse(
+				InitializeRequestSchema,
+				initialize_request,
+			);
+			this.#client_capabilities_map.set(
+				this.#session_id,
+				validated_initialize.capabilities,
+			);
+			this.#event_target.dispatchEvent(
+				new CustomEvent('initialize', {
+					detail: validated_initialize,
+				}),
+			);
 			return {
-				protocolVersion,
+				protocolVersion: validated_initialize.protocolVersion,
 				...options,
 				serverInfo: server_info,
 			};
@@ -83,6 +112,30 @@ export class McpServer {
 		this.#init_completion();
 	}
 
+	get #session_id() {
+		return this.#session_storage.getStore();
+	}
+
+	get #client_capabilities() {
+		return this.#client_capabilities_map.get(this.#session_id);
+	}
+
+	currentClientCapabilities() {
+		return this.#client_capabilities;
+	}
+
+	#lazyily_create_client() {
+		if (!this.#client) {
+			this.#client = new JSONRPCClient((payload, context = {}) => {
+				this.#event_target.dispatchEvent(
+					new CustomEvent('send', {
+						detail: { request: payload, context },
+					}),
+				);
+			});
+		}
+	}
+
 	/**
 	 * @template {keyof McpEvents} TEvent
 	 * @param {TEvent} event
@@ -90,12 +143,8 @@ export class McpServer {
 	 * @param {AddEventListenerOptions} [options]
 	 */
 	on(event, callback, options) {
-		if (event === 'send' && !this.#client) {
-			this.#client = new JSONRPCClient((payload) => {
-				this.#event_target.dispatchEvent(
-					new CustomEvent('send', { detail: payload }),
-				);
-			});
+		if (event === 'send') {
+			this.#lazyily_create_client();
 		}
 
 		this.#event_target.addEventListener(
@@ -110,9 +159,10 @@ export class McpServer {
 	/**
 	 * @param {string} method
 	 * @param {JSONRPCParams} [params]
+	 * @param {Record<string, any>} [extra]
 	 */
-	#notify(method, params) {
-		this.#client?.notify(method, params);
+	#notify(method, params, extra) {
+		this.#client?.notify(method, params, extra);
 	}
 
 	/**
@@ -243,7 +293,12 @@ export class McpServer {
 
 		if (this.#options.capabilities?.resources?.subscribe) {
 			this.#server.addMethod('resources/subscribe', async ({ uri }) => {
-				this.#subscriptions.resource.add(uri);
+				let subscriptions = this.#subscriptions.resource.get(uri);
+				if (!subscriptions) {
+					subscriptions = new Set();
+					this.#subscriptions.resource.set(uri, subscriptions);
+				}
+				subscriptions.add(this.#session_id);
 				return {};
 			});
 		}
@@ -408,10 +463,14 @@ export class McpServer {
 	}
 	/**
 	 * @param {JSONRPCRequest} request
+	 * @param {string} [session_id]
 	 * @returns {ReturnType<JSONRPCServer['receive']>}
 	 */
-	receive(request) {
-		return this.#server.receive(request);
+	receive(request, session_id) {
+		return this.#session_storage.run(
+			session_id,
+			async () => await this.#server.receive(request),
+		);
 	}
 
 	/**
@@ -423,10 +482,48 @@ export class McpServer {
 		if (this.#subscriptions[what].has(id)) {
 			const resource = this.#resources.get(id);
 			if (!resource) return;
-			this.#notify(`notifications/resources/updated`, {
-				uri: id,
-				title: resource.name,
-			});
+			const sessions = this.#subscriptions[what].get(id);
+			this.#notify(
+				`notifications/resources/updated`,
+				{
+					uri: id,
+					title: resource.name,
+				},
+				{
+					sessions: sessions ? [...sessions] : undefined,
+				},
+			);
+		}
+	}
+
+	/**
+	 * @template {StandardSchema} TSchema
+	 * @param {TSchema} schema
+	 * @returns {Promise<StandardSchemaV1.InferOutput<TSchema>>}
+	 */
+	async elicitation(schema) {
+		if (!this.#client_capabilities?.elicitation)
+			throw new Error("Client doesn't support elicitation");
+
+		this.#lazyily_create_client();
+		let validated_result = schema['~standard'].validate(
+			await this.#client?.request(
+				'elicitation/create',
+				{
+					params: await this.#options.adapter.toJsonSchema(schema),
+				},
+				{
+					sessions: [this.#session_id],
+				},
+			),
+		);
+		if (validated_result instanceof Promise)
+			validated_result = await validated_result;
+		if (validated_result.issues) {
+			throw new Error(
+				`Invalid elicitation result: ${JSON.stringify(validated_result.issues)}`,
+			);
 		}
+		return validated_result.value;
 	}
 }

package/src/internal/internal.d.ts

@@ -6,6 +6,7 @@ import {
 	CallToolResult,
 	ReadResourceResult,
 	CompleteResult,
+	InitializeRequest,
 } from '../validation/index.js';
 
 export type Tool<TSchema extends StandardSchemaV1 = StandardSchemaV1<any>> = {
@@ -67,5 +68,11 @@ export type ServerInfo = {
 export type SubscriptionsKeys = 'resource';
 
 export type McpEvents = {
-	send: (message: JSONRPCRequest) => void;
+	send: (message: {
+		request: JSONRPCRequest;
+		context: {
+			sessions?: string[] | undefined;
+		};
+	}) => void;
+	initialize: (initialize_request: InitializeRequest) => void;
 };

package/src/validation/index.d.ts

@@ -675,6 +675,25 @@ export const CompleteResultSchema: v.LooseObjectSchema<{
     }, undefined>;
     readonly _meta: v.OptionalSchema<v.LooseObjectSchema<{}, undefined>, undefined>;
 }, undefined>;
+export const ClientCapabilitiesSchema: v.LooseObjectSchema<{
+    readonly roots: v.OptionalSchema<v.LooseObjectSchema<{
+        readonly listChanged: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly sampling: v.OptionalSchema<v.LooseObjectSchema<{}, undefined>, undefined>;
+    readonly elicitation: v.OptionalSchema<v.LooseObjectSchema<{}, undefined>, undefined>;
+}, undefined>;
+export const InitializeRequestSchema: v.LooseObjectSchema<{
+    readonly protocolVersion: v.StringSchema<undefined>;
+    readonly capabilities: v.LooseObjectSchema<{
+        readonly roots: v.OptionalSchema<v.LooseObjectSchema<{
+            readonly listChanged: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        readonly sampling: v.OptionalSchema<v.LooseObjectSchema<{}, undefined>, undefined>;
+        readonly elicitation: v.OptionalSchema<v.LooseObjectSchema<{}, undefined>, undefined>;
+    }, undefined>;
+}, undefined>;
+export type ClientCapabilities = v.InferInput<typeof ClientCapabilitiesSchema>;
+export type InitializeRequest = v.InferInput<typeof InitializeRequestSchema>;
 export type CallToolResult = v.InferInput<typeof CallToolResultSchema>;
 export type ReadResourceResult = v.InferInput<typeof ReadResourceResultSchema>;
 export type GetPromptResult = v.InferInput<typeof GetPromptResultSchema>;

package/src/validation/index.js

@@ -231,6 +231,29 @@ export const CompleteResultSchema = v.looseObject({
 	_meta: v.optional(v.looseObject({})),
 });
 
+export const ClientCapabilitiesSchema = v.looseObject({
+	roots: v.optional(
+		v.looseObject({
+			listChanged: v.optional(v.boolean()),
+		}),
+	),
+	sampling: v.optional(v.looseObject({})),
+	elicitation: v.optional(v.looseObject({})),
+});
+
+export const InitializeRequestSchema = v.looseObject({
+	protocolVersion: v.string(),
+	capabilities: ClientCapabilitiesSchema,
+});
+
+/**
+ * @typedef {v.InferInput<typeof ClientCapabilitiesSchema>} ClientCapabilities
+ */
+
+/**
+ * @typedef {v.InferInput<typeof InitializeRequestSchema>} InitializeRequest
+ */
+
 /**
  * @typedef {v.InferInput<typeof CallToolResultSchema>} CallToolResult
  */