tmcp 1.4.0 → 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paolo Ricciuti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -19,25 +19,25 @@ tmcp offers significant advantages over the official MCP SDK:
 
 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`
+- **Zod** - `@tmcp/adapter-zod`
+- **Valibot** - `@tmcp/adapter-valibot`
+- **ArkType** - `@tmcp/adapter-arktype`
+- **Effect Schema** - `@tmcp/adapter-effect`
+- **Zod v3** - `@tmcp/adapter-zod-v3`
 
 ## Installation
 
 ```bash
 pnpm install tmcp
 # Choose your preferred schema library adapter
-ènpm install @tmcpkit/adapter-zod zod
+pnpm install @tmcp/adapter-zod zod
 ```
 
 ## Quick Start
 
 ```javascript
 import { McpServer } from 'tmcp';
-import { ZodJsonSchemaAdapter } from '@tmcpkit/adapter-zod';
+import { ZodJsonSchemaAdapter } from '@tmcp/adapter-zod';
 import { z } from 'zod';
 
 const adapter = new ZodJsonSchemaAdapter();
@@ -71,13 +71,21 @@ server.tool(
 	async ({ operation, a, b }) => {
 		switch (operation) {
 			case 'add':
-				return a + b;
+				return {
+					content: [{ type: 'text', text: `${a} + ${b} = ${a + b}` }],
+				};
 			case 'subtract':
-				return a - b;
+				return {
+					content: [{ type: 'text', text: `${a} - ${b} = ${a - b}` }],
+				};
 			case 'multiply':
-				return a * b;
+				return {
+					content: [{ type: 'text', text: `${a} × ${b} = ${a * b}` }],
+				};
 			case 'divide':
-				return a / b;
+				return {
+					content: [{ type: 'text', text: `${a} ÷ ${b} = ${a / b}` }],
+				};
 		}
 	},
 );
@@ -116,7 +124,7 @@ server.tool(
 	},
 	async (input) => {
 		// Tool implementation
-		return result;
+		return { content: [{ type: 'text', text: 'Tool result' }] };
 	},
 );
 ```
@@ -131,7 +139,15 @@ server.prompt(
     name: 'prompt-name',
     description: 'Prompt description',
     schema: yourSchema, // optional
-    complete: (arg, context) => ['completion1', 'completion2'] // optional
+    complete: {
+      paramName: (arg, context) => ({
+        completion: {
+          values: ['completion1', 'completion2'],
+          total: 2,
+          hasMore: false
+        }
+      })
+    } // optional
   },
   async (input) => {
     // Prompt implementation
@@ -168,7 +184,15 @@ server.template(
     name: 'template-name',
     description: 'Template description',
     uri: 'file://path/{id}/resource',
-    complete: (arg, context) => ['id1', 'id2'] // optional
+    complete: {
+      id: (arg, context) => ({
+        completion: {
+          values: ['id1', 'id2', 'id3'],
+          total: 3,
+          hasMore: false
+        }
+      })
+    } // optional
   },
   async (uri, params) => {
     // Template implementation using params.id
@@ -177,16 +201,138 @@ server.template(
 );
 ```
 
-##### `receive(request)`
+##### `receive(request, sessionId)`
 
 Process an incoming MCP request.
 
 ```javascript
-const response = server.receive(jsonRpcRequest);
+const response = server.receive(jsonRpcRequest, sessionId);
+```
+
+##### `elicitation(schema)`
+
+Request client elicitation with schema validation.
+
+```javascript
+const result = await server.elicitation(schema);
+```
+
+##### `message(request)`
+
+Request language model sampling from the client.
+
+```javascript
+const result = await server.message({
+	messages: [
+		{
+			role: 'user',
+			content: { type: 'text', text: 'Hello!' },
+		},
+	],
+});
+```
+
+##### `refreshRoots()`
+
+Refresh the roots list from the client.
+
+```javascript
+await server.refreshRoots();
+console.log(server.roots); // Access current roots
+```
+
+##### `changed(type, id)`
+
+Send notifications for subscriptions.
+
+```javascript
+server.changed('resource', 'file://path/to/resource');
+```
+
+##### `on(event, callback)`
+
+Listen to server events.
+
+```javascript
+server.on('initialize', (data) => {
+	console.log('Client initialized:', data);
+});
+
+server.on('send', ({ request, context }) => {
+	console.log('Sending request:', request);
+});
 ```
 
 ## Advanced Examples
 
+### Client Interaction Features
+
+```javascript
+// Elicitation - Request structured data from client
+const userData = await server.elicitation(
+	z.object({
+		name: z.string(),
+		age: z.number(),
+		preferences: z.array(z.string()),
+	}),
+);
+
+// Message sampling - Request AI responses
+const aiResponse = await server.message({
+	messages: [
+		{
+			role: 'user',
+			content: { type: 'text', text: 'Explain quantum computing' },
+		},
+	],
+	maxTokens: 100,
+});
+
+// Roots management - Access client's filesystem roots
+await server.refreshRoots();
+console.log('Available roots:', server.roots);
+```
+
+### Event Handling
+
+```javascript
+// Listen to server events
+server.on('initialize', (data) => {
+	console.log('Client capabilities:', data.capabilities);
+});
+
+server.on('send', ({ request, context }) => {
+	console.log('Outgoing request:', request.method);
+});
+```
+
+### Resource Subscriptions
+
+```javascript
+// Subscribe to resource changes
+server.resource(
+	{
+		name: 'file-watcher',
+		description: 'Watch file changes',
+		uri: 'file://watched/file.txt',
+	},
+	async (uri) => {
+		return {
+			contents: [
+				{
+					uri,
+					mimeType: 'text/plain',
+					text: await readFile(uri),
+				},
+			],
+		};
+	},
+);
+
+// Notify subscribers when resource changes
+server.changed('resource', 'file://watched/file.txt');
+```
+
 ### Multiple Schema Libraries
 
 ```javascript
@@ -199,7 +345,9 @@ server.tool(
 		name: 'zod-tool',
 		schema: z.object({ name: z.string() }),
 	},
-	async ({ name }) => `Hello ${name}`,
+	async ({ name }) => ({
+		content: [{ type: 'text', text: `Hello ${name}` }],
+	}),
 );
 
 server.tool(
@@ -207,11 +355,114 @@ server.tool(
 		name: 'valibot-tool',
 		schema: v.object({ age: v.number() }),
 	},
-	async ({ age }) => `Age: ${age}`,
+	async ({ age }) => ({
+		content: [{ type: 'text', text: `Age: ${age}` }],
+	}),
 );
 ```
 
-### Resource Templates with Completion
+### 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.
+
+#### Completion Response Format
+
+```javascript
+{
+  completion: {
+    values: string[],      // Array of completion values (max 100 items)
+    total?: number,        // Total number of available completions
+    hasMore?: boolean      // Whether there are more completions available
+  }
+}
+```
+
+#### Prompt Parameter Completion
+
+```javascript
+server.prompt(
+	{
+		name: 'story-generator',
+		description: 'Generate a story with specific parameters',
+		schema: z.object({
+			genre: z.string(),
+			length: z.enum(['short', 'medium', 'long']),
+			character: z.string(),
+		}),
+		complete: {
+			genre: (arg, context) => {
+				const genres = [
+					'fantasy',
+					'sci-fi',
+					'mystery',
+					'romance',
+					'thriller',
+				];
+				const filtered = genres.filter((g) =>
+					g.startsWith(arg.toLowerCase()),
+				);
+
+				return {
+					completion: {
+						values: filtered,
+						total: filtered.length,
+						hasMore: false,
+					},
+				};
+			},
+			length: (arg, context) => {
+				const lengths = ['short', 'medium', 'long'];
+				const filtered = lengths.filter((l) => l.includes(arg));
+
+				return {
+					completion: {
+						values: filtered,
+						total: filtered.length,
+						hasMore: false,
+					},
+				};
+			},
+			character: (arg, context) => {
+				// Dynamic completion based on genre
+				const characters = {
+					fantasy: ['wizard', 'dragon', 'knight', 'elf'],
+					'sci-fi': ['robot', 'alien', 'cyborg', 'space-explorer'],
+					mystery: ['detective', 'suspect', 'witness', 'victim'],
+					default: ['hero', 'villain', 'sidekick', 'mentor'],
+				};
+
+				const genre = context.params?.genre || 'default';
+				const charList = characters[genre] || characters.default;
+				const filtered = charList.filter((c) => c.includes(arg));
+
+				return {
+					completion: {
+						values: filtered,
+						total: filtered.length,
+						hasMore: false,
+					},
+				};
+			},
+		},
+	},
+	async (input) => {
+		return {
+			description: `A ${input.length} ${input.genre} story featuring a ${input.character}`,
+			messages: [
+				{
+					role: 'user',
+					content: {
+						type: 'text',
+						text: `Write a ${input.length} ${input.genre} story featuring a ${input.character}.`,
+					},
+				},
+			],
+		};
+	},
+);
+```
+
+#### Resource Template Completion
 
 ```javascript
 server.template(
@@ -219,9 +470,20 @@ 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'];
+		complete: {
+			userId: (arg, context) => {
+				// Filter users based on the current input
+				const allUsers = ['user1', 'user2', 'user3', 'admin-user'];
+				const filtered = allUsers.filter((id) => id.includes(arg));
+
+				return {
+					completion: {
+						values: filtered.slice(0, 10), // Limit to 10 results
+						total: filtered.length,
+						hasMore: filtered.length > 10,
+					},
+				};
+			},
 		},
 	},
 	async (uri, params) => {
@@ -239,6 +501,118 @@ server.template(
 );
 ```
 
+#### Advanced Completion Examples
+
+```javascript
+// Completion with async data fetching
+server.template(
+	{
+		name: 'project-files',
+		description: 'Access project files by path',
+		uri: 'projects/{projectId}/files/{filePath}',
+		complete: {
+			projectId: (arg, context) => {
+				// Static list of project IDs
+				const projects = ['web-app', 'mobile-app', 'api-server'];
+				const filtered = projects.filter((p) => p.includes(arg));
+
+				return {
+					completion: {
+						values: filtered,
+						total: filtered.length,
+						hasMore: false,
+					},
+				};
+			},
+			filePath: async (arg, context) => {
+				// Dynamic file path completion based on project
+				const projectId = context.params?.projectId;
+				if (!projectId) {
+					return {
+						completion: {
+							values: [],
+							total: 0,
+							hasMore: false,
+						},
+					};
+				}
+
+				// Simulate fetching files from filesystem
+				const files = await getProjectFiles(projectId);
+				const filtered = files.filter((f) => f.includes(arg));
+
+				return {
+					completion: {
+						values: filtered.slice(0, 20),
+						total: filtered.length,
+						hasMore: filtered.length > 20,
+					},
+				};
+			},
+		},
+	},
+	async (uri, params) => {
+		const content = await readProjectFile(
+			params.projectId,
+			params.filePath,
+		);
+		return {
+			contents: [
+				{
+					uri,
+					mimeType: 'text/plain',
+					text: content,
+				},
+			],
+		};
+	},
+);
+
+// Completion with pagination support
+server.prompt(
+	{
+		name: 'search-documents',
+		description: 'Search through large document collection',
+		schema: z.object({
+			query: z.string(),
+			category: z.string(),
+		}),
+		complete: {
+			category: (arg, context) => {
+				// Large category list with pagination
+				const allCategories = generateCategoryList(); // Assume this returns 500+ items
+				const filtered = allCategories.filter((c) =>
+					c.toLowerCase().includes(arg.toLowerCase()),
+				);
+
+				return {
+					completion: {
+						values: filtered.slice(0, 50), // Show first 50 matches
+						total: filtered.length,
+						hasMore: filtered.length > 50,
+					},
+				};
+			},
+		},
+	},
+	async (input) => {
+		const results = await searchDocuments(input.query, input.category);
+		return {
+			description: `Search results for "${input.query}" in ${input.category}`,
+			messages: [
+				{
+					role: 'user',
+					content: {
+						type: 'text',
+						text: `Found ${results.length} documents matching "${input.query}"`,
+					},
+				},
+			],
+		};
+	},
+);
+```
+
 ### Complex Validation
 
 ```javascript
@@ -266,7 +640,15 @@ server.tool(
 	async (input) => {
 		// Input is fully typed and validated
 		const { user, preferences, tags } = input;
-		return await createUser(user, preferences, tags);
+		const result = await createUser(user, preferences, tags);
+		return {
+			content: [
+				{
+					type: 'text',
+					text: `User created: ${user.name} (${user.email})`,
+				},
+			],
+		};
 	},
 );
 ```
@@ -275,6 +657,10 @@ server.tool(
 
 Contributions are welcome! Please see our [contributing guidelines](../../CONTRIBUTING.md) for details.
 
+## Acknowledgments
+
+Huge thanks to Sean O'Bannon that provided us with the `@tmcp` scope on npm.
+
 ## License
 
 MIT © Paolo Ricciuti

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmcp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "The main tmcp library",
   "main": "src/index.js",
   "type": "module",
@@ -28,6 +28,7 @@
   },
   "dependencies": {
     "json-rpc-2.0": "^1.7.1",
+    "sqids": "^0.3.0",
     "uri-template-matcher": "^1.1.0",
     "valibot": "^1.1.0"
   },