Merge branch 'main' into ihrpr/resource-link

Author: ihrpr

README.md

@@ -55,8 +55,7 @@ import { z } from "zod";
 // Create an MCP server
 const server = new McpServer({
   name: "demo-server",
-  version: "1.0.0",
-  title: "Demo Server"  // Optional display name
+  version: "1.0.0"
 });
 
 // Add an addition tool
@@ -79,10 +78,10 @@ server.registerResource(
     title: "Greeting Resource",      // Display name for UI
     description: "Dynamic greeting generator"
   },
-  async (uri, params) => ({
+  async (uri, { name }) => ({
     contents: [{
       uri: uri.href,
-      text: `Hello, ${params.name}!`
+      text: `Hello, ${name}!`
     }]
   })
 );
@@ -109,9 +108,8 @@ The McpServer is your core interface to the MCP protocol. It handles connection
 
 ```typescript
 const server = new McpServer({
-  name: "my-app",              // Unique identifier for your server
-  version: "1.0.0",            // Server version
-  title: "My Application"      // Optional display name for UI
+  name: "my-app",
+  version: "1.0.0"
 });
 ```
 
@@ -145,10 +143,10 @@ server.registerResource(
     title: "User Profile",
     description: "User profile information"
   },
-  async (uri, params) => ({
+  async (uri, { userId }) => ({
     contents: [{
       uri: uri.href,
-      text: `Profile data for user ${params.userId}`
+      text: `Profile data for user ${userId}`
     }]
   })
 );
@@ -258,14 +256,36 @@ All resources, tools, and prompts support an optional `title` field for better U
 
 **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";
 
-// Falls back to 'name' if 'title' is not provided
-const displayName = getDisplayName(tool);  // Returns title if available, otherwise name
+// Automatically handles the precedence: title → annotations.title → name
+const displayName = getDisplayName(tool);
 ```
 
 ## Running Your Server
@@ -481,8 +501,7 @@ import { z } from "zod";
 
 const server = new McpServer({
   name: "echo-server",
-  version: "1.0.0",
-  title: "Echo Server"
+  version: "1.0.0"
 });
 
 server.registerResource(
@@ -492,10 +511,10 @@ server.registerResource(
     title: "Echo Resource",
     description: "Echoes back messages as resources"
   },
-  async (uri, params) => ({
+  async (uri, { message }) => ({
     contents: [{
       uri: uri.href,
-      text: `Resource echo: ${params.message}`
+      text: `Resource echo: ${message}`
     }]
   })
 );
@@ -517,7 +536,7 @@ server.registerPrompt(
   {
     title: "Echo Prompt",
     description: "Creates a prompt to process a message",
-    arguments: { message: z.string() }
+    argsSchema: { message: z.string() }
   },
   ({ message }) => ({
     messages: [{
@@ -543,8 +562,7 @@ import { z } from "zod";
 
 const server = new McpServer({
   name: "sqlite-explorer",
-  version: "1.0.0",
-  title: "SQLite Explorer"
+  version: "1.0.0"
 });
 
 // Helper to create DB connection

src/examples/client/simpleStreamableHttp.ts

@@ -330,7 +330,7 @@ async function listTools(): Promise<void> {
       console.log('  No tools available');
     } else {
       for (const tool of toolsResult.tools) {
-        console.log(`  - ${getDisplayName(tool)}: ${tool.description}`);
+        console.log(`  - id: ${tool.name}, name: ${getDisplayName(tool)}, description: ${tool.description}`);
       }
     }
   } catch (error) {
@@ -417,7 +417,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: {
@@ -430,7 +430,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
@@ -466,7 +466,7 @@ async function listPrompts(): Promise<void> {
       console.log('  No prompts available');
     } else {
       for (const prompt of promptsResult.prompts) {
-        console.log(`  - ${getDisplayName(prompt)}: ${prompt.description}`);
+        console.log(`  - id: ${prompt.name}, name: ${getDisplayName(prompt)}, description: ${prompt.description}`);
       }
     }
   } catch (error) {
@@ -517,7 +517,7 @@ async function listResources(): Promise<void> {
       console.log('  No resources available');
     } else {
       for (const resource of resourcesResult.resources) {
-        console.log(`  - ${getDisplayName(resource)}: ${resource.uri}`);
+        console.log(`  - id: ${resource.name}, name: ${getDisplayName(resource)}, description: ${resource.uri}`);
       }
     }
   } catch (error) {

src/examples/server/simpleStreamableHttp.ts

@@ -17,8 +17,7 @@ const useOAuth = process.argv.includes('--oauth');
 const getServer = () => {
   const server = new McpServer({
     name: 'simple-streamable-http-server',
-    version: '1.0.0',
-    title: 'Simple Streamable HTTP Server',  // Display name for UI
+    version: '1.0.0'
   }, { capabilities: { logging: {} } });
 
   // Register a simple tool that returns a greeting
@@ -94,7 +93,7 @@ const getServer = () => {
     {
       title: 'Greeting Template',  // Display name for UI
       description: 'A simple greeting prompt template',
-      arguments: {
+      argsSchema: {
         name: z.string().describe('Name to include in greeting'),
       },
     },
@@ -158,10 +157,10 @@ const getServer = () => {
   server.registerResource(
     'greeting-resource',
     'https://example.com/greetings/default',
-    { 
+    {
       title: 'Default Greeting',  // Display name for UI
       description: 'A simple greeting resource',
-      mimeType: 'text/plain' 
+      mimeType: 'text/plain'
     },
     async (): Promise<ReadResourceResult> => {
       return {

src/server/mcp.test.ts

@@ -18,6 +18,7 @@ import {
 import { ResourceTemplate } from "./mcp.js";
 import { completable } from "./completable.js";
 import { UriTemplate } from "../shared/uriTemplate.js";
+import { getDisplayName } from "../shared/metadataUtils.js";
 
 describe("McpServer", () => {
   /***
@@ -3598,3 +3599,140 @@ describe("prompt()", () => {
     expect(result.resources[0].mimeType).toBe("text/markdown");
   });
 });
+
+describe("Tool title precedence", () => {
+  test("should follow correct title precedence: title → annotations.title → name", async () => {
+    const mcpServer = new McpServer({
+      name: "test server",
+      version: "1.0",
+    });
+    const client = new Client({
+      name: "test client",
+      version: "1.0",
+    });
+
+    // Tool 1: Only name
+    mcpServer.tool(
+      "tool_name_only",
+      async () => ({
+        content: [{ type: "text", text: "Response" }],
+      })
+    );
+
+    // Tool 2: Name and annotations.title
+    mcpServer.tool(
+      "tool_with_annotations_title",
+      "Tool with annotations title",
+      {
+        title: "Annotations Title"
+      },
+      async () => ({
+        content: [{ type: "text", text: "Response" }],
+      })
+    );
+
+    // Tool 3: Name and title (using registerTool)
+    mcpServer.registerTool(
+      "tool_with_title",
+      {
+        title: "Regular Title",
+        description: "Tool with regular title"
+      },
+      async () => ({
+        content: [{ type: "text", text: "Response" }],
+      })
+    );
+
+    // Tool 4: All three - title should win
+    mcpServer.registerTool(
+      "tool_with_all_titles",
+      {
+        title: "Regular Title Wins",
+        description: "Tool with all titles",
+        annotations: {
+          title: "Annotations Title Should Not Show"
+        }
+      },
+      async () => ({
+        content: [{ type: "text", text: "Response" }],
+      })
+    );
+
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await Promise.all([
+      client.connect(clientTransport),
+      mcpServer.connect(serverTransport),
+    ]);
+
+    const result = await client.request(
+      { method: "tools/list" },
+      ListToolsResultSchema,
+    );
+
+
+    expect(result.tools).toHaveLength(4);
+
+    // Tool 1: Only name - should display name
+    const tool1 = result.tools.find(t => t.name === "tool_name_only");
+    expect(tool1).toBeDefined();
+    expect(getDisplayName(tool1!)).toBe("tool_name_only");
+
+    // Tool 2: Name and annotations.title - should display annotations.title
+    const tool2 = result.tools.find(t => t.name === "tool_with_annotations_title");
+    expect(tool2).toBeDefined();
+    expect(tool2!.annotations?.title).toBe("Annotations Title");
+    expect(getDisplayName(tool2!)).toBe("Annotations Title");
+
+    // Tool 3: Name and title - should display title
+    const tool3 = result.tools.find(t => t.name === "tool_with_title");
+    expect(tool3).toBeDefined();
+    expect(tool3!.title).toBe("Regular Title");
+    expect(getDisplayName(tool3!)).toBe("Regular Title");
+
+    // Tool 4: All three - title should take precedence
+    const tool4 = result.tools.find(t => t.name === "tool_with_all_titles");
+    expect(tool4).toBeDefined();
+    expect(tool4!.title).toBe("Regular Title Wins");
+    expect(tool4!.annotations?.title).toBe("Annotations Title Should Not Show");
+    expect(getDisplayName(tool4!)).toBe("Regular Title Wins");
+  });
+
+  test("getDisplayName unit tests for title precedence", () => {
+    
+    // Test 1: Only name
+    expect(getDisplayName({ name: "tool_name" })).toBe("tool_name");
+    
+    // Test 2: Name and title - title wins
+    expect(getDisplayName({ 
+      name: "tool_name", 
+      title: "Tool Title" 
+    })).toBe("Tool Title");
+    
+    // Test 3: Name and annotations.title - annotations.title wins
+    expect(getDisplayName({ 
+      name: "tool_name",
+      annotations: { title: "Annotations Title" }
+    })).toBe("Annotations Title");
+    
+    // Test 4: All three - title wins (correct precedence)
+    expect(getDisplayName({ 
+      name: "tool_name", 
+      title: "Regular Title",
+      annotations: { title: "Annotations Title" }
+    })).toBe("Regular Title");
+    
+    // Test 5: Empty title should not be used
+    expect(getDisplayName({ 
+      name: "tool_name", 
+      title: "",
+      annotations: { title: "Annotations Title" }
+    })).toBe("Annotations Title");
+    
+    // Test 6: Undefined vs null handling
+    expect(getDisplayName({ 
+      name: "tool_name", 
+      title: undefined,
+      annotations: { title: "Annotations Title" }
+    })).toBe("Annotations Title");
+  });
+});