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.

18.2 KB
Raw Blame
import type { Schema, Tool } from 'ai';
import { Client, type Tool as McpTool } from '@modelcontextprotocol/client';
import { logger } from '../../utils/logger.js';
import { redactSecrets } from '../../utils/redact.js';
import { resolveSecrets } from './config.js';
import { exposedToolName } from './naming.js';
import { toInputSchema } from './schema.js';
import { buildMcpTool } from './tool.js';
import { createTransport, describeTarget } from './transport.js';
import type { McpCallResultLike } from './result.js';
import type { McpGate, McpResourceGate, McpServerConfig, McpServerState, McpServerStatus, McpToolStatus } from './types.js';
import { isResourceAllowed, isResourceAutoApproved, resourcesEnabled } from './resource-policy.js';
import { buildResourceTools, ResourceCatalog, resourceResultToText } from './resources.js';

export const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
export const DEFAULT_CALL_TIMEOUT_MS = 60_000;
export const CLOSE_TIMEOUT_MS = 3_000;

export interface McpBackoff {
  initialMs: number;
  maxMs: number;
  maxAttempts: number;
  stableMs: number;
}

const DEFAULT_BACKOFF: McpBackoff = { initialMs: 1_000, maxMs: 300_000, maxAttempts: 10, stableMs: 60_000 };

export interface McpManagerOptions {
  gate: McpGate;
  resourceGate?: McpResourceGate;
  onToolsChanged?: () => void;
  connectTimeoutMs?: number;
  backoff?: Partial<McpBackoff>;
}

interface DescribedTool {
  status: McpToolStatus;
  description?: string;
  schema?: Schema<Record<string, unknown>>;
}

interface ToolEntry extends McpToolStatus {
  tool?: Tool;
}

interface ServerEntry {
  id: string;
  config: McpServerConfig;
  state: McpServerState;
  error?: string;
  client?: Client;
  stderrTail: () => string;
  tools: ToolEntry[];
  resourcesAvailable?: boolean;
  attempts: number;
  connectedAt?: number;
  generation: number;
  timer?: ReturnType<typeof setTimeout>;
}

function clientInfo(): { name: string; version: string } {
  const version = (globalThis as { __MERCURY_VERSION__?: string }).__MERCURY_VERSION__ ?? '0.0.0';
  return { name: 'mercury', version };
}

function errorMessage(err: unknown): string {
  const data = (err as { data?: { status?: unknown; statusText?: unknown; text?: unknown } } | null)?.data;
  if (data && typeof data.status === 'number') {
    const statusText = typeof data.statusText === 'string' && data.statusText ? ` ${data.statusText}` : '';
    const body = typeof data.text === 'string' && data.text.trim() ? `: ${data.text.trim().slice(0, 200)}` : '';
    return redactSecrets(`HTTP ${data.status}${statusText}${body}`);
  }
  return redactSecrets(err instanceof Error ? err.message : String(err));
}

const CONNECTION_ERROR_CODES = new Set([
  'ECONNREFUSED',
  'ECONNRESET',
  'ENOTFOUND',
  'EAI_AGAIN',
  'EHOSTUNREACH',
  'ENETUNREACH',
  'ETIMEDOUT',
  'EPIPE',
  'UND_ERR_SOCKET',
  'UND_ERR_CONNECT_TIMEOUT',
]);

function isConnectionError(err: unknown): boolean {
  let current: unknown = err;
  for (let depth = 0; depth < 5 && current && typeof current === 'object'; depth++) {
    const { code, message, cause } = current as { code?: unknown; message?: unknown; cause?: unknown };
    if (typeof code === 'string' && CONNECTION_ERROR_CODES.has(code)) return true;
    if (message === 'fetch failed') return true;
    current = cause;
  }
  return false;
}

export function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  const timeout = new Promise<never>((_, reject) => {
    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms} ms`)), ms);
  });
  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}

async function closeQuietly(client: Client): Promise<void> {
  try {
    await withTimeout(client.close(), CLOSE_TIMEOUT_MS, 'close');
  } catch {
    return;
  }
}

export function isToolAllowed(config: McpServerConfig, toolName: string): boolean {
  const filter = config.tools ?? {};
  if (filter.deny?.includes(toolName)) return false;
  return filter.allow?.includes('*') === true || filter.allow?.includes(toolName) === true;
}

export function isToolAutoApproved(config: McpServerConfig, toolName: string): boolean {
  return config.tools?.autoApprove?.includes(toolName) === true;
}

export function describeTools(serverId: string, config: McpServerConfig, tools: McpTool[]): DescribedTool[] {
  const taken = new Set<string>();
  const seen = new Set<string>();
  const described: DescribedTool[] = [];
  for (const tool of tools) {
    if (seen.has(tool.name)) continue;
    seen.add(tool.name);
    const exposedName = exposedToolName(serverId, tool.name, taken);
    taken.add(exposedName);
    const schema = toInputSchema(tool.inputSchema);
    described.push({
      status: {
        name: tool.name,
        exposedName,
        allowed: isToolAllowed(config, tool.name),
        autoApprove: isToolAutoApproved(config, tool.name),
        skipped: 'skip' in schema ? schema.skip : undefined,
      },
      description: tool.description,
      schema: 'schema' in schema ? schema.schema : undefined,
    });
  }
  return described;
}

function baseStatus(id: string, config: McpServerConfig): Omit<McpServerStatus, 'state'> {
  return {
    id,
    transport: config.transport,
    enabled: config.enabled !== false,
    target: describeTarget(config),
    toolCount: 0,
    tools: [],
  };
}

export async function probeMcpServer(
  id: string,
  config: McpServerConfig,
  timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS,
): Promise<McpServerStatus> {
  let stderrTail = (): string => '';
  const client = new Client(clientInfo());
  try {
    const created = createTransport(config, resolveSecrets(config));
    stderrTail = created.stderrTail;
    await withTimeout(client.connect(created.transport), timeoutMs, 'connect');
    const { tools } = client.getServerCapabilities()?.tools
      ? await withTimeout(client.listTools(), timeoutMs, 'tools/list') : { tools: [] };
    const statuses = describeTools(id, config, tools).map((d) => d.status);
    return { ...baseStatus(id, config), state: 'connected', toolCount: statuses.length, tools: statuses };
  } catch (err) {
    return {
      ...baseStatus(id, config),
      state: 'failed',
      error: errorMessage(err),
      stderrTail: stderrTail() || undefined,
    };
  } finally {
    await closeQuietly(client);
  }
}

export class McpManager {
  private readonly servers = new Map<string, ServerEntry>();
  private readonly connectTimeoutMs: number;
  private readonly backoff: McpBackoff;
  private closed = false;
  private readonly resourceCatalog = new ResourceCatalog();

  constructor(servers: Record<string, McpServerConfig>, private readonly options: McpManagerOptions) {
    this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
    this.backoff = { ...DEFAULT_BACKOFF, ...options.backoff };
    for (const [id, config] of Object.entries(servers)) {
      this.servers.set(id, {
        id,
        config,
        state: config.enabled === false ? 'disabled' : 'connecting',
        stderrTail: () => '',
        tools: [],
        attempts: 0,
        generation: 0,
      });
    }
  }

  async connectAll(): Promise<void> {
    const pending = [...this.servers.values()].filter((entry) => entry.state !== 'disabled');
    await Promise.allSettled(pending.map((entry) => this.connect(entry)));
  }

  getTools(): Record<string, Tool> {
    const tools: Record<string, Tool> = {};
    for (const entry of this.servers.values()) {
      if (entry.state !== 'connected' && entry.state !== 'reconnecting') continue;
      for (const tool of entry.tools) {
        if (tool.tool) tools[tool.exposedName] = tool.tool;
      }
    }
    if (this.options.resourceGate && this.resourceServers().length) {
      Object.assign(tools, buildResourceTools({
        servers: async (signal) => {
          const verdict = await this.options.resourceGate!({ operation: 'servers', signal });
          if (!verdict.allowed) throw new Error(verdict.reason ?? 'MCP resource servers are not available');
          if (signal?.aborted) throw new Error('MCP resource request was cancelled');
          return this.resourceServers();
        },
        list: (server, cursor, signal) => this.listResources(server, cursor, signal),
        read: (server, uri, signal) => this.readResource(server, uri, signal),
      }));
    }
    return tools;
  }

  private resourceServers(): string[] {
    return [...this.servers.values()].filter((entry) => resourcesEnabled(entry.config) && entry.resourcesAvailable
      && (entry.state === 'connected' || entry.state === 'reconnecting')).map((entry) => entry.id);
  }

  private resourceServer(id: string): ServerEntry {
    const entry = this.servers.get(id);
    if (!entry || !resourcesEnabled(entry.config) || !entry.resourcesAvailable || !this.options.resourceGate) {
      throw new Error(`MCP resources are not enabled for server ${id}`);
    }
    return entry;
  }

  private async resourceRequest<T>(entry: ServerEntry, signal: AbortSignal | undefined, operation: (client: Client) => Promise<T>): Promise<T> {
    if (signal?.aborted) throw new Error('MCP resource request was cancelled');
    const client = entry.client;
    if (!client || entry.state !== 'connected' || this.closed) throw new Error(`server ${entry.id} is ${entry.state}`);
    const generation = entry.generation;
    try {
      const result = await operation(client);
      if (signal?.aborted) throw new Error('MCP resource request was cancelled');
      if (entry.generation !== generation || entry.client !== client) throw new Error('MCP server reconnected; repeat the resource request');
      return result;
    } catch (err) {
      if (isConnectionError(err)) this.scheduleReconnect(entry, errorMessage(err), generation);
      throw err;
    }
  }

  private async listResources(serverId: string, cursor: string | undefined, signal: AbortSignal | undefined): Promise<string> {
    const entry = this.resourceServer(serverId);
    if (signal?.aborted) throw new Error('MCP resource request was cancelled');
    const verdict = await this.options.resourceGate!({ serverId, operation: 'list', autoApprove: false, signal });
    if (!verdict.allowed) throw new Error(verdict.reason ?? 'MCP resource list was not approved');
    if (signal?.aborted) throw new Error('MCP resource request was cancelled');
    if (!entry.client || entry.state !== 'connected') throw new Error(`server ${serverId} is ${entry.state}`);
    const saved = cursor ? this.resourceCatalog.continuation(serverId, entry.generation, cursor) : undefined;
    if (saved?.resources.length) return this.resourceCatalog.render(saved);
    // listResources() auto-fetches every page in SDK v2. A protocol request
    // deliberately fetches only one page, including the initial page.
    const page = await this.resourceRequest(entry, signal, (client) => client.request({
      method: 'resources/list',
      params: saved?.remoteCursor ? { cursor: saved.remoteCursor } : {},
    }, { signal, timeout: entry.config.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS }));
    return this.resourceCatalog.render(this.resourceCatalog.prepare(serverId, entry.generation, page,
      (uri) => isResourceAllowed(entry.config, uri)));
  }

  private async readResource(serverId: string, uri: string, signal: AbortSignal | undefined): Promise<string> {
    const entry = this.resourceServer(serverId);
    if (!isResourceAllowed(entry.config, uri)) throw new Error(`MCP resource URI is not allowed for server ${serverId}`);
    if (signal?.aborted) throw new Error('MCP resource request was cancelled');
    const verdict = await this.options.resourceGate!({ serverId, operation: 'read', uri, autoApprove: isResourceAutoApproved(entry.config, uri), signal });
    if (!verdict.allowed) throw new Error(verdict.reason ?? 'MCP resource read was not approved');
    const result = await this.resourceRequest(entry, signal, (client) => client.readResource({ uri }, {
      signal, timeout: entry.config.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS, cacheMode: 'bypass',
    }));
    return resourceResultToText(serverId, uri, result);
  }

  isAutoApproved(exposedName: string): boolean {
    for (const entry of this.servers.values()) {
      const tool = entry.tools.find((t) => t.exposedName === exposedName);
      if (tool) return tool.autoApprove;
    }
    return false;
  }

  status(): McpServerStatus[] {
    return [...this.servers.values()].map((entry) => ({
      ...baseStatus(entry.id, entry.config),
      state: entry.state,
      error: entry.error,
      toolCount: entry.tools.length,
      tools: entry.tools.map((tool) => ({
        name: tool.name,
        exposedName: tool.exposedName,
        allowed: tool.allowed,
        autoApprove: tool.autoApprove,
        skipped: tool.skipped,
      })),
      stderrTail: entry.stderrTail() || undefined,
    }));
  }

  async testServer(id: string): Promise<McpServerStatus | undefined> {
    const entry = this.servers.get(id);
    return entry ? probeMcpServer(id, entry.config, this.connectTimeoutMs) : undefined;
  }

  async close(): Promise<void> {
    this.closed = true;
    this.resourceCatalog.clear();
    await Promise.allSettled(
      [...this.servers.values()].map(async (entry) => {
        if (entry.timer) clearTimeout(entry.timer);
        entry.timer = undefined;
        entry.generation++;
        const client = entry.client;
        entry.client = undefined;
        entry.tools = [];
        if (entry.state !== 'disabled') {
          entry.state = 'failed';
          entry.error = 'manager closed';
        }
        if (client) await closeQuietly(client);
      }),
    );
  }

  private async connect(entry: ServerEntry): Promise<void> {
    if (this.closed) return;
    entry.timer = undefined;
    const generation = ++entry.generation;
    let created;
    try {
      created = createTransport(entry.config, resolveSecrets(entry.config));
    } catch (err) {
      this.fail(entry, errorMessage(err));
      return;
    }
    entry.stderrTail = created.stderrTail;
    const client = new Client(clientInfo(), {
      listChanged: {
        tools: {
          onChanged: (err, tools) => {
            if (entry.generation !== generation) return;
            if (err) {
              logger.warn({ server: entry.id, err: errorMessage(err) }, 'MCP tool list refresh failed');
              return;
            }
            if (tools) this.applyTools(entry, tools);
          },
        },
      },
    });
    let established = false;
    client.onclose = () => {
      if (established) this.scheduleReconnect(entry, 'connection closed', generation);
    };
    try {
      await withTimeout(client.connect(created.transport), this.connectTimeoutMs, 'connect');
      const { tools } = client.getServerCapabilities()?.tools
        ? await withTimeout(client.listTools(), this.connectTimeoutMs, 'tools/list') : { tools: [] };
      if (entry.generation !== generation || this.closed) {
        await closeQuietly(client);
        return;
      }
      established = true;
      entry.client = client;
      entry.state = 'connected';
      entry.error = undefined;
      entry.connectedAt = Date.now();
      entry.resourcesAvailable = !!client.getServerCapabilities()?.resources;
      this.applyTools(entry, tools);
      logger.info({ server: entry.id, tools: entry.tools.length }, 'MCP server connected');
    } catch (err) {
      this.scheduleReconnect(entry, errorMessage(err), generation);
      await closeQuietly(client);
    }
  }

  private scheduleReconnect(entry: ServerEntry, reason: string, generation: number): void {
    if (this.closed || entry.generation !== generation) return;
    entry.generation++;
    this.resourceCatalog.clear(entry.id);
    const client = entry.client;
    entry.client = undefined;
    if (client) void closeQuietly(client);
    entry.error = reason;
    if (entry.connectedAt !== undefined && Date.now() - entry.connectedAt >= this.backoff.stableMs) entry.attempts = 0;
    entry.connectedAt = undefined;
    entry.attempts++;
    if (entry.attempts > this.backoff.maxAttempts) {
      this.fail(entry, `${reason} (gave up after ${this.backoff.maxAttempts} attempts)`);
      return;
    }
    entry.state = 'reconnecting';
    const base = Math.min(this.backoff.maxMs, this.backoff.initialMs * 2 ** (entry.attempts - 1));
    const delay = Math.round(base * (0.8 + Math.random() * 0.4));
    logger.warn({ server: entry.id, attempt: entry.attempts, delayMs: delay, reason }, 'MCP server unavailable, retrying');
    entry.timer = setTimeout(() => void this.connect(entry), delay);
    entry.timer.unref?.();
  }

  private fail(entry: ServerEntry, reason: string): void {
    entry.state = 'failed';
    entry.error = reason;
    entry.client = undefined;
    this.resourceCatalog.clear(entry.id);
    logger.warn({ server: entry.id, reason }, 'MCP server failed');
    if (entry.tools.length) {
      entry.tools = [];
      this.options.onToolsChanged?.();
    }
  }

  private applyTools(entry: ServerEntry, tools: McpTool[]): void {
    entry.tools = describeTools(entry.id, entry.config, tools).map(({ status, description, schema }) => {
      if (status.skipped) {
        logger.warn({ server: entry.id, tool: status.name, reason: status.skipped }, 'MCP tool skipped');
      }
      const tool =
        status.allowed && schema
          ? buildMcpTool({
              serverId: entry.id,
              toolName: status.name,
              exposedName: status.exposedName,
              description,
              inputSchema: schema,
              autoApprove: status.autoApprove,
              gate: this.options.gate,
              call: (name, args, signal) => this.call(entry, name, args, signal),
            })
          : undefined;
      return { ...status, tool };
    });
    this.options.onToolsChanged?.();
  }

  private async call(
    entry: ServerEntry,
    toolName: string,
    args: Record<string, unknown>,
    signal: AbortSignal | undefined,
  ): Promise<McpCallResultLike> {
    const client = entry.client;
    if (!client || entry.state !== 'connected') {
      throw new Error(`server ${entry.id} is ${entry.state}`);
    }
    const generation = entry.generation;
    try {
      return await client.callTool(
        { name: toolName, arguments: args },
        { signal, timeout: entry.config.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS },
      );
    } catch (err) {
      if (isConnectionError(err)) this.scheduleReconnect(entry, errorMessage(err), generation);
      throw err;
    }
  }
}