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");
+ });
+});