Render markdown resources via react-markdown + fix preview overflow

- Add react-markdown / remark-gfm dependencies.
- ContentViewer accepts an optional mimeType prop; when it matches
  text/markdown (or text/x-markdown), text blocks render via
  react-markdown wrapped in a `.markdown-content` container. Non-markdown
  text now uses the existing Code "wrapping" variant so long lines stay
  inside the panel.
- ResourcePreviewPanel infers `text/markdown` from a `.md` / `.markdown`
  URI suffix when the server didn't supply a mimeType, and threads the
  effective mime through to ContentViewer per content item.
- ResourcesScreen flex children get miw=0 so a long unwrappable line in
  the resource body can no longer push the preview past the viewport's
  right edge.
- App.css gains a `.markdown-content` ruleset constraining nested pre,
  table, code, and img elements to the container's width.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: cliffhall

clients/web/package-lock.json

@@ -39,6 +39,8 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-icons": "^5.6.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
     "zod": "^4.3.6",
     "zustand": "^5.0.13"
   },

clients/web/package.json

@@ -147,3 +147,38 @@
 .grid-align-start {
   align-items: start;
 }
+
+/* ── Markdown content (third-party HTML from react-markdown) ───── */
+
+.markdown-content {
+  max-width: 100%;
+  overflow-wrap: anywhere;
+}
+
+.markdown-content > :first-child {
+  margin-top: 0;
+}
+
+.markdown-content > :last-child {
+  margin-bottom: 0;
+}
+
+.markdown-content pre {
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.markdown-content code {
+  word-break: break-word;
+}
+
+.markdown-content table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.markdown-content img {
+  max-width: 100%;
+  height: auto;
+}

clients/web/src/App.css

@@ -104,4 +104,42 @@ describe("ContentViewer", () => {
     expect(screen.queryByRole("img")).not.toBeInTheDocument();
     expect(screen.queryByRole("button")).not.toBeInTheDocument();
   });
+
+  it("renders text as markdown when mimeType is text/markdown", () => {
+    const block: ContentBlock = {
+      type: "text",
+      text: "# Title\n\nSome **bold** text.",
+    };
+    renderWithMantine(<ContentViewer block={block} mimeType="text/markdown" />);
+    expect(
+      screen.getByRole("heading", { level: 1, name: "Title" }),
+    ).toBeInTheDocument();
+    expect(screen.getByText("bold")).toBeInTheDocument();
+  });
+
+  it("accepts mimeType with parameters (e.g. text/markdown; charset=utf-8)", () => {
+    const block: ContentBlock = { type: "text", text: "# Heading" };
+    renderWithMantine(
+      <ContentViewer block={block} mimeType="text/markdown; charset=utf-8" />,
+    );
+    expect(
+      screen.getByRole("heading", { level: 1, name: "Heading" }),
+    ).toBeInTheDocument();
+  });
+
+  it("falls back to code rendering for non-markdown mime types", () => {
+    const block: ContentBlock = { type: "text", text: "# not markdown" };
+    renderWithMantine(<ContentViewer block={block} mimeType="text/plain" />);
+    expect(screen.getByText("# not markdown")).toBeInTheDocument();
+    // No <h1> generated by react-markdown
+    expect(screen.queryByRole("heading", { level: 1 })).not.toBeInTheDocument();
+  });
+
+  it("renders a copy overlay for markdown content when copyable", () => {
+    const block: ContentBlock = { type: "text", text: "# hi" };
+    renderWithMantine(
+      <ContentViewer block={block} mimeType="text/markdown" copyable />,
+    );
+    expect(screen.getByRole("button")).toBeInTheDocument();
+  });
 });

clients/web/src/components/elements/ContentViewer/ContentViewer.test.tsx

@@ -1,10 +1,18 @@
 import { Code, Flex, Image, Stack, Text } from "@mantine/core";
 import type { ContentBlock } from "@modelcontextprotocol/sdk/types.js";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
 import { CopyButton } from "../CopyButton/CopyButton";
 
 export interface ContentViewerProps {
   block: ContentBlock;
   copyable?: boolean;
+  /**
+   * Optional MIME type for the block. When `text/markdown` (or
+   * `text/x-markdown`), text content is rendered via react-markdown
+   * instead of as preformatted code.
+   */
+  mimeType?: string;
 }
 
 function formatJson(content: string): string {
@@ -21,6 +29,12 @@ function isJsonText(block: ContentBlock): boolean {
   return trimmed.startsWith("{") || trimmed.startsWith("[");
 }
 
+function isMarkdownMime(mimeType: string | undefined): boolean {
+  if (!mimeType) return false;
+  const base = mimeType.split(";")[0].trim().toLowerCase();
+  return base === "text/markdown" || base === "text/x-markdown";
+}
+
 function buildDataUri(mimeType: string, data: string): string {
   return `data:${mimeType};base64,${data}`;
 }
@@ -36,21 +50,49 @@ const CopyOverlay = Flex.withProps({
   right: 4,
 });
 
+const MarkdownWrapper = Flex.withProps({
+  className: "markdown-content",
+  direction: "column",
+});
+
 const PreviewImage = Image.withProps({
   alt: "Content preview",
   maw: 400,
   radius: "md",
 });
 
-export function ContentViewer({ block, copyable = false }: ContentViewerProps) {
+export function ContentViewer({
+  block,
+  copyable = false,
+  mimeType,
+}: ContentViewerProps) {
   switch (block.type) {
     case "text": {
+      const renderAsMarkdown = isMarkdownMime(mimeType);
+      if (renderAsMarkdown) {
+        return (
+          <Stack gap="xs">
+            <ContentWrapper>
+              <MarkdownWrapper>
+                <ReactMarkdown remarkPlugins={[remarkGfm]}>
+                  {block.text}
+                </ReactMarkdown>
+              </MarkdownWrapper>
+              {copyable && (
+                <CopyOverlay>
+                  <CopyButton value={block.text} />
+                </CopyOverlay>
+              )}
+            </ContentWrapper>
+          </Stack>
+        );
+      }
       const isJson = isJsonText(block);
       const displayText = isJson ? formatJson(block.text) : block.text;
       return (
         <Stack gap="xs">
           <ContentWrapper>
-            <Code block p={36}>
+            <Code block p={36} variant="wrapping">
               {displayText}
             </Code>
             {copyable && (

clients/web/src/components/elements/ContentViewer/ContentViewer.tsx

@@ -199,4 +199,59 @@ describe("ResourcePreviewPanel", () => {
     );
     expect(screen.getByText("text/markdown")).toBeInTheDocument();
   });
+
+  it("renders text/markdown content as markdown", () => {
+    renderWithMantine(
+      <ResourcePreviewPanel
+        {...baseProps}
+        resource={{ name: "readme", uri: "file:///readme.md" }}
+        contents={[
+          {
+            uri: "file:///readme.md",
+            mimeType: "text/markdown",
+            text: "# Hello",
+          },
+        ]}
+      />,
+    );
+    expect(
+      screen.getByRole("heading", { level: 1, name: "Hello" }),
+    ).toBeInTheDocument();
+  });
+
+  it("infers markdown from a .md URI when mimeType is missing", () => {
+    renderWithMantine(
+      <ResourcePreviewPanel
+        {...baseProps}
+        resource={{ name: "notes", uri: "demo://resource/notes.md" }}
+        contents={[
+          {
+            uri: "demo://resource/notes.md",
+            text: "## From URI",
+          },
+        ]}
+      />,
+    );
+    expect(
+      screen.getByRole("heading", { level: 2, name: "From URI" }),
+    ).toBeInTheDocument();
+  });
+
+  it("does not render plain-text content as markdown even with markdown-looking text", () => {
+    renderWithMantine(
+      <ResourcePreviewPanel
+        {...baseProps}
+        resource={{ name: "notes", uri: "file:///notes.txt" }}
+        contents={[
+          {
+            uri: "file:///notes.txt",
+            mimeType: "text/plain",
+            text: "# not a heading",
+          },
+        ]}
+      />,
+    );
+    expect(screen.queryByRole("heading", { level: 1 })).not.toBeInTheDocument();
+    expect(screen.getByText("# not a heading")).toBeInTheDocument();
+  });
 });

clients/web/src/components/groups/ResourcePreviewPanel/ResourcePreviewPanel.test.tsx

@@ -88,6 +88,30 @@ const ActionGroup = Group.withProps({
 
 const Spacer = Flex.withProps({});
 
+// Infer a markdown MIME from the URI when the server didn't supply one.
+// MCP servers often return `text/plain` (or omit mimeType entirely) for
+// `.md` resources; the file extension is the most reliable fallback signal.
+function inferMimeFromUri(uri: string): string | undefined {
+  const path = uri.split("?")[0].split("#")[0];
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".md") || lower.endsWith(".markdown")) {
+    return "text/markdown";
+  }
+  return undefined;
+}
+
+function effectiveMime(
+  itemMime: string | undefined,
+  resource: Resource,
+): string {
+  return (
+    itemMime ??
+    resource.mimeType ??
+    inferMimeFromUri(resource.uri) ??
+    "application/octet-stream"
+  );
+}
+
 export function ResourcePreviewPanel({
   resource,
   contents,
@@ -98,8 +122,7 @@ export function ResourcePreviewPanel({
   onUnsubscribe,
 }: ResourcePreviewPanelProps) {
   const { uri, annotations } = resource;
-  const mimeType =
-    contents[0]?.mimeType ?? resource.mimeType ?? "application/octet-stream";
+  const mimeType = effectiveMime(contents[0]?.mimeType, resource);
 
   return (
     <Stack gap="md">
@@ -111,7 +134,12 @@ export function ResourcePreviewPanel({
         </UriGroup>
       </HeaderRow>
       {contents.map((item, index) => (
-        <ContentViewer key={index} block={toContentBlock(item)} copyable />
+        <ContentViewer
+          key={index}
+          block={toContentBlock(item)}
+          mimeType={effectiveMime(item.mimeType, resource)}
+          copyable
+        />
       ))}
       <MetaRow>
         {lastUpdated ? (

clients/web/src/components/groups/ResourcePreviewPanel/ResourcePreviewPanel.tsx

@@ -183,16 +183,16 @@ export function ResourcesScreen({
       </Sidebar>
 
       {selectedTemplate ? (
-        <Group flex={1} gap="md" align="flex-start" wrap="nowrap">
-          <ScrollArea.Autosize flex={1} mah={SCROLL_MAX_HEIGHT}>
+        <Group flex={1} miw={0} gap="md" align="flex-start" wrap="nowrap">
+          <ScrollArea.Autosize flex={1} miw={0} mah={SCROLL_MAX_HEIGHT}>
             <DetailCard>
               <ResourceTemplatePanel
                 template={selectedTemplate}
                 onReadResource={handleReadResource}
               />
             </DetailCard>
           </ScrollArea.Autosize>
-          <ScrollArea.Autosize flex={1} mah={SCROLL_MAX_HEIGHT}>
+          <ScrollArea.Autosize flex={1} miw={0} mah={SCROLL_MAX_HEIGHT}>
             {renderReadState() ?? (
               <DetailCard>
                 <EmptyState>Enter a URI and click Read to preview</EmptyState>
@@ -201,7 +201,10 @@ export function ResourcesScreen({
           </ScrollArea.Autosize>
         </Group>
       ) : selectedResource ? (
-        <ScrollArea.Autosize flex={1} mah={SCROLL_MAX_HEIGHT}>
+        // miw=0 lets the flex item shrink below its content's intrinsic
+        // width; without it a single long unwrappable line in the resource
+        // body would push the panel past the viewport's right edge.
+        <ScrollArea.Autosize flex={1} miw={0} mah={SCROLL_MAX_HEIGHT}>
           {renderReadState()}
         </ScrollArea.Autosize>
       ) : (