tmcp 1.10.1 → 1.10.3

package/README.md

@@ -249,6 +249,67 @@ Send notifications for subscriptions.
 server.changed('resource', 'file://path/to/resource');
 ```
 
+##### `progress(progress, total?, message?)`
+
+Report progress during long-running operations. Progress notifications are only sent when a progress token is provided by the client in the request's `_meta.progressToken` field.
+
+```javascript
+server.tool(
+	{
+		name: 'process-large-file',
+		description: 'Process a large file with progress updates',
+	},
+	async (input) => {
+		const totalSteps = 100;
+
+		for (let i = 0; i <= totalSteps; i++) {
+			// Report progress with current step, total steps, and optional message
+			server.progress(
+				i,
+				totalSteps,
+				`Processing step ${i}/${totalSteps}`,
+			);
+
+			// Simulate work
+			await processStep(i);
+		}
+
+		return {
+			content: [{ type: 'text', text: 'Processing complete!' }],
+		};
+	},
+);
+```
+
+**Parameters:**
+
+- `progress` (number): Current progress value (should be ≤ total and always increase)
+- `total` (number, optional): Maximum progress value (defaults to 1)
+- `message` (string, optional): Descriptive message about current progress
+
+**Notes:**
+
+- Progress notifications are only sent when the client provides a `progressToken` in the request
+- Progress values should be monotonically increasing within a single operation
+- Each session maintains its own progress context
+
+##### `log(level, data, logger?)`
+
+Send log messages to connected clients when logging is enabled.
+
+```javascript
+// Log at different severity levels
+server.log('info', 'Server started successfully');
+server.log('warning', 'Configuration missing, using defaults');
+server.log('error', 'Failed to connect to database', 'database-logger');
+```
+
+**Parameters:**
+
+- `level` (string): Log level ('debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency')
+- `data` (any): Data to log
+- `logger` (string, optional): Logger name/category
+
 ##### `on(event, callback)`
 
 Listen to server events.
@@ -265,6 +326,94 @@ server.on('send', ({ request, context }) => {
 
 ## Advanced Examples
 
+### Progress Reporting
+
+Provide real-time progress updates for long-running operations:
+
+```javascript
+server.tool(
+	{
+		name: 'analyze-codebase',
+		description: 'Analyze a large codebase with progress tracking',
+		schema: z.object({
+			path: z.string(),
+			includeTests: z.boolean().default(false),
+		}),
+	},
+	async ({ path, includeTests }) => {
+		// Discover files to analyze
+		const files = await discoverFiles(path, includeTests);
+		const totalFiles = files.length;
+
+		server.progress(0, totalFiles, 'Starting analysis...');
+
+		const results = [];
+		for (let i = 0; i < files.length; i++) {
+			const file = files[i];
+
+			// Update progress with current file being processed
+			server.progress(
+				i + 1,
+				totalFiles,
+				`Analyzing ${file} (${i + 1}/${totalFiles})`,
+			);
+
+			// Analyze the file
+			const analysis = await analyzeFile(file);
+			results.push(analysis);
+		}
+
+		// Final progress update
+		server.progress(totalFiles, totalFiles, 'Analysis complete!');
+
+		return {
+			content: [
+				{
+					type: 'text',
+					text: `Analyzed ${totalFiles} files. Found ${results.length} issues.`,
+				},
+			],
+			structuredContent: {
+				totalFiles,
+				results,
+				issues: results.length,
+			},
+		};
+	},
+);
+
+// Progress also works in prompts and resources
+server.prompt(
+	{
+		name: 'generate-report',
+		description: 'Generate a comprehensive report',
+		schema: z.object({
+			sections: z.array(z.string()),
+		}),
+	},
+	async ({ sections }) => {
+		const messages = [];
+
+		for (let i = 0; i < sections.length; i++) {
+			server.progress(
+				i,
+				sections.length,
+				`Generating section: ${sections[i]}`,
+			);
+
+			const content = await generateSection(sections[i]);
+			messages.push({
+				role: 'user',
+				content: { type: 'text', text: content },
+			});
+		}
+
+		server.progress(sections.length, sections.length, 'Report complete');
+		return { messages };
+	},
+);
+```
+
 ### Client Interaction Features
 
 ```javascript
@@ -333,34 +482,6 @@ server.resource(
 server.changed('resource', 'file://watched/file.txt');
 ```
 
-### Multiple Schema Libraries
-
-```javascript
-// Use different schemas for different tools
-import { z } from 'zod';
-import * as v from 'valibot';
-
-server.tool(
-	{
-		name: 'zod-tool',
-		schema: z.object({ name: z.string() }),
-	},
-	async ({ name }) => ({
-		content: [{ type: 'text', text: `Hello ${name}` }],
-	}),
-);
-
-server.tool(
-	{
-		name: 'valibot-tool',
-		schema: v.object({ age: v.number() }),
-	},
-	async ({ age }) => ({
-		content: [{ type: 'text', text: `Age: ${age}` }],
-	}),
-);
-```
-
 ### Completion API
 
 The completion API allows you to provide auto-completion suggestions for prompt and template parameters. Completion functions return an object with `completion` containing `values`, `total`, and `hasMore` properties.
@@ -653,6 +774,232 @@ server.tool(
 );
 ```
 
+## Dynamic Enabling/Disabling
+
+All MCP capabilities (tools, prompts, resources, templates) support dynamic enabling and disabling through the `enabled` function. This allows you to conditionally show or hide capabilities based on runtime conditions, user permissions, or any other logic.
+
+### Basic Usage
+
+The `enabled` function is called before each list operation and determines whether the capability should be included in the response:
+
+```javascript
+server.tool(
+	{
+		name: 'admin-only-tool',
+		description: 'Administrative tool',
+		enabled: () => {
+			// Only show this tool if user is admin
+			return getCurrentUser().isAdmin;
+		},
+	},
+	async (input) => {
+		return { content: [{ type: 'text', text: 'Admin action completed' }] };
+	},
+);
+```
+
+### Async Enabled Functions
+
+The `enabled` function can be synchronous or asynchronous:
+
+```javascript
+server.resource(
+	{
+		name: 'private-document',
+		description: 'Access private documents',
+		uri: 'private://document.txt',
+		enabled: async () => {
+			// Check permissions asynchronously
+			const user = await getCurrentUser();
+			return await hasPermission(user.id, 'read-private-docs');
+		},
+	},
+	async (uri) => {
+		return {
+			contents: [
+				{
+					uri,
+					mimeType: 'text/plain',
+					text: await readPrivateDocument(uri),
+				},
+			],
+		};
+	},
+);
+```
+
+### Context-Aware Enabling
+
+Within the `enabled` function you can read the session context with `server.ctx`, allowing for user-specific or session-specific logic:
+
+```javascript
+server.prompt(
+	{
+		name: 'personalized-prompt',
+		description: 'User-specific prompt template',
+		enabled: () => {
+			// Access session information
+			const sessionId = server.ctx.sessionId;
+			const userPrefs = getUserPreferences(sessionId);
+			return userPrefs.enablePersonalization;
+		},
+	},
+	async (input) => {
+		return {
+			messages: [
+				{
+					role: 'user',
+					content: { type: 'text', text: 'Personalized content...' },
+				},
+			],
+		};
+	},
+);
+```
+
+or enable a something based on client capabilities or info
+
+```javascript
+server.prompt(
+	{
+		name: 'personalized-prompt',
+		description: 'Claude Code prompt',
+		enabled: () => {
+			// Access session information
+			const clientInfo = server.currentClientInfo();
+			return clientInfo.name === 'Claude Code';
+		},
+	},
+	async (input) => {
+		return {
+			messages: [
+				{
+					role: 'user',
+					content: { type: 'text', text: 'Personalized content...' },
+				},
+			],
+		};
+	},
+);
+```
+
+or
+
+```javascript
+server.prompt(
+	{
+		name: 'fetch-repositories',
+		description: 'fetch the repositories of the user',
+		enabled: () => {
+			// Access session information
+			const clientInfo = server.currentClientCapabilities();
+			return clientInfo.elicitation != null;
+		},
+	},
+	async (input) => {
+		const username = await server.elicitation(
+			v.object({
+				value: v.string(),
+			}),
+		);
+		const repos = await fetchRepos(username.value);
+		return {
+			messages: [
+				{
+					role: 'user',
+					content: {
+						type: 'text',
+						text: `Your repositories are ${repos.join(', ')}`,
+					},
+				},
+			],
+		};
+	},
+);
+```
+
+### Template Enabling
+
+URI templates also support the `enabled` function:
+
+```javascript
+server.template(
+	{
+		name: 'user-files',
+		description: 'Access user-specific files',
+		uri: 'users/{userId}/files/{filename}',
+		enabled: async () => {
+			// Check if file system is available
+			return await isFileSystemMounted();
+		},
+		complete: {
+			userId: (arg, context) => ({
+				completion: {
+					values: ['user1', 'user2', 'user3'],
+					total: 3,
+					hasMore: false,
+				},
+			}),
+		},
+	},
+	async (uri, params) => {
+		const content = await readUserFile(params.userId, params.filename);
+		return {
+			contents: [
+				{
+					uri,
+					mimeType: 'text/plain',
+					text: content,
+				},
+			],
+		};
+	},
+);
+```
+
+### Error Handling
+
+If an `enabled` function throws an error, the capability will be treated as disabled:
+
+```javascript
+server.tool(
+	{
+		name: 'network-tool',
+		description: 'Tool requiring network access',
+		enabled: () => {
+			// If network check fails, tool is disabled
+			if (!checkNetworkConnection()) {
+				throw new Error('Network unavailable');
+			}
+			return true;
+		},
+	},
+	async (input) => {
+		return {
+			content: [{ type: 'text', text: 'Network operation completed' }],
+		};
+	},
+);
+```
+
+### Performance Considerations
+
+- The `enabled` function is called every time a list is requested
+- Keep enabled functions lightweight to avoid performance issues
+- Consider caching expensive checks when possible
+- Async functions add latency to list operations
+
+### Use Cases
+
+Common scenarios where `enabled` functions are useful:
+
+1. **Permission-based access**: Show tools only to authorized users
+2. **Feature flags**: Enable/disable features based on configuration
+3. **Resource availability**: Hide resources when underlying systems are unavailable
+4. **User preferences**: Customize available capabilities per user
+5. **Time-based access**: Enable tools only during specific hours
+6. **License restrictions**: Limit features based on subscription level
+
 ## Contributing
 
 Contributions are welcome! Please see our [contributing guidelines](../../CONTRIBUTING.md) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmcp",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "description": "The main tmcp library",
   "main": "src/index.js",
   "type": "module",
@@ -31,7 +31,7 @@
     "@standard-schema/spec": "^1.0.0",
     "json-rpc-2.0": "^1.7.1",
     "sqids": "^0.3.0",
-    "uri-template-matcher": "^1.1.0",
+    "uri-template-matcher": "^1.1.1",
     "valibot": "^1.1.0"
   },
   "devDependencies": {

package/src/index.js

@@ -3,7 +3,7 @@
  * @import SqidsType from "sqids";
  * @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 } from "./validation/index.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 { JSONRPCClient, JSONRPCServer } from 'json-rpc-2.0';
@@ -77,6 +77,17 @@ async function decode_cursor(cursor) {
 	return decoded;
 }
 
+/**
+ * @param {()=>boolean | Promise<boolean>} enabled
+ */
+async function safe_enabled(enabled) {
+	try {
+		return await enabled();
+	} catch {
+		return false;
+	}
+}
+
 /**
  * @typedef {ClientCapabilitiesType} ClientCapabilities
  */
@@ -129,7 +140,7 @@ export class McpServer {
 	};
 
 	/**
-	 * @type {AsyncLocalStorage<Context>}
+	 * @type {AsyncLocalStorage<Context & { progress_token?: string }>}
 	 */
 	#ctx_storage = new AsyncLocalStorage();
 
@@ -138,6 +149,11 @@ export class McpServer {
 	 */
 	#client_capabilities_map = new Map();
 
+	/**
+	 * @type {Map<string|undefined, ClientInfo>}
+	 */
+	#client_info_map = new Map();
+
 	/**
 	 * @type {Map<string|undefined, string>}
 	 */
@@ -195,6 +211,12 @@ export class McpServer {
 					validated_initialize.capabilities,
 				);
 
+				// Store client info
+				this.#client_info_map.set(
+					session_id,
+					validated_initialize.clientInfo,
+				);
+
 				// Dispatch initialization event
 				this.#event_target.dispatchEvent(
 					new CustomEvent('initialize', {
@@ -258,14 +280,34 @@ export class McpServer {
 		return this.#ctx_storage.getStore()?.sessionId;
 	}
 
+	get #progress_token() {
+		return this.#ctx_storage.getStore()?.progress_token;
+	}
+
+	/**
+	 * The context of the current request, include the session ID and any auth information.
+	 * @type {Context}
+	 */
 	get ctx() {
-		return this.#ctx_storage.getStore() ?? {};
+		// eslint-disable-next-line no-unused-vars
+		const { progress_token, ...rest } = this.#ctx_storage.getStore() ?? {};
+		return rest;
 	}
 
 	get #client_capabilities() {
 		return this.#client_capabilities_map.get(this.#session_id);
 	}
 
+	/**
+	 * Get the client information (name, version, etc.) of the client that initiated the current request...useful if you want to do something different based on the client.
+	 */
+	currentClientInfo() {
+		return this.#client_info_map.get(this.#session_id);
+	}
+
+	/**
+	 * Get the client capabilities of the client that initiated the current request, you can use this to verify the client support something before invoking the respective method.
+	 */
 	currentClientCapabilities() {
 		return this.#client_capabilities;
 	}
@@ -322,34 +364,41 @@ export class McpServer {
 	#init_tools() {
 		if (!this.#options.capabilities?.tools) return;
 		this.#server.addMethod('tools/list', async () => {
-			const available_tools = await Promise.all(
-				[...this.#tools].map(async ([name, tool]) => {
-					return {
-						name,
-						title: tool.title || tool.description,
-						description: tool.description,
-
-						inputSchema: tool.schema
-							? await this.#options.adapter.toJsonSchema(
-									tool.schema,
-								)
-							: { type: 'object', properties: {} },
-						...(tool.outputSchema
-							? {
-									outputSchema:
-										await this.#options.adapter.toJsonSchema(
-											tool.outputSchema,
-										),
-								}
-							: {}),
-						...(tool.annotations
-							? {
-									annotations: tool.annotations,
-								}
-							: {}),
-					};
-				}),
-			);
+			const available_tools = (
+				await Promise.all(
+					[...this.#tools].map(async ([name, tool]) => {
+						if (
+							tool.enabled != null &&
+							(await safe_enabled(tool.enabled)) === false
+						)
+							return null;
+						return {
+							name,
+							title: tool.title || tool.description,
+							description: tool.description,
+
+							inputSchema: tool.schema
+								? await this.#options.adapter.toJsonSchema(
+										tool.schema,
+									)
+								: { type: 'object', properties: {} },
+							...(tool.outputSchema
+								? {
+										outputSchema:
+											await this.#options.adapter.toJsonSchema(
+												tool.outputSchema,
+											),
+									}
+								: {}),
+							...(tool.annotations
+								? {
+										annotations: tool.annotations,
+									}
+								: {}),
+						};
+					}),
+				)
+			).filter((tool) => tool !== null);
 			return {
 				tools: available_tools,
 			};
@@ -419,39 +468,49 @@ export class McpServer {
 	#init_prompts() {
 		if (!this.#options.capabilities?.prompts) return;
 		this.#server.addMethod('prompts/list', async ({ cursor } = {}) => {
-			const all_prompts = await Promise.all(
-				[...this.#prompts].map(async ([name, prompt]) => {
-					const arguments_schema = prompt.schema
-						? await this.#options.adapter.toJsonSchema(
-								prompt.schema,
-							)
-						: {
-								type: 'object',
-								properties:
-									/** @type {Record<string, {description: string}>} */ ({}),
-								required: [],
-							};
-					const keys = Object.keys(arguments_schema.properties ?? {});
-					const required = arguments_schema.required ?? [];
-					return {
-						name,
-						title: prompt.title || prompt.description,
-						description: prompt.description,
-						arguments: keys.map((key) => {
-							const property = arguments_schema.properties?.[key];
-							const description =
-								property && property !== true
-									? property.description
-									: key;
-							return {
-								name: key,
-								required: required.includes(key),
-								description,
-							};
-						}),
-					};
-				}),
-			);
+			const all_prompts = (
+				await Promise.all(
+					[...this.#prompts].map(async ([name, prompt]) => {
+						if (
+							prompt.enabled != null &&
+							(await safe_enabled(prompt.enabled)) === false
+						)
+							return null;
+						const arguments_schema = prompt.schema
+							? await this.#options.adapter.toJsonSchema(
+									prompt.schema,
+								)
+							: {
+									type: 'object',
+									properties:
+										/** @type {Record<string, {description: string}>} */ ({}),
+									required: [],
+								};
+						const keys = Object.keys(
+							arguments_schema.properties ?? {},
+						);
+						const required = arguments_schema.required ?? [];
+						return {
+							name,
+							title: prompt.title || prompt.description,
+							description: prompt.description,
+							arguments: keys.map((key) => {
+								const property =
+									arguments_schema.properties?.[key];
+								const description =
+									property && property !== true
+										? property.description
+										: key;
+								return {
+									name: key,
+									required: required.includes(key),
+									description,
+								};
+							}),
+						};
+					}),
+				)
+			).filter((prompt) => prompt !== null);
 
 			const pagination_options = this.#options.pagination?.prompts;
 			if (!pagination_options || pagination_options.size == null) {
@@ -528,6 +587,11 @@ export class McpServer {
 			for (const [uri, { description, name, title, ...resource }] of this
 				.#resources) {
 				if (!resource.template) {
+					if (
+						resource.enabled != null &&
+						(await safe_enabled(resource.enabled)) === false
+					)
+						continue;
 					all_resources.push({
 						name,
 						title: title || description,
@@ -535,6 +599,11 @@ export class McpServer {
 						uri,
 					});
 				} else if (resource.list_resources) {
+					if (
+						resource.enabled != null &&
+						(await safe_enabled(resource.enabled)) === false
+					)
+						continue;
 					const template_resources = await resource.list_resources();
 					all_resources.push(...template_resources);
 				}
@@ -563,20 +632,29 @@ export class McpServer {
 		});
 		this.#server.addMethod('resources/templates/list', async () => {
 			return {
-				resourceTemplates: [...this.#resources].reduce(
-					(arr, [uri, { description, name, title, template }]) => {
-						if (template) {
-							arr.push({
-								name,
-								title: title || description,
-								description,
-								uriTemplate: uri,
-							});
-						}
-						return arr;
-					},
-					/** @type {Array<{name: string, title: string, description: string, uriTemplate: string}>} */ ([]),
-				),
+				resourceTemplates: (
+					await Promise.all(
+						[...this.#resources].map(
+							async ([
+								uri,
+								{ description, name, title, template, enabled },
+							]) => {
+								if (!template) return null;
+								if (
+									enabled != null &&
+									(await safe_enabled(enabled)) === false
+								)
+									return null;
+								return {
+									name,
+									title: title || description,
+									description,
+									uriTemplate: uri,
+								};
+							},
+						),
+					)
+				).filter((resource) => resource != null),
 			};
 		});
 		this.#server.addMethod('resources/read', async ({ uri }) => {
@@ -640,9 +718,7 @@ export class McpServer {
 			this.roots = [];
 		}
 	}
-	/**
-	 *
-	 */
+
 	#init_completion() {
 		this.#server.addMethod(
 			'completion/complete',
@@ -660,9 +736,7 @@ export class McpServer {
 			},
 		);
 	}
-	/**
-	 *
-	 */
+
 	#init_logging() {
 		if (!this.#options.capabilities?.logging) return;
 
@@ -672,13 +746,25 @@ export class McpServer {
 		});
 	}
 	/**
+	 * 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.
+	 *
+	 * Tools will be invoked by the LLM when it thinks it needs to use them, you can use the annotations to provide additional information about the tool, like what it does, how to use it, etc.
 	 * @template {StandardSchema | undefined} [TSchema=undefined]
 	 * @template {StandardSchema | undefined} [TOutputSchema=undefined]
-	 * @param {{ name: string; description: string; title?: string; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never; outputSchema?: StandardSchemaV1.InferOutput<TOutputSchema extends undefined ? never : TOutputSchema> extends Record<string, unknown> ? TOutputSchema : never; annotations?: ToolAnnotations }} options
+	 * @param {{ name: string; description: string; title?: string; enabled?: ()=>boolean | Promise<boolean>; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never; outputSchema?: StandardSchemaV1.InferOutput<TOutputSchema extends undefined ? never : TOutputSchema> extends Record<string, unknown> ? TOutputSchema : never; annotations?: ToolAnnotations }} options
 	 * @param {TSchema extends undefined ? (()=>Promise<CallToolResult<TOutputSchema extends undefined ? undefined : StandardSchemaV1.InferInput<TOutputSchema extends undefined ? never : TOutputSchema>>> | CallToolResult<TOutputSchema extends undefined ? undefined : StandardSchemaV1.InferInput<TOutputSchema extends undefined ? never : TOutputSchema>>) : ((input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<CallToolResult<TOutputSchema extends undefined ? undefined : StandardSchemaV1.InferInput<TOutputSchema extends undefined ? never : TOutputSchema>>> | CallToolResult<TOutputSchema extends undefined ? undefined : StandardSchemaV1.InferInput<TOutputSchema extends undefined ? never : TOutputSchema>>)} execute
 	 */
 	tool(
-		{ name, description, title, schema, outputSchema, annotations },
+		{
+			name,
+			description,
+			title,
+			schema,
+			outputSchema,
+			annotations,
+			enabled,
+		},
 		execute,
 	) {
 		if (this.#options.capabilities?.tools?.listChanged) {
@@ -687,6 +773,7 @@ export class McpServer {
 		this.#tools.set(name, {
 			description,
 			title,
+			enabled,
 			schema,
 			outputSchema,
 			execute,
@@ -694,11 +781,16 @@ export class McpServer {
 		});
 	}
 	/**
+	 * Add a prompt to the server. Prompts are used to provide the user with pre-defined messages that adds context to the LLM.
+	 * Use the description and title to help the user to understand what the prompt does and when to use it.
+	 *
+	 * A prompt can also have a schema that defines the input it expects, the user will be prompted to enter the inputs you request. It can also have a complete function
+	 * for each input that will be used to provide completions for the user.
 	 * @template {StandardSchema | undefined} [TSchema=undefined]
-	 * @param {{ name: string; description: string; title?: string; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never; complete?: NoInfer<TSchema extends undefined ? never : Partial<Record<keyof (StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>), Completion>>> }} options
+	 * @param {{ name: string; description: string; title?: string; enabled?: ()=>boolean | Promise<boolean>; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never; complete?: NoInfer<TSchema extends undefined ? never : Partial<Record<keyof (StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>), Completion>>> }} options
 	 * @param {TSchema extends undefined ? (()=>Promise<GetPromptResult> | GetPromptResult) : (input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<GetPromptResult> | GetPromptResult} execute
 	 */
-	prompt({ name, description, title, schema, complete }, execute) {
+	prompt({ name, description, title, schema, complete, enabled }, execute) {
 		if (complete) {
 			this.#completions['ref/prompt'].set(name, complete);
 		}
@@ -710,6 +802,7 @@ export class McpServer {
 			title,
 			schema,
 			execute,
+			enabled,
 		});
 	}
 	/**
@@ -727,32 +820,50 @@ export class McpServer {
 		}
 		this.#resources.set(uri, resource);
 	}
+
 	/**
-	 * @param {{ name: string; description: string; title?: string; uri: string }} options
+	 * 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.
+	 * @param {{ name: string; description: string; title?: string; uri: string, enabled?: ()=>boolean | Promise<boolean>; }} options
 	 * @param {(uri: string) => Promise<ReadResourceResult> | ReadResourceResult} execute
 	 */
-	resource({ name, description, title, uri }, execute) {
+	resource({ name, description, title, uri, enabled }, execute) {
 		this.#resource({
 			name,
 			description,
 			title,
 			uri,
 			execute,
+			enabled,
 			template: false,
 		});
 	}
 	/**
+	 * 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.
+	 * Resource templates can have a list method that returns a list of resources that match the template and a complete method that returns a list of resources given one of the template variables, this method will
+	 * be invoked to provide completions for the template variables to the user.
+	 * Use the description and title to help the user to understand what the resource is.
 	 * @template {string} TUri
 	 * @template {ExtractURITemplateVariables<TUri>} TVariables
-	 * @param {{ name: string; description: string; title?: string; uri: TUri; complete?: NoInfer<TVariables extends never ? never : Partial<Record<TVariables, Completion>>>; list?: () => Promise<Array<Resource>> | Array<Resource> }} options
+	 * @param {{ name: string; description: string; title?: string; enabled?: ()=>boolean | Promise<boolean>; uri: TUri; complete?: NoInfer<TVariables extends never ? never : Partial<Record<TVariables, Completion>>>; list?: () => Promise<Array<Resource>> | Array<Resource> }} options
 	 * @param {(uri: string, params: Record<TVariables, string | string[]>) => Promise<ReadResourceResult> | ReadResourceResult} execute
 	 */
 	template(
-		{ name, description, title, uri, complete, list: list_resources },
+		{
+			name,
+			description,
+			title,
+			uri,
+			complete,
+			list: list_resources,
+			enabled,
+		},
 		execute,
 	) {
 		this.#resource({
 			name,
+			enabled,
 			description,
 			title,
 			uri,
@@ -763,6 +874,8 @@ export class McpServer {
 		});
 	}
 	/**
+	 * The main function that receive a JSONRpc message and either dispatch a `send` event or process the request.
+	 *
 	 * @param {JSONRPCResponse | JSONRPCRequest} message
 	 * @param {Context} [ctx]
 	 * @returns {ReturnType<JSONRPCServer['receive']> | ReturnType<JSONRPCClient['receive'] | undefined>}
@@ -788,8 +901,11 @@ export class McpServer {
 					this.#options.logging?.default ?? 'info',
 				);
 			}
+			const progress_token = /** @type {string | undefined} */ (
+				validated_message.output.params?._meta?.progressToken
+			);
 			return this.#ctx_storage.run(
-				ctx ?? {},
+				{ ...(ctx ?? {}), progress_token },
 				async () =>
 					await this.#server.receive(validated_message.output),
 			);
@@ -833,6 +949,12 @@ export class McpServer {
 	}
 
 	/**
+	 * Emit an elicitation request to the client. Elicitations are used to ask the user for input in a structured way, the client will show a UI to the user to fill the input.
+	 * The schema should be a valid Standard Schema V1 schema and should be an Object with the properties you need.
+	 * The client will return the validated input as a JSON object that matches the schema.
+	 *
+	 * If the client doesn't support elicitation, it will throw an error.
+	 *
 	 * @template {StandardSchema} TSchema
 	 * @param {TSchema} schema
 	 * @returns {Promise<StandardSchemaV1.InferOutput<TSchema>>}
@@ -894,8 +1016,33 @@ export class McpServer {
 		return v.parse(CreateMessageResultSchema, response);
 	}
 
+	/**
+	 * Send a progress notification to the client. This is useful for long-running operations where you want to inform the user about the progress.
+	 *
+	 * @param {number} progress The current progress value, it should be between 0 and total and should always increase
+	 * @param {number} [total] The total value, defaults to 1
+	 * @param {string} [message] An optional message to accompany the progress update
+	 */
+	progress(progress, total = 1, message = undefined) {
+		if (this.#progress_token != null) {
+			this.#notify(
+				'notifications/progress',
+				{
+					progress,
+					total,
+					message,
+					progressToken: this.#progress_token,
+				},
+				{
+					sessions: this.#session_id ? [this.#session_id] : undefined,
+				},
+			);
+		}
+	}
+
 	/**
 	 * Log a message to the client if logging is enabled and the level is appropriate
+	 *
 	 * @param {LoggingLevel} level
 	 * @param {unknown} data
 	 * @param {string} [logger]

package/src/internal/internal.d.ts

@@ -19,6 +19,7 @@ export type Tool<TSchema extends StandardSchemaV1 = StandardSchemaV1<any>, TOutp
 	outputSchema?: TOutputSchema;
 	title?: string;
 	annotations?: ToolAnnotations;
+	enabled?: () => boolean | Promise<boolean>;
 	execute: (
 		input?: StandardSchemaV1.InferInput<TSchema>,
 	) => Promise<CallToolResult> | CallToolResult;
@@ -33,6 +34,7 @@ export type Prompt<TSchema extends StandardSchemaV1 = StandardSchemaV1<any>> = {
 	description: string;
 	schema: TSchema;
 	title?: string;
+	enabled?: () => boolean | Promise<boolean>;
 	execute: (
 		input?: StandardSchemaV1.InferInput<TSchema>,
 	) => Promise<GetPromptResult> | GetPromptResult;
@@ -44,6 +46,7 @@ export type StoredResource =
 			name: string;
 			template: true;
 			title?: string;
+			enabled?: () => boolean | Promise<boolean>;
 			list_resources?: () =>
 				| Promise<Array<Resource>>
 				| Array<Resource>;
@@ -57,6 +60,7 @@ export type StoredResource =
 			name: string;
 			template: false;
 			title?: string;
+			enabled?: () => boolean | Promise<boolean>;
 			execute: (
 				uri: string,
 			) => Promise<ReadResourceResult> | ReadResourceResult;

package/src/types/index.d.ts

@@ -11,7 +11,21 @@ declare module 'tmcp' {
 			uri: string;
 			name?: string;
 		}>;
+		/**
+		 * The context of the current request, include the session ID and any auth information.
+		 * */
 		get ctx(): Context;
+		/**
+		 * Get the client information (name, version, etc.) of the client that initiated the current request...useful if you want to do something different based on the client.
+		 */
+		currentClientInfo(): {
+			version: string;
+			name: string;
+			title?: string | undefined;
+		} | undefined;
+		/**
+		 * Get the client capabilities of the client that initiated the current request, you can use this to verify the client support something before invoking the respective method.
+		 */
 		currentClientCapabilities(): {
 			experimental?: {} | undefined;
 			sampling?: {} | undefined;
@@ -22,40 +36,67 @@ declare module 'tmcp' {
 		} | undefined;
 		
 		on<TEvent extends keyof McpEvents>(event: TEvent, callback: McpEvents[TEvent], options?: AddEventListenerOptions): () => void;
-		
-		tool<TSchema extends StandardSchema | undefined = undefined, TOutputSchema extends StandardSchema | undefined = undefined>({ name, description, title, schema, outputSchema, annotations }: {
+		/**
+		 * 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.
+		 *
+		 * Tools will be invoked by the LLM when it thinks it needs to use them, you can use the annotations to provide additional information about the tool, like what it does, how to use it, etc.
+		 * */
+		tool<TSchema extends StandardSchema | undefined = undefined, TOutputSchema extends StandardSchema | undefined = undefined>({ name, description, title, schema, outputSchema, annotations, enabled, }: {
 			name: string;
 			description: string;
 			title?: string;
+			enabled?: () => boolean | Promise<boolean>;
 			schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never;
 			outputSchema?: StandardSchemaV1.InferOutput<TOutputSchema extends undefined ? never : TOutputSchema> extends Record<string, unknown> ? TOutputSchema : never;
 			annotations?: ToolAnnotations;
 		}, execute: TSchema extends undefined ? (() => Promise<CallToolResult<TOutputSchema extends undefined ? undefined : StandardSchemaV1.InferInput<TOutputSchema extends undefined ? never : TOutputSchema>>> | CallToolResult<TOutputSchema extends undefined ? undefined : StandardSchemaV1.InferInput<TOutputSchema extends undefined ? never : TOutputSchema>>) : ((input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<CallToolResult<TOutputSchema extends undefined ? undefined : StandardSchemaV1.InferInput<TOutputSchema extends undefined ? never : TOutputSchema>>> | CallToolResult<TOutputSchema extends undefined ? undefined : StandardSchemaV1.InferInput<TOutputSchema extends undefined ? never : TOutputSchema>>)): void;
-		
-		prompt<TSchema extends StandardSchema | undefined = undefined>({ name, description, title, schema, complete }: {
+		/**
+		 * Add a prompt to the server. Prompts are used to provide the user with pre-defined messages that adds context to the LLM.
+		 * Use the description and title to help the user to understand what the prompt does and when to use it.
+		 *
+		 * A prompt can also have a schema that defines the input it expects, the user will be prompted to enter the inputs you request. It can also have a complete function
+		 * for each input that will be used to provide completions for the user.
+		 * */
+		prompt<TSchema extends StandardSchema | undefined = undefined>({ name, description, title, schema, complete, enabled }: {
 			name: string;
 			description: string;
 			title?: string;
+			enabled?: () => boolean | Promise<boolean>;
 			schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never;
 			complete?: NoInfer<TSchema extends undefined ? never : Partial<Record<keyof StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>, Completion>>>;
 		}, execute: TSchema extends undefined ? (() => Promise<GetPromptResult> | GetPromptResult) : (input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<GetPromptResult> | GetPromptResult): void;
-		
-		resource({ name, description, title, uri }: {
+		/**
+		 * 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.
+		 * */
+		resource({ name, description, title, uri, enabled }: {
 			name: string;
 			description: string;
 			title?: string;
 			uri: string;
+			enabled?: () => boolean | Promise<boolean>;
 		}, execute: (uri: string) => Promise<ReadResourceResult> | ReadResourceResult): void;
-		
-		template<TUri extends string, TVariables extends ExtractURITemplateVariables<TUri>>({ name, description, title, uri, complete, list: list_resources }: {
+		/**
+		 * 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.
+		 * Resource templates can have a list method that returns a list of resources that match the template and a complete method that returns a list of resources given one of the template variables, this method will
+		 * be invoked to provide completions for the template variables to the user.
+		 * Use the description and title to help the user to understand what the resource is.
+		 * */
+		template<TUri extends string, TVariables extends ExtractURITemplateVariables<TUri>>({ name, description, title, uri, complete, list: list_resources, enabled, }: {
 			name: string;
 			description: string;
 			title?: string;
+			enabled?: () => boolean | Promise<boolean>;
 			uri: TUri;
 			complete?: NoInfer<TVariables extends never ? never : Partial<Record<TVariables, Completion>>>;
 			list?: () => Promise<Array<Resource>> | Array<Resource>;
 		}, execute: (uri: string, params: Record<TVariables, string | string[]>) => Promise<ReadResourceResult> | ReadResourceResult): void;
-		
+		/**
+		 * The main function that receive a JSONRpc message and either dispatch a `send` event or process the request.
+		 *
+		 * */
 		receive(message: JSONRPCResponse | JSONRPCRequest, ctx?: Context): ReturnType<JSONRPCServer["receive"]> | ReturnType<JSONRPCClient["receive"] | undefined>;
 		/**
 		 * Send a notification for subscriptions
@@ -65,14 +106,30 @@ declare module 'tmcp' {
 		 * Refresh roots list from client
 		 */
 		refreshRoots(): Promise<void>;
-		
+		/**
+		 * Emit an elicitation request to the client. Elicitations are used to ask the user for input in a structured way, the client will show a UI to the user to fill the input.
+		 * The schema should be a valid Standard Schema V1 schema and should be an Object with the properties you need.
+		 * The client will return the validated input as a JSON object that matches the schema.
+		 *
+		 * If the client doesn't support elicitation, it will throw an error.
+		 *
+		 * */
 		elicitation<TSchema extends StandardSchema>(schema: TSchema): Promise<StandardSchemaV1.InferOutput<TSchema>>;
 		/**
 		 * Request language model sampling from the client
 		 * */
 		message(request: CreateMessageRequestParams): Promise<CreateMessageResult>;
+		/**
+		 * Send a progress notification to the client. This is useful for long-running operations where you want to inform the user about the progress.
+		 *
+		 * @param progress The current progress value, it should be between 0 and total and should always increase
+		 * @param total The total value, defaults to 1
+		 * @param message An optional message to accompany the progress update
+		 */
+		progress(progress: number, total?: number, message?: string): void;
 		/**
 		 * Log a message to the client if logging is enabled and the level is appropriate
+		 *
 		 * 
 		 */
 		log(level: LoggingLevel, data: unknown, logger?: string): void;

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

@@ -55,6 +55,6 @@
 		null,
 		null
 	],
-	"mappings": ";;;;;cAsFaA,SAASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aCi3CsCC,kBAAkBA;MC76ClEC,UAAUA;;;;;MAsCVC,aAAaA;;;;;;;;;;;;;MAabC,UAAUA;;;;;;MAMVC,iBAAiBA;;MAEjBC,SAASA;;;;;;;;;;;;ODeRC,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": ";;;;;cAiGaA,SAASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aCs2CsCC,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",
 	"ignoreList": []
 }