Package com.github.thought2code.mcp.annotated.server

Interface McpStructuredContent

public interface McpStructuredContent
Marker interface for MCP tool method results that return structured content.

This interface is used to distinguish between simple text results and complex results containing structured data. When an MCP tool method returns an object implementing this interface, the MCP server will provide both text representation and structured data representation.

Usage Scenarios

  • Simple Text Results: When tool methods return String or other primitive types, only text content is provided
  • Structured Results: When tool methods return objects implementing this interface, both text and structured data are provided

Example Usage


 public class WeatherTool {

   @McpTool(description = "Get weather information")
   public WeatherData getWeather(@McpToolParam(name = "city") String city) {
     final int temperature = 25;
     final String condition = "Sunny";
     return new WeatherData(city, temperature, condition);
   }

   // Structured result class implementing McpStructuredContent
   public record WeatherData(
       @McpJsonSchemaProperty(description = "City name") String city,
       @McpJsonSchemaProperty(description = "Temperature") int temperature,
       @McpJsonSchemaProperty(description = "Condition") String condition)
       implements McpStructuredContent {

     @Override
     public String asTextContent() {
       return String.format("City: %s, Temperature: %d°C, Condition: %s",
           city, temperature, condition);
     }
   }
 }

MCP Response Format

When a tool returns an object implementing this interface, the MCP response will contain: 

 {
   "content": [
     {
       "type": "text",
       "text": "City: New York, Temperature: 25°C, Condition: Sunny"
     }
   ],
   "structuredContent": {
     "city": "New York",
     "temperature": 25,
     "condition": "Sunny"
   }
 }

Implementation Requirements

  • Implementing classes must provide meaningful text representation for direct AI model consumption
  • Fields of implementing classes will be automatically serialized as structured content
  • Text content should be concise and clear for AI understanding
  • Structured content should contain complete detailed information

Default Implementation

The interface provides a default implementation of asTextContent() that returns the result of Object.toString(). If the default implementation doesn't meet requirements, implementing classes should override this method.
Author:
codeboyzhou
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default String
    asTextContent()
    Returns the text representation of this structured content.

  • Method Details

    • asTextContent

      default String asTextContent()
      Returns the text representation of this structured content.

      The text representation should provide a concise summary of the content, suitable for direct consumption by AI models. The result of this method will be used as the text content in the MCP response's content field.

      Implementation Guidelines

      • Conciseness: Text should be brief, avoiding excessive details
      • Readability: Use natural language that's easy for AI to understand
      • Completeness: Include key information, but not necessarily all details
      • Consistency: Text content should be consistent with structured data

      Examples For weather query results:

      • Good implementation: "City: New York, Temperature: 25°C, Condition: Sunny"
      • Poor implementation: Returning full JSON strings or overly simplified information
      Returns:
      the text representation of the structured content, should not return null
      See Also: