Create implementation plan

[nikonovd]

What should we do?

• Create an implementation plan / gap analysis to see what's necessary to be done

Why should we do it?

• Reduce risks of missing essential parts of the implementation

[nikonovd]

MCP 2025-11-25 Specification Model Update Plan

Issue: #6228 - Agentic AI: Add MCP model attributes of 2025-11-25 specification

Overview

This document outlines the implementation plan for updating the MCP client domain models to align with the MCP 2025-11-25 specification. The goal is to extend our existing models with missing attributes to ensure compatibility with the latest MCP features.

Gap Analysis Summary

Domain Model	Missing Properties
ToolDefinition	title, icons, outputSchema, annotations
ResourceDescription	title, icons, size, annotations
ResourceTemplate	title, icons, annotations
ResourceData	annotations
PromptDescription	title, icons

---

Implementation Plan

Phase 1: Introduce Shared Types

Create reusable types that are used across multiple domain models.

Task 1.1: Create Icon Record

File: io.camunda.connector.agenticai.mcp.client.model.Icon

@AgenticAiRecord
public record Icon(
    String src,
    String mimeType,
    List<String> sizes
) {}

Unit Tests:

• Serialization/deserialization with all fields
• Deserialization with null optional fields
• Empty sizes list handling

Task 1.2: Create Annotations Record

File: io.camunda.connector.agenticai.mcp.client.model.Annotations

@AgenticAiRecord
public record Annotations(
    List<String> audience,   // Valid values: "user", "assistant"
    Double priority,          // Range: 0.0 to 1.0
    String lastModified       // ISO 8601 timestamp
) {}

Unit Tests:

• Serialization/deserialization with all fields
• Deserialization with null optional fields

---

Phase 2: Update Tool-Related Models

Task 2.1: Extend ToolDefinition

File: io.camunda.connector.agenticai.model.tool.ToolDefinition

Add the following fields:

• String title
• List<Icon> icons
• Map<String, Object> outputSchema
• Annotations annotations

Unit Tests:

• Existing tests remain passing (backwards compatibility)
• Serialization/deserialization with new optional fields
• Deserialization of MCP spec example payloads
• Builder pattern works with new fields

---

Phase 3: Update Resource-Related Models

Task 3.1: Extend ResourceDescription

File: io.camunda.connector.agenticai.mcp.client.model.result.ResourceDescription

Add the following fields:

• String title
• List<Icon> icons
• Long size
• Annotations annotations

Unit Tests:

• Existing tests remain passing
• Serialization/deserialization with new optional fields
• Builder pattern works with new fields
• Size field handles null values

Task 3.2: Extend ResourceTemplate

File: io.camunda.connector.agenticai.mcp.client.model.result.ResourceTemplate

Add the following fields:

• String title
• List<Icon> icons
• Annotations annotations

Unit Tests:

• Existing tests remain passing
• Serialization/deserialization with new optional fields
• Builder pattern works with new fields

Task 3.3: Extend ResourceData

File: io.camunda.connector.agenticai.mcp.client.model.result.ResourceData

Add annotations field to each variant:

• BlobResourceData → add Annotations annotations
• TextResourceData → add Annotations annotations
• CamundaDocumentResourceData → add Annotations annotations

Unit Tests:

• Existing tests remain passing
• Serialization/deserialization with annotations
• McpClientReadResourceResult.convertStorableMcpResultData preserves annotations

---

Phase 4: Update Prompt-Related Models

Task 4.1: Extend PromptDescription

File: io.camunda.connector.agenticai.mcp.client.model.result.PromptDescription

Add the following fields:

• String title
• List<Icon> icons

Unit Tests:

• Existing tests remain passing
• Serialization/deserialization with new optional fields

---

Phase 5: Update MCP Client Mapping Layer

Update the mapping logic that converts MCP SDK responses to our domain models.

Task 5.1: Update Tool Mapping

Files to update:

• Mapper/converter that creates ToolDefinition from MCP SDK Tool

Unit Tests:

• Mapping preserves new fields when present
• Mapping handles null/missing new fields gracefully

Task 5.2: Update Resource Mapping

Files to update:

• Mapper/converter that creates ResourceDescription from MCP SDK
• Mapper/converter that creates ResourceTemplate from MCP SDK
• Mapper/converter that creates ResourceData from MCP SDK

Unit Tests:

• Mapping preserves new fields when present
• Annotations are correctly mapped
• Icons list is correctly mapped

Task 5.3: Update Prompt Mapping

Files to update:

• Mapper/converter that creates PromptDescription from MCP SDK

Unit Tests:

• Mapping preserves new fields when present

---

Testing Strategy

Unit Tests

Each modified class should have corresponding unit tests covering:

1. Backwards Compatibility

   • Existing JSON payloads (without new fields) deserialize correctly
   • All existing functionality remains intact

2. New Field Handling

   • New optional fields deserialize when present
   • New optional fields default to null when absent
   • Serialization includes new fields when non-null

3. Edge Cases

   • Empty collections vs null

Integration Tests

Integration tests are located in connectors-e2e-test/connectors-e2e-test-agentic-ai module. The existing test classes McpStandaloneLangchain4JTests and McpStandaloneMcpSdkTests should be extended to verify the new properties.

WireMock Stub Mappings to Update

The following WireMock mapping files need to be updated to include the new MCP 2025-11-25 attributes:

Mapping File	New Properties to Add
mappings/mcp-tools-list.json	title, icons, outputSchema, annotations to tool objects
mappings/mcp-resources-list.json	title, icons, size, annotations to resource objects
mappings/mcp-resource-templates-list.json	title, icons, annotations to resource template objects
mappings/mcp-resources-read.json	annotations to resource content objects
mappings/mcp-prompts-list.json	icons to prompt objects (note: title already exists)
mappings/mcp-prompts-get.json	annotations to prompt message content objects (if applicable)

Test Assertions to Add

McpStandaloneLangchain4JTests / McpStandaloneMcpSdkTests:

1. toolsListAndCall test - Add assertions for:

   • ToolDefinition.title() is correctly mapped
   • ToolDefinition.icons() contains expected icon data
   • ToolDefinition.outputSchema() is correctly mapped
   • ToolDefinition.annotations() is correctly mapped

2. resourcesListAndRead test - Add assertions for:

   • ResourceDescription.title() is correctly mapped
   • ResourceDescription.icons() contains expected icon data
   • ResourceDescription.size() is correctly mapped
   • ResourceDescription.annotations() is correctly mapped
   • ResourceData variants include annotations

3. resourceTemplatesListAndRead test - Add assertions for:

   • ResourceTemplate.title() is correctly mapped
   • ResourceTemplate.icons() contains expected icon data
   • ResourceTemplate.annotations() is correctly mapped

4. promptsListAndGet test - Add assertions for:

   • PromptDescription.title() is correctly mapped (already present in stub)
   • PromptDescription.icons() contains expected icon data

Example WireMock Stub Update (mcp-tools-list.json)

{
  "name": "toolA",
  "title": "Tool A Display Name",
  "description": "The first tool",
  "inputSchema": { ... },
  "outputSchema": {
    "type": "object",
    "properties": {
      "result": { "type": "string" }
    }
  },
  "icons": [
    {
      "src": "https://example.com/tool-a-icon.png",
      "mimeType": "image/png",
      "sizes": ["48x48"]
    }
  ],
  "annotations": {
    "audience": ["user", "assistant"],
    "priority": 0.8,
    "lastModified": "2025-01-15T10:30:00Z"
  }
}

Test File Locations

Component	Test Location
Shared types (Icon, Annotations)	src/test/java/io/camunda/connector/agenticai/mcp/client/model/
ToolDefinition	src/test/java/io/camunda/connector/agenticai/model/tool/ToolDefinitionTest.java
Result models	src/test/java/io/camunda/connector/agenticai/mcp/client/model/result/
Mappers	src/test/java/io/camunda/connector/agenticai/mcp/client/
Integration tests	connectors-e2e-test/connectors-e2e-test-agentic-ai/.../mcp/McpStandalone*Tests.java
WireMock stubs	connectors-e2e-test/connectors-e2e-test-agentic-ai/src/test/resources/mappings/

---

Implementation Checklist

Phase 1: Shared Types

• Create Icon record
• Create Annotations record
• Unit tests for Icon
• Unit tests for Annotations

Phase 2: Tool Models

• Extend ToolDefinition with new fields
• Update ToolDefinition unit tests

Phase 3: Resource Models

• Extend ResourceDescription with new fields
• Extend ResourceTemplate with new fields
• Extend ResourceData variants with annotations
• Update ResourceDescription unit tests
• Update ResourceTemplate unit tests
• Update ResourceData unit tests
• Verify McpClientReadResourceResult preserves annotations

Phase 4: Prompt Models

• Extend PromptDescription with new fields
• Update PromptDescription unit tests

Phase 5: Mapping Layer

• Update tool mapping logic
• Update resource mapping logic
• Update prompt mapping logic
• Unit tests for all mapping changes

Phase 6: Integration Tests

• Update mcp-tools-list.json WireMock stub with new properties
• Update mcp-resources-list.json WireMock stub with new properties
• Update mcp-resource-templates-list.json WireMock stub with new properties
• Update mcp-resources-read.json WireMock stub with annotations
• Update mcp-prompts-list.json WireMock stub with icons
• Update mcp-prompts-get.json WireMock stub with annotations (if applicable)
• Add assertions in McpStandaloneLangchain4JTests for new properties
• Add assertions in McpStandaloneMcpSdkTests for new properties

Final Validation

• All existing tests pass
• New tests pass
• Build succeeds
• Integration tests pass (if applicable)

---

Notes

• All new fields are optional and can be null to maintain backwards compatibility with older MCP servers
• The @AgenticAiRecord annotation should be used for new records to ensure consistent builder generation
• Jackson annotations may be needed for proper JSON serialization/deserialization
• Consider using @JsonInclude(JsonInclude.Include.NON_NULL) to exclude null fields from serialization if desired