neondeck 1.0.0-beta.4

package/src/domains/mcp/policy.ts

@@ -0,0 +1,15 @@
+import type { McpConfig } from './schemas';
+
+export type McpPolicyDecision = 'allow' | 'ask' | 'deny';
+
+export function decideMcpToolPolicy(input: {
+  config: McpConfig;
+  serverId: string;
+  toolName: string;
+}): McpPolicyDecision {
+  const server = input.config.servers[input.serverId];
+  const policy = server?.tools;
+  if (policy?.deny?.includes(input.toolName)) return 'deny';
+  if (policy?.autoApprove?.includes(input.toolName)) return 'allow';
+  return 'ask';
+}

package/src/domains/mcp/registry.ts

@@ -0,0 +1,461 @@
+import type { ToolDefinition } from '@flue/runtime';
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+import {
+  subscribeConfigEvents,
+  type ConfigChangeEvent,
+} from '../../modules/config/events';
+import { runtimePaths, type RuntimePaths } from '../../runtime-home';
+import { runMcpToolThroughGate } from './gate';
+import { mcpServerEnabled, type McpServerConfig } from './schemas';
+import { readMcpConfig } from './config';
+import {
+  createMcpOAuthProvider,
+  hasMcpOAuthTokens,
+  readMcpOAuthStatus,
+  type McpOAuthStatus,
+} from './oauth';
+import { connectSdkMcpServer, type McpSdkConnection } from './stdio';
+import {
+  deleteMcpToolCatalog,
+  listMcpToolCatalog,
+  markMcpCatalogUnavailable,
+  replaceMcpToolCatalog,
+  type McpToolCatalogRecord,
+} from './store';
+
+export type McpServerStatus =
+  | 'disabled'
+  | 'connected'
+  | 'connecting'
+  | 'disconnected'
+  | 'needs-login'
+  | 'error';
+
+export type McpServerSnapshot = {
+  id: string;
+  transport: 'http' | 'stdio';
+  enabled: boolean;
+  status: McpServerStatus;
+  auth: {
+    kind: 'none' | 'header' | 'oauth';
+    authorized: boolean;
+    expiresAt: string | null;
+    scopes: string[];
+  };
+  toolCount: number;
+  message: string;
+  lastConnectedAt: string | null;
+  lastErrorAt: string | null;
+};
+
+type RegistryEntry = {
+  status: McpServerStatus;
+  message: string;
+  connection: McpSdkConnection | null;
+  tools: ToolDefinition[];
+  catalog: McpToolCatalogRecord[];
+  lastConnectedAt: string | null;
+  lastErrorAt: string | null;
+  refreshPromise: Promise<void> | null;
+  pendingServer: McpServerConfig | null;
+  refreshGeneration: number;
+};
+
+const registries = new Map<string, McpRegistry>();
+
+type McpRegistryPublishTestHookInput = {
+  serverId: string;
+  tools: ToolDefinition[];
+};
+
+type McpRegistryPendingRefreshTestHookInput = {
+  serverId: string;
+  server: McpServerConfig;
+};
+
+type McpRegistryRefreshTestHookInput = {
+  serverId: string;
+  server: McpServerConfig;
+};
+
+let mcpRegistryPublishTestHook:
+  ((input: McpRegistryPublishTestHookInput) => void) | null = null;
+let mcpRegistryPendingRefreshTestHook:
+  ((input: McpRegistryPendingRefreshTestHookInput) => void) | null = null;
+let mcpRegistryRefreshTestHook:
+  ((input: McpRegistryRefreshTestHookInput) => void) | null = null;
+
+export function setMcpRegistryPublishHookForTests(
+  hook: ((input: McpRegistryPublishTestHookInput) => void) | null,
+) {
+  const previous = mcpRegistryPublishTestHook;
+  mcpRegistryPublishTestHook = hook;
+  return () => {
+    mcpRegistryPublishTestHook = previous;
+  };
+}
+
+export function setMcpRegistryPendingRefreshHookForTests(
+  hook: ((input: McpRegistryPendingRefreshTestHookInput) => void) | null,
+) {
+  const previous = mcpRegistryPendingRefreshTestHook;
+  mcpRegistryPendingRefreshTestHook = hook;
+  return () => {
+    mcpRegistryPendingRefreshTestHook = previous;
+  };
+}
+
+export function setMcpRegistryRefreshHookForTests(
+  hook: ((input: McpRegistryRefreshTestHookInput) => void) | null,
+) {
+  const previous = mcpRegistryRefreshTestHook;
+  mcpRegistryRefreshTestHook = hook;
+  return () => {
+    mcpRegistryRefreshTestHook = previous;
+  };
+}
+
+export function getMcpRegistry(paths = runtimePaths()) {
+  const existing = registries.get(paths.home);
+  if (existing) return existing;
+  const registry = new McpRegistry(paths);
+  registries.set(paths.home, registry);
+  return registry;
+}
+
+export function mcpAgentToolsSync(paths = runtimePaths()) {
+  return getMcpRegistry(paths).toolsSync();
+}
+
+export function mcpSnapshotSync(paths = runtimePaths()) {
+  return getMcpRegistry(paths).snapshotSync();
+}
+
+export class McpRegistry {
+  private readonly entries = new Map<string, RegistryEntry>();
+  private unsubscribe: (() => void) | null = null;
+  private startPromise: Promise<void> | null = null;
+
+  constructor(private readonly paths: RuntimePaths) {}
+
+  async start() {
+    if (this.unsubscribe) return this.startPromise ?? Promise.resolve();
+    this.unsubscribe = subscribeConfigEvents((event) => {
+      if (!event.files.includes(this.paths.mcp)) return;
+      void this.refresh(refreshTargetFromConfigEvent(event)).catch((error) => {
+        console.error('[neondeck] failed to refresh MCP registry', error);
+      });
+    });
+    this.startPromise = this.refresh()
+      .then(() => undefined)
+      .catch((error) => {
+        console.error('[neondeck] failed to initialize MCP registry', error);
+      });
+    return this.startPromise;
+  }
+
+  async stop() {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.startPromise = null;
+    await Promise.all(
+      [...this.entries.values()].map((entry) => entry.connection?.close()),
+    );
+    this.entries.clear();
+  }
+
+  toolsSync() {
+    return [...this.entries.values()].flatMap((entry) => entry.tools);
+  }
+
+  snapshotSync() {
+    return [...this.entries.entries()].map(([id, entry]) => ({
+      id,
+      status: entry.status,
+      message: entry.message,
+      toolCount: entry.tools.length,
+      lastConnectedAt: entry.lastConnectedAt,
+      lastErrorAt: entry.lastErrorAt,
+    }));
+  }
+
+  async status() {
+    const config = await readMcpConfig(this.paths);
+    return Promise.all(
+      Object.entries(config.servers).map(async ([id, server]) => {
+        const entry = this.entries.get(id);
+        const auth = await snapshotAuthStatus(id, server, this.paths);
+        return {
+          id,
+          transport: server.transport,
+          enabled: mcpServerEnabled(server),
+          auth,
+          status:
+            entry?.status ??
+            (mcpServerEnabled(server) ? 'disconnected' : 'disabled'),
+          toolCount: entry?.tools.length ?? 0,
+          message: entry?.message ?? 'MCP server has not been refreshed.',
+          lastConnectedAt: entry?.lastConnectedAt ?? null,
+          lastErrorAt: entry?.lastErrorAt ?? null,
+        } satisfies McpServerSnapshot;
+      }),
+    );
+  }
+
+  async listTools(serverId?: string) {
+    return listMcpToolCatalog(this.paths, { serverId });
+  }
+
+  async refresh(serverId?: string) {
+    const config = await readMcpConfig(this.paths);
+    const configuredIds = new Set(Object.keys(config.servers));
+    const targetFound =
+      !serverId ||
+      Object.hasOwn(config.servers, serverId) ||
+      this.entries.has(serverId);
+
+    for (const [id, entry] of this.entries) {
+      if (configuredIds.has(id)) continue;
+      entry.refreshGeneration += 1;
+      entry.pendingServer = null;
+      await entry.connection?.close().catch(() => undefined);
+      this.entries.delete(id);
+    }
+
+    await Promise.all(
+      Object.entries(config.servers)
+        .filter(([id]) => !serverId || id === serverId)
+        .map(([id, server]) => this.refreshOne(id, server)),
+    );
+    return targetFound;
+  }
+
+  private async refreshOne(id: string, server: McpServerConfig) {
+    mcpRegistryRefreshTestHook?.({ serverId: id, server });
+    const current = this.entry(id);
+    current.refreshGeneration += 1;
+    const generation = current.refreshGeneration;
+    if (current.refreshPromise) {
+      current.pendingServer = server;
+      mcpRegistryPendingRefreshTestHook?.({ serverId: id, server });
+      return current.refreshPromise;
+    }
+
+    current.refreshPromise = this.connectOne(id, server, generation).finally(
+      async () => {
+        current.refreshPromise = null;
+        const pendingServer = current.pendingServer;
+        current.pendingServer = null;
+        if (pendingServer) await this.refreshOne(id, pendingServer);
+      },
+    );
+    return current.refreshPromise;
+  }
+
+  private async connectOne(
+    id: string,
+    server: McpServerConfig,
+    generation: number,
+  ) {
+    const entry = this.entry(id);
+    const isCurrent = () => entry.refreshGeneration === generation;
+    if (!mcpServerEnabled(server)) {
+      const previousConnection = entry.connection;
+      await previousConnection?.close().catch(() => undefined);
+      if (!isCurrent()) return;
+      if (entry.connection === previousConnection) entry.connection = null;
+      entry.tools = [];
+      entry.status = 'disabled';
+      entry.message = 'MCP server is disabled.';
+      await markMcpCatalogUnavailable(id, this.paths);
+      return;
+    }
+
+    const authProvider =
+      server.transport === 'http' && server.auth?.kind === 'oauth'
+        ? createMcpOAuthProvider({
+            paths: this.paths,
+            serverId: id,
+            server,
+          })
+        : undefined;
+
+    if (
+      server.transport === 'http' &&
+      server.auth?.kind === 'oauth' &&
+      !(await hasMcpOAuthTokens(id, this.paths))
+    ) {
+      const previousConnection = entry.connection;
+      await previousConnection?.close().catch(() => undefined);
+      if (!isCurrent()) return;
+      if (entry.connection === previousConnection) entry.connection = null;
+      entry.catalog = await cachedCatalog(id, this.paths);
+      if (!isCurrent()) return;
+      entry.tools = disconnectedTools(id, entry.catalog);
+      entry.status = 'needs-login';
+      entry.message =
+        'OAuth login is required before connecting this MCP server.';
+      await markMcpCatalogUnavailable(id, this.paths);
+      return;
+    }
+
+    if (!isCurrent()) return;
+    entry.status = 'connecting';
+    entry.message = 'Connecting MCP server.';
+    try {
+      const previousConnection = entry.connection;
+      await previousConnection?.close().catch(() => undefined);
+      if (!isCurrent()) return;
+      if (entry.connection === previousConnection) entry.connection = null;
+      const headers = resolveHeaderAuth(server);
+      const connection = await connectSdkMcpServer({
+        serverId: id,
+        server,
+        headers,
+        authProvider,
+        gate: (input) => runMcpToolThroughGate(input, this.paths),
+      });
+      if (!isCurrent()) {
+        await connection.close().catch(() => undefined);
+        return;
+      }
+      const now = new Date().toISOString();
+      const catalog = connection.catalog.map((tool) => ({
+        ...tool,
+        status: 'available' as const,
+        updatedAt: now,
+      }));
+      await replaceMcpToolCatalog(id, catalog, this.paths);
+      if (!isCurrent()) {
+        await connection.close().catch(() => undefined);
+        await this.clearStaleCatalog(id);
+        return;
+      }
+      mcpRegistryPublishTestHook?.({
+        serverId: id,
+        tools: connection.tools,
+      });
+      entry.connection = connection;
+      entry.tools = connection.tools;
+      entry.catalog = catalog;
+      entry.status = 'connected';
+      entry.message = `Connected with ${connection.tools.length} tools.`;
+      entry.lastConnectedAt = now;
+      entry.lastErrorAt = null;
+    } catch (error) {
+      if (!isCurrent()) return;
+      const message = error instanceof Error ? error.message : String(error);
+      const previousConnection = entry.connection;
+      await previousConnection?.close().catch(() => undefined);
+      if (!isCurrent()) return;
+      if (entry.connection === previousConnection) entry.connection = null;
+      await markMcpCatalogUnavailable(id, this.paths);
+      entry.catalog =
+        entry.catalog.length > 0
+          ? entry.catalog
+          : await cachedCatalog(id, this.paths);
+      entry.tools = disconnectedTools(id, entry.catalog);
+      entry.status =
+        error instanceof UnauthorizedError ? 'needs-login' : 'error';
+      entry.message =
+        error instanceof UnauthorizedError
+          ? 'OAuth login is required before connecting this MCP server.'
+          : message;
+      entry.lastErrorAt = new Date().toISOString();
+    }
+  }
+
+  private entry(id: string) {
+    const existing = this.entries.get(id);
+    if (existing) return existing;
+    const entry: RegistryEntry = {
+      status: 'disconnected',
+      message: 'MCP server has not connected yet.',
+      connection: null,
+      tools: [],
+      catalog: [],
+      lastConnectedAt: null,
+      lastErrorAt: null,
+      refreshPromise: null,
+      pendingServer: null,
+      refreshGeneration: 0,
+    };
+    this.entries.set(id, entry);
+    return entry;
+  }
+
+  private async clearStaleCatalog(id: string) {
+    const config = await readMcpConfig(this.paths).catch(() => null);
+    const server = config?.servers[id];
+    if (!server) {
+      await deleteMcpToolCatalog(id, this.paths);
+      return;
+    }
+    await markMcpCatalogUnavailable(id, this.paths);
+  }
+}
+
+function refreshTargetFromConfigEvent(event: ConfigChangeEvent) {
+  if (!event.target || event.target === 'all') return undefined;
+  return event.target;
+}
+
+async function cachedCatalog(serverId: string, paths: RuntimePaths) {
+  const catalog = await listMcpToolCatalog(paths, { serverId });
+  return catalog.map((tool) => ({ ...tool, status: 'unavailable' as const }));
+}
+
+function resolveHeaderAuth(server: McpServerConfig) {
+  if (server.transport !== 'http' || server.auth?.kind !== 'header')
+    return undefined;
+  const headers: Record<string, string> = {};
+  for (const [name, ref] of Object.entries(server.auth.headers)) {
+    const value = process.env[ref.env];
+    if (value !== undefined) headers[name] = value;
+  }
+  return headers;
+}
+
+async function snapshotAuthStatus(
+  serverId: string,
+  server: McpServerConfig,
+  paths: RuntimePaths,
+): Promise<McpServerSnapshot['auth']> {
+  if (server.transport === 'stdio') {
+    return { kind: 'none', authorized: true, expiresAt: null, scopes: [] };
+  }
+  if (server.auth?.kind === 'oauth') {
+    const status: McpOAuthStatus = await readMcpOAuthStatus(serverId, paths);
+    return {
+      kind: 'oauth',
+      authorized: status.authorized,
+      expiresAt: status.expiresAt,
+      scopes: status.scopes,
+    };
+  }
+  return {
+    kind: server.auth?.kind ?? 'none',
+    authorized: true,
+    expiresAt: null,
+    scopes: [],
+  };
+}
+
+function disconnectedTools(serverId: string, catalog: McpToolCatalogRecord[]) {
+  return catalog.map((tool) => ({
+    name: tool.adaptedName,
+    description: `${tool.description} Currently unavailable because MCP server "${serverId}" is disconnected.`,
+    input: undefined,
+    output: undefined,
+    async run() {
+      return {
+        ok: false,
+        status: 'server-disconnected',
+        server: serverId,
+        tool: tool.toolName,
+        untrusted: true,
+        message: `MCP server "${serverId}" is disconnected.`,
+      };
+    },
+  })) satisfies ToolDefinition[];
+}

package/src/domains/mcp/schemas.ts

@@ -0,0 +1,171 @@
+import * as v from 'valibot';
+
+const nonEmptyStringSchema = v.pipe(v.string(), v.minLength(1));
+export const mcpServerIdSchema = v.pipe(
+  v.string(),
+  v.regex(
+    /^[a-z][a-z0-9-]{1,31}$/,
+    'Expected a lowercase MCP server id using 2-32 letters, numbers, or dashes.',
+  ),
+);
+export const mcpToolNameSchema = nonEmptyStringSchema;
+export const mcpEnvVarNameSchema = v.pipe(
+  v.string(),
+  v.regex(/^[A-Z_][A-Z0-9_]*$/, 'Expected an environment variable name.'),
+);
+
+export const mcpEnvRefSchema = v.strictObject({
+  env: mcpEnvVarNameSchema,
+});
+
+export const mcpToolPolicySchema = v.strictObject({
+  autoApprove: v.optional(v.array(mcpToolNameSchema)),
+  deny: v.optional(v.array(mcpToolNameSchema)),
+});
+
+const mcpNoneAuthSchema = v.strictObject({
+  kind: v.literal('none'),
+});
+
+const mcpHeaderAuthSchema = v.strictObject({
+  kind: v.literal('header'),
+  headers: v.record(nonEmptyStringSchema, mcpEnvRefSchema),
+});
+
+const mcpOAuthAuthSchema = v.strictObject({
+  kind: v.literal('oauth'),
+  clientId: v.optional(nonEmptyStringSchema),
+  clientSecret: v.optional(mcpEnvRefSchema),
+});
+
+export const mcpAuthConfigSchema = v.variant('kind', [
+  mcpNoneAuthSchema,
+  mcpHeaderAuthSchema,
+  mcpOAuthAuthSchema,
+]);
+
+const mcpCommonServerFields = {
+  enabled: v.optional(v.boolean()),
+  tools: v.optional(mcpToolPolicySchema),
+  timeoutMs: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+};
+
+const mcpHttpServerSchema = v.pipe(
+  v.strictObject({
+    ...mcpCommonServerFields,
+    transport: v.literal('http'),
+    url: nonEmptyStringSchema,
+    auth: v.optional(mcpAuthConfigSchema),
+  }),
+  v.check(
+    (server) => isAllowedMcpHttpUrl(server.url),
+    'MCP HTTP servers must use https:// except localhost and 127.0.0.1.',
+  ),
+  v.check(
+    (server) => server.auth?.kind !== 'oauth' || server.transport === 'http',
+    'OAuth MCP auth is only valid for HTTP servers.',
+  ),
+);
+
+const mcpStdioServerSchema = v.strictObject({
+  ...mcpCommonServerFields,
+  transport: v.literal('stdio'),
+  command: nonEmptyStringSchema,
+  args: v.optional(v.array(v.string())),
+  cwd: v.optional(nonEmptyStringSchema),
+  env: v.optional(v.record(mcpEnvVarNameSchema, mcpEnvRefSchema)),
+});
+
+export const mcpServerConfigSchema = v.variant('transport', [
+  mcpHttpServerSchema,
+  mcpStdioServerSchema,
+]);
+
+export const mcpConfigSchema = v.strictObject({
+  servers: v.record(mcpServerIdSchema, mcpServerConfigSchema),
+});
+
+export const mcpActionResultSchema = v.looseObject({
+  ok: v.boolean(),
+  action: v.string(),
+  changed: v.boolean(),
+  message: v.string(),
+});
+
+export const mcpEmptyInputSchema = v.object({});
+
+export const mcpServerIdInputSchema = v.object({
+  id: mcpServerIdSchema,
+});
+
+export const mcpServerAddInputSchema = v.object({
+  id: mcpServerIdSchema,
+  server: mcpServerConfigSchema,
+});
+
+export const mcpServerUpdateInputSchema = v.object({
+  id: mcpServerIdSchema,
+  server: v.record(v.string(), v.unknown()),
+});
+
+export const mcpServerRemoveInputSchema = v.object({
+  id: mcpServerIdSchema,
+  confirm: v.optional(v.boolean()),
+});
+
+export const mcpApprovalResolveInputSchema = v.object({
+  id: nonEmptyStringSchema,
+  decision: v.picklist(['approve', 'deny']),
+  approverSurface: v.optional(nonEmptyStringSchema),
+  confirm: v.optional(v.boolean()),
+});
+
+export const mcpLoginStartInputSchema = v.object({
+  id: mcpServerIdSchema,
+  redirectUrl: v.optional(nonEmptyStringSchema),
+});
+
+export const mcpLogoutInputSchema = v.object({
+  id: mcpServerIdSchema,
+  confirm: v.optional(v.boolean()),
+});
+
+export const mcpListAuditInputSchema = v.object({
+  serverId: v.optional(mcpServerIdSchema),
+  limit: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+});
+
+export type McpConfig = v.InferOutput<typeof mcpConfigSchema>;
+export type McpServerConfig = v.InferOutput<typeof mcpServerConfigSchema>;
+export type McpToolPolicy = v.InferOutput<typeof mcpToolPolicySchema>;
+export type McpAuthConfig = v.InferOutput<typeof mcpAuthConfigSchema>;
+export type McpEnvRef = v.InferOutput<typeof mcpEnvRefSchema>;
+
+export function parseMcpConfig(value: unknown, path: string): McpConfig {
+  const result = v.safeParse(mcpConfigSchema, value);
+  if (!result.success) {
+    throw new Error(`${path}: ${v.summarize(result.issues)}`);
+  }
+  return result.output;
+}
+
+export function defaultMcpConfig(): McpConfig {
+  return { servers: {} };
+}
+
+export function mcpServerEnabled(server: McpServerConfig) {
+  return server.enabled ?? true;
+}
+
+function isAllowedMcpHttpUrl(value: string) {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+
+  if (url.protocol === 'https:') return true;
+  if (url.protocol !== 'http:') return false;
+  return url.hostname === '127.0.0.1' || url.hostname === 'localhost';
+}