Merge pull request #31 from IBM/new-roadmap

New roadmap

Author: chrishayuk

README.md

@@ -162,6 +162,53 @@ async def process_data(data: str) -> dict:
 mcp.run(host="0.0.0.0", port=8000)  # HTTP server
 ```
 
+### MCP Apps — Rich UI Views in Claude.ai
+
+Render interactive charts, maps, tables, and more directly in Claude.ai using [MCP Apps](https://modelcontextprotocol.io) structured content.
+
+```python
+from chuk_mcp_server import ChukMCPServer
+
+mcp = ChukMCPServer(name="my-view-server", version="1.0.0")
+
+@mcp.tool(
+    name="show_chart",
+    description="Show sales data as a chart.",
+    meta={
+        "ui": {
+            "resourceUri": "ui://my-view-server/chart",
+            "viewUrl": "https://chuk-mcp-ui-views.fly.dev/chart/v1",
+        }
+    },
+)
+async def show_chart(chart_type: str = "bar") -> dict:
+    return {
+        "content": [{"type": "text", "text": "Sales chart."}],
+        "structuredContent": {
+            "type": "chart",
+            "version": "1.0",
+            "title": "Q1 Sales",
+            "chartType": chart_type,
+            "data": [{"label": "Revenue", "values": [
+                {"label": "Jan", "value": 4200},
+                {"label": "Feb", "value": 5100},
+                {"label": "Mar", "value": 4800},
+            ]}],
+        },
+    }
+
+mcp.run()
+```
+
+**How it works:**
+- `meta.ui.resourceUri` — a `ui://` URI identifying the view
+- `meta.ui.viewUrl` — HTTPS URL serving the view's HTML/JS bundle
+- The server **automatically** registers an MCP resource at the `resourceUri` that fetches the HTML from `viewUrl`
+- The server **automatically** enables the `experimental` capability
+- Claude.ai reads the HTML via `resources/read`, renders it in an iframe, and passes `structuredContent` as the data payload
+
+See [`examples/mcp_apps_view_example.py`](examples/mcp_apps_view_example.py) for a complete example.
+
 ### Cloud Deployment (Auto-Detection)
 
 ```python
@@ -239,6 +286,7 @@ See [Performance Benchmarks](https://IBM.github.io/chuk-mcp-server/benchmarks) f
 
 ### Real-World Examples
 
+- **[chuk-mcp-chart](https://github.com/chrishayuk/chuk-mcp-chart)** - Interactive chart server with MCP Apps views
 - **[chuk-mcp-linkedin](https://github.com/IBM/chuk-mcp-linkedin)** - LinkedIn OAuth integration
 - **[chuk-mcp-stage](https://github.com/IBM/chuk-mcp-stage)** - 3D scene management with Google Drive
 

examples/mcp_apps_view_example.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+MCP Apps View Example — render rich UI views in Claude.ai
+
+This example shows how to create tools that render interactive views
+(charts, maps, tables, etc.) using MCP Apps structured content.
+
+When Claude.ai calls a tool with `_meta.ui`, it:
+1. Reads the view HTML via `resources/read` on the `resourceUri`
+2. Renders it in an iframe
+3. Passes `structuredContent` as the data payload
+
+ChukMCPServer handles step 1 automatically — when you register a tool
+with `_meta.ui.resourceUri` (ui:// scheme) and `_meta.ui.viewUrl`,
+the server auto-creates a resource that fetches the HTML from the CDN.
+
+Requirements:
+    pip install chuk-mcp-server httpx
+"""
+
+from chuk_mcp_server import ChukMCPServer
+
+mcp = ChukMCPServer(
+    name="view-example",
+    version="1.0.0",
+    description="MCP Apps view example server",
+)
+
+
+# ---------------------------------------------------------------------------
+# A tool that renders a chart view in Claude.ai
+# ---------------------------------------------------------------------------
+#
+# The `meta` dict tells Claude.ai this tool produces a rich view:
+#   - resourceUri: a ui:// URI identifying the view (used for resources/read)
+#   - viewUrl: the HTTPS URL serving the view's HTML/JS bundle
+#
+# ChukMCPServer automatically:
+#   - Registers a resource at the resourceUri that fetches HTML from viewUrl
+#   - Enables the `experimental` capability
+#
+@mcp.tool(
+    name="show_chart",
+    description="Show programming language popularity as a chart.",
+    read_only_hint=True,
+    meta={
+        "ui": {
+            "resourceUri": "ui://view-example/chart",
+            "viewUrl": "https://chuk-mcp-ui-views.fly.dev/chart/v1",
+        }
+    },
+)
+async def show_chart(chart_type: str = "bar") -> dict:
+    """Render a chart. Returns structured content for the view iframe."""
+    return {
+        "content": [{"type": "text", "text": "Programming language popularity chart."}],
+        "structuredContent": {
+            "type": "chart",
+            "version": "1.0",
+            "title": "Programming Language Popularity 2025",
+            "chartType": chart_type,
+            "data": [
+                {
+                    "label": "Popularity (%)",
+                    "values": [
+                        {"label": "Python", "value": 28.1},
+                        {"label": "JavaScript", "value": 21.3},
+                        {"label": "TypeScript", "value": 12.7},
+                        {"label": "Java", "value": 10.5},
+                        {"label": "C#", "value": 7.8},
+                        {"label": "Go", "value": 5.2},
+                        {"label": "Rust", "value": 3.9},
+                    ],
+                }
+            ],
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# A tool that renders a markdown view
+# ---------------------------------------------------------------------------
+@mcp.tool(
+    name="show_readme",
+    description="Show a rich markdown document.",
+    read_only_hint=True,
+    meta={
+        "ui": {
+            "resourceUri": "ui://view-example/markdown",
+            "viewUrl": "https://chuk-mcp-ui-views.fly.dev/markdown/v1",
+        }
+    },
+)
+async def show_readme() -> dict:
+    """Render a markdown document in a rich view."""
+    return {
+        "content": [{"type": "text", "text": "Project README document."}],
+        "structuredContent": {
+            "type": "markdown",
+            "version": "1.0",
+            "title": "My Project",
+            "content": (
+                "# My Project\n\n"
+                "A sample project demonstrating **MCP Apps** views.\n\n"
+                "## Features\n\n"
+                "- Interactive charts\n"
+                "- Rich markdown rendering\n"
+                "- Data tables with sorting\n\n"
+                "```python\n"
+                'mcp.tool(meta={"ui": {...}})\n'
+                "```\n"
+            ),
+        },
+    }
+
+
+if __name__ == "__main__":
+    mcp.run()

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-mcp-server"
-version = "0.23.4"
+version = "0.23.9"
 description = "A developer-friendly MCP framework powered by chuk_mcp"
 readme = "README.md"
 license = {text = "Apache-2.0"}

src/chuk_mcp_server/endpoints/mcp.py

@@ -247,7 +247,7 @@ async def _handle_post(self, request: Request) -> Response:
             request_data = orjson.loads(body) if body else {}
             method = request_data.get(KEY_METHOD)
 
-            logger.debug(f"Processing {method} request")
+            logger.warning(f"MCP: {method} (session={session_id and session_id[:8]})")
 
             # Notifications (no "id") get a 202 immediately — no SSE stream needed
             is_notification = KEY_ID not in request_data
@@ -296,7 +296,14 @@ async def _handle_json_request(
                 HEADER_CORS_ORIGIN: CORS_ALLOW_ALL,
                 HEADER_MCP_PROTOCOL_VERSION: protocol_version,
             }
-            return Response("", status_code=HttpStatus.ACCEPTED, headers=headers)
+            if effective_session:
+                headers[HEADER_MCP_SESSION_ID] = effective_session
+            return Response(
+                "",
+                status_code=HttpStatus.ACCEPTED,
+                media_type=CONTENT_TYPE_JSON,
+                headers=headers,
+            )
 
         # Build response headers
         headers = {
@@ -388,18 +395,24 @@ async def _handle_sse_request(
             created_session_id = self.protocol.session_manager.create_session(client_info, protocol_version)
             logger.info(f"Created SSE session: {created_session_id[:8]}...")
 
+        effective_session = created_session_id or session_id
         return StreamingResponse(
-            self._sse_stream_generator(request_data, created_session_id or session_id, method, oauth_token),
-            headers=self._sse_headers(created_session_id),
+            self._sse_stream_generator(request_data, effective_session, method, oauth_token),
+            headers=self._sse_headers(effective_session),
         )
 
     def _emit_sse_event(self, event_type: str, data: dict[str, Any], session_id: str | None) -> tuple[str, ...]:
-        """Build SSE event lines with optional event ID for resumability."""
+        """Build SSE event lines.
+
+        Events are buffered internally for Last-Event-ID resumability but
+        the ``id:`` field is NOT emitted in the SSE stream (matching FastMCP
+        behaviour).  The replay path (_handle_get with Last-Event-ID) does
+        include ``id:`` so clients can resume correctly.
+        """
         lines: list[str] = [event_type]
         if session_id:
             event_id = self.protocol.next_sse_event_id(session_id)
             self.protocol.buffer_sse_event(session_id, event_id, data)
-            lines.append(f"id: {event_id}\r\n")
         data_str: str = orjson.dumps(data).decode()
         lines.append(f"data: {data_str}\r\n")
         lines.append(SSE_LINE_END)

src/chuk_mcp_server/protocol/handler.py

@@ -146,10 +146,83 @@ def _sse_event_counters(self) -> dict[str, int]:
     # ================================================================
 
     def register_tool(self, tool: ToolHandler) -> None:
-        """Register a tool handler."""
+        """Register a tool handler.
+
+        Automatically enables ``experimental`` capability when a tool
+        carries ``_meta`` (e.g. MCP Apps view tools), matching FastMCP
+        behaviour so clients know structured content is supported.
+
+        When a tool has ``_meta.ui.resourceUri`` and ``_meta.ui.viewUrl``,
+        a resource handler is auto-registered so that clients (e.g. Claude.ai)
+        can ``resources/read`` the view HTML inline.
+        """
         self.tools[tool.name] = tool
+        if tool.meta and not getattr(self.capabilities, "experimental", None):
+            if hasattr(self.capabilities, "enable_experimental"):
+                self.capabilities.enable_experimental()
+                logger.debug("Enabled experimental capability (tool with _meta registered)")
+
+        # Auto-register view resource when tool has _meta.ui with viewUrl
+        if tool.meta:
+            self._maybe_register_view_resource(tool.meta)
+
         logger.debug(f"Registered tool: {tool.name}")
 
+    def _maybe_register_view_resource(self, meta: dict[str, Any]) -> None:
+        """Auto-register an MCP resource for a view tool's HTML.
+
+        When a tool declares ``_meta.ui.resourceUri`` (a ``ui://`` URI) and
+        ``_meta.ui.viewUrl`` (the HTTPS URL serving the view HTML), the
+        server automatically creates a resource handler that fetches the
+        HTML from the CDN and serves it via ``resources/read``.  This is
+        required for clients like Claude.ai that load MCP Apps views inline.
+        """
+        if not isinstance(meta, dict):
+            return
+        ui = meta.get("ui")
+        if not ui:
+            return
+
+        resource_uri = ui.get("resourceUri", "")
+        view_url = ui.get("viewUrl")
+
+        if not resource_uri or not view_url:
+            return
+
+        # Only handle ui:// scheme URIs
+        if not resource_uri.startswith("ui://"):
+            return
+
+        # Skip if already registered
+        if resource_uri in self.resources:
+            return
+
+        try:
+            import httpx  # noqa: F811 — lazy import, transitive dep
+
+            async def _fetch_view_html() -> str:
+                async with httpx.AsyncClient() as client:
+                    resp = await client.get(view_url, follow_redirects=True)
+                    resp.raise_for_status()
+                    return resp.text
+
+            # Derive a short name from the URI (e.g. "ui://server/chart" → "chart")
+            view_name = resource_uri.rsplit("/", 1)[-1] if "/" in resource_uri else resource_uri
+
+            resource = ResourceHandler.from_function(
+                uri=resource_uri,
+                func=_fetch_view_html,
+                name=view_name,
+                description=f"{view_name.title()} view HTML",
+                mime_type="text/html;profile=mcp-app",
+                cache_ttl=3600,  # Cache for 1 hour — view HTML rarely changes
+            )
+            self.register_resource(resource)
+            logger.debug(f"Auto-registered view resource: {resource_uri} → {view_url}")
+
+        except ImportError:
+            logger.debug("httpx not available; skipping auto view resource for %s", resource_uri)
+
     def register_resource(self, resource: ResourceHandler) -> None:
         """Register a resource handler."""
         self.resources[resource.uri] = resource

src/chuk_mcp_server/types/capabilities.py

@@ -33,6 +33,17 @@ def __init__(
         self._filter_kwargs: dict[str, Any] = _filter_kwargs or {}
         self._experimental: dict[str, Any] | None = _experimental
 
+    def enable_experimental(self, value: dict[str, Any] | None = None) -> None:
+        """Dynamically enable the ``experimental`` capability.
+
+        Called automatically when a tool with ``_meta`` is registered so
+        that clients (e.g. Claude.ai) know structured content is supported.
+        """
+        exp = value if value is not None else {}
+        self._experimental = exp
+        self._filter_kwargs["experimental"] = exp
+        object.__setattr__(self, "experimental", exp)
+
     def model_dump(self, **dump_kwargs: Any) -> dict[str, Any]:
         """Filter out unwanted fields from model_dump"""
         result = super().model_dump(**dump_kwargs)

tests/endpoints/test_mcp.py

@@ -306,12 +306,11 @@ async def test_sse_stream_generator_success(self):
         async for chunk in self.endpoint._sse_stream_generator(request_data, "test-session", "tools/list"):
             stream_data.append(chunk)
 
-        # Verify SSE format: event, id, data, blank line
-        assert len(stream_data) == 4
+        # Verify SSE format: event, data, blank line (no id: field, matching FastMCP)
+        assert len(stream_data) == 3
         assert stream_data[0] == "event: message\r\n"
-        assert stream_data[1] == "id: 1\r\n"
-        assert stream_data[2] == f"data: {orjson.dumps(mock_response).decode()}\r\n"
-        assert stream_data[3] == "\r\n"
+        assert stream_data[1] == f"data: {orjson.dumps(mock_response).decode()}\r\n"
+        assert stream_data[2] == "\r\n"
 
     @pytest.mark.asyncio
     async def test_sse_stream_generator_notification(self):
@@ -338,20 +337,19 @@ async def test_sse_stream_generator_exception(self):
         async for chunk in self.endpoint._sse_stream_generator(request_data, "test-session", "tools/list"):
             stream_data.append(chunk)
 
-        # Verify error event format: event, id, data, blank line
-        assert len(stream_data) == 4
+        # Verify error event format: event, data, blank line (no id: field, matching FastMCP)
+        assert len(stream_data) == 3
         assert stream_data[0] == "event: error\r\n"
-        assert stream_data[1] == "id: 1\r\n"
 
         # Parse error data
-        error_data = stream_data[2].replace("data: ", "").replace("\r\n", "")
+        error_data = stream_data[1].replace("data: ", "").replace("\r\n", "")
         error_response = orjson.loads(error_data)
         assert error_response["jsonrpc"] == "2.0"
         assert error_response["id"] == "test-id"
         assert error_response["error"]["code"] == -32603
         assert error_response["error"]["message"] == "Internal server error"
 
-        assert stream_data[3] == "\r\n"
+        assert stream_data[2] == "\r\n"
 
     def test_cors_response(self):
         """Test CORS response generation."""
@@ -436,8 +434,8 @@ async def test_logging_integration(self):
         with patch("chuk_mcp_server.endpoints.mcp.logger") as mock_logger:
             await self.endpoint.handle_request(request)
 
-            # Verify debug logging was called
-            mock_logger.debug.assert_called_with("Processing tools/list request")
+            # Verify method logging was called
+            mock_logger.warning.assert_any_call("MCP: tools/list (session=test-ses)")
 
     @pytest.mark.asyncio
     async def test_complex_sse_initialize_flow(self):