[mcp-ui] Adding MCP-UI support to those that support URLs

[mattpodwysocki]

Description

Adds MCP-UI support to URL-returning tools, enabling rich iframe embedding in compatible MCP clients
while maintaining full backwards compatibility.

What is MCP-UI?

MCP-UI is an open specification that allows MCP tools to return interactive UI resources that clients can
render as embedded iframes. This enables richer, more visual experiences in supporting clients like
Goose, while seamlessly falling back to text URLs in clients like Claude Desktop.

Changes

Enhanced Tools (3 total):

• preview_style_tool - Embeds Mapbox style previews
• geojson_preview_tool - Embeds geojson.io visualizations
• style_comparison_tool - Embeds side-by-side style comparisons

Implementation Details:

• Tools now return both text URL and UIResource content
• MCP-UI is enabled by default (fully backwards compatible)
• Added @mcp-ui/server@^5.13.1 dependency
• Configuration via ENABLE_MCP_UI env var or --disable-mcp-ui flag
• Helper function isMcpUiEnabled() in src/config/toolConfig.ts

Backwards Compatibility:

• Clients without MCP-UI support (e.g., Claude Desktop) ignore the UIResource and use the text URL
• Clients with MCP-UI support (e.g., Goose) can render embedded iframes
• No breaking changes - existing integrations continue working unchanged

Documentation:

• Updated README.md with MCP-UI configuration section
• Updated CLAUDE.md with developer guidance
• Added inline code comments

Files Changed

• src/config/toolConfig.ts - Configuration and helper functions
• src/tools/preview-style-tool/PreviewStyleTool.ts - MCP-UI support
• src/tools/geojson-preview-tool/GeojsonPreviewTool.ts - MCP-UI support
• src/tools/style-comparison-tool/StyleComparisonTool.ts - MCP-UI support
• package.json - Added @mcp-ui/server dependency
• test/**/*.test.ts - Updated tests for default enabled behavior
• README.md & CLAUDE.md - Documentation updates

Test

Unit Tests:

• ✅ All 282 tests passing
• ✅ New tests for MCP-UI enabled (default) behavior
• ✅ New tests for MCP-UI disabled behavior
• ✅ Configuration parsing tests for --disable-mcp-ui flag
• ✅ Environment variable override tests

Manual Testing:

1. With MCP-UI enabled (default):

   npm run build
   # Test in Goose or ui-inspector - should see both text URL and UIResource
   

2. With MCP-UI disabled:
   ENABLE_MCP_UI=false npm run build

Should return only text URL (original behavior)

3. Backwards compatibility:
   - Tested in Claude Desktop - works unchanged (ignores UIResource)
   - Text URLs remain fully functional in all clients

Test Prompts:

Preview a Mapbox style:
Preview Mapbox style Urban Night with my public token

Results in Claude with no MCP-UI support (redacted for security)

Results in Goose with MCP-UI support

Preview GeoJSON:
Preview this GeoJSON: {"type": "Point", "coordinates": [2.2945, 48.8584]}

In Claude Desktop with no MCP-UI support

In Goose with MCP-UI support (note there is a CORS issue)

We can ask Goose, however to visualize it inline with their own OSM view:

Expected Behavior:

• MCP-UI supporting clients: See embedded iframe
• Non-supporting clients: See clickable text URL
• Both provide full functionality

Code Quality:

• ✅ Linter passed (68 pre-existing warnings unrelated to this PR)
• ✅ Formatter passed
• ✅ Build successful

---

Checklist

• Code has been tested locally
• Unit tests have been added or updated
• Documentation has been updated if needed

---

Additional Notes

[zmofei]

Nice improvement.

• [nit] Can we Bounding Box tool add this as well?
• Are we able to adjust the hight of iframe? Will this help?
  • 

[mattpodwysocki]

Nice improvement.

• [nit] Can we Bounding Box tool add this as well?

• Are we able to adjust the hight of iframe? Will this help?

  • 

@zmofei increased the size to 1100x700 as a suggested size. That works for the most part.

[Valiunia]

I thought it's static image api and not geojson.io?