Merge pull request #631 from modelcontextprotocol/ihrpr/title

Add title to tools, resources, prompts

Author: ihrpr

README.md

@@ -54,22 +54,30 @@ import { z } from "zod";
 
 // Create an MCP server
 const server = new McpServer({
-  name: "Demo",
+  name: "demo-server",
   version: "1.0.0"
 });
 
 // Add an addition tool
-server.tool("add",
-  { a: z.number(), b: z.number() },
+server.registerTool("add",
+  {
+    title: "Addition Tool",
+    description: "Add two numbers",
+    inputSchema: { a: z.number(), b: z.number() }
+  },
   async ({ a, b }) => ({
     content: [{ type: "text", text: String(a + b) }]
   })
 );
 
 // Add a dynamic greeting resource
-server.resource(
+server.registerResource(
   "greeting",
   new ResourceTemplate("greeting://{name}", { list: undefined }),
+  { 
+    title: "Greeting Resource",      // Display name for UI
+    description: "Dynamic greeting generator"
+  },
   async (uri, { name }) => ({
     contents: [{
       uri: uri.href,
@@ -100,7 +108,7 @@ The McpServer is your core interface to the MCP protocol. It handles connection
 
 ```typescript
 const server = new McpServer({
-  name: "My App",
+  name: "my-app",
   version: "1.0.0"
 });
 ```
@@ -111,9 +119,14 @@ Resources are how you expose data to LLMs. They're similar to GET endpoints in a
 
 ```typescript
 // Static resource
-server.resource(
+server.registerResource(
   "config",
   "config://app",
+  {
+    title: "Application Config",
+    description: "Application configuration data",
+    mimeType: "text/plain"
+  },
   async (uri) => ({
     contents: [{
       uri: uri.href,
@@ -123,9 +136,13 @@ server.resource(
 );
 
 // Dynamic resource with parameters
-server.resource(
+server.registerResource(
   "user-profile",
   new ResourceTemplate("users://{userId}/profile", { list: undefined }),
+  {
+    title: "User Profile",
+    description: "User profile information"
+  },
   async (uri, { userId }) => ({
     contents: [{
       uri: uri.href,
@@ -141,11 +158,15 @@ Tools let LLMs take actions through your server. Unlike resources, tools are exp
 
 ```typescript
 // Simple tool with parameters
-server.tool(
+server.registerTool(
   "calculate-bmi",
   {
-    weightKg: z.number(),
-    heightM: z.number()
+    title: "BMI Calculator",
+    description: "Calculate Body Mass Index",
+    inputSchema: {
+      weightKg: z.number(),
+      heightM: z.number()
+    }
   },
   async ({ weightKg, heightM }) => ({
     content: [{
@@ -156,9 +177,13 @@ server.tool(
 );
 
 // Async tool with external API call
-server.tool(
+server.registerTool(
   "fetch-weather",
-  { city: z.string() },
+  {
+    title: "Weather Fetcher",
+    description: "Get weather data for a city",
+    inputSchema: { city: z.string() }
+  },
   async ({ city }) => {
     const response = await fetch(`https://api.weather.com/${city}`);
     const data = await response.text();
@@ -174,9 +199,13 @@ server.tool(
 Prompts are reusable templates that help LLMs interact with your server effectively:
 
 ```typescript
-server.prompt(
+server.registerPrompt(
   "review-code",
-  { code: z.string() },
+  {
+    title: "Code Review",
+    description: "Review code for best practices and potential issues",
+    arguments: { code: z.string() }
+  },
   ({ code }) => ({
     messages: [{
       role: "user",
@@ -189,6 +218,44 @@ server.prompt(
 );
 ```
 
+### Display Names and Metadata
+
+All resources, tools, and prompts support an optional `title` field for better UI presentation. The `title` is used as a display name, while `name` remains the unique identifier.
+
+**Note:** The `register*` methods (`registerTool`, `registerPrompt`, `registerResource`) are the recommended approach for new code. The older methods (`tool`, `prompt`, `resource`) remain available for backwards compatibility.
+
+#### Title Precedence for Tools
+
+For tools specifically, there are two ways to specify a title:
+- `title` field in the tool configuration
+- `annotations.title` field (when using the older `tool()` method with annotations)
+
+The precedence order is: `title` → `annotations.title` → `name`
+
+```typescript
+// Using registerTool (recommended)
+server.registerTool("my_tool", {
+  title: "My Tool",              // This title takes precedence
+  annotations: {
+    title: "Annotation Title"    // This is ignored if title is set
+  }
+}, handler);
+
+// Using tool with annotations (older API)
+server.tool("my_tool", "description", {
+  title: "Annotation Title"      // This is used as title
+}, handler);
+```
+
+When building clients, use the provided utility to get the appropriate display name:
+
+```typescript
+import { getDisplayName } from "@modelcontextprotocol/sdk/shared/metadataUtils.js";
+
+// Automatically handles the precedence: title → annotations.title → name
+const displayName = getDisplayName(tool);
+```
+
 ## Running Your Server
 
 MCP servers in TypeScript need to be connected to a transport to communicate with clients. How you start the server depends on the choice of transport:
@@ -401,13 +468,17 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { z } from "zod";
 
 const server = new McpServer({
-  name: "Echo",
+  name: "echo-server",
   version: "1.0.0"
 });
 
-server.resource(
+server.registerResource(
   "echo",
   new ResourceTemplate("echo://{message}", { list: undefined }),
+  {
+    title: "Echo Resource",
+    description: "Echoes back messages as resources"
+  },
   async (uri, { message }) => ({
     contents: [{
       uri: uri.href,
@@ -416,17 +487,25 @@ server.resource(
   })
 );
 
-server.tool(
+server.registerTool(
   "echo",
-  { message: z.string() },
+  {
+    title: "Echo Tool",
+    description: "Echoes back the provided message",
+    inputSchema: { message: z.string() }
+  },
   async ({ message }) => ({
     content: [{ type: "text", text: `Tool echo: ${message}` }]
   })
 );
 
-server.prompt(
+server.registerPrompt(
   "echo",
-  { message: z.string() },
+  {
+    title: "Echo Prompt",
+    description: "Creates a prompt to process a message",
+    argsSchema: { message: z.string() }
+  },
   ({ message }) => ({
     messages: [{
       role: "user",
@@ -450,7 +529,7 @@ import { promisify } from "util";
 import { z } from "zod";
 
 const server = new McpServer({
-  name: "SQLite Explorer",
+  name: "sqlite-explorer",
   version: "1.0.0"
 });
 
@@ -463,9 +542,14 @@ const getDb = () => {
   };
 };
 
-server.resource(
+server.registerResource(
   "schema",
   "schema://main",
+  {
+    title: "Database Schema",
+    description: "SQLite database schema",
+    mimeType: "text/plain"
+  },
   async (uri) => {
     const db = getDb();
     try {
@@ -484,9 +568,13 @@ server.resource(
   }
 );
 
-server.tool(
+server.registerTool(
   "query",
-  { sql: z.string() },
+  {
+    title: "SQL Query",
+    description: "Execute SQL queries on the database",
+    inputSchema: { sql: z.string() }
+  },
   async ({ sql }) => {
     const db = getDb();
     try {

src/examples/client/simpleStreamableHttp.ts

@@ -15,6 +15,7 @@ import {
   LoggingMessageNotificationSchema,
   ResourceListChangedNotificationSchema,
 } from '../../types.js';
+import { getDisplayName } from '../../shared/metadataUtils.js';
 
 // Create readline interface for user input
 const readline = createInterface({
@@ -317,7 +318,7 @@ async function listTools(): Promise<void> {
       console.log('  No tools available');
     } else {
       for (const tool of toolsResult.tools) {
-        console.log(`  - ${tool.name}: ${tool.description}`);
+        console.log(`  - id: ${tool.name}, name: ${getDisplayName(tool)}, description: ${tool.description}`);
       }
     }
   } catch (error) {
@@ -380,7 +381,7 @@ async function runNotificationsToolWithResumability(interval: number, count: num
   try {
     console.log(`Starting notification stream with resumability: interval=${interval}ms, count=${count || 'unlimited'}`);
     console.log(`Using resumption token: ${notificationsToolLastEventId || 'none'}`);
-    
+
     const request: CallToolRequest = {
       method: 'tools/call',
       params: {
@@ -393,7 +394,7 @@ async function runNotificationsToolWithResumability(interval: number, count: num
       notificationsToolLastEventId = event;
       console.log(`Updated resumption token: ${event}`);
     };
-    
+
     const result = await client.request(request, CallToolResultSchema, {
       resumptionToken: notificationsToolLastEventId,
       onresumptiontoken: onLastEventIdUpdate
@@ -429,7 +430,7 @@ async function listPrompts(): Promise<void> {
       console.log('  No prompts available');
     } else {
       for (const prompt of promptsResult.prompts) {
-        console.log(`  - ${prompt.name}: ${prompt.description}`);
+        console.log(`  - id: ${prompt.name}, name: ${getDisplayName(prompt)}, description: ${prompt.description}`);
       }
     }
   } catch (error) {
@@ -480,7 +481,7 @@ async function listResources(): Promise<void> {
       console.log('  No resources available');
     } else {
       for (const resource of resourcesResult.resources) {
-        console.log(`  - ${resource.name}: ${resource.uri}`);
+        console.log(`  - id: ${resource.name}, name: ${getDisplayName(resource)}, description: ${resource.uri}`);
       }
     }
   } catch (error) {

src/examples/server/simpleStreamableHttp.ts

@@ -17,15 +17,18 @@ const useOAuth = process.argv.includes('--oauth');
 const getServer = () => {
   const server = new McpServer({
     name: 'simple-streamable-http-server',
-    version: '1.0.0',
+    version: '1.0.0'
   }, { capabilities: { logging: {} } });
 
   // Register a simple tool that returns a greeting
-  server.tool(
+  server.registerTool(
     'greet',
-    'A simple greeting tool',
     {
-      name: z.string().describe('Name to greet'),
+      title: 'Greeting Tool',  // Display name for UI
+      description: 'A simple greeting tool',
+      inputSchema: {
+        name: z.string().describe('Name to greet'),
+      },
     },
     async ({ name }): Promise<CallToolResult> => {
       return {
@@ -84,12 +87,15 @@ const getServer = () => {
     }
   );
 
-  // Register a simple prompt
-  server.prompt(
+  // Register a simple prompt with title
+  server.registerPrompt(
     'greeting-template',
-    'A simple greeting prompt template',
     {
-      name: z.string().describe('Name to include in greeting'),
+      title: 'Greeting Template',  // Display name for UI
+      description: 'A simple greeting prompt template',
+      argsSchema: {
+        name: z.string().describe('Name to include in greeting'),
+      },
     },
     async ({ name }): Promise<GetPromptResult> => {
       return {
@@ -148,10 +154,14 @@ const getServer = () => {
   );
 
   // Create a simple resource at a fixed URI
-  server.resource(
+  server.registerResource(
     'greeting-resource',
     'https://example.com/greetings/default',
-    { mimeType: 'text/plain' },
+    {
+      title: 'Default Greeting',  // Display name for UI
+      description: 'A simple greeting resource',
+      mimeType: 'text/plain'
+    },
     async (): Promise<ReadResourceResult> => {
       return {
         contents: [