Fix/mcp app blank UI (#580)

* fix: use official ext-apps useApp hook to fix blank MCP App rendering

The custom useToolData hook had lifecycle issues that prevented the UI
from rendering in Claude Desktop/web: no appInfo in App constructor,
unhandled connect() Promise, app.close() on unmount conflicting with
React Strict Mode. Switched to the official useApp hook from
@modelcontextprotocol/ext-apps/react which handles initialization
handshake, handler registration, and cleanup correctly.

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: align MCP App UI types with actual server response format

- useToolData hook now uses official useApp from ext-apps/react
- OperationResultData uses success:boolean + data.id/name (matching
  McpToolResponse from handlers-n8n-manager.ts)
- ValidationSummaryData handles both direct results (validate_node,
  validate_workflow) and wrapped results (n8n_validate_workflow)
- Added visible error/connection states for debugging

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: bump version to 2.34.5 for npm publish

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.github/workflows/release.yml

@@ -283,8 +283,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
       
-      - name: Build project
+      - name: Build project (server + UI apps)
-        run: npm run build
+        run: npm run build:all
 
       # Database is already built and committed during development
       # Rebuilding here causes segfault due to memory pressure (exit code 139)
@@ -322,8 +322,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
       
-      - name: Build project
+      - name: Build project (server + UI apps)
-        run: npm run build
+        run: npm run build:all
 
       # Database is already built and committed during development
       - name: Verify database exists
@@ -347,6 +347,8 @@ jobs:
           # Copy necessary files
           cp -r dist $PUBLISH_DIR/
           cp -r data $PUBLISH_DIR/
+          mkdir -p $PUBLISH_DIR/ui-apps
+          cp -r ui-apps/dist $PUBLISH_DIR/ui-apps/
           cp README.md $PUBLISH_DIR/
           cp LICENSE $PUBLISH_DIR/
           cp .env.example $PUBLISH_DIR/
@@ -377,7 +379,7 @@ jobs:
           pkg.license = 'MIT';
           pkg.bugs = { url: 'https://github.com/czlonkowski/n8n-mcp/issues' };
           pkg.homepage = 'https://github.com/czlonkowski/n8n-mcp#readme';
-          pkg.files = ['dist/**/*', 'data/nodes.db', '.env.example', 'README.md', 'LICENSE'];
+          pkg.files = ['dist/**/*', 'ui-apps/dist/**/*', 'data/nodes.db', '.env.example', 'README.md', 'LICENSE'];
           delete pkg.private;
           require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2));
           "

CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.34.5] - 2026-02-08
+
+### Fixed
+
+- **MCP Apps: Fix blank UI and wrong status badge in Claude**: Rewrote `useToolData` hook to use the official `useApp` hook from `@modelcontextprotocol/ext-apps/react` for proper lifecycle management. Updated UI types and components to match actual server response format (`success: boolean` instead of `status: string`, nested `data` object for workflow details). Validation summary now handles both direct and wrapped (`n8n_validate_workflow`) response shapes.
+
+Conceived by Romuald Czlonkowski - https://www.aiadvisors.pl/en
+
+## [2.34.3] - 2026-02-07
+
+### Fixed
+
+- **MCP Apps: Use correct MIME type for ext-apps spec**: Changed resource MIME type from `text/html` to `text/html;profile=mcp-app` (the `RESOURCE_MIME_TYPE` constant from `@modelcontextprotocol/ext-apps`). Without this profile parameter, Claude Desktop/web fails to recognize resources as MCP Apps and shows "Failed to load MCP App: the resource may exceed the 5 MB size limit."
+
+Conceived by Romuald Czlonkowski - https://www.aiadvisors.pl/en
+
+## [2.34.2] - 2026-02-07
+
+### Fixed
+
+- **CI: UI apps missing from npm package**: Release pipeline only ran `npm run build` (TypeScript), so `ui-apps/dist/` was never built and excluded from published packages
+  - Changed build step to `npm run build:all` in `build-and-verify` and `publish-npm` jobs
+  - Added `ui-apps/dist/` to npm publish staging directory
+  - Added `ui-apps/dist/**/*` to published package files list
+
+Conceived by Romuald Czlonkowski - https://www.aiadvisors.pl/en
+
 ## [2.34.1] - 2026-02-07
 
 ### Changed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.34.1",
+  "version": "2.34.5",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/mcp/ui/app-configs.ts

@@ -6,7 +6,7 @@ export const UI_APP_CONFIGS: UIAppConfig[] = [
     displayName: 'Operation Result',
     description: 'Visual summary of workflow operations (create, update, delete, test)',
     uri: 'ui://n8n-mcp/operation-result',
-    mimeType: 'text/html',
+    mimeType: 'text/html;profile=mcp-app',
     toolPatterns: [
       'n8n_create_workflow',
       'n8n_update_full_workflow',
@@ -22,7 +22,7 @@ export const UI_APP_CONFIGS: UIAppConfig[] = [
     displayName: 'Validation Summary',
     description: 'Visual summary of node and workflow validation results',
     uri: 'ui://n8n-mcp/validation-summary',
-    mimeType: 'text/html',
+    mimeType: 'text/html;profile=mcp-app',
     toolPatterns: [
       'validate_node',
       'validate_workflow',

tests/unit/mcp/ui/app-configs.test.ts

@@ -65,9 +65,9 @@ describe('UI_APP_CONFIGS', () => {
     }
   });
 
-  it('should have consistent mimeType of text/html', () => {
+  it('should have consistent mimeType of text/html;profile=mcp-app', () => {
     for (const config of UI_APP_CONFIGS) {
-      expect(config.mimeType).toBe('text/html');
+      expect(config.mimeType).toBe('text/html;profile=mcp-app');
     }
   });
 

ui-apps/src/apps/operation-result/App.tsx

@@ -5,13 +5,26 @@ import { useToolData } from '@shared/hooks/useToolData';
 import type { OperationResultData } from '@shared/types';
 
 export default function App() {
-  const data = useToolData<OperationResultData>();
+  const { data, error, isConnected } = useToolData<OperationResultData>();
 
-  if (!data) {
+  if (error) {
-    return <div style={{ padding: '16px', color: 'var(--n8n-text-muted)' }}>Loading...</div>;
+    return <div style={{ padding: '16px', color: '#ef4444' }}>Error: {error}</div>;
   }
 
-  const isSuccess = data.status === 'success';
+  if (!isConnected) {
+    return <div style={{ padding: '16px', color: '#9ca3af' }}>Connecting...</div>;
+  }
+
+  if (!data) {
+    return <div style={{ padding: '16px', color: '#9ca3af' }}>Waiting for data...</div>;
+  }
+
+  const isSuccess = data.success === true;
+  const workflowName = data.data?.name || data.data?.workflowName;
+  const workflowId = data.data?.id || data.data?.workflowId;
+  const nodeCount = data.data?.nodeCount;
+  const isDeleted = data.data?.deleted === true;
+  const operationsApplied = data.data?.operationsApplied;
 
   return (
     <div style={{ maxWidth: '480px' }}>
@@ -19,66 +32,35 @@ export default function App() {
         <Badge variant={isSuccess ? 'success' : 'error'}>
           {isSuccess ? 'Success' : 'Error'}
         </Badge>
-        <h2 style={{ fontSize: '16px', fontWeight: 600 }}>{data.operation}</h2>
       </div>
 
+      {(workflowName || workflowId) && (
         <Card title="Workflow">
           <div style={{ fontSize: '14px' }}>
-          {data.workflowName && <div><strong>Name:</strong> {data.workflowName}</div>}
+            {workflowName && <div><strong>Name:</strong> {workflowName}</div>}
-          {data.workflowId && <div><strong>ID:</strong> {data.workflowId}</div>}
+            {workflowId && <div><strong>ID:</strong> {workflowId}</div>}
-          {data.timestamp && (
+            {nodeCount !== undefined && <div><strong>Nodes:</strong> {nodeCount}</div>}
-            <div style={{ color: 'var(--n8n-text-muted)', fontSize: '12px', marginTop: '4px' }}>
+            {isDeleted && <div style={{ color: 'var(--n8n-warning)', marginTop: '4px' }}>Deleted</div>}
-              {data.timestamp}
+            {operationsApplied !== undefined && (
-            </div>
+              <div><strong>Operations applied:</strong> {operationsApplied}</div>
             )}
           </div>
         </Card>
+      )}
 
-      {data.message && (
+      {(data.message || data.error) && (
         <Card>
-          <div style={{ fontSize: '13px' }}>{data.message}</div>
+          <div style={{ fontSize: '13px' }}>{data.message || data.error}</div>
         </Card>
       )}
 
-      {data.changes && (
+      {data.details && (
-        <>
+        <Expandable title="Details">
-          {data.changes.nodesAdded && data.changes.nodesAdded.length > 0 && (
+          <pre style={{ fontSize: '11px', whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}>
-            <Expandable title="Nodes Added" count={data.changes.nodesAdded.length} defaultOpen>
+            {JSON.stringify(data.details, null, 2)}
-              <ul style={{ listStyle: 'none', fontSize: '13px' }}>
+          </pre>
-                {data.changes.nodesAdded.map((node, i) => (
-                  <li key={i} style={{ padding: '4px 0', borderBottom: '1px solid var(--n8n-border)' }}>
-                    <span style={{ color: 'var(--n8n-success)' }}>+</span> {node}
-                  </li>
-                ))}
-              </ul>
         </Expandable>
       )}
-
-          {data.changes.nodesModified && data.changes.nodesModified.length > 0 && (
-            <Expandable title="Nodes Modified" count={data.changes.nodesModified.length}>
-              <ul style={{ listStyle: 'none', fontSize: '13px' }}>
-                {data.changes.nodesModified.map((node, i) => (
-                  <li key={i} style={{ padding: '4px 0', borderBottom: '1px solid var(--n8n-border)' }}>
-                    <span style={{ color: 'var(--n8n-warning)' }}>~</span> {node}
-                  </li>
-                ))}
-              </ul>
-            </Expandable>
-          )}
-
-          {data.changes.nodesRemoved && data.changes.nodesRemoved.length > 0 && (
-            <Expandable title="Nodes Removed" count={data.changes.nodesRemoved.length}>
-              <ul style={{ listStyle: 'none', fontSize: '13px' }}>
-                {data.changes.nodesRemoved.map((node, i) => (
-                  <li key={i} style={{ padding: '4px 0', borderBottom: '1px solid var(--n8n-border)' }}>
-                    <span style={{ color: 'var(--n8n-error)' }}>-</span> {node}
-                  </li>
-                ))}
-              </ul>
-            </Expandable>
-          )}
-        </>
-      )}
     </div>
   );
 }

ui-apps/src/apps/validation-summary/App.tsx

@@ -2,40 +2,59 @@ import React from 'react';
 import '@shared/styles/theme.css';
 import { Card, Badge, Expandable } from '@shared/components';
 import { useToolData } from '@shared/hooks/useToolData';
-import type { ValidationSummaryData } from '@shared/types';
+import type { ValidationSummaryData, ValidationError, ValidationWarning } from '@shared/types';
 
 export default function App() {
-  const data = useToolData<ValidationSummaryData>();
+  const { data: raw, error, isConnected } = useToolData<ValidationSummaryData>();
 
-  if (!data) {
+  if (error) {
-    return <div style={{ padding: '16px', color: 'var(--n8n-text-muted)' }}>Loading...</div>;
+    return <div style={{ padding: '16px', color: '#ef4444' }}>Error: {error}</div>;
   }
 
+  if (!isConnected) {
+    return <div style={{ padding: '16px', color: '#9ca3af' }}>Connecting...</div>;
+  }
+
+  if (!raw) {
+    return <div style={{ padding: '16px', color: '#9ca3af' }}>Waiting for data...</div>;
+  }
+
+  // n8n_validate_workflow wraps result in { success, data: {...} }
+  // validate_node and validate_workflow return data directly
+  const inner = raw.data || raw;
+  const valid = inner.valid ?? raw.valid ?? false;
+  const displayName = raw.displayName || raw.data?.workflowName;
+  const errors: ValidationError[] = inner.errors || raw.errors || [];
+  const warnings: ValidationWarning[] = inner.warnings || raw.warnings || [];
+  const suggestions: string[] = inner.suggestions || raw.suggestions || [];
+  const errorCount = raw.summary?.errorCount ?? inner.summary?.errorCount ?? errors.length;
+  const warningCount = raw.summary?.warningCount ?? inner.summary?.warningCount ?? warnings.length;
+
   return (
     <div style={{ maxWidth: '480px' }}>
       <div style={{ display: 'flex', alignItems: 'center', gap: '12px', marginBottom: '16px' }}>
-        <Badge variant={data.valid ? 'success' : 'error'}>
+        <Badge variant={valid ? 'success' : 'error'}>
-          {data.valid ? 'Valid' : 'Invalid'}
+          {valid ? 'Valid' : 'Invalid'}
         </Badge>
-        {data.displayName && (
+        {displayName && (
-          <span style={{ fontSize: '14px', color: 'var(--n8n-text-muted)' }}>{data.displayName}</span>
+          <span style={{ fontSize: '14px', color: 'var(--n8n-text-muted)' }}>{displayName}</span>
         )}
       </div>
 
       <Card>
         <div style={{ display: 'flex', gap: '16px', fontSize: '13px' }}>
           <div>
-            <span style={{ color: 'var(--n8n-error)' }}>{data.errorCount}</span> errors
+            <span style={{ color: 'var(--n8n-error)' }}>{errorCount}</span> errors
           </div>
           <div>
-            <span style={{ color: 'var(--n8n-warning)' }}>{data.warningCount}</span> warnings
+            <span style={{ color: 'var(--n8n-warning)' }}>{warningCount}</span> warnings
           </div>
         </div>
       </Card>
 
-      {data.errors.length > 0 && (
+      {errors.length > 0 && (
-        <Expandable title="Errors" count={data.errors.length} defaultOpen>
+        <Expandable title="Errors" count={errors.length} defaultOpen>
-          {data.errors.map((err, i) => (
+          {errors.map((err, i) => (
             <div key={i} style={{
               padding: '8px',
               marginBottom: '6px',
@@ -44,7 +63,9 @@ export default function App() {
               fontSize: '12px',
               color: 'var(--n8n-error)',
             }}>
-              <div style={{ fontWeight: 600 }}>{err.type}</div>
+              {(err.type || err.node) && (
+                <div style={{ fontWeight: 600 }}>{err.type || err.node}</div>
+              )}
               {err.property && <div style={{ opacity: 0.8 }}>Property: {err.property}</div>}
               <div>{err.message}</div>
               {err.fix && (
@@ -55,9 +76,9 @@ export default function App() {
         </Expandable>
       )}
 
-      {data.warnings.length > 0 && (
+      {warnings.length > 0 && (
-        <Expandable title="Warnings" count={data.warnings.length}>
+        <Expandable title="Warnings" count={warnings.length}>
-          {data.warnings.map((warn, i) => (
+          {warnings.map((warn, i) => (
             <div key={i} style={{
               padding: '8px',
               marginBottom: '6px',
@@ -66,7 +87,9 @@ export default function App() {
               fontSize: '12px',
               color: 'var(--n8n-warning)',
             }}>
-              <div style={{ fontWeight: 600 }}>{warn.type}</div>
+              {(warn.type || warn.node) && (
+                <div style={{ fontWeight: 600 }}>{warn.type || warn.node}</div>
+              )}
               {warn.property && <div style={{ opacity: 0.8 }}>Property: {warn.property}</div>}
               <div>{warn.message}</div>
             </div>
@@ -74,10 +97,10 @@ export default function App() {
         </Expandable>
       )}
 
-      {data.suggestions && data.suggestions.length > 0 && (
+      {suggestions.length > 0 && (
-        <Expandable title="Suggestions" count={data.suggestions.length}>
+        <Expandable title="Suggestions" count={suggestions.length}>
           <ul style={{ paddingLeft: '16px', fontSize: '12px' }}>
-            {data.suggestions.map((suggestion, i) => (
+            {suggestions.map((suggestion, i) => (
               <li key={i} style={{ padding: '2px 0', color: 'var(--n8n-info)' }}>{suggestion}</li>
             ))}
           </ul>

ui-apps/src/shared/hooks/useToolData.ts

@@ -1,14 +1,17 @@
-import { useState, useEffect } from 'react';
+import { useState, useCallback } from 'react';
-import { App } from '@modelcontextprotocol/ext-apps';
+import { useApp } from '@modelcontextprotocol/ext-apps/react';
 
-export function useToolData<T>(): T | null {
+interface UseToolDataResult<T> {
+  data: T | null;
+  error: string | null;
+  isConnected: boolean;
+}
+
+export function useToolData<T>(): UseToolDataResult<T> {
   const [data, setData] = useState<T | null>(null);
 
-  useEffect(() => {
+  const onAppCreated = useCallback((app: any) => {
-    const app = new App();
-
     app.ontoolresult = (result: any) => {
-      // The host pushes tool result content; parse the first text item as JSON
       if (result?.content) {
         const textItem = Array.isArray(result.content)
           ? result.content.find((c: any) => c.type === 'text')
@@ -17,19 +20,22 @@ export function useToolData<T>(): T | null {
           try {
             setData(JSON.parse(textItem.text) as T);
           } catch {
-            // Not JSON — use raw text as-is
             setData(textItem.text as unknown as T);
           }
         }
       }
     };
-
-    app.connect();
-
-    return () => {
-      app.close();
-    };
   }, []);
 
-  return data;
+  const { isConnected, error } = useApp({
+    appInfo: { name: 'n8n-mcp-ui', version: '1.0.0' },
+    capabilities: {},
+    onAppCreated,
+  });
+
+  return {
+    data,
+    error: error?.message ?? null,
+    isConnected,
+  };
 }

ui-apps/src/shared/types.ts

@@ -1,38 +1,67 @@
+// Matches the McpToolResponse format from handlers-n8n-manager.ts
 export interface OperationResultData {
-  status: 'success' | 'error';
+  success: boolean;
-  operation: string;
+  data?: {
-  workflowName?: string;
+    id?: string;
+    name?: string;
+    active?: boolean;
+    nodeCount?: number;
     workflowId?: string;
-  timestamp?: string;
+    workflowName?: string;
-  message?: string;
+    deleted?: boolean;
-  changes?: {
+    operationsApplied?: number;
-    nodesAdded?: string[];
+    [key: string]: unknown;
-    nodesModified?: string[];
-    nodesRemoved?: string[];
   };
+  message?: string;
+  error?: string;
   details?: Record<string, unknown>;
 }
 
 export interface ValidationError {
-  type: string;
+  type?: string;
   property?: string;
   message: string;
   fix?: string;
+  node?: string;
+  details?: unknown;
 }
 
 export interface ValidationWarning {
-  type: string;
+  type?: string;
   property?: string;
   message: string;
+  node?: string;
+  details?: unknown;
 }
 
+// Matches the validate_node / validate_workflow response format from server.ts
 export interface ValidationSummaryData {
   valid: boolean;
-  errorCount: number;
+  nodeType?: string;
-  warningCount: number;
+  displayName?: string;
   errors: ValidationError[];
   warnings: ValidationWarning[];
   suggestions?: string[];
-  nodeType?: string;
+  summary?: {
-  displayName?: string;
+    errorCount?: number;
+    warningCount?: number;
+    hasErrors?: boolean;
+    suggestionCount?: number;
+    [key: string]: unknown;
+  };
+  // n8n_validate_workflow wraps result in success/data
+  success?: boolean;
+  data?: {
+    valid?: boolean;
+    workflowId?: string;
+    workflowName?: string;
+    errors?: ValidationError[];
+    warnings?: ValidationWarning[];
+    suggestions?: string[];
+    summary?: {
+      errorCount?: number;
+      warningCount?: number;
+      [key: string]: unknown;
+    };
+  };
 }