Upgrade MCP protocol to 2025-11-25

[mihaelamj]

Summary

Upgrade MCP protocol from 2025-06-18 to 2025-11-25 (released November 25, 2025 - MCP's first anniversary).

New Features in 2025-11-25

Tasks abstraction - A new primitive for tracking long-running server work:

• Any request can be augmented with a task
• Clients can query task status
• Results available for server-defined duration after task creation

This could be useful for long-running operations like database searches or document processing.

Icons - Visual identifiers for servers, tools, prompts, and resources.

References

• MCP Specification 2025-11-25
• One Year of MCP Blog Post

TODO

• Update MCPProtocolVersion in Protocol.swift to 2025-11-25
• Add 2025-06-18 to MCPProtocolVersionsSupported for backward compatibility
• Add Icon struct to Protocol.swift
• Update Implementation struct to include optional icons array
• Create Cupertino icon (64x64 PNG) and add to assets/
• Add icon to serverInfo in MCPServer initialization response
• Update MCPClient and MockAIAgent if needed
• Add/update tests

Version Support After Upgrade

public let MCPProtocolVersion = "2025-11-25"
public let MCPProtocolVersionsSupported = [
    "2025-11-25",
    "2025-06-18", 
    "2024-11-05",
]

[mihaelamj]

Investigation Results

Good News: No Breaking Changes

The 2025-11-25 protocol has no breaking changes. Existing implementations continue working. New features are opt-in.

What's New in 2025-11-25

1. Tasks (Experimental)

Tasks enable tracking long-running server operations. This is optional - servers can declare support via capabilities.

Task Status Lifecycle:

working → input_required → working → completed
                ↓                        ↓
            cancelled                  failed

New Methods:

• tasks/get - Poll task status
• tasks/result - Retrieve completed task results
• tasks/cancel - Cancel in-progress tasks
• tasks/list - List all tasks (paginated)

New Capabilities:

{
  "capabilities": {
    "tasks": {
      "list": {},
      "cancel": {},
      "requests": {
        "tools": {
          "call": {}
        }
      }
    }
  }
}

2. Icons Support

New icons property for implementations, tools, prompts, and resources:

{
  "icons": [
    {
      "src": "https://example.com/icon.png",
      "mimeType": "image/png",
      "sizes": ["48x48"]
    }
  ]
}

3. Tool-Level Task Negotiation

Tools can declare task support via execution.taskSupport:

• "required" - Must use task augmentation
• "optional" - Can use either
• "forbidden" (default) - Normal execution only

---

Implementation Plan

Phase 1: Version Bump (Minimal)

Just add version support without implementing Tasks:

public let MCPProtocolVersion = "2025-11-25"
public let MCPProtocolVersionsSupported = [
    "2025-11-25",
    "2025-06-18", 
    "2024-11-05",
]

This is sufficient for compatibility - Tasks are optional.

Phase 2: Tasks Support (Future)

If we want task-augmented tool calls (useful for long searches):

1. Add Task types in Protocol.swift:

   • Task struct (taskId, status, statusMessage, createdAt, lastUpdatedAt, ttl, pollInterval)
   • TaskStatus enum (working, input_required, completed, failed, cancelled)
   • CreateTaskResult response type

2. Add Task capabilities to ServerCapabilities

3. Implement Task methods in MCPServer.swift:

   • tasks/get
   • tasks/result
   • tasks/list
   • tasks/cancel

4. Add task storage - In-memory dictionary with TTL cleanup

5. Update tool execution to optionally return CreateTaskResult

---

Minimal Changes for Phase 1

Files to modify:

• Protocol.swift - Version constant
• MCPServer.swift - Version negotiation (already handles this)
• Tests - Update expected version

Estimated: ~10 lines of code change for basic compatibility.

---

References

• MCP 2025-11-25 Specification
• Tasks Specification
• Lifecycle & Capabilities

[mihaelamj]

Icon Support

Adding icon support to serverInfo in the initialize response.

Implementation

Update Implementation struct in Protocol.swift:

public struct Implementation: Codable, Sendable {
    public let name: String
    public let version: String
    public let icons: [Icon]?  // NEW
    
    // ...
}

public struct Icon: Codable, Sendable {
    public let src: String
    public let mimeType: String?
    public let sizes: [String]?
    public let theme: String?  // "light" or "dark"
    
    public init(
        src: String,
        mimeType: String? = nil,
        sizes: [String]? = nil,
        theme: String? = nil
    ) {
        self.src = src
        self.mimeType = mimeType
        self.sizes = sizes
        self.theme = theme
    }
}

Server Response

The initialize response will include:

{
  "serverInfo": {
    "name": "cupertino",
    "version": "0.9.2",
    "icons": [
      {
        "src": "https://raw.githubusercontent.com/mihaelamj/cupertino/main/assets/icon.png",
        "mimeType": "image/png",
        "sizes": ["64x64"]
      }
    ]
  }
}

Icon Options

1. GitHub raw URL - Host in repo under assets/icon.png
2. Data URI - Embed base64 encoded image directly (no external fetch)

Data URI example:

{
  "src": "data:image/png;base64,iVBORw0KGgo...",
  "mimeType": "image/png"
}

Required MIME Types (per spec)

Clients MUST support:

• image/png
• image/jpeg

Clients SHOULD support:

• image/svg+xml
• image/webp

TODO

• Create Cupertino icon (64x64 PNG)
• Add Icon struct to Protocol.swift
• Update Implementation to include optional icons
• Add icon to serverInfo in MCPServer initialization