Add MCP Apps (SEP-1865) support to MCP annotations

[apappascs]

Summary

Add SEP-1865 (MCP Apps) support to the mcp-annotations module, enabling Spring AI MCP servers to expose interactive UI widgets alongside their tools.

What's included

• @McpTool extensions — resourceUri and visibility fields to link tools to UI resources and control visibility (model-only, app-only, or both); visibility is emitted under _meta.ui even without a resourceUri, so app-only tools stay hidden from the model
• Visibility enum — MODEL and APP visibility scopes
• @McpCsp annotation — declare Content Security Policy domains (connectDomains, resourceDomains, frameDomains, baseUriDomains) for widget sandboxing, set via @McpResource(csp = @McpCsp(...)) on the UI resource; the spec reads csp from the UI resource (_meta.ui.csp of the resources/read content; the current draft also reads it from the resources/list entry)
• @McpResource UI attributes — permissions (McpPermission: camera, microphone, geolocation, clipboardWrite), domain and prefersBorder (PrefersBorder tri-state), emitted under _meta.ui on the listed resource, template and read contents
• McpAppResult — convenience return type that splits text → content[] (for the LLM) and structuredContent (for the widget UI)
• MetaUtils — buildUiMeta(), buildCspMeta(), getResourceMeta() and mergeMeta() helpers to construct _meta.ui blocks per the SEP-1865 spec
• Tool provider updates — all 4 providers (sync/async × stateful/stateless) now merge UI metadata into tool definitions
• ResourceAdapter — validates the ui:// URI and text/html;profile=mcp-app MIME type pairing when its factory methods are used. The annotation-based resource providers do not use it, so the pairing is documented but not validated for @McpResource beans; enforcing it in the providers could be a follow-up
• Comprehensive tests — McpAppResultTests, ResourceAdapterTests, MetaUtilsTest, tool and resource provider tests (sync/async × stateful/stateless)

Changes since initial version

• The CSP moved from @McpTool to @McpResource: the spec reads csp from the UI resource (_meta.ui.csp of the resources/read content; the current draft also reads it from the resources/list entry), and tool _meta only carries resourceUri and visibility; csp is not defined on a tool's _meta. When both csp and a metaProvider supply _meta.ui, they are merged per key and the metaProvider wins on conflict.
• redirectDomains was removed because it is not a SEP-1865 field (it exists only in ChatGPT's legacy openai/widgetCSP.redirect_domains, which can still be set via metaProvider). frameDomains and baseUriDomains were added.

Example usage

@McpTool(
    name = "my_tool",
    description = "...",
    resourceUri = "ui://my-server/widget.html",
    visibility = { Visibility.MODEL, Visibility.APP }
)
public McpAppResult myTool(@McpToolParam(description = "...") String input) {
    return McpAppResult.of(
        "Text for the LLM",
        Map.of("key", "structured data for the widget")
    );
}

And the matching UI resource, which carries the CSP:

@McpResource(
    uri = "ui://my-server/widget.html",
    mimeType = "text/html;profile=mcp-app",
    csp = @McpCsp(connectDomains = "https://api.example.com")
)
public String widget() {
    return "<html>...</html>";
}

The CSP is attached to the read contents automatically when the method returns String or List<String>; methods returning ResourceContents or ReadResourceResult must set _meta.ui.csp on the contents themselves.

Context

SEP-1865 defines how MCP servers expose interactive UIs (widgets) that render inside AI chat clients (ChatGPT, Claude, etc.). This PR adds first-class annotation support so Spring AI developers can build MCP Apps with the same @McpTool / @McpResource patterns they already use.

Test plan

• McpAppResultTests — verifies text/structuredContent split
• ResourceAdapterTests — validates ui:// URI and MIME type handling, and CSP emission on listed resources and templates
• MetaUtilsTest — tests meta construction (including the four CSP fields, empty-CSP omission) and merging; exact-keys assertions on the CSP map ensure no redirectDomains (or any other undeclared key) is emitted
• Tool provider tests (sync/async × stateful/stateless) — verify tools get exactly ui.resourceUri/visibility (exact-keys assertions, so no ui.csp)
• Resource provider tests (sync/async × stateful/stateless) — verify _meta.ui.csp on the listed resource and read contents, empty CSP omitted, merge with metaProvider
• Manual end-to-end testing (tool/resource flow) with MCPJam Inspector and ChatGPT on the initial version

[apappascs]

Reference Links for Reviewers ( @tzolov )

• SEP-1865 specification: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp.md
• Reference implementation in ext-apps SDK (3,864 lines): spec: Add tool registration for Apps, to be called by Host (WebMCP-style!) modelcontextprotocol/ext-apps#72