@n8n/frontend-module-mcp 0.1.0

package/src/clients.utils.ts

@@ -0,0 +1,124 @@
+import type { Component } from 'vue';
+
+import { MCP_CLIENT_BRAND_MATCHERS, MCP_INSTANCE_SCOPES } from '@n8n/api-types';
+import type {
+	McpClientBrandName,
+	McpClientConnectedPeriod,
+	McpClientType,
+	McpClientTypeFilter,
+	OAuthClientResponseDto,
+} from '@n8n/api-types';
+import type { BaseTextKey, I18nClass } from '@n8n/i18n';
+
+import ClaudeIcon from './assets/client-icons/claude.svg?component';
+import CursorIcon from './assets/client-icons/cursor.svg?component';
+import MistralIcon from './assets/client-icons/mistral.svg?component';
+import OpenAiIcon from './assets/client-icons/openai.svg?component';
+import VsCodeIcon from './assets/client-icons/vscode.svg?component';
+
+export interface McpClientBrand {
+	icon: Component | null;
+	type: McpClientType | null;
+}
+
+/** Logos for the brands recognized by the shared name-pattern matchers. */
+const BRAND_ICONS: Record<McpClientBrandName, Component> = {
+	claude: ClaudeIcon,
+	cursor: CursorIcon,
+	vscode: VsCodeIcon,
+	openai: OpenAiIcon,
+	mistral: MistralIcon,
+};
+
+// Client names are bounded (a user's own registered clients), so memoizing the
+// regex scan by name is safe; the map would need eviction only if that set ever
+// became unbounded.
+const brandCache = new Map<string, McpClientBrand>();
+
+export function getClientBrand(clientName: string): McpClientBrand {
+	let brand = brandCache.get(clientName);
+	if (!brand) {
+		const match = MCP_CLIENT_BRAND_MATCHERS.find(({ pattern }) => pattern.test(clientName));
+		brand = match
+			? { icon: BRAND_ICONS[match.brand], type: match.type }
+			: { icon: null, type: null };
+		brandCache.set(clientName, brand);
+	}
+	return brand;
+}
+
+/**
+ * i18n key suffix for a granted scope's human label, e.g. `workflow:read` →
+ * `workflow.read`. Unknown scopes have no label and are rendered verbatim.
+ */
+export function scopeLabelKeySuffix(scope: string): string {
+	return scope.replace(':', '.');
+}
+
+/**
+ * Human label for a granted scope. Unknown scopes have no i18n entry and render
+ * verbatim.
+ */
+export function scopeLabel(
+	i18n: { baseText: (key: BaseTextKey) => string },
+	scope: string,
+): string {
+	const key = `settings.mcp.oAuthClients.scope.${scopeLabelKeySuffix(scope)}` as BaseTextKey;
+	const label = i18n.baseText(key);
+	return label === key ? scope : label;
+}
+
+/**
+ * Whether a grant covers every scope the instance currently offers.
+ * Older grants need fresh consent for scopes introduced after they were made.
+ *
+ * `offeredScopes` comes from the backend, which drops scopes this instance
+ * cannot serve (agent scopes when the agents module is off). Without it a
+ * full grant on such an instance would never count as full access.
+ */
+export function isFullAccessGrant(scopes: string[], offeredScopes?: string[]): boolean {
+	const required = offeredScopes?.length ? offeredScopes : MCP_INSTANCE_SCOPES;
+	return scopes.length > 0 && required.every((scope) => scopes.includes(scope));
+}
+
+/** Scopes spelled out in a one-line grant summary before the rest collapse into "+N". */
+const ACCESS_SUMMARY_VISIBLE_SCOPES = 2;
+
+/**
+ * One-line summary of a client's grant for list rows: "Full access", "No access",
+ * or the first two scope labels followed by a "+N" overflow.
+ */
+export function getAccessSummary(
+	i18n: Pick<I18nClass, 'baseText'>,
+	client: Pick<OAuthClientResponseDto, 'scopes'>,
+	offeredScopes?: string[],
+): string {
+	if (client.scopes.length === 0) return i18n.baseText('settings.mcp.oAuthClients.access.none');
+	if (isFullAccessGrant(client.scopes, offeredScopes)) {
+		return i18n.baseText('settings.mcp.oAuthClients.access.full');
+	}
+	const visible = client.scopes
+		.slice(0, ACCESS_SUMMARY_VISIBLE_SCOPES)
+		.map((scope) => scopeLabel(i18n, scope))
+		.join(', ');
+	const remaining = client.scopes.length - ACCESS_SUMMARY_VISIBLE_SCOPES;
+	if (remaining <= 0) return visible;
+	return `${visible} ${i18n.baseText('settings.mcp.oAuthClients.scope.more', {
+		interpolate: { count: remaining },
+	})}`;
+}
+
+/** UI state of the connected-clients search + filter popover; applied server-side. */
+export interface OAuthClientFilters {
+	search: string;
+	type: McpClientTypeFilter | null;
+	ownerId: string | null;
+	connected: McpClientConnectedPeriod | null;
+}
+
+export const EMPTY_OAUTH_CLIENT_FILTERS: OAuthClientFilters = {
+	search: '',
+	type: null,
+	ownerId: null,
+	connected: null,
+};

package/src/components/ConnectionParameter.vue

@@ -0,0 +1,213 @@
+<script setup lang="ts">
+import { useI18n } from '@n8n/i18n';
+import { useClipboard } from '@n8n/composables/useClipboard';
+import { N8nButton, N8nTooltip, N8nInfoTip, N8nInput, N8nLoading } from '@n8n/design-system';
+import { MCP_TOOLTIP_DELAY } from '../mcp.constants';
+
+type Props = {
+	id: string;
+	label: string;
+	value: string;
+	valueLoading?: boolean;
+	infoTip?: string;
+	allowCopy?: boolean;
+};
+
+const { copy, copied, isSupported } = useClipboard();
+const i18n = useI18n();
+
+const props = withDefaults(defineProps<Props>(), {
+	allowCopy: true,
+	maxWidth: undefined,
+	infoTip: undefined,
+	valueLoading: false,
+});
+
+const emit = defineEmits<{
+	copy: [value: string];
+}>();
+
+const handleCopy = async (value: string) => {
+	await copy(value);
+	emit('copy', value);
+};
+</script>
+
+<template>
+	<div :class="$style.container">
+		<div :class="$style['label-wrapper']">
+			<label :class="$style.label" :for="`connection-parameter-${props.id}`">
+				{{ props.label }}
+			</label>
+			<div v-if="props.infoTip" :class="$style['info-tip']">
+				<N8nInfoTip type="tooltip" size="small" :enterable="false">
+					{{ props.infoTip }}
+				</N8nInfoTip>
+			</div>
+		</div>
+		<div
+			:id="`connection-parameter-${props.id}`"
+			:class="{
+				[$style['parameter-value']]: true,
+				[$style['parameter-value--loading']]: props.valueLoading,
+			}"
+			data-test-id="connection-parameter-value"
+		>
+			<div :class="$style['input-wrapper']">
+				<N8nLoading
+					v-if="props.valueLoading"
+					:loading="props.valueLoading"
+					variant="h1"
+					:class="$style['parameter-skeleton']"
+				/>
+				<N8nInput v-else v-model="props.value" type="text" :readonly="true" />
+			</div>
+			<div :class="$style['copy-button-wrapper']">
+				<slot name="customActions" />
+				<N8nTooltip
+					:disabled="!isSupported"
+					:content="copied ? i18n.baseText('generic.copied') : i18n.baseText('generic.copy')"
+					:show-after="MCP_TOOLTIP_DELAY"
+					placement="bottom"
+				>
+					<N8nButton
+						v-if="props.allowCopy && isSupported"
+						variant="subtle"
+						icon-only
+						:icon="copied ? 'check' : 'copy'"
+						:class="$style['copy-button']"
+						:disabled="props.valueLoading"
+						@click="handleCopy(props.value)"
+					/>
+				</N8nTooltip>
+			</div>
+		</div>
+	</div>
+</template>
+
+<style module lang="scss">
+.container {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing--4xs);
+}
+
+.label-wrapper {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing--4xs);
+
+	.info-tip {
+		visibility: hidden;
+		cursor: pointer;
+		padding-top: 1px;
+
+		:global(.n8n-info-tip) {
+			display: flex;
+		}
+	}
+
+	&:hover .info-tip span {
+		visibility: visible;
+	}
+}
+
+.label {
+	font-size: var(--font-size--sm);
+	color: var(--color--text--shade-1);
+}
+
+.parameter-value {
+	display: flex;
+	align-items: stretch;
+	justify-content: space-between;
+	font-size: var(--font-size--2xs);
+	color: var(--color--text);
+	gap: var(--spacing--2xs);
+	border: var(--border);
+	border-radius: var(--radius);
+	overflow: hidden;
+
+	&--loading {
+		gap: 0;
+	}
+
+	.input-wrapper {
+		flex: 1;
+		min-width: 0;
+		display: flex;
+		align-items: center;
+
+		:global(.n8n-input__wrapper) {
+			--input--border--shadow: 0 0 0 0 transparent;
+			--input--border--shadow--hover: 0 0 0 0 transparent;
+			--input--border--shadow--focus: 0 0 0 0 transparent;
+
+			&:focus-within {
+				outline: none;
+			}
+		}
+	}
+
+	:global(.n8n-input) {
+		flex: 1;
+		align-items: center;
+
+		input {
+			font-family: monospace;
+			font-size: var(--font-size--2xs);
+			border: none;
+			color: var(--color--text);
+			min-height: var(--spacing--md);
+			height: var(--spacing--md);
+		}
+	}
+
+	.parameter-skeleton div {
+		margin: 0;
+		height: calc(var(--spacing--xl) - 2 * var(--border-width));
+		border-radius: 0 0 var(--radius) var(--radius);
+	}
+
+	button {
+		height: auto;
+		border: none;
+		border-radius: 0;
+		box-shadow: none;
+
+		&:hover {
+			border-color: inherit;
+			box-shadow: none;
+		}
+
+		&:active {
+			box-shadow: none;
+		}
+	}
+
+	button + button {
+		border-left: var(--border);
+	}
+
+	@media screen and (max-width: 820px) {
+		word-wrap: break-word;
+		margin-top: var(--spacing--2xs);
+	}
+}
+
+.copy-button-wrapper {
+	display: flex;
+	align-items: stretch;
+	border-left: var(--border);
+
+	// Tooltip triggers wrap each button in a span, which must stretch it too.
+	> span {
+		display: flex;
+	}
+}
+
+.copy-button {
+	border: none;
+	border-radius: 0;
+}
+</style>

package/src/components/MCPAgentsSelect.vue

@@ -0,0 +1,176 @@
+<script setup lang="ts">
+import { useMCPStore } from '../mcp.store';
+import { LOADING_INDICATOR_TIMEOUT } from '../mcp.constants';
+import { N8nSelect, N8nOption, N8nText } from '@n8n/design-system';
+import { computed, onMounted, ref, useCssModule } from 'vue';
+import type { McpAgent } from '../mcp.types';
+import { useI18n } from '@n8n/i18n';
+import { useToast } from '@n8n/composables/useToast';
+import { sleep } from '@n8n/utils/sleep';
+
+defineProps<{
+	placeholder?: string;
+	disabled?: boolean;
+}>();
+
+const i18n = useI18n();
+const toast = useToast();
+
+const modelValue = defineModel<string[]>({ default: () => [] });
+
+const emit = defineEmits<{
+	ready: [];
+	confirm: [];
+}>();
+
+const mcpStore = useMCPStore();
+
+const isLoading = ref(false);
+const hasFetched = ref(false);
+const isDropdownVisible = ref(false);
+const selectRef = ref<InstanceType<typeof N8nSelect>>();
+const agentOptions = ref<McpAgent[]>([]);
+let loadingTimeoutId: ReturnType<typeof setTimeout> | null = null;
+
+const showEmptyState = computed(() => {
+	return !isLoading.value && hasFetched.value && agentOptions.value.length === 0;
+});
+
+const $style = useCssModule();
+
+// `popper-class` is a string prop, so the classes are joined here rather than
+// passed as an object binding.
+const popperClass = computed(() =>
+	[
+		isLoading.value ? $style['mcp-agents-select-loading'] : '',
+		showEmptyState.value ? $style['mcp-agents-select-empty'] : '',
+	]
+		.filter(Boolean)
+		.join(' '),
+);
+
+const projectName = (agent: McpAgent) =>
+	agent.project?.type === 'personal'
+		? i18n.baseText('projects.menu.personal')
+		: (agent.project?.name ?? '');
+
+async function searchAgents(query?: string) {
+	if (loadingTimeoutId) {
+		clearTimeout(loadingTimeoutId);
+		loadingTimeoutId = null;
+	}
+	isLoading.value = true;
+	hasFetched.value = false;
+	try {
+		const response = await mcpStore.getMcpEligibleAgents({
+			take: 10,
+			query: query ?? undefined,
+		});
+		agentOptions.value = response?.data ?? [];
+	} catch (e) {
+		toast.showError(e, i18n.baseText('settings.mcp.connectAgents.error'));
+	} finally {
+		await sleep(LOADING_INDICATOR_TIMEOUT);
+		isLoading.value = false;
+		hasFetched.value = true;
+	}
+}
+
+function focusOnInput() {
+	selectRef.value?.focusOnInput();
+}
+
+function onVisibleChange(visible: boolean) {
+	isDropdownVisible.value = visible;
+}
+
+function onKeydownCapture(event: KeyboardEvent) {
+	if (event.key === 'Enter' && !isDropdownVisible.value && modelValue.value.length > 0) {
+		event.preventDefault();
+		event.stopPropagation();
+		emit('confirm');
+	}
+}
+
+onMounted(async () => {
+	await searchAgents();
+	emit('ready');
+});
+
+defineExpose({
+	focusOnInput,
+});
+</script>
+
+<template>
+	<div @keydown.enter.capture="onKeydownCapture">
+		<N8nSelect
+			ref="selectRef"
+			v-model="modelValue"
+			data-test-id="mcp-agents-select"
+			:placeholder="placeholder"
+			:disabled="disabled"
+			:loading="isLoading"
+			:multiple="true"
+			:filterable="true"
+			:remote="true"
+			:remote-method="searchAgents"
+			size="medium"
+			:popper-class="popperClass"
+			:teleported="false"
+			@visible-change="onVisibleChange"
+		>
+			<N8nOption v-if="showEmptyState" value="" disabled :class="$style['empty-option']">
+				{{ i18n.baseText('settings.mcp.connectAgents.emptyState') }}
+			</N8nOption>
+			<N8nOption
+				v-for="agent in agentOptions"
+				:key="agent.id"
+				:value="agent.id"
+				:label="agent.name"
+			>
+				<div :class="$style.option">
+					<N8nText :class="$style.truncate">{{ projectName(agent) }}</N8nText>
+					<span :class="$style.separator">/</span>
+					<N8nText :class="$style.truncate" color="text-dark">{{ agent.name }}</N8nText>
+				</div>
+			</N8nOption>
+		</N8nSelect>
+	</div>
+</template>
+
+<style module lang="scss">
+.mcp-agents-select-loading,
+.mcp-agents-select-empty {
+	display: flex;
+	min-height: var(--spacing--5xl);
+	align-items: center;
+	justify-content: space-around;
+}
+
+.empty-option {
+	cursor: default !important;
+	color: var(--color--text) !important;
+}
+
+.option {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing--4xs);
+	min-width: 0;
+	overflow: hidden;
+}
+
+.separator {
+	user-select: none;
+	color: var(--color--text--tint-1);
+}
+
+.truncate {
+	display: block;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	min-width: 0;
+}
+</style>

package/src/components/MCPEmptyState.vue

@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { N8nButton, N8nIcon, N8nTooltip } from '@n8n/design-system';
+import { MCP_DOCS_PAGE_URL } from '../mcp.constants';
+import { useI18n } from '@n8n/i18n';
+import McpEmptyStateCard from './McpEmptyStateCard.vue';
+
+type Props = {
+	disabled?: boolean;
+	loading?: boolean;
+	managedByEnv?: boolean;
+};
+
+const props = withDefaults(defineProps<Props>(), {
+	disabled: false,
+	loading: false,
+	managedByEnv: false,
+});
+
+const emit = defineEmits<{
+	turnOnMcp: [];
+}>();
+
+const i18n = useI18n();
+
+const buttonDisabled = computed(() => props.disabled || props.loading);
+</script>
+
+<template>
+	<McpEmptyStateCard
+		surface
+		:class="$style.card"
+		data-test-id="mcp-empty-state-container"
+		:title="i18n.baseText('settings.mcp.actionBox.heading')"
+		:description="i18n.baseText('settings.mcp.emptyState.description')"
+	>
+		<template #actions>
+			<N8nButton
+				variant="ghost"
+				size="medium"
+				:href="MCP_DOCS_PAGE_URL"
+				target="_blank"
+				data-test-id="mcp-empty-state-learn-more"
+			>
+				{{ i18n.baseText('generic.learnMore') }} <N8nIcon icon="arrow-up-right" size="small" />
+			</N8nButton>
+			<N8nTooltip :disabled="!buttonDisabled">
+				<template #content>
+					<span v-if="props.loading">{{ i18n.baseText('generic.loading') }}...</span>
+					<span v-else-if="props.managedByEnv">
+						{{ i18n.baseText('settings.mcp.managedByEnv.tooltip') }}
+					</span>
+					<span v-else>
+						{{ i18n.baseText('settings.mcp.toggle.disabled.tooltip') }}
+					</span>
+				</template>
+				<N8nButton
+					variant="solid"
+					size="medium"
+					:disabled="buttonDisabled"
+					data-test-id="enable-mcp-access-button"
+					@click="emit('turnOnMcp')"
+				>
+					{{ i18n.baseText('settings.mcp.actionBox.button.label') }}
+				</N8nButton>
+			</N8nTooltip>
+		</template>
+	</McpEmptyStateCard>
+</template>
+
+<style lang="scss" module>
+.card {
+	margin-top: var(--spacing--xl);
+}
+</style>