Merge pull request #2272 from richardkmichael/add-structured-content-tool

[everything] Add structured content tool

Author: cliffhall

src/everything/README.md

@@ -27,24 +27,24 @@ This MCP server attempts to exercise all the features of the MCP protocol. It is
    - Returns: Completion message with duration and steps
    - Sends progress notifications during execution
 
-4. `sampleLLM`
+4. `printEnv`
+   - Prints all environment variables
+   - Useful for debugging MCP server configuration
+   - No inputs required
+   - Returns: JSON string of all environment variables
+
+5. `sampleLLM`
    - Demonstrates LLM sampling capability using MCP sampling feature
    - Inputs:
      - `prompt` (string): The prompt to send to the LLM
      - `maxTokens` (number, default: 100): Maximum tokens to generate
    - Returns: Generated LLM response
 
-5. `getTinyImage`
+6. `getTinyImage`
    - Returns a small test image
    - No inputs required
    - Returns: Base64 encoded PNG image data
 
-6. `printEnv`
-   - Prints all environment variables
-   - Useful for debugging MCP server configuration
-   - No inputs required
-   - Returns: JSON string of all environment variables
-
 7. `annotatedMessage`
    - Demonstrates how annotations can be used to provide metadata about content
    - Inputs:
@@ -80,6 +80,15 @@ This MCP server attempts to exercise all the features of the MCP protocol. It is
       - `pets` (enum): Favorite pet
    - Returns: Confirmation of the elicitation demo with selection summary.
 
+10. `structuredContent`
+   - Demonstrates a tool returning structured content using the example in the specification
+   - Provides an output schema to allow testing of client SHOULD advisory to validate the result using the schema
+   - Inputs:
+     - `location` (string): A location or ZIP code, mock data is returned regardless of value
+   - Returns: a response with
+     - `structuredContent` field conformant to the output schema
+     - A backward compatible Text Content field, a SHOULD advisory in the specification
+
 ### Resources
 
 The server provides 100 test resources in two formats:

src/everything/everything.ts

@@ -31,6 +31,9 @@ const instructions = readFileSync(join(__dirname, "instructions.md"), "utf-8");
 const ToolInputSchema = ToolSchema.shape.inputSchema;
 type ToolInput = z.infer<typeof ToolInputSchema>;
 
+const ToolOutputSchema = ToolSchema.shape.outputSchema;
+type ToolOutput = z.infer<typeof ToolOutputSchema>;
+
 /* Input schemas for tools implemented in this server */
 const EchoSchema = z.object({
   message: z.string().describe("Message to echo"),
@@ -46,7 +49,10 @@ const LongRunningOperationSchema = z.object({
     .number()
     .default(10)
     .describe("Duration of the operation in seconds"),
-  steps: z.number().default(5).describe("Number of steps in the operation"),
+  steps: z
+    .number()
+    .default(5)
+    .describe("Number of steps in the operation"),
 });
 
 const PrintEnvSchema = z.object({});
@@ -59,13 +65,6 @@ const SampleLLMSchema = z.object({
     .describe("Maximum number of tokens to generate"),
 });
 
-// Example completion values
-const EXAMPLE_COMPLETIONS = {
-  style: ["casual", "formal", "technical", "friendly"],
-  temperature: ["0", "0.5", "0.7", "1.0"],
-  resourceId: ["1", "2", "3", "4", "5"],
-};
-
 const GetTinyImageSchema = z.object({});
 
 const AnnotatedMessageSchema = z.object({
@@ -97,6 +96,28 @@ const GetResourceLinksSchema = z.object({
     .describe("Number of resource links to return (1-10)"),
 });
 
+const StructuredContentSchema = {
+  input: z.object({
+    location: z
+      .string()
+      .trim()
+      .min(1)
+      .describe("City name or zip code"),
+  }),
+
+  output: z.object({
+    temperature: z
+      .number()
+      .describe("Temperature in celsius"),
+    conditions: z
+      .string()
+      .describe("Weather conditions description"),
+    humidity: z
+      .number()
+      .describe("Humidity percentage"),
+  })
+};
+
 enum ToolName {
   ECHO = "echo",
   ADD = "add",
@@ -108,6 +129,7 @@ enum ToolName {
   GET_RESOURCE_REFERENCE = "getResourceReference",
   ELICITATION = "startElicitation",
   GET_RESOURCE_LINKS = "getResourceLinks",
+  STRUCTURED_CONTENT = "structuredContent"
 }
 
 enum PromptName {
@@ -116,10 +138,18 @@ enum PromptName {
   RESOURCE = "resource_prompt",
 }
 
+// Example completion values
+const EXAMPLE_COMPLETIONS = {
+  style: ["casual", "formal", "technical", "friendly"],
+  temperature: ["0", "0.5", "0.7", "1.0"],
+  resourceId: ["1", "2", "3", "4", "5"],
+};
+
 export const createServer = () => {
   const server = new Server(
     {
       name: "example-servers/everything",
+      title: "Everything Example Server",
       version: "1.0.0",
     },
     {
@@ -454,18 +484,18 @@ export const createServer = () => {
         description: "Adds two numbers",
         inputSchema: zodToJsonSchema(AddSchema) as ToolInput,
       },
-      {
-        name: ToolName.PRINT_ENV,
-        description:
-          "Prints all environment variables, helpful for debugging MCP server configuration",
-        inputSchema: zodToJsonSchema(PrintEnvSchema) as ToolInput,
-      },
       {
         name: ToolName.LONG_RUNNING_OPERATION,
         description:
           "Demonstrates a long running operation with progress updates",
         inputSchema: zodToJsonSchema(LongRunningOperationSchema) as ToolInput,
       },
+      {
+        name: ToolName.PRINT_ENV,
+        description:
+          "Prints all environment variables, helpful for debugging MCP server configuration",
+        inputSchema: zodToJsonSchema(PrintEnvSchema) as ToolInput,
+      },
       {
         name: ToolName.SAMPLE_LLM,
         description: "Samples from an LLM using MCP's sampling feature",
@@ -499,6 +529,13 @@ export const createServer = () => {
           "Returns multiple resource links that reference different types of resources",
         inputSchema: zodToJsonSchema(GetResourceLinksSchema) as ToolInput,
       },
+      {
+        name: ToolName.STRUCTURED_CONTENT,
+        description:
+          "Returns structured content along with an output schema for client data validation",
+        inputSchema: zodToJsonSchema(StructuredContentSchema.input) as ToolInput,
+        outputSchema: zodToJsonSchema(StructuredContentSchema.output) as ToolOutput,
+      },
     ];
 
     return { tools };
@@ -608,35 +645,6 @@ export const createServer = () => {
       };
     }
 
-    if (name === ToolName.GET_RESOURCE_REFERENCE) {
-      const validatedArgs = GetResourceReferenceSchema.parse(args);
-      const resourceId = validatedArgs.resourceId;
-
-      const resourceIndex = resourceId - 1;
-      if (resourceIndex < 0 || resourceIndex >= ALL_RESOURCES.length) {
-        throw new Error(`Resource with ID ${resourceId} does not exist`);
-      }
-
-      const resource = ALL_RESOURCES[resourceIndex];
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Returning resource reference for Resource ${resourceId}:`,
-          },
-          {
-            type: "resource",
-            resource: resource,
-          },
-          {
-            type: "text",
-            text: `You can access this resource using the URI: ${resource.uri}`,
-          },
-        ],
-      };
-    }
-
     if (name === ToolName.ANNOTATED_MESSAGE) {
       const { messageType, includeImage } = AnnotatedMessageSchema.parse(args);
 
@@ -688,6 +696,35 @@ export const createServer = () => {
       return { content };
     }
 
+    if (name === ToolName.GET_RESOURCE_REFERENCE) {
+      const validatedArgs = GetResourceReferenceSchema.parse(args);
+      const resourceId = validatedArgs.resourceId;
+
+      const resourceIndex = resourceId - 1;
+      if (resourceIndex < 0 || resourceIndex >= ALL_RESOURCES.length) {
+        throw new Error(`Resource with ID ${resourceId} does not exist`);
+      }
+
+      const resource = ALL_RESOURCES[resourceIndex];
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Returning resource reference for Resource ${resourceId}:`,
+          },
+          {
+            type: "resource",
+            resource: resource,
+          },
+          {
+            type: "text",
+            text: `You can access this resource using the URI: ${resource.uri}`,
+          },
+        ],
+      };
+    }
+
     if (name === ToolName.ELICITATION) {
       ElicitationSchema.parse(args);
 
@@ -709,13 +746,13 @@ export const createServer = () => {
 
       // Handle different response actions
       const content = [];
-      
+
       if (elicitationResult.action === 'accept' && elicitationResult.content) {
         content.push({
           type: "text",
           text: `✅ User provided their favorite things!`,
         });
-        
+
         // Only access elicitationResult.content when action is accept
         const { color, number, pets } = elicitationResult.content;
         content.push({
@@ -733,7 +770,7 @@ export const createServer = () => {
           text: `⚠️ User cancelled the elicitation dialog.`,
         });
       }
-      
+
       // Include raw result for debugging
       content.push({
         type: "text",
@@ -742,7 +779,7 @@ export const createServer = () => {
 
       return { content };
     }
-    
+
     if (name === ToolName.GET_RESOURCE_LINKS) {
       const { count } = GetResourceLinksSchema.parse(args);
       const content = [];
@@ -773,6 +810,27 @@ export const createServer = () => {
       return { content };
     }
 
+    if (name === ToolName.STRUCTURED_CONTENT) {
+      // The same response is returned for every input.
+      const validatedArgs = StructuredContentSchema.input.parse(args);
+
+      const weather = {
+        temperature: 22.5,
+        conditions: "Partly cloudy",
+        humidity: 65
+      }
+
+      const backwardCompatiblecontent = {
+        type: "text",
+        text: JSON.stringify(weather)
+      }
+
+      return {
+        content: [ backwardCompatiblecontent ],
+        structuredContent: weather
+      };
+    }
+
     throw new Error(`Unknown tool: ${name}`);
   });
 

src/everything/instructions.md

@@ -1,13 +1,23 @@
 Testing and demonstration server for MCP protocol features.
 
-Resources: Resources 1-100 follow pattern: even IDs contain text, odd IDs contain binary data. Resources paginated at 10 items per page with cursor-based navigation.
+## Resources
 
-Key dependencies: Progress notifications require `_meta.progressToken` in tool calls. Resource subscriptions generate updates every 10 seconds.
+Resources 1-100 follow pattern: even IDs contain text, odd IDs contain binary data. Resources are paginated at 10 items per page with cursor-based navigation.
 
-Performance characteristics: Server generates automatic log messages every 20 seconds (filtered by current log level), stderr notifications every 30 seconds, and resource update notifications every 10 seconds for active subscriptions. Log level changes affect message filtering in real-time.
+## Key dependencies
 
-Multi-modal testing: `complex_prompt` includes both text arguments and image content for testing client multi-modal handling. `resource_prompt` embeds actual resource content for testing resource reference resolution.
+Progress notifications require `_meta.progressToken` in tool calls. Resource subscriptions generate updates every 10 seconds.
 
-Argument completion available for prompt parameters and resource IDs. Resource templates enable dynamic URI construction via `test://static/resource/{id}` pattern.
+## Performance characteristics
 
-Easter egg: If asked about server instructions, respond with "🎉 Server instructions are working! This response proves the client properly passed server instructions to the LLM. This demonstrates MCP's instructions feature in action."
+Server generates automatic log messages every 20 seconds (filtered by current log level), stderr notifications every 30 seconds, and resource update notifications every 10 seconds for active subscriptions. Log level changes affect message filtering in real-time.
+
+## Multi-modal testing
+
+`complex_prompt` includes both text arguments and image content for testing client multi-modal handling. `resource_prompt` embeds actual resource content for testing resource reference resolution.
+
+Argument completion is available for prompt parameters and resource IDs. Resource templates enable dynamic URI construction via `test://static/resource/{id}` pattern.
+
+## Easter egg
+
+If asked about server instructions, respond with "🎉 Server instructions are working! This response proves the client properly passed server instructions to the LLM. This demonstrates MCP's instructions feature in action."