tmcp 1.11.0 → 1.12.1

package/README.md

@@ -201,12 +201,78 @@ server.template(
 );
 ```
 
-##### `receive(request, sessionId)`
+##### `withContext<T>()`
 
-Process an incoming MCP request.
+Specify the type of custom context for type-safe access to application-specific data.
 
 ```javascript
-const response = server.receive(jsonRpcRequest, sessionId);
+interface MyCustomContext {
+    userId: string;
+    permissions: string[];
+    database: DatabaseConnection;
+}
+
+const server = new McpServer(serverInfo, options).withContext<MyCustomContext>();
+
+// Now you can access typed custom context in handlers
+server.tool(
+    {
+        name: 'get-user-data',
+        description: 'Get current user data',
+    },
+    async () => {
+        const { userId, database } = server.ctx.custom!;
+        const userData = await database.users.findById(userId);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(userData) }],
+        };
+    },
+);
+```
+
+##### `ctx`
+
+Access the current request context, including session ID, auth info, and custom context.
+
+```javascript
+server.tool(
+    {
+        name: 'context-aware-tool',
+        description: 'Tool that uses request context',
+    },
+    async () => {
+        const { sessionId, auth, custom } = server.ctx;
+        
+        if (!custom?.userId) {
+            throw new Error('User authentication required');
+        }
+        
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Hello user ${custom.userId} in session ${sessionId}`,
+                },
+            ],
+        };
+    },
+);
+```
+
+##### `receive(request, context?)`
+
+Process an incoming MCP request with optional context.
+
+```javascript
+// Basic usage
+const response = server.receive(jsonRpcRequest);
+
+// With custom context (typically used by transports)
+const response = server.receive(jsonRpcRequest, {
+    sessionId: 'session-123',
+    auth: authInfo,
+    custom: customContextData,
+});
 ```
 
 ##### `elicitation(schema)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmcp",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "description": "The main tmcp library",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -5,7 +5,7 @@
  * @import { JSONRPCRequest, JSONRPCParams } from "json-rpc-2.0";
  * @import { ExtractURITemplateVariables } from "./internal/uri-template.js";
  * @import { CallToolResult, ReadResourceResult, GetPromptResult, ClientCapabilities as ClientCapabilitiesType, JSONRPCRequest as JSONRPCRequestType, JSONRPCResponse, CreateMessageRequestParams, CreateMessageResult, Resource, LoggingLevel, ToolAnnotations, ClientInfo } from "./validation/index.js";
- * @import { Tool, Completion, Prompt, StoredResource, ServerOptions, ServerInfo, SubscriptionsKeys, McpEvents } from "./internal/internal.js";
+ * @import { Tool, Completion, Prompt, StoredResource, ServerOptions, ServerInfo, SubscriptionsKeys, ChangedArgs, McpEvents } from "./internal/internal.js";
  */
 import { JSONRPCClient, JSONRPCServer } from 'json-rpc-2.0';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -762,6 +762,25 @@ export class McpServer {
 			return {};
 		});
 	}
+
+	#notify_tools_list_changed() {
+		if (this.#options.capabilities?.tools?.listChanged) {
+			this.#notify('notifications/tools/list_changed', {});
+		}
+	}
+
+	#notify_prompts_list_changed() {
+		if (this.#options.capabilities?.prompts?.listChanged) {
+			this.#notify('notifications/prompts/list_changed', {});
+		}
+	}
+
+	#notify_resources_list_changed() {
+		if (this.#options.capabilities?.resources?.listChanged) {
+			this.#notify('notifications/resources/list_changed', {});
+		}
+	}
+
 	/**
 	 * 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.
@@ -784,9 +803,7 @@ export class McpServer {
 		},
 		execute,
 	) {
-		if (this.#options.capabilities?.tools?.listChanged) {
-			this.#notify('notifications/tools/list_changed', {});
-		}
+		this.#notify_tools_list_changed();
 		this.#tools.set(name, {
 			description,
 			title,
@@ -811,9 +828,7 @@ export class McpServer {
 		if (complete) {
 			this.#completions['ref/prompt'].set(name, complete);
 		}
-		if (this.#options.capabilities?.prompts?.listChanged) {
-			this.#notify('notifications/prompts/list_changed', {});
-		}
+		this.#notify_prompts_list_changed();
 		this.#prompts.set(name, {
 			description,
 			title,
@@ -832,9 +847,7 @@ export class McpServer {
 		if (resource.template) {
 			this.#templates.add(uri);
 		}
-		if (this.#options.capabilities?.resources?.listChanged) {
-			this.#notify('notifications/resources/list_changed', {});
-		}
+		this.#notify_resources_list_changed();
 		this.#resources.set(uri, resource);
 	}
 
@@ -937,24 +950,40 @@ export class McpServer {
 
 	/**
 	 * Send a notification for subscriptions
-	 * @param {SubscriptionsKeys} what
-	 * @param {string} id
+	 * @template {keyof ChangedArgs} TWhat
+	 * @param {[what: TWhat, ...ChangedArgs[TWhat]]} args
 	 */
-	changed(what, id) {
-		if (this.#subscriptions[what].has(id)) {
-			const resource = this.#resources.get(id);
-			if (!resource) return;
-			const sessions = this.#subscriptions[what].get(id);
-			this.#notify(
-				`notifications/resources/updated`,
-				{
-					uri: id,
-					title: resource.name,
-				},
-				{
-					sessions: sessions ? [...sessions] : undefined,
-				},
-			);
+	changed(...args) {
+		const [what, id] = args;
+		if (what === 'prompts') {
+			this.#notify_prompts_list_changed();
+		} else if (what === 'tools') {
+			this.#notify_tools_list_changed();
+		} else if (what === 'resources') {
+			this.#notify_resources_list_changed();
+		} else {
+			if (
+				this.#subscriptions[
+					/** @type {SubscriptionsKeys} */ (what)
+				].has(id)
+			) {
+				const resource = this.#resources.get(id);
+				if (!resource) return;
+				const sessions =
+					this.#subscriptions[
+						/** @type {SubscriptionsKeys} */ (what)
+					].get(id);
+				this.#notify(
+					`notifications/resources/updated`,
+					{
+						uri: id,
+						title: resource.name,
+					},
+					{
+						sessions: sessions ? [...sessions] : undefined,
+					},
+				);
+			}
 		}
 	}
 
@@ -973,10 +1002,11 @@ export class McpServer {
 	 * If the client doesn't support elicitation, it will throw an error.
 	 *
 	 * @template {StandardSchema extends undefined ? never : StandardSchema} TSchema
+	 * @param {string} message
 	 * @param {TSchema} schema
 	 * @returns {Promise<StandardSchemaV1.InferOutput<TSchema>>}
 	 */
-	async elicitation(schema) {
+	async elicitation(message, schema) {
 		if (!this.#client_capabilities?.elicitation)
 			throw new McpError(-32601, "Client doesn't support elicitation");
 
@@ -985,7 +1015,9 @@ export class McpServer {
 			await this.#client?.request(
 				'elicitation/create',
 				{
-					params: await this.#options.adapter.toJsonSchema(schema),
+					message,
+					requestedSchema:
+						await this.#options.adapter.toJsonSchema(schema),
 				},
 				{
 					sessions: [this.#session_id],

package/src/internal/internal.d.ts

@@ -85,7 +85,18 @@ export type ServerInfo = {
 	description: string;
 };
 
-export type SubscriptionsKeys = 'resource';
+export type ChangedArgs = {
+	'resource': [id: string];
+	'tools': [];
+	'prompts': [];
+	'resources': [];
+}
+
+type SubscriptionsKeysObj = {
+	[K in keyof ChangedArgs as ChangedArgs[K]["length"] extends 0 ? "without_args" : "with_args"]: K
+};
+
+export type SubscriptionsKeys = SubscriptionsKeysObj["with_args"];
 
 export type McpEvents = {
 	send: (message: {

package/src/types/index.d.ts

@@ -107,7 +107,7 @@ declare module 'tmcp' {
 		/**
 		 * Send a notification for subscriptions
 		 * */
-		changed(what: SubscriptionsKeys, id: string): void;
+		changed<TWhat extends keyof ChangedArgs>(what: TWhat, ...args: ChangedArgs[TWhat]): void;
 		/**
 		 * Refresh roots list from client
 		 */
@@ -120,7 +120,7 @@ declare module 'tmcp' {
 		 * If the client doesn't support elicitation, it will throw an error.
 		 *
 		 * */
-		elicitation<TSchema extends StandardSchema extends undefined ? never : StandardSchema>(schema: TSchema): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+		elicitation<TSchema extends StandardSchema extends undefined ? never : StandardSchema>(message: string, schema: TSchema): Promise<StandardSchemaV1.InferOutput<TSchema>>;
 		/**
 		 * Request language model sampling from the client
 		 * */
@@ -202,7 +202,12 @@ declare module 'tmcp' {
 		description: string;
 	};
 
-	type SubscriptionsKeys = 'resource';
+	type ChangedArgs = {
+		'resource': [id: string];
+		'tools': [];
+		'prompts': [];
+		'resources': [];
+	}
 
 	type McpEvents = {
 		send: (message: {

package/src/types/index.d.ts.map

@@ -7,7 +7,7 @@
 		"Completion",
 		"ServerOptions",
 		"ServerInfo",
-		"SubscriptionsKeys",
+		"ChangedArgs",
 		"McpEvents",
 		"JSONRPCResponseSchema",
 		"ClientCapabilitiesSchema",
@@ -55,6 +55,6 @@
 		null,
 		null
 	],
-	"mappings": ";;;;;cAqGaA,SAASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aCk2CsCC,kBAAkBA;MC56ClEC,UAAUA;;;;;MAyCVC,aAAaA;;;;;;;;;;;;;MAabC,UAAUA;;;;;;MAMVC,iBAAiBA;;MAEjBC,SAASA;;;;;;;;;;;;ODWRC,qBAAqBA;;;;;;;;;;;;;;OAuGrBC,wBAAwBA;;;;;;;;;;;;;;;;;;;;;;;OA6BxBC,6BAA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuB7BC,wBAAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmMxBC,cAAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4GdC,wBAAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8PxBC,qBAAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BrBC,qBAAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2GrBC,oBAAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoEpBC,kBAAkBA;OAuGlBC,gCAAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8ChCC,yBAAyBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+LzBC,oBAAoBA;;;;;;;;;;;;;;;;;;;;;;MA8H2BC,kBAAkBA;MASbC,uBAAuBA;;;;;;MAO5BC,kBAAkBA;MAGrBC,eAAeA;MAGhBC,cAAcA;MAGFC,0BAA0BA;MAGjCC,mBAAmBA;MAY9BC,QAAQA;MAMDC,eAAeA;MAGlBC,YAAYA;MAGTC,eAAeA;;ME7/CnEC,IAAIA;;;;;;;MAOJC,cAAcA;;;;;;;MAOdC,cAAcA;;;;;MAKdC,qBAAqBA;;;;;;;;;;;;;;;;;MAiBrBC,4BAA4BA;;;;;;MAMrBC,2BAA2BA;;;;;;;OCjC1BC,iBAAiBA;;;;;;;;;;;;;;;;cAAjBA,iBAAiBA",
+	"mappings": ";;;;;cAqGaA,SAASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aCk2CsCC,kBAAkBA;MC56ClEC,UAAUA;;;;;MAyCVC,aAAaA;;;;;;;;;;;;;MAabC,UAAUA;;;;;;MAMVC,WAAWA;;;;;;;MAaXC,SAASA;;;;;;;;;;;;ODARC,qBAAqBA;;;;;;;;;;;;;;OAuGrBC,wBAAwBA;;;;;;;;;;;;;;;;;;;;;;;OA6BxBC,6BAA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuB7BC,wBAAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmMxBC,cAAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4GdC,wBAAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8PxBC,qBAAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BrBC,qBAAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2GrBC,oBAAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoEpBC,kBAAkBA;OAuGlBC,gCAAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8ChCC,yBAAyBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+LzBC,oBAAoBA;;;;;;;;;;;;;;;;;;;;;;MA8H2BC,kBAAkBA;MASbC,uBAAuBA;;;;;;MAO5BC,kBAAkBA;MAGrBC,eAAeA;MAGhBC,cAAcA;MAGFC,0BAA0BA;MAGjCC,mBAAmBA;MAY9BC,QAAQA;MAMDC,eAAeA;MAGlBC,YAAYA;MAGTC,eAAeA;;ME7/CnEC,IAAIA;;;;;;;MAOJC,cAAcA;;;;;;;MAOdC,cAAcA;;;;;MAKdC,qBAAqBA;;;;;;;;;;;;;;;;;MAiBrBC,4BAA4BA;;;;;;MAMrBC,2BAA2BA;;;;;;;OCjC1BC,iBAAiBA;;;;;;;;;;;;;;;;cAAjBA,iBAAiBA",
 	"ignoreList": []
 }