Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

7.0 KB
Raw Blame
import { z } from 'zod';
import { redactSecrets, registerSecretValue } from '../../utils/redact.js';
import type { McpServerConfig } from './types.js';
import { isResourceUri } from './resource-policy.js';

export const SERVER_ID_PATTERN = /^[a-z][a-z0-9-]{0,23}$/;

const ENV_REF = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g;

const toolNames = z.array(z.string().min(1)).optional();
const resourceUri = z.string().refine(isResourceUri, 'expected an absolute resource URI (at most 2048 characters, no whitespace)');
const resourcePatterns = z.array(z.union([z.literal('*'), resourceUri])).max(256).optional();

const shared = {
  enabled: z.boolean().optional(),
  timeoutMs: z.number().int().positive().max(600_000).optional(),
  tools: z
    .object({ allow: toolNames, deny: toolNames, autoApprove: toolNames })
    .strict()
    .optional(),
  resources: z.object({
    allow: resourcePatterns,
    deny: resourcePatterns,
    autoApprove: z.array(resourceUri).max(256).optional(),
  }).strict().optional(),
};

const stdioServer = z
  .object({
    transport: z.literal('stdio'),
    command: z.string().min(1),
    args: z.array(z.string()).optional(),
    env: z.record(z.string()).optional(),
    cwd: z.string().min(1).optional(),
    ...shared,
  })
  .strict();

const httpServer = z
  .object({
    transport: z.literal('http'),
    url: z
      .string()
      .url()
      .refine((value) => /^https?:\/\//i.test(value), 'url must use http or https'),
    headers: z.record(z.string()).optional(),
    allowPrivate: z.boolean().optional(),
    ...shared,
  })
  .strict();

const serverSchema = z.discriminatedUnion('transport', [stdioServer, httpServer]);

export interface McpConfigValidation {
  servers: Record<string, McpServerConfig>;
  problems: string[];
  warnings: string[];
}

function formatIssue(id: string, issue: z.ZodIssue): string {
  const path = issue.path.length ? `.${issue.path.join('.')}` : '';
  return `mcp.servers.${id}${path}: ${issue.message}`;
}

function literalSecretWarnings(id: string, field: 'env' | 'headers', values: Record<string, string> | undefined): string[] {
  if (!values) return [];
  const warnings: string[] = [];
  for (const [key, value] of Object.entries(values)) {
    const withoutRefs = value.replace(ENV_REF, '');
    if (withoutRefs !== value && !withoutRefs.trim()) continue;
    if (redactSecrets(withoutRefs) !== withoutRefs) {
      warnings.push(`mcp.servers.${id}.${field}.${key} looks like a literal secret; use "\${env:NAME}" and keep the value in .env`);
    }
  }
  return warnings;
}

/**
 * Mercury's own credentials. `${env:NAME}` can read any variable, so a server
 * config naming one of these would hand it to a third-party server: allowed
 * (it may be deliberate), but always called out.
 */
const MERCURY_OWN_SECRETS = new Set([
  'AIMLAPI_API_KEY', 'ANTHROPIC_API_KEY', 'ATLASCLOUD_API_KEY', 'BOTS_WEBHOOK_SECRET', 'CLOUDGPU_API_KEY', 'DEEPSEEK_API_KEY',
  'DISCORD_BOT_TOKEN', 'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GROK_API_KEY', 'LITELLM_API_KEY', 'LM_STUDIO_API_KEY',
  'MERCURY_CLOUD_ACCESS_KEY', 'MERCURY_CLOUD_AGENT_API_KEY', 'MERCURY_CLOUD_REFRESH_TOKEN', 'MIMO_API_KEY',
  'MIMO_TOKEN_PLAN_API_KEY', 'OLLAMA_CLOUD_API_KEY', 'OPENAI_API_KEY', 'OPENAI_COMPAT_API_KEY', 'OPENROUTER_API_KEY',
  'RUNCRATE_API_KEY', 'SLACK_APP_TOKEN', 'SLACK_BOT_TOKEN', 'SPOTIFY_CLIENT_SECRET', 'TELEGRAM_BOT_TOKEN',
]);

function ownSecretWarnings(id: string, server: McpServerConfig): string[] {
  const values = [...(server.args ?? []), ...Object.values(server.env ?? {}), ...Object.values(server.headers ?? {})];
  const named = new Set<string>();
  for (const value of values) {
    for (const match of value.matchAll(ENV_REF)) if (MERCURY_OWN_SECRETS.has(match[1])) named.add(match[1]);
  }
  return [...named].map((name) => `mcp.servers.${id} is given ${name}, one of Mercury's own keys; the server "${id}" will see it. Use a separate key unless you mean this.`);
}

function hiddenAutoApproveWarnings(id: string, server: McpServerConfig, kind: 'tools' | 'resources' = 'tools'): string[] {
  const allow = server[kind]?.allow ?? [];
  const deny = server[kind]?.deny ?? [];
  const prefix = `mcp.servers.${id}.${kind}.autoApprove`;
  return (server[kind]?.autoApprove ?? []).flatMap((name) => {
    if (deny.includes(name) || (kind === 'resources' && deny.includes('*'))) return [`${prefix}: "${name}" is in ${kind}.deny, so the agent can't see it; remove it from ${kind}.deny`];
    if (allow.includes('*') || allow.includes(name)) return [];
    return [`${prefix}: "${name}" is not allowed, so the agent can't see it; add it to ${kind}.allow`];
  });
}

export function validateMcpConfig(raw: unknown): McpConfigValidation {
  const result: McpConfigValidation = { servers: {}, problems: [], warnings: [] };
  if (raw === undefined || raw === null) return result;
  if (typeof raw !== 'object' || Array.isArray(raw)) {
    result.problems.push('mcp: expected a mapping with a "servers" key');
    return result;
  }
  const servers = (raw as { servers?: unknown }).servers;
  if (servers === undefined || servers === null) return result;
  if (typeof servers !== 'object' || Array.isArray(servers)) {
    result.problems.push('mcp.servers: expected a mapping of server id to server settings');
    return result;
  }
  for (const [id, value] of Object.entries(servers as Record<string, unknown>)) {
    if (!SERVER_ID_PATTERN.test(id)) {
      result.problems.push(`mcp.servers.${id}: server id must match ${SERVER_ID_PATTERN.source}`);
      continue;
    }
    const parsed = serverSchema.safeParse(value);
    if (!parsed.success) {
      result.problems.push(formatIssue(id, parsed.error.issues[0]!));
      continue;
    }
    const server = parsed.data as McpServerConfig;
    result.servers[id] = server;
    result.warnings.push(
      ...literalSecretWarnings(id, 'env', server.env),
      ...literalSecretWarnings(id, 'headers', server.headers),
      ...hiddenAutoApproveWarnings(id, server),
      ...hiddenAutoApproveWarnings(id, server, 'resources'),
      ...ownSecretWarnings(id, server),
    );
  }
  return result;
}

export interface ResolvedSecrets {
  args: string[];
  env: Record<string, string>;
  headers: Record<string, string>;
}

function resolveValue(value: string, source: NodeJS.ProcessEnv): string {
  return value.replace(ENV_REF, (_match, name: string) => {
    const resolved = source[name];
    if (resolved === undefined || resolved === '') {
      throw new Error(`env ${name} is not set`);
    }
    registerSecretValue(resolved);
    return resolved;
  });
}

function resolveRecord(values: Record<string, string> | undefined, source: NodeJS.ProcessEnv): Record<string, string> {
  const out: Record<string, string> = {};
  for (const [key, value] of Object.entries(values ?? {})) {
    out[key] = resolveValue(value, source);
  }
  return out;
}

export function resolveSecrets(server: McpServerConfig, source: NodeJS.ProcessEnv = process.env): ResolvedSecrets {
  return {
    args: (server.args ?? []).map((arg) => resolveValue(arg, source)),
    env: resolveRecord(server.env, source),
    headers: resolveRecord(server.headers, source),
  };
}