tmcp 1.0.1 → 1.1.0

package/README.md

@@ -0,0 +1,277 @@
+# tmcp
+
+A lightweight, schema-agnostic Model Context Protocol (MCP) server implementation with unified API design.
+
+## Why tmcp?
+
+tmcp offers significant advantages over the official MCP SDK:
+
+- **🔄 Schema Agnostic**: Works with any validation library through adapters
+- **📦 No Weird Dependencies**: Minimal footprint with only essential dependencies (looking at you `express`)
+- **🎯 Unified API**: Consistent, intuitive interface across all MCP capabilities
+- **🔌 Extensible**: Easy to add support for new schema libraries
+- **⚡ Lightweight**: No bloat, just what you need
+
+## Supported Schema Libraries
+
+tmcp works with all major schema validation libraries through its adapter system:
+
+- **Zod** - `@tmcpkit/adapter-zod`
+- **Valibot** - `@tmcpkit/adapter-valibot`
+- **ArkType** - `@tmcpkit/adapter-arktype`
+- **Effect Schema** - `@tmcpkit/adapter-effect`
+- **Zod v3** - `@tmcpkit/adapter-zod-v3`
+
+## Installation
+
+```bash
+pnpm install tmcp
+# Choose your preferred schema library adapter
+ènpm install @tmcpkit/adapter-zod zod
+```
+
+## Quick Start
+
+```javascript
+import { McpServer } from 'tmcp';
+import { ZodJsonSchemaAdapter } from '@tmcpkit/adapter-zod';
+import { z } from 'zod';
+
+const adapter = new ZodJsonSchemaAdapter();
+const server = new McpServer(
+	{
+		name: 'my-server',
+		version: '1.0.0',
+		description: 'My awesome MCP server',
+	},
+	{
+		adapter,
+		capabilities: {
+			tools: { listChanged: true },
+			prompts: { listChanged: true },
+			resources: { listChanged: true },
+		},
+	},
+);
+
+// Define a tool with type-safe schema
+server.tool(
+	{
+		name: 'calculate',
+		description: 'Perform mathematical calculations',
+		schema: z.object({
+			operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+			a: z.number(),
+			b: z.number(),
+		}),
+	},
+	async ({ operation, a, b }) => {
+		switch (operation) {
+			case 'add':
+				return a + b;
+			case 'subtract':
+				return a - b;
+			case 'multiply':
+				return a * b;
+			case 'divide':
+				return a / b;
+		}
+	},
+);
+
+// Process incoming requests
+server.receive(request);
+```
+
+## API Reference
+
+### McpServer
+
+The main server class that handles MCP protocol communications.
+
+#### Constructor
+
+```javascript
+new McpServer(serverInfo, options);
+```
+
+- `serverInfo`: Server metadata (name, version, description)
+- `options`: Configuration object with adapter and capabilities
+
+#### Methods
+
+##### `tool(definition, handler)`
+
+Register a tool with optional schema validation.
+
+```javascript
+server.tool(
+	{
+		name: 'tool-name',
+		description: 'Tool description',
+		schema: yourSchema, // optional
+	},
+	async (input) => {
+		// Tool implementation
+		return result;
+	},
+);
+```
+
+##### `prompt(definition, handler)`
+
+Register a prompt template with optional schema validation.
+
+```javascript
+server.prompt(
+  {
+    name: 'prompt-name',
+    description: 'Prompt description',
+    schema: yourSchema, // optional
+    complete: (arg, context) => ['completion1', 'completion2'] // optional
+  },
+  async (input) => {
+    // Prompt implementation
+    return { messages: [...] };
+  }
+);
+```
+
+##### `resource(definition, handler)`
+
+Register a static resource.
+
+```javascript
+server.resource(
+  {
+    name: 'resource-name',
+    description: 'Resource description',
+    uri: 'file://path/to/resource'
+  },
+  async (uri, params) => {
+    // Resource implementation
+    return { contents: [...] };
+  }
+);
+```
+
+##### `template(definition, handler)`
+
+Register a URI template for dynamic resources.
+
+```javascript
+server.template(
+  {
+    name: 'template-name',
+    description: 'Template description',
+    uri: 'file://path/{id}/resource',
+    complete: (arg, context) => ['id1', 'id2'] // optional
+  },
+  async (uri, params) => {
+    // Template implementation using params.id
+    return { contents: [...] };
+  }
+);
+```
+
+##### `receive(request)`
+
+Process an incoming MCP request.
+
+```javascript
+const response = server.receive(jsonRpcRequest);
+```
+
+## Advanced Examples
+
+### 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 }) => `Hello ${name}`,
+);
+
+server.tool(
+	{
+		name: 'valibot-tool',
+		schema: v.object({ age: v.number() }),
+	},
+	async ({ age }) => `Age: ${age}`,
+);
+```
+
+### Resource Templates with Completion
+
+```javascript
+server.template(
+	{
+		name: 'user-profile',
+		description: 'Get user profile by ID',
+		uri: 'users/{userId}/profile',
+		complete: (arg, context) => {
+			// Provide completions for userId parameter
+			return ['user1', 'user2', 'user3'];
+		},
+	},
+	async (uri, params) => {
+		const user = await getUserById(params.userId);
+		return {
+			contents: [
+				{
+					uri,
+					mimeType: 'application/json',
+					text: JSON.stringify(user),
+				},
+			],
+		};
+	},
+);
+```
+
+### Complex Validation
+
+```javascript
+const complexSchema = z.object({
+	user: z.object({
+		name: z.string().min(1),
+		email: z.string().email(),
+		age: z.number().min(18).max(120),
+	}),
+	preferences: z
+		.object({
+			theme: z.enum(['light', 'dark']),
+			notifications: z.boolean(),
+		})
+		.optional(),
+	tags: z.array(z.string()).default([]),
+});
+
+server.tool(
+	{
+		name: 'create-user',
+		description: 'Create a new user with preferences',
+		schema: complexSchema,
+	},
+	async (input) => {
+		// Input is fully typed and validated
+		const { user, preferences, tags } = input;
+		return await createUser(user, preferences, tags);
+	},
+);
+```
+
+## Contributing
+
+Contributions are welcome! Please see our [contributing guidelines](../../CONTRIBUTING.md) for details.
+
+## License
+
+MIT © Paolo Ricciuti

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "The main tmcp library",
   "main": "src/index.js",
   "type": "module",
@@ -34,6 +34,7 @@
   "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"
+    "generate:types": "rm -f ./src/*.d.ts && tsc ./src/*.js --declaration --emitDeclarationOnly --target esnext --allowJs --moduleresolution nodenext --module nodenext && publint",
+    "prepublish": "pnpm generate:types"
   }
 }

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
@@ -52,11 +59,19 @@ export class McpServer<StandardSchema extends StandardSchemaV1> {
      * @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 { 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,7 @@
 /**
  * @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 { 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';
@@ -36,17 +36,25 @@ export class McpServer {
 		'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 +74,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 +222,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(
@@ -339,4 +379,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

@@ -31,11 +31,10 @@ export type Resource = {
 };
 
 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 +45,9 @@ export type ServerInfo = {
 	version: string;
 	description: string;
 };
+
+export type SubscriptionsKeys = 'resource';
+
+export type McpEvents = {
+	send: (message: JSONRPCRequest) => void;
+};