tmcp 1.0.0 → 1.0.1

package/package.json

@@ -1,13 +1,39 @@
 {
-	"name": "tmcp",
-	"version": "1.0.0",
-	"description": "",
-	"main": "index.js",
-	"scripts": {
-		"test": "echo \"Error: no test specified\" && exit 1"
-	},
-	"keywords": [],
-	"author": "Paolo Ricciuti",
-	"license": "MIT",
-	"type": "module"
-}
+  "name": "tmcp",
+  "version": "1.0.1",
+  "description": "The main tmcp library",
+  "main": "src/index.js",
+  "type": "module",
+  "keywords": [],
+  "author": "Paolo Ricciuti",
+  "license": "MIT",
+  "files": [
+    "src/"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./adapter": {
+      "types": "./src/adapter.d.ts",
+      "default": "./src/adapter.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "json-rpc-2.0": "^1.7.1",
+    "uri-template-matcher": "^1.1.0",
+    "valibot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@standard-schema/spec": "^1.0.0",
+    "@types/json-schema": "^7.0.15",
+    "publint": "^0.3.12"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "typecheck": "tsc --noEmit",
+    "generate:types": "rm -f ./src/*.d.ts && tsc ./src/*.js --declaration --emitDeclarationOnly --target esnext --allowJs --moduleresolution nodenext --module nodenext && publint"
+  }
+}

package/src/adapter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @import { StandardSchemaV1 } from "@standard-schema/spec";
+ * @import { JSONSchema7 } from "json-schema";
+ */
+/**
+ * @template {StandardSchemaV1} TSchema
+ */
+export class JsonSchemaAdapter<TSchema extends StandardSchemaV1> {
+    /**
+     * @param {TSchema} schema
+     * @returns {Promise<JSONSchema7>}
+     */
+    toJsonSchema(schema: TSchema): Promise<JSONSchema7>;
+}
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { JSONSchema7 } from "json-schema";

package/src/adapter.js

@@ -0,0 +1,19 @@
+/* eslint-disable no-unused-vars */
+
+/**
+ * @import { StandardSchemaV1 } from "@standard-schema/spec";
+ * @import { JSONSchema7 } from "json-schema";
+ */
+
+/**
+ * @template {StandardSchemaV1} TSchema
+ */
+export class JsonSchemaAdapter {
+	/**
+	 * @param {TSchema} schema
+	 * @returns {Promise<JSONSchema7>}
+	 */
+	toJsonSchema(schema) {
+		throw new Error('toJsonSchema method not implemented');
+	}
+}

package/src/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @template {StandardSchemaV1} StandardSchema
+ */
+export class McpServer<StandardSchema extends StandardSchemaV1> {
+    /**
+     * @param {ServerInfo} server_info
+     * @param {ServerOptions<StandardSchema>} options
+     */
+    constructor(server_info: ServerInfo, options: ServerOptions<StandardSchema>);
+    /**
+     * @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
+     * @param {TSchema extends undefined ? (()=>Promise<unknown> | unknown) : ((input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<unknown> | unknown)} execute
+     */
+    tool<TSchema extends StandardSchema | undefined = undefined>({ name, description, schema }: {
+        name: string;
+        description: string;
+        schema?: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema> extends Record<string, unknown> ? TSchema : never;
+    }, 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 {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;
+    }, 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
+     */
+    resource({ name, description, uri }: {
+        name: string;
+        description: string;
+        uri: string;
+    }, execute: (uri: string, params?: unknown) => Promise<unknown> | unknown): void;
+    /**
+     * @param {{ name: string; description: string; uri: string; complete?: Completion }} options
+     * @param {(uri: string, params?: unknown) => Promise<unknown> | unknown} execute
+     */
+    template({ name, description, uri, complete }: {
+        name: string;
+        description: string;
+        uri: string;
+        complete?: Completion;
+    }, execute: (uri: string, params?: unknown) => Promise<unknown> | unknown): void;
+    /**
+     * @param {JSONRPCRequest} request
+     * @returns {ReturnType<JSONRPCServer['receive']>}
+     */
+    receive(request: JSONRPCRequest): ReturnType<JSONRPCServer["receive"]>;
+    #private;
+}
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Completion } from "./internal/internal.js";
+import type { JSONRPCRequest } from "json-rpc-2.0";
+import { JSONRPCServer } from 'json-rpc-2.0';
+import type { ServerInfo } from "./internal/internal.js";
+import type { ServerOptions } from "./internal/internal.js";

package/src/index.js

@@ -0,0 +1,342 @@
+/**
+ * @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 { JSONRPCServer, JSONRPCClient } from 'json-rpc-2.0';
+import { UriTemplateMatcher } from 'uri-template-matcher';
+
+/**
+ * @template {StandardSchemaV1} StandardSchema
+ */
+export class McpServer {
+	#server = new JSONRPCServer();
+	/**
+	 * @type {JSONRPCClient | undefined}
+	 */
+	#client;
+	#options;
+	/**
+	 * @type {Map<string, Tool<any>>}
+	 */
+	#tools = new Map();
+	/**
+	 * @type {Map<string, Prompt<any>>}
+	 */
+	#prompts = new Map();
+	/**
+	 * @type {Map<string, Resource>}
+	 */
+	#resources = new Map();
+	#templates = new UriTemplateMatcher();
+	/**
+	 * @type {{ [ref: string]: Map<string, Completion> }}
+	 */
+	#completions = {
+		'ref/prompt': new Map(),
+		'ref/resource': new Map(),
+	};
+	/**
+	 * @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,
+				...options,
+				serverInfo: server_info,
+			};
+		});
+		this.#server.addMethod('ping', () => {
+			return {};
+		});
+		this.#server.addMethod('notifications/initialized', () => {
+			return null;
+		});
+		this.#init_tools();
+		this.#init_prompts();
+		this.#init_resources();
+		this.#init_completion();
+	}
+
+	/**
+	 * @param {string} method
+	 * @param {JSONRPCParams} [params]
+	 */
+	#notify(method, params) {
+		this.#client?.notify(method, params);
+	}
+
+	/**
+	 *
+	 */
+	#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.description,
+						description: tool.description,
+						inputSchema: tool.schema
+							? await this.#options.adapter.toJsonSchema(
+									tool.schema,
+								)
+							: { type: 'object', properties: {} },
+					};
+				}),
+			);
+			return {
+				tools: available_tools,
+			};
+		});
+		this.#server.addMethod(
+			'tools/call',
+			async ({ name, arguments: args }) => {
+				const tool = this.#tools.get(name);
+				if (!tool) {
+					throw new Error(`Tool ${name} not found`);
+				}
+				if (!tool.schema) {
+					return tool.execute();
+				}
+				let validated_args = tool.schema['~standard'].validate(args);
+				if (validated_args instanceof Promise)
+					validated_args = await validated_args;
+				if (validated_args.issues) {
+					throw new Error(
+						`Invalid arguments for tool ${name}: ${JSON.stringify(validated_args.issues)}`,
+					);
+				}
+				return tool.execute(validated_args.value);
+			},
+		);
+	}
+	/**
+	 *
+	 */
+	#init_prompts() {
+		if (!this.#options.capabilities?.prompts) return;
+		this.#server.addMethod('prompts/list', async () => {
+			const available_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.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,
+							};
+						}),
+					};
+				}),
+			);
+			return {
+				prompts: available_prompts,
+			};
+		});
+		this.#server.addMethod(
+			'prompts/get',
+			async ({ name, arguments: args }) => {
+				const prompt = this.#prompts.get(name);
+				if (!prompt) {
+					throw new Error(`Tool ${name} not found`);
+				}
+				if (!prompt.schema) {
+					return prompt.execute();
+				}
+				let validated_args = prompt.schema['~standard'].validate(args);
+				if (validated_args instanceof Promise)
+					validated_args = await validated_args;
+				if (validated_args.issues) {
+					throw new Error(
+						`Invalid arguments for tool ${name}: ${JSON.stringify(validated_args.issues)}`,
+					);
+				}
+				return prompt.execute(validated_args.value);
+			},
+		);
+	}
+	/**
+	 *
+	 */
+	#init_resources() {
+		if (!this.#options.capabilities?.resources) return;
+		this.#server.addMethod('resources/list', async () => {
+			return {
+				resources: [...this.#resources].reduce(
+					(arr, [uri, { description, name, template }]) => {
+						if (!template) {
+							arr.push({
+								name,
+								description,
+								uri,
+							});
+						}
+						return arr;
+					},
+					/** @type {Array<{name: string, description: string, uri: string}>} */ ([]),
+				),
+			};
+		});
+		this.#server.addMethod('resources/templates/list', async () => {
+			return {
+				resourceTemplates: [...this.#resources].reduce(
+					(arr, [uri, { description, name, template }]) => {
+						if (template) {
+							arr.push({
+								name,
+								description,
+								uriTemplate: uri,
+							});
+						}
+						return arr;
+					},
+					/** @type {Array<{name: string, description: string, uriTemplate: string}>} */ ([]),
+				),
+			};
+		});
+		this.#server.addMethod('resources/read', async ({ uri }) => {
+			let resource = this.#resources.get(uri);
+			let params;
+			if (!resource) {
+				const match = this.#templates.match(uri);
+				if (match) {
+					resource = this.#resources.get(match.template);
+					params = match.params;
+				}
+				if (!resource) {
+					throw new Error(`Resource ${uri} not found`);
+				}
+			}
+			return resource.execute(uri, params);
+		});
+	}
+	/**
+	 *
+	 */
+	#init_completion() {
+		this.#server.addMethod(
+			'completion/complete',
+			({ argument, ref, context }) => {
+				const completions = this.#completions[ref.type];
+				if (!completions) return null;
+				const complete = completions.get(ref.uri ?? ref.name);
+				if (!complete) return null;
+				return {
+					completion: {
+						values: complete(argument, context),
+						hasMore: false,
+					},
+				};
+			},
+		);
+	}
+	/**
+	 * @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
+	 * @param {TSchema extends undefined ? (()=>Promise<unknown> | unknown) : ((input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<unknown> | unknown)} execute
+	 */
+	tool({ name, description, schema }, execute) {
+		if (this.#options.capabilities?.tools?.listChanged) {
+			this.#notify('notifications/tools/list_changed', {});
+		}
+		this.#tools.set(name, {
+			description,
+			schema,
+			execute,
+		});
+	}
+	/**
+	 * @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 {TSchema extends undefined ? (()=>Promise<unknown> | unknown) : (input: StandardSchemaV1.InferInput<TSchema extends undefined ? never : TSchema>) => Promise<unknown> | unknown} execute
+	 */
+	prompt({ name, description, schema, complete }, execute) {
+		if (complete) {
+			this.#completions['ref/prompt'].set(name, complete);
+		}
+		if (this.#options.capabilities?.prompts?.listChanged) {
+			this.#notify('notifications/prompts/list_changed', {});
+		}
+		this.#prompts.set(name, {
+			description,
+			schema,
+			execute,
+		});
+	}
+	/**
+	 * @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]
+	 */
+	#resource(name, description, uri, execute, complete, template = false) {
+		if (complete) {
+			this.#completions['ref/resource'].set(uri, complete);
+		}
+		if (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,
+		});
+	}
+	/**
+	 * @param {{ name: string; description: string; uri: string }} options
+	 * @param {(uri: string, params?: unknown) => Promise<unknown> | unknown} execute
+	 */
+	resource({ name, description, uri }, execute) {
+		this.#resource(name, description, uri, execute, undefined, false);
+	}
+	/**
+	 * @param {{ name: string; description: string; uri: string; complete?: Completion }} options
+	 * @param {(uri: string, params?: unknown) => Promise<unknown> | unknown} execute
+	 */
+	template({ name, description, uri, complete }, execute) {
+		this.#resource(name, description, uri, execute, complete, true);
+	}
+	/**
+	 * @param {JSONRPCRequest} request
+	 * @returns {ReturnType<JSONRPCServer['receive']>}
+	 */
+	receive(request) {
+		return this.#server.receive(request);
+	}
+}

package/src/internal/internal.d.ts

@@ -0,0 +1,48 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { JSONRPCRequest } from 'json-rpc-2.0';
+import { JsonSchemaAdapter } from '../adapter.js';
+
+export type Tool<TSchema extends StandardSchemaV1 = StandardSchemaV1<any>> = {
+	description: string;
+	schema: TSchema;
+	execute: (
+		input?: StandardSchemaV1.InferInput<TSchema>,
+	) => Promise<unknown> | unknown;
+};
+
+export type Completion = (
+	argument: { name: string; value: string },
+	context: { arguments: Record<string, string> },
+) => string[];
+
+export type Prompt<TSchema extends StandardSchemaV1 = StandardSchemaV1<any>> = {
+	description: string;
+	schema: TSchema;
+	execute: (
+		input?: StandardSchemaV1.InferInput<TSchema>,
+	) => Promise<unknown> | unknown;
+};
+
+export type Resource = {
+	description: string;
+	name: string;
+	template: boolean;
+	execute: (uri: string, params?: unknown) => 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 };
+	};
+	instructions?: string;
+	adapter: JsonSchemaAdapter<TSchema>;
+};
+
+export type ServerInfo = {
+	name: string;
+	version: string;
+	description: string;
+};

package/.claude/settings.local.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "mcp__npm__search_npm"
-    ],
-    "deny": []
-  }
-}