feat: tool outputSchema, resource/template annotations, structuredContent — bump to v0.31.0

- Add outputSchema support on MCPTool with automatic structuredContent generation
- Add MCPResourceAnnotations (audience, priority) for resources and resource templates
- Builder-style API: setOutputSchema(), setAudience(), setPriority()
- structuredContent auto-generated for tools with outputSchema when handler returns valid JSON
- 27 new tests covering all new features — total: 1064 tests

Author: Nicola Spieser

.gitignore

@@ -21,3 +21,4 @@ test/native/test_session
 test/native/test_content_transport
 test/native/test_advanced
 test/native/test_integration
+test/native/test_output_annotations

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.31.0] — 2026-02-21
+
+### Added
+- **Tool `outputSchema`**: Optional JSON Schema for structured tool output per MCP 2025-03-26 spec. Tools with `outputSchema` automatically include `structuredContent` in their response when the handler returns valid JSON.
+- **Resource annotations**: `audience` and `priority` hints on `MCPResource` for guiding client/model behavior. Builder-style API: `res.setAudience("user").setPriority(0.8f)`.
+- **Resource template annotations**: Same annotation support on `MCPResourceTemplate`.
+- **`MCPResourceAnnotations` struct**: Reusable annotations with `setAudience()`, `setPriority()`, and `toJson()`.
+- **27 new tests** covering outputSchema serialization, structuredContent generation (simple + rich handlers, arrays, error cases, non-JSON), resource/template annotation serialization, builder chains, and default state. Total: **1064 tests**.
+
+### Changed
+- `MCPTool::toJson()` now emits `outputSchema` when set.
+- `MCPResource::toJson()` and `MCPResourceTemplate::toJson()` now emit `annotations` when set.
+- Tool call dispatch (`_handleToolsCall`) auto-generates `structuredContent` from handler output for tools with `outputSchema`.
+
 ## [0.29.1] - 2026-02-21
 
 ### Features

docs/API.md

@@ -290,6 +290,35 @@ mcpd implements MCP specification 2025-03-26 via Streamable HTTP transport.
 | `resources/subscribe` | Subscribe to change notifications for a resource URI |
 | `resources/unsubscribe` | Unsubscribe from resource change notifications |
 
+### Tool Output Schema & Structured Content
+
+Tools can declare an `outputSchema` (JSON Schema) describing their structured output:
+
+```cpp
+MCPTool tool("get_reading", "Get sensor reading", inputSchema, handler);
+tool.setOutputSchema(R"({"type":"object","properties":{"temp":{"type":"number"}}})");
+mcp.addTool(tool);
+```
+
+When a tool with `outputSchema` returns valid JSON, the response automatically includes both `content` (text) and `structuredContent` (parsed JSON), per MCP 2025-03-26 spec.
+
+### Resource & Template Annotations
+
+Resources and resource templates support `audience` and `priority` annotations:
+
+```cpp
+MCPResource res("file://log", "Log", "System log", "text/plain", handler);
+res.setAudience("user").setPriority(0.8f);
+mcp.addResource(res);
+
+MCPResourceTemplate tmpl("sensor://{id}", "Sensor", "Desc", "text/plain", handler);
+tmpl.setAudience("assistant").setPriority(0.5f);
+mcp.addResourceTemplate(tmpl);
+```
+
+- `audience`: `"user"` or `"assistant"` — hints who the content is primarily for
+- `priority`: `0.0` to `1.0` — relative importance hint for ordering/filtering
+
 ### Session Management
 
 - Session ID sent via `Mcp-Session-Id` header

library.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpd",
-  "version": "0.27.5",
+  "version": "0.31.0",
   "description": "MCP Server SDK for Microcontrollers — Expose ESP32/RP2040/STM32 hardware as AI-accessible tools via Model Context Protocol",
   "keywords": [
     "mcp",

library.properties

@@ -1,5 +1,5 @@
 name=mcpd
-version=0.27.5
+version=0.31.0
 author=Nicola Spieser
 maintainer=Nicola Spieser <redbasecap-buiss@users.noreply.github.com>
 sentence=MCP Server SDK for Microcontrollers

src/MCPResource.h

@@ -17,6 +17,27 @@ namespace mcpd {
  */
 using MCPResourceHandler = std::function<String()>;
 
+/**
+ * Resource annotations per MCP 2025-03-26 spec.
+ * Describes the intended audience and priority of a resource.
+ */
+struct MCPResourceAnnotations {
+    String audience;     // "user", "assistant", or empty (both)
+    float priority = -1; // 0.0 to 1.0, -1 = unset
+    bool hasAnnotations = false;
+
+    MCPResourceAnnotations& setAudience(const char* a) { audience = a; hasAnnotations = true; return *this; }
+    MCPResourceAnnotations& setPriority(float p) { priority = p; hasAnnotations = true; return *this; }
+
+    void toJson(JsonObject& obj) const {
+        if (!audience.isEmpty()) {
+            JsonArray arr = obj["audience"].to<JsonArray>();
+            arr.add(audience);
+        }
+        if (priority >= 0.0f) obj["priority"] = priority;
+    }
+};
+
 /**
  * Represents a single MCP resource.
  */
@@ -26,6 +47,7 @@ struct MCPResource {
     String description;
     String mimeType;
     MCPResourceHandler handler;
+    MCPResourceAnnotations annotations;
 
     MCPResource() = default;
 
@@ -35,6 +57,25 @@ struct MCPResource {
         : uri(uri), name(name), description(description),
           mimeType(mimeType), handler(handler) {}
 
+    /** Builder-style: set annotations */
+    MCPResource& annotate(const MCPResourceAnnotations& ann) {
+        annotations = ann;
+        annotations.hasAnnotations = true;
+        return *this;
+    }
+
+    /** Convenience: set audience hint */
+    MCPResource& setAudience(const char* audience) {
+        annotations.setAudience(audience);
+        return *this;
+    }
+
+    /** Convenience: set priority hint (0.0–1.0) */
+    MCPResource& setPriority(float priority) {
+        annotations.setPriority(priority);
+        return *this;
+    }
+
     /**
      * Serialize for resources/list response.
      */
@@ -43,6 +84,10 @@ struct MCPResource {
         obj["name"] = name;
         obj["description"] = description;
         obj["mimeType"] = mimeType;
+        if (annotations.hasAnnotations) {
+            JsonObject ann = obj["annotations"].to<JsonObject>();
+            annotations.toJson(ann);
+        }
     }
 };
 

src/MCPResourceTemplate.h

@@ -16,6 +16,8 @@
 #include <map>
 #include <vector>
 
+#include "MCPResource.h"  // For MCPResourceAnnotations
+
 namespace mcpd {
 
 /**
@@ -36,6 +38,7 @@ struct MCPResourceTemplate {
     String description;
     String mimeType;
     MCPResourceTemplateHandler handler;
+    MCPResourceAnnotations annotations;
 
     MCPResourceTemplate() = default;
 
@@ -45,6 +48,25 @@ struct MCPResourceTemplate {
         : uriTemplate(uriTemplate), name(name), description(description),
           mimeType(mimeType), handler(handler) {}
 
+    /** Builder-style: set annotations */
+    MCPResourceTemplate& annotate(const MCPResourceAnnotations& ann) {
+        annotations = ann;
+        annotations.hasAnnotations = true;
+        return *this;
+    }
+
+    /** Convenience: set audience hint */
+    MCPResourceTemplate& setAudience(const char* audience) {
+        annotations.setAudience(audience);
+        return *this;
+    }
+
+    /** Convenience: set priority hint (0.0–1.0) */
+    MCPResourceTemplate& setPriority(float priority) {
+        annotations.setPriority(priority);
+        return *this;
+    }
+
     /**
      * Serialize for resources/templates/list response.
      */
@@ -53,6 +75,10 @@ struct MCPResourceTemplate {
         obj["name"] = name;
         obj["description"] = description;
         obj["mimeType"] = mimeType;
+        if (annotations.hasAnnotations) {
+            JsonObject ann = obj["annotations"].to<JsonObject>();
+            annotations.toJson(ann);
+        }
     }
 
     /**

src/MCPTool.h

@@ -50,7 +50,8 @@ struct MCPToolAnnotations {
 struct MCPTool {
     String name;
     String description;
-    String inputSchemaJson;  // JSON Schema as string
+    String inputSchemaJson;   // JSON Schema as string
+    String outputSchemaJson;  // Optional: JSON Schema for structured output
     MCPToolHandler handler;
     MCPToolAnnotations annotations;
 
@@ -92,6 +93,12 @@ struct MCPTool {
         return *this;
     }
 
+    /** Set output schema (builder-style). Enables structured content in tool results. */
+    MCPTool& setOutputSchema(const char* schemaJson) {
+        outputSchemaJson = schemaJson;
+        return *this;
+    }
+
     /** Convenience: mark as local-only (openWorldHint=false) */
     MCPTool& markLocalOnly() {
         annotations.openWorldHint = false;
@@ -112,6 +119,13 @@ struct MCPTool {
         deserializeJson(schemaDoc, inputSchemaJson);
         obj["inputSchema"] = schemaDoc.as<JsonVariant>();
 
+        // Include output schema if set
+        if (!outputSchemaJson.isEmpty()) {
+            JsonDocument outDoc;
+            deserializeJson(outDoc, outputSchemaJson);
+            obj["outputSchema"] = outDoc.as<JsonVariant>();
+        }
+
         // Include annotations if set
         if (annotations.hasAnnotations) {
             JsonObject ann = obj["annotations"].to<JsonObject>();

src/mcpd.cpp

@@ -782,6 +782,17 @@ String Server::_handleToolsCall(JsonVariant params, JsonVariant id) {
                 JsonDocument result;
                 JsonObject resultObj = result.to<JsonObject>();
                 toolResult.toJson(resultObj);
+
+                // If tool has outputSchema and first content is text, include structuredContent
+                if (!tool.outputSchemaJson.isEmpty() && !toolResult.isError &&
+                    !toolResult.content.empty() && toolResult.content[0].type == MCPContent::TEXT) {
+                    JsonDocument structured;
+                    DeserializationError err = deserializeJson(structured, toolResult.content[0].text);
+                    if (!err) {
+                        resultObj["structuredContent"] = structured.as<JsonVariant>();
+                    }
+                }
+
                 serializeJson(result, resultStr);
                 if (toolResult.isError) callIsError = true;
             } else {
@@ -802,6 +813,16 @@ String Server::_handleToolsCall(JsonVariant params, JsonVariant id) {
                 if (callIsError) {
                     result["isError"] = true;
                 }
+
+                // If tool has outputSchema, include structuredContent
+                if (!tool.outputSchemaJson.isEmpty() && !callIsError) {
+                    JsonDocument structured;
+                    DeserializationError err = deserializeJson(structured, handlerResult);
+                    if (!err) {
+                        result["structuredContent"] = structured.as<JsonVariant>();
+                    }
+                }
+
                 serializeJson(result, resultStr);
             }
 

src/mcpd.h

@@ -44,7 +44,7 @@
 #include "MCPTransportBLE.h"
 #endif
 
-#define MCPD_VERSION "0.30.0"
+#define MCPD_VERSION "0.31.0"
 #define MCPD_MCP_PROTOCOL_VERSION "2025-03-26"
 
 namespace mcpd {