tmcp 1.0.2 → 1.2.0

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "tmcp",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "The main tmcp library",
   "main": "src/index.js",
   "type": "module",
   "keywords": [],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paoloricciuti/tmcp.git",
+    "directory": "packages/tmcp"
+  },
   "author": "Paolo Ricciuti",
   "license": "MIT",
   "files": [

package/src/index.d.ts

@@ -7,6 +7,13 @@ export class McpServer<StandardSchema extends StandardSchemaV1> {
      * @param {ServerOptions<StandardSchema>} options
      */
     constructor(server_info: ServerInfo, options: ServerOptions<StandardSchema>);
+    /**
+     * @template {keyof McpEvents} TEvent
+     * @param {TEvent} event
+     * @param {McpEvents[TEvent]} callback
+     * @param {AddEventListenerOptions} [options]
+     */
+    on<TEvent extends keyof McpEvents>(event: TEvent, callback: McpEvents[TEvent], options?: AddEventListenerOptions): void;
     /**
      * @template {StandardSchema | undefined} [TSchema=undefined]
      * @param {{ name: string; description: string; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never }} options
@@ -19,44 +26,55 @@ export class McpServer<StandardSchema extends StandardSchemaV1> {
     }, execute: TSchema extends undefined ? (() => Promise<unknown> | unknown) : ((input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<unknown> | unknown)): void;
     /**
      * @template {StandardSchema | undefined} [TSchema=undefined]
-     * @param {{ name: string; description: string; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never; complete?: Completion }} options
+     * @param {{ name: string; description: string; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never; complete?: TSchema extends undefined ? never : Partial<Record<keyof (StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>), Completion>> }} options
      * @param {TSchema extends undefined ? (()=>Promise<unknown> | unknown) : (input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<unknown> | unknown} execute
      */
     prompt<TSchema extends StandardSchema | undefined = undefined>({ name, description, schema, complete }: {
         name: string;
         description: string;
         schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never;
-        complete?: Completion;
+        complete?: TSchema extends undefined ? never : Partial<Record<keyof StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>, Completion>>;
     }, execute: TSchema extends undefined ? (() => Promise<unknown> | unknown) : (input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<unknown> | unknown): void;
     /**
      * @param {{ name: string; description: string; uri: string }} options
-     * @param {(uri: string, params?: unknown) => Promise<unknown> | unknown} execute
+     * @param {(uri: string) => Promise<unknown> | unknown} execute
      */
     resource({ name, description, uri }: {
         name: string;
         description: string;
         uri: string;
-    }, execute: (uri: string, params?: unknown) => Promise<unknown> | unknown): void;
+    }, execute: (uri: string) => Promise<unknown> | unknown): void;
     /**
-     * @param {{ name: string; description: string; uri: string; complete?: Completion }} options
-     * @param {(uri: string, params?: unknown) => Promise<unknown> | unknown} execute
+     * @template {string} TUri
+     * @template {ExtractURITemplateVariables<TUri>} TVariables
+     * @param {{ name: string; description: string; uri: TUri; complete?: TVariables extends never ? never : Partial<Record<TVariables, Completion>> }} options
+     * @param {(uri: string, params: Record<TVariables, string | string[]>) => Promise<unknown> | unknown} execute
      */
-    template({ name, description, uri, complete }: {
+    template<TUri extends string, TVariables extends ExtractURITemplateVariables<TUri>>({ name, description, uri, complete }: {
         name: string;
         description: string;
-        uri: string;
-        complete?: Completion;
-    }, execute: (uri: string, params?: unknown) => Promise<unknown> | unknown): void;
+        uri: TUri;
+        complete?: TVariables extends never ? never : Partial<Record<TVariables, Completion>>;
+    }, execute: (uri: string, params: Record<TVariables, string | string[]>) => Promise<unknown> | unknown): void;
     /**
      * @param {JSONRPCRequest} request
      * @returns {ReturnType<JSONRPCServer['receive']>}
      */
     receive(request: JSONRPCRequest): ReturnType<JSONRPCServer["receive"]>;
+    /**
+     * Send a notification for subscriptions
+     * @param {SubscriptionsKeys} what
+     * @param {string} id
+     */
+    changed(what: SubscriptionsKeys, id: string): void;
     #private;
 }
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { McpEvents } from "./internal/internal.js";
 import type { Completion } from "./internal/internal.js";
+import type { ExtractURITemplateVariables } from "./internal/uri-template.js";
 import type { JSONRPCRequest } from "json-rpc-2.0";
 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";

package/src/index.js

@@ -1,7 +1,8 @@
 /**
  * @import { StandardSchemaV1 } from "@standard-schema/spec";
  * @import { JSONRPCRequest, JSONRPCParams } from "json-rpc-2.0";
- * @import { Tool, Completion, Prompt, Resource, ServerOptions, ServerInfo } from "./internal/internal.js";
+ * @import { ExtractURITemplateVariables } from "./internal/uri-template.js";
+ * @import { Tool, Completion, Prompt, Resource, ServerOptions, ServerInfo, SubscriptionsKeys, McpEvents } from "./internal/internal.js";
  */
 import { JSONRPCServer, JSONRPCClient } from 'json-rpc-2.0';
 import { UriTemplateMatcher } from 'uri-template-matcher';
@@ -30,23 +31,31 @@ export class McpServer {
 	#resources = new Map();
 	#templates = new UriTemplateMatcher();
 	/**
-	 * @type {{ [ref: string]: Map<string, Completion> }}
+	 * @type {{ [ref: string]: Map<string, Partial<Record<string, Completion>>> }}
 	 */
 	#completions = {
 		'ref/prompt': new Map(),
 		'ref/resource': new Map(),
 	};
+
+	#event_target = new EventTarget();
+
+	/**
+	 * @type {Record<SubscriptionsKeys, Set<string>>}
+	 */
+	#subscriptions = {
+		/**
+		 * @type {Set<string>}
+		 */
+		resource: new Set(),
+	};
+
 	/**
 	 * @param {ServerInfo} server_info
 	 * @param {ServerOptions<StandardSchema>} options
 	 */
 	constructor(server_info, options) {
 		this.#options = options;
-		if (options.send) {
-			this.#client = new JSONRPCClient((payload) => {
-				options.send?.(payload);
-			});
-		}
 		this.#server.addMethod('initialize', ({ protocolVersion }) => {
 			return {
 				protocolVersion,
@@ -66,6 +75,30 @@ export class McpServer {
 		this.#init_completion();
 	}
 
+	/**
+	 * @template {keyof McpEvents} TEvent
+	 * @param {TEvent} event
+	 * @param {McpEvents[TEvent]} callback
+	 * @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 }),
+				);
+			});
+		}
+
+		this.#event_target.addEventListener(
+			event,
+			(e) => {
+				callback(/** @type {CustomEvent} */ (e).detail);
+			},
+			options,
+		);
+	}
+
 	/**
 	 * @param {string} method
 	 * @param {JSONRPCParams} [params]
@@ -190,6 +223,14 @@ export class McpServer {
 	 */
 	#init_resources() {
 		if (!this.#options.capabilities?.resources) return;
+
+		if (this.#options.capabilities?.resources?.subscribe) {
+			this.#server.addMethod('resources/subscribe', async ({ uri }) => {
+				this.#subscriptions.resource.add(uri);
+				return {};
+			});
+		}
+
 		this.#server.addMethod('resources/list', async () => {
 			return {
 				resources: [...this.#resources].reduce(
@@ -237,7 +278,12 @@ export class McpServer {
 					throw new Error(`Resource ${uri} not found`);
 				}
 			}
-			return resource.execute(uri, params);
+			if (resource.template) {
+				if (!params)
+					throw new Error('Missing parameters for template resource');
+				return resource.execute(uri, params);
+			}
+			return resource.execute(uri);
 		});
 	}
 	/**
@@ -251,9 +297,11 @@ export class McpServer {
 				if (!completions) return null;
 				const complete = completions.get(ref.uri ?? ref.name);
 				if (!complete) return null;
+				const actual_complete = complete[argument.name];
+				if (!actual_complete) return null;
 				return {
 					completion: {
-						values: complete(argument, context),
+						values: actual_complete(argument.value, context),
 						hasMore: false,
 					},
 				};
@@ -277,7 +325,7 @@ export class McpServer {
 	}
 	/**
 	 * @template {StandardSchema | undefined} [TSchema=undefined]
-	 * @param {{ name: string; description: string; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never; complete?: Completion }} options
+	 * @param {{ name: string; description: string; schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never; complete?: TSchema extends undefined ? never : Partial<Record<keyof (StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>), Completion>> }} options
 	 * @param {TSchema extends undefined ? (()=>Promise<unknown> | unknown) : (input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<unknown> | unknown} execute
 	 */
 	prompt({ name, description, schema, complete }, execute) {
@@ -294,43 +342,48 @@ export class McpServer {
 		});
 	}
 	/**
-	 * @param {string} name
-	 * @param {string} description
-	 * @param {string} uri
-	 * @param {(uri: string, params?: unknown) => Promise<unknown> | unknown} execute
-	 * @param {Completion} [complete]
-	 * @param {boolean} [template=false]
+	 * @type {(resource: Resource & {complete?: Partial<Record<string,Completion>>, uri: string})=> void}
 	 */
-	#resource(name, description, uri, execute, complete, template = false) {
+	#resource({ uri, complete, ...resource }) {
 		if (complete) {
 			this.#completions['ref/resource'].set(uri, complete);
 		}
-		if (template) {
+		if (resource.template) {
 			this.#templates.add(uri);
 		}
 		if (this.#options.capabilities?.resources?.listChanged) {
 			this.#notify('notifications/resources/list_changed', {});
 		}
-		this.#resources.set(uri, {
-			description,
-			name,
-			execute,
-			template,
-		});
+		this.#resources.set(uri, resource);
 	}
 	/**
 	 * @param {{ name: string; description: string; uri: string }} options
-	 * @param {(uri: string, params?: unknown) => Promise<unknown> | unknown} execute
+	 * @param {(uri: string) => Promise<unknown> | unknown} execute
 	 */
 	resource({ name, description, uri }, execute) {
-		this.#resource(name, description, uri, execute, undefined, false);
+		this.#resource({
+			name,
+			description,
+			uri,
+			execute,
+			template: false,
+		});
 	}
 	/**
-	 * @param {{ name: string; description: string; uri: string; complete?: Completion }} options
-	 * @param {(uri: string, params?: unknown) => Promise<unknown> | unknown} execute
+	 * @template {string} TUri
+	 * @template {ExtractURITemplateVariables<TUri>} TVariables
+	 * @param {{ name: string; description: string; uri: TUri; complete?: TVariables extends never ? never : Partial<Record<TVariables, Completion>> }} options
+	 * @param {(uri: string, params: Record<TVariables, string | string[]>) => Promise<unknown> | unknown} execute
 	 */
 	template({ name, description, uri, complete }, execute) {
-		this.#resource(name, description, uri, execute, complete, true);
+		this.#resource({
+			name,
+			description,
+			uri,
+			execute,
+			complete,
+			template: true,
+		});
 	}
 	/**
 	 * @param {JSONRPCRequest} request
@@ -339,4 +392,20 @@ export class McpServer {
 	receive(request) {
 		return this.#server.receive(request);
 	}
+
+	/**
+	 * Send a notification for subscriptions
+	 * @param {SubscriptionsKeys} what
+	 * @param {string} id
+	 */
+	changed(what, id) {
+		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,
+			});
+		}
+	}
 }

package/src/internal/internal.d.ts

@@ -11,7 +11,7 @@ export type Tool<TSchema extends StandardSchemaV1 = StandardSchemaV1<any>> = {
 };
 
 export type Completion = (
-	argument: { name: string; value: string },
+	query: string,
 	context: { arguments: Record<string, string> },
 ) => string[];
 
@@ -23,19 +23,28 @@ export type Prompt<TSchema extends StandardSchemaV1 = StandardSchemaV1<any>> = {
 	) => Promise<unknown> | unknown;
 };
 
-export type Resource = {
-	description: string;
-	name: string;
-	template: boolean;
-	execute: (uri: string, params?: unknown) => Promise<unknown> | unknown;
-};
+export type Resource =
+	| {
+			description: string;
+			name: string;
+			template: true;
+			execute: (
+				uri: string,
+				params: Record<string, string | string[]>,
+			) => Promise<unknown> | unknown;
+	  }
+	| {
+			description: string;
+			name: string;
+			template: false;
+			execute: (uri: string) => Promise<unknown> | unknown;
+	  };
 
 export type ServerOptions<TSchema extends StandardSchemaV1> = {
-	send?: (payload: JSONRPCRequest) => void;
 	capabilities?: {
 		tools?: { listChanged?: boolean };
 		resources?: { listChanged?: boolean; subscribe?: boolean };
-		prompts?: { listChanged?: boolean; subscribe?: boolean };
+		prompts?: { listChanged?: boolean };
 	};
 	instructions?: string;
 	adapter: JsonSchemaAdapter<TSchema>;
@@ -46,3 +55,9 @@ export type ServerInfo = {
 	version: string;
 	description: string;
 };
+
+export type SubscriptionsKeys = 'resource';
+
+export type McpEvents = {
+	send: (message: JSONRPCRequest) => void;
+};

package/src/internal/uri-template.d.ts

@@ -0,0 +1,45 @@
+// Helper type to remove whitespace
+type Trim<S extends string> = S extends ` ${infer R}`
+	? Trim<R>
+	: S extends `${infer L} `
+		? Trim<L>
+		: S;
+
+// Helper type to extract variable name, removing modifiers
+type ExtractVarName<S extends string> = S extends `${infer Name}:${string}`
+	? Trim<Name> // Remove prefix modifier
+	: S extends `${infer Name}*`
+		? Trim<Name> // Remove explode modifier
+		: Trim<S>;
+
+// Helper type to split comma-separated variables
+type SplitVariables<S extends string> = S extends `${infer First},${infer Rest}`
+	? ExtractVarName<First> | SplitVariables<Rest>
+	: ExtractVarName<S>;
+
+// Helper type to extract content from braces and handle operators
+type ExtractFromExpression<S extends string> = S extends `+${infer Vars}`
+	? SplitVariables<Vars> // Reserved {+var}
+	: S extends `#${infer Vars}`
+		? SplitVariables<Vars> // Fragment {#var}
+		: S extends `.${infer Vars}`
+			? SplitVariables<Vars> // Label {.var}
+			: S extends `/${infer Vars}`
+				? SplitVariables<Vars> // Path {/var}
+				: S extends `;${infer Vars}`
+					? SplitVariables<Vars> // Path-style {;var}
+					: S extends `?${infer Vars}`
+						? SplitVariables<Vars> // Query {?var}
+						: S extends `&${infer Vars}`
+							? SplitVariables<Vars> // Query continuation {&var}
+							: SplitVariables<S>; // Simple {var}
+
+// Main recursive type to extract all variables from URI template
+type ExtractVariablesFromTemplate<S extends string> =
+	S extends `${string}{${infer Expression}}${infer Rest}`
+		? ExtractFromExpression<Expression> | ExtractVariablesFromTemplate<Rest>
+		: never;
+
+// Main exported type
+export type ExtractURITemplateVariables<T extends string> =
+	ExtractVariablesFromTemplate<T>;