/**
 * MCP (Model Context Protocol) Integration Types
 *
 * MCP 是 AI Agent 与外部工具/资源交互的标准协议。
 * 本模块定义了 MCP Server 配置、工具发现和连接状态的类型。
 */

// ============================================================
// Configuration Types
// ============================================================

/** MCP Server 传输类型 */
export type McpTransportType = 'stdio' | 'sse';

/** 单个 MCP Server 的配置 */
export interface McpServerConfig {
  /** 唯一标识，如 "calendar-server"，用于工具名前缀 */
  id: string;
  /** 可读名称，显示在工具描述中 */
  name: string;
  /** 传输类型 */
  transport: McpTransportType;
  /** stdio 模式：要执行的命令 */
  command?: string;
  /** stdio 模式：命令参数 */
  args?: string[];
  /** stdio 模式：传给子进程的环境变量 */
  env?: Record<string, string>;
  /** SSE 模式：Server URL */
  url?: string;
  /** 此 Server 的工具是否可并发执行（默认 true） */
  toolsConcurrencySafe?: boolean;
  /** 连接超时 ms（默认 10000） */
  connectTimeoutMs?: number;
  /** 工具执行超时 ms（默认 30000） */
  toolTimeoutMs?: number;
  /** 是否启用（默认 true） */
  enabled?: boolean;
}

/** 租户级 MCP 配置 */
export interface McpTenantConfig {
  /** 是否为此租户启用 MCP */
  enabled: boolean;
  /** MCP Server 列表 */
  servers: McpServerConfig[];
}

// ============================================================
// Runtime Types
// ============================================================

/** 发现的 MCP 工具定义 — 带前缀，可直接传给 Claude API */
export interface McpToolDefinition {
  /** 带前缀的工具名：mcp__{serverId}__{originalName} */
  name: string;
  /** MCP Server 上的原始工具名 */
  originalName: string;
  /** 所属 MCP Server ID */
  serverId: string;
  /** 工具描述（已添加 [MCP:serverName] 前缀） */
  description: string;
  /** JSON Schema for tool input */
  input_schema: Record<string, unknown>;
  /** 并发安全性（继承自 Server 配置） */
  isConcurrencySafe: boolean;
}

/** MCP Server 连接状态 */
export enum McpConnectionState {
  DISCONNECTED = 'disconnected',
  CONNECTING = 'connecting',
  CONNECTED = 'connected',
  ERROR = 'error',
}

/** 单个 MCP Server 的运行时状态 */
export interface McpServerState {
  config: McpServerConfig;
  state: McpConnectionState;
  tools: McpToolDefinition[];
  lastError?: string;
  connectedAt?: Date;
  client?: any; // MCP SDK Client instance
  transport?: any; // MCP SDK Transport instance
}

/** MCP 工具名前缀常量 */
export const MCP_TOOL_PREFIX = 'mcp__';
