mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-02-08 22:33:08 +00:00
fix: align MCP Apps with official ext-apps spec (#574)
* feat: add MCP Apps with rich HTML UIs for tool results Add MCP Apps infrastructure that allows MCP hosts like Claude Desktop to render rich HTML UIs alongside tool results via `_meta.ui` and the MCP resources protocol. - Server-side UI module (src/mcp/ui/) with UIAppRegistry, tool-to-UI mapping, and _meta.ui injection into tool responses - React + Vite build pipeline (ui-apps/) producing self-contained HTML per app using vite-plugin-singlefile - Operation Result UI for workflow CRUD tools (create, update, delete, test, autofix, deploy) - Validation Summary UI for validation tools (validate_node, validate_workflow, n8n_validate_workflow) - Shared component library (Card, Badge, Expandable) with n8n dark theme - MCP resources protocol support (ListResources, ReadResource handlers) - Graceful degradation when ui-apps/dist/ is not built - 22 unit tests across 3 test files Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * test: improve MCP Apps test coverage and add security hardening - Expand test suite from 22 to 57 tests across 3 test files - Add UIAppRegistry.reset() for proper test isolation between tests - Replace some fs mocks with real temp directory tests in registry - Add edge case coverage: empty strings, pre-load state, double load, malformed URIs, duplicate tool patterns, empty HTML files - Add regression tests for specific tool-to-UI mappings - Add URI format consistency validation across all configs - Improve _meta.ui injection tests with structuredContent coexistence - Coverage: statements 79.4% -> 80%, lines 79.4% -> 80% Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: align MCP Apps with official ext-apps spec Update URI scheme from n8n-mcp://ui/ to ui://n8n-mcp/ per MCP spec. Move _meta.ui.resourceUri to tool definitions (tools/list) instead of tool call responses. Rewrite UI apps hook to use @modelcontextprotocol/ext-apps App class instead of window.__MCP_DATA__. Conceived by Romuald Czlonkowski - https://www.aiadvisors.pl/en Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Romuald Członkowski
committed by
GitHub
GitHub
parent
1f45cc6dcc
commit
23b90d01a6
@@ -27,9 +27,9 @@ describe('UI_APP_CONFIGS', () => {
|
||||
}
|
||||
});
|
||||
|
||||
it('should have URIs following n8n-mcp://ui/{id} pattern', () => {
|
||||
it('should have URIs following ui://n8n-mcp/{id} pattern', () => {
|
||||
for (const config of UI_APP_CONFIGS) {
|
||||
expect(config.uri).toBe(`n8n-mcp://ui/${config.id}`);
|
||||
expect(config.uri).toBe(`ui://n8n-mcp/${config.id}`);
|
||||
}
|
||||
});
|
||||
|
||||
@@ -71,9 +71,9 @@ describe('UI_APP_CONFIGS', () => {
|
||||
}
|
||||
});
|
||||
|
||||
it('should have URIs that start with the n8n-mcp://ui/ scheme', () => {
|
||||
it('should have URIs that start with the ui://n8n-mcp/ scheme', () => {
|
||||
for (const config of UI_APP_CONFIGS) {
|
||||
expect(config.uri).toMatch(/^n8n-mcp:\/\/ui\//);
|
||||
expect(config.uri).toMatch(/^ui:\/\/n8n-mcp\//);
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ import { existsSync, readFileSync } from 'fs';
|
||||
const mockExistsSync = vi.mocked(existsSync);
|
||||
const mockReadFileSync = vi.mocked(readFileSync);
|
||||
|
||||
describe('UI Meta Injection Logic', () => {
|
||||
describe('UI Meta Injection on Tool Definitions', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
UIAppRegistry.reset();
|
||||
@@ -24,74 +24,69 @@ describe('UI Meta Injection Logic', () => {
|
||||
UIAppRegistry.load();
|
||||
});
|
||||
|
||||
it('should add _meta.ui for matching tools', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('n8n_create_workflow');
|
||||
expect(uiApp).not.toBeNull();
|
||||
expect(uiApp!.html).not.toBeNull();
|
||||
it('should add _meta.ui.resourceUri to matching tool definitions', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_create_workflow', description: 'Create workflow', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
|
||||
// Simulate the injection logic from server.ts
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'result' }],
|
||||
};
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse._meta).toBeDefined();
|
||||
expect(mcpResponse._meta.ui.app).toBe('n8n-mcp://ui/operation-result');
|
||||
expect(tools[0]._meta).toBeDefined();
|
||||
expect(tools[0]._meta.ui.resourceUri).toBe('ui://n8n-mcp/operation-result');
|
||||
});
|
||||
|
||||
it('should add _meta.ui for validation tools', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('validate_workflow');
|
||||
expect(uiApp).not.toBeNull();
|
||||
it('should add _meta.ui.resourceUri to validation tool definitions', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'validate_workflow', description: 'Validate', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'validation result' }],
|
||||
};
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse._meta).toBeDefined();
|
||||
expect(mcpResponse._meta.ui.app).toBe('n8n-mcp://ui/validation-summary');
|
||||
expect(tools[0]._meta).toBeDefined();
|
||||
expect(tools[0]._meta.ui.resourceUri).toBe('ui://n8n-mcp/validation-summary');
|
||||
});
|
||||
|
||||
it('should NOT add _meta.ui for non-matching tools', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('get_node_info');
|
||||
expect(uiApp).toBeNull();
|
||||
it('should NOT add _meta to non-matching tool definitions', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'get_node_info', description: 'Get info', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'node info' }],
|
||||
};
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse._meta).toBeUndefined();
|
||||
expect(tools[0]._meta).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should produce _meta with exact shape { ui: { app: string } }', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('n8n_create_workflow')!;
|
||||
const meta = { ui: { app: uiApp.config.uri } };
|
||||
it('should inject _meta on matching tools and skip non-matching in a mixed list', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_create_workflow', description: 'Create', inputSchema: { type: 'object', properties: {} } },
|
||||
{ name: 'get_node_info', description: 'Info', inputSchema: { type: 'object', properties: {} } },
|
||||
{ name: 'validate_node', description: 'Validate', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
|
||||
expect(meta).toEqual({
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
|
||||
expect(tools[0]._meta).toBeDefined();
|
||||
expect(tools[0]._meta.ui.resourceUri).toBe('ui://n8n-mcp/operation-result');
|
||||
expect(tools[1]._meta).toBeUndefined();
|
||||
expect(tools[2]._meta).toBeDefined();
|
||||
expect(tools[2]._meta.ui.resourceUri).toBe('ui://n8n-mcp/validation-summary');
|
||||
});
|
||||
|
||||
it('should produce _meta with exact shape { ui: { resourceUri: string } }', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_create_workflow', description: 'Create', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
|
||||
expect(tools[0]._meta).toEqual({
|
||||
ui: {
|
||||
app: 'n8n-mcp://ui/operation-result',
|
||||
resourceUri: 'ui://n8n-mcp/operation-result',
|
||||
},
|
||||
});
|
||||
expect(Object.keys(meta)).toEqual(['ui']);
|
||||
expect(Object.keys(meta.ui)).toEqual(['app']);
|
||||
expect(typeof meta.ui.app).toBe('string');
|
||||
});
|
||||
|
||||
it('should produce _meta.ui.app that matches the config uri', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('validate_node')!;
|
||||
const meta = { ui: { app: uiApp.config.uri } };
|
||||
expect(meta.ui.app).toBe(uiApp.config.uri);
|
||||
expect(meta.ui.app).toBe('n8n-mcp://ui/validation-summary');
|
||||
expect(Object.keys(tools[0]._meta)).toEqual(['ui']);
|
||||
expect(Object.keys(tools[0]._meta.ui)).toEqual(['resourceUri']);
|
||||
expect(typeof tools[0]._meta.ui.resourceUri).toBe('string');
|
||||
});
|
||||
});
|
||||
|
||||
@@ -101,114 +96,50 @@ describe('UI Meta Injection Logic', () => {
|
||||
UIAppRegistry.load();
|
||||
});
|
||||
|
||||
it('should NOT add _meta.ui even for matching tools', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('n8n_create_workflow');
|
||||
expect(uiApp).not.toBeNull();
|
||||
expect(uiApp!.html).toBeNull();
|
||||
it('should NOT add _meta even for matching tools', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_create_workflow', description: 'Create', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'result' }],
|
||||
};
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse._meta).toBeUndefined();
|
||||
expect(tools[0]._meta).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should NOT add _meta.ui for validation tools without HTML', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('validate_node');
|
||||
expect(uiApp).not.toBeNull();
|
||||
expect(uiApp!.html).toBeNull();
|
||||
it('should NOT add _meta for validation tools without HTML', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'validate_node', description: 'Validate', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'result' }],
|
||||
};
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse._meta).toBeUndefined();
|
||||
expect(tools[0]._meta).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('when registry has not been loaded at all', () => {
|
||||
it('should NOT add _meta because getAppForTool returns null', () => {
|
||||
// Registry never loaded - reset() was called in beforeEach
|
||||
const uiApp = UIAppRegistry.getAppForTool('n8n_create_workflow');
|
||||
expect(uiApp).toBeNull();
|
||||
it('should NOT add _meta because registry is not loaded', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_create_workflow', description: 'Create', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'result' }],
|
||||
};
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse._meta).toBeUndefined();
|
||||
expect(tools[0]._meta).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('coexistence with structuredContent', () => {
|
||||
describe('empty tool list', () => {
|
||||
beforeEach(() => {
|
||||
mockExistsSync.mockReturnValue(true);
|
||||
mockReadFileSync.mockReturnValue('<html>ui</html>');
|
||||
UIAppRegistry.load();
|
||||
});
|
||||
|
||||
it('should coexist with structuredContent on the response', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('n8n_create_workflow');
|
||||
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'result' }],
|
||||
structuredContent: { workflowId: '123', status: 'created' },
|
||||
};
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse.structuredContent).toBeDefined();
|
||||
expect(mcpResponse.structuredContent.workflowId).toBe('123');
|
||||
expect(mcpResponse._meta).toBeDefined();
|
||||
expect(mcpResponse._meta.ui.app).toBe('n8n-mcp://ui/operation-result');
|
||||
});
|
||||
|
||||
it('should not overwrite existing _meta properties when merging', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('n8n_create_workflow');
|
||||
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'result' }],
|
||||
_meta: { existingProp: 'value' },
|
||||
};
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ...mcpResponse._meta, ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse._meta.existingProp).toBe('value');
|
||||
expect(mcpResponse._meta.ui.app).toBe('n8n-mcp://ui/operation-result');
|
||||
});
|
||||
|
||||
it('should work with responses that have both structuredContent and existing _meta', () => {
|
||||
const uiApp = UIAppRegistry.getAppForTool('validate_workflow');
|
||||
|
||||
const mcpResponse: any = {
|
||||
content: [{ type: 'text', text: 'validation ok' }],
|
||||
structuredContent: { valid: true, errors: [] },
|
||||
_meta: { timing: 42 },
|
||||
};
|
||||
|
||||
if (uiApp && uiApp.html) {
|
||||
mcpResponse._meta = { ...mcpResponse._meta, ui: { app: uiApp.config.uri } };
|
||||
}
|
||||
|
||||
expect(mcpResponse.structuredContent.valid).toBe(true);
|
||||
expect(mcpResponse._meta.timing).toBe(42);
|
||||
expect(mcpResponse._meta.ui.app).toBe('n8n-mcp://ui/validation-summary');
|
||||
it('should handle an empty tools array without error', () => {
|
||||
const tools: any[] = [];
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
expect(tools.length).toBe(0);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -287,6 +287,75 @@ describe('UIAppRegistry', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('injectToolMeta()', () => {
|
||||
it('should not modify tools before load() is called', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_create_workflow', description: 'Create', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
expect(tools[0]._meta).toBeUndefined();
|
||||
});
|
||||
|
||||
describe('after loading with HTML', () => {
|
||||
beforeEach(() => {
|
||||
mockExistsSync.mockReturnValue(true);
|
||||
mockReadFileSync.mockReturnValue('<html>loaded</html>');
|
||||
UIAppRegistry.load();
|
||||
});
|
||||
|
||||
it('should set _meta.ui.resourceUri on matching operation tools', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_create_workflow', description: 'Create', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
expect(tools[0]._meta).toEqual({ ui: { resourceUri: 'ui://n8n-mcp/operation-result' } });
|
||||
});
|
||||
|
||||
it('should set _meta.ui.resourceUri on matching validation tools', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'validate_node', description: 'Validate', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
expect(tools[0]._meta).toEqual({ ui: { resourceUri: 'ui://n8n-mcp/validation-summary' } });
|
||||
});
|
||||
|
||||
it('should not set _meta on tools without a matching UI app', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'search_nodes', description: 'Search', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
expect(tools[0]._meta).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should handle a mix of matching and non-matching tools', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_delete_workflow', description: 'Delete', inputSchema: { type: 'object', properties: {} } },
|
||||
{ name: 'get_node_essentials', description: 'Essentials', inputSchema: { type: 'object', properties: {} } },
|
||||
{ name: 'validate_workflow', description: 'Validate', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
expect(tools[0]._meta?.ui?.resourceUri).toBe('ui://n8n-mcp/operation-result');
|
||||
expect(tools[1]._meta).toBeUndefined();
|
||||
expect(tools[2]._meta?.ui?.resourceUri).toBe('ui://n8n-mcp/validation-summary');
|
||||
});
|
||||
});
|
||||
|
||||
describe('after loading without HTML', () => {
|
||||
beforeEach(() => {
|
||||
mockExistsSync.mockReturnValue(false);
|
||||
UIAppRegistry.load();
|
||||
});
|
||||
|
||||
it('should not set _meta when HTML is not available', () => {
|
||||
const tools: any[] = [
|
||||
{ name: 'n8n_create_workflow', description: 'Create', inputSchema: { type: 'object', properties: {} } },
|
||||
];
|
||||
UIAppRegistry.injectToolMeta(tools);
|
||||
expect(tools[0]._meta).toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('reset()', () => {
|
||||
it('should clear loaded state so getters return defaults', () => {
|
||||
mockExistsSync.mockReturnValue(true);
|
||||
|
||||
Reference in New Issue
Block a user