MCP 应用程序接口参考

本文档提供 AG-Kit 模型上下文协议（MCP）集成组件的完整应用程序接口参考。

核心类

AGKitMCPServer

将 AG-Kit 工具作为标准 MCP 服务器暴露。

构造函数

new AGKitMCPServer(config: AGKitMCPServerConfig)

参数：

config: AGKitMCPServerConfig - 服务器配置对象

AGKitMCPServerConfig 接口：

interface AGKitMCPServerConfig {
  name: string;                    // 服务器名称
  version: string;                 // 服务器版本
  description?: string;            // 可选的服务器描述
  enableLogging?: boolean;         // 启用调试日志（默认：true）
  includeMetadata?: boolean;       // 包含执行元数据（默认：true）
  errorHandling?: 'throw' | 'return_error'; // 错误处理策略（默认：'return_error'）
  transformInput?: (input: any) => any;     // 输入转换函数
  transformOutput?: (output: any) => any;   // 输出转换函数
}

方法

`registerTool()`

向服务器注册单个 AG-Kit 工具。

registerTool(tool: BaseTool, toolConfig?: MCPToolConfig): MCPToolMetadata

参数：

tool: BaseTool - 要注册的 AG-Kit 工具
toolConfig?: MCPToolConfig - 可选的工具配置

返回： MCPToolMetadata - 已注册工具的元数据 MCPToolConfig 接口：

interface MCPToolConfig {
  name?: string;        // 覆盖工具名称
  description?: string; // 覆盖工具描述
  namePrefix?: string;  // 为工具名称添加前缀
}

registerTools()

使用共享配置注册多个 AG-Kit 工具。

registerTools(tools: BaseTool[], toolConfig?: MCPToolConfig): MCPToolMetadata[]

参数：

tools: BaseTool[] - 要注册的 AG-Kit 工具数组
toolConfig?: MCPToolConfig - 可选的共享配置

返回： MCPToolMetadata[] - 已注册工具的元数据数组

unregisterTool()

从服务器移除工具。

unregisterTool(name: string): boolean

参数：

name: string - 要移除的工具名称

返回： boolean - 如果工具被移除返回 true，未找到返回 false

run()

使用指定传输方式启动 MCP 服务器。

run(transportConfig: MCPTransportConfig): Promise<void>

参数：

transportConfig: MCPTransportConfig - 传输配置

MCPTransportConfig 类型：

type MCPTransportConfig = {
  type: 'stdio';
} | {
  type: 'memory';
  memoryId?: string;
} | {
  type: 'sse';
  sseSetup: SSETransportSetup;
} | {
  type: 'streamableHttp';
  streamableHttpSetup: StreamableHTTPTransportSetup;
}

stop()

停止 MCP 服务器并清理资源。

stop(): Promise<void>

callTool()

直接执行已注册工具。

callTool(name: string, args: Record<string, any>): Promise<CallToolResult>

参数：

name: string - 要执行的工具名称
args: Record<string, any> - 工具参数

返回： Promise<CallToolResult> - MCP 格式的工具结果

listTools()

获取所有已注册工具的列表。

listTools(): Array<{name: string; description: string; inputSchema: any}>

返回： 工具元数据对象数组

isServerRunning()

检查服务器当前是否运行中。

isServerRunning(): boolean

返回： boolean - 如果服务器正在运行返回 true

getStats()

获取服务器统计信息和详情。

getStats(): {
  totalTools: number;
  toolNames: string[];
  toolTypes: Record<string, number>;
  isRunning: boolean;
  serverInfo: {
    name: string;
    version: string;
    description?: string;
  };
}

addEventListener()

添加服务器事件监听器。

addEventListener(listener: MCPEventListener): void

参数：

listener: MCPEventListener - 事件监听函数

removeEventListener()

移除事件监听器。

removeEventListener(listener: MCPEventListener): boolean

参数：

listener: MCPEventListener - 要移除的事件监听器

返回： boolean - 如果监听器被移除返回 true

MCPClientManager

管理外部 MCP 服务器的连接。

构造函数

new MCPClientManager()

方法

addServer()

添加并连接到 MCP 服务器。

addServer(
  serverId: string, 
  config: MCPClientConfig, 
  connectionOptions?: MCPConnectionOptions
): Promise<void>

参数：

serverId: string - 服务器的唯一标识符
config: MCPClientConfig - 客户端配置
connectionOptions?: MCPConnectionOptions - 可选的连接设置

MCPClientConfig 接口：

interface MCPClientConfig {
  name: string;
  version: string;
  transport?: MCPTransportConfig;  // 如果未提供客户端则为必需
  client?: Client;                 // 预连接客户端
  onReconnectNeeded?: (serverId: string, config: MCPClientConfig) => Promise<Client>;
  capabilities?: {
    experimental?: Record<string, any>;
    sampling?: Record<string, any>;
  };
}

MCPConnectionOptions 接口：

interface MCPConnectionOptions {
  autoReconnect?: boolean;         // 启用自动重连（默认：true）
  reconnectDelay?: number;         // 重连尝试间隔（默认：5000ms）
  maxReconnectAttempts?: number;   // 最大重连尝试次数（默认：3）
  heartbeatInterval?: number;      // 心跳间隔（默认：30000ms）
}

disconnectServer()

断开与特定服务器的连接。

disconnectServer(serverId: string): Promise<void>

disconnectAll()

断开与所有服务器的连接。

disconnectAll(): Promise<void>

createClientTools()

为所有可用 MCP 工具创建 AG-Kit 工具包装器。

createClientTools(serverId?: string): MCPClientTool[]

参数：

serverId?: string - 可选服务器 ID 用于筛选工具

返回： MCPClientTool[] - 包装工具数组

createClientTool()

为特定 MCP 工具创建 AG-Kit 工具包装器。

createClientTool(
  serverId: string, 
  toolName: string, 
  agKitToolName?: string
): MCPClientTool

参数：

serverId: string - 包含工具的服务器 ID
toolName: string - MCP 工具名称
agKitToolName?: string - AG-Kit 工具的自定义名称

返回： MCPClientTool - 包装工具实例

callTool()

直接调用 MCP 工具。

callTool(serverId: string, toolName: string, args: any): Promise<any>

isServerConnected()

检查服务器是否已连接。

isServerConnected(serverId: string): boolean

getStats()

获取客户端管理器统计信息。

getStats(): {
  connectedServers: number;
  totalTools: number;
  serverStatus: Record<string, boolean>;
}

addEventListener()

添加客户端事件监听器。

addEventListener(listener: MCPEventListener): void

removeEventListener()

移除事件监听器。

removeEventListener(listener: MCPEventListener): boolean

MCPClientTool

包装外部 MCP 工具以在 AG-Kit 工具系统中工作。

构造函数

new MCPClientTool(
  mcpClient: Client,
  mcpToolMetadata: MCPToolMetadata,
  config?: MCPToolConfig,
  adapterConfig?: MCPAdapterConfig
)

参数：

mcpClient: Client - MCP 客户端实例
mcpToolMetadata: MCPToolMetadata - 来自 MCP 服务器的工具元

方法

invoke()

执行MCP工具（继承自BaseTool）。

invoke(input: any, context?: ToolExecutionContext): Promise<ToolResult>

getMCPMetadata()

获取原始MCP工具元数据。

getMCPMetadata(): MCPToolMetadata

isConnected()

检查底层MCP客户端是否已连接。

isConnected(): boolean

updateConfig()

更新工具配置。

updateConfig(newConfig: Partial<MCPToolConfig>): void

updateAdapterConfig()

更新适配器配置。

updateAdapterConfig(newAdapterConfig: Partial<MCPAdapterConfig>): void

MCPToolkit

用于管理外部服务器MCP工具的高级工具包。

构造函数

new MCPToolkit(name?: string)

参数：

name?: string - 可选工具包名称（默认：“mcp-toolkit”）

方法

addServer()

添加MCP服务器并加载其工具。

addServer(serverId: string, config: MCPClientConfig): Promise<void>

removeServer()

移除服务器及其工具。

removeServer(serverId: string): Promise<void>

getConnectedServers()

获取已连接服务器ID列表。

getConnectedServers(): string[]

getServerTools()

获取特定服务器的工具。

getServerTools(serverId: string): MCPClientTool[]

refresh()

刷新所有服务器连接并重新加载工具。

refresh(): Promise<void>

cleanup()

清理所有资源并断开与服务器的连接。

cleanup(): Promise<void>

getClientManager()

获取底层客户端管理器。

getClientManager(): MCPClientManager

getStats()

获取工具包统计信息。

getStats(): {
  name: string;
  description?: string;
  toolCount: number;
  mcp: {
    connectedServers: number;
    totalTools: number;
    serverStatus: Record<string, boolean>;
  };
}

实用函数

zodSchemaToMCPSchema()

将Zod模式转换为MCP JSON模式格式。

function zodSchemaToMCPSchema(zodSchema: z.ZodSchema<any>): any

参数：

zodSchema: z.ZodSchema<any> - 待转换的Zod模式

返回： MCP兼容的JSON模式对象

convertAGKitToolToMCPMetadata()

将AG-Kit BaseTool转换为MCP工具元数据。

function convertAGKitToolToMCPMetadata(
  tool: BaseTool,
  config?: AGKitMCPServerConfig,
  toolConfig?: MCPToolConfig
): MCPToolMetadata

createAGKitMCPServer()

创建并配置MCP服务器的实用函数。

async function createAGKitMCPServer(
  config: AGKitMCPServerConfig,
  tools?: BaseTool[]
): Promise<AGKitMCPServer>

createMCPToolkit()

创建预配置服务器的新MCP工具包。

type MCPServersConfig =
  | Record<string, MCPClientConfig>
  | Array<{ id: string; config: MCPClientConfig }>;

async function createMCPToolkit(
  servers: MCPServersConfig,
  name?: string
): Promise<MCPToolkit>

参数：

servers - 服务器配置（推荐使用对象映射格式或数组格式）
name - 可选工具包名称

示例：

// 对象映射格式（推荐）
const toolkit = await createMCPToolkit({
  time: {
    command: "uvx",
    args: ["mcp-server-time"]
  },
  weather: {
    url: "http://localhost:3000/mcp"
  }
});

// 完整MCPClientConfig的对象映射（如需自定义名称/版本）
const toolkit2 = await createMCPToolkit({
  time: {
    name: "custom-time-server",
    version: "2.0.0",
    transport: {
      command: "uvx",
      args: ["mcp-server-time"]
    }
  }
});

// 数组格式（向后兼容）
const toolkit3 = await createMCPToolkit([
  { 
    id: "time", 
    config: { 
      transport: { 
        command: "uvx", 
        args: ["mcp-server-time"] 
      } 
    } 
  }
]);

内存传输注册表

MemoryTransportRegistry

用于管理内存中MCP传输的单例注册表。

方法

getInstance()

获取单例实例。

static getInstance(): MemoryTransportRegistry

registerServer()

使用内存传输注册MCP服务器。

registerServer(memoryId: string, server: AGKitMCPServer): void

unregisterServer()

注销服务器。

unregisterServer(memoryId: string): void

getServer()

获取已注册的服务器。

getServer(memoryId: string): AGKitMCPServer | undefined

createTransportPair()

创建内存传输的链接对。

createTransportPair(memoryId: string): {server: any; client: any}

getClientTransport()

获取用于连接的客户端传输。

getClientTransport(memoryId: string): any

callTool()

通过内存传输直接调用工具。

async callTool(
  memoryId: string, 
  toolName: string, 
  args: Record<string, any>
): Promise<CallToolResult>

listTools()

通过内存传输列出工具。

async listTools(memoryId: string): Promise<Array<{
  name: string; 
  description: string; 
  inputSchema: any;
}>>

类型定义

MCPEvent

所有MCP事件的联合类型。

type MCPEvent =
  | { type: 'connected'; clientName: string }
  | { type: 'disconnected'; clientName: string; reason?: string }
  | { type: 'tool_discovered'; tool: MCPToolMetadata }
  | { type: 'tool_called'; toolName: string; arguments: any }
  | { type: 'tool_result'; toolName: string; result: CallToolResult }
  | { type: 'error'; error: Error; context?: string }

MCPEventListener

事件监听器函数类型。

type MCPEventListener = (event: MCPEvent) => void

MCPClientStatus

MCP客户端连接的状态信息。

interface MCPClientStatus {
  connected: boolean;
  sessionId?: string;
  serverInfo?: {
    name: string;
    version: string;
  };
  capabilities?: Record<string, any>;
  toolCount: number;
  resourceCount: number;
  promptCount: number;
  lastActivity?: Date;
  reconnectAttempts?: number;
  errors: Array<{
    timestamp: Date;
    error: Error;
    context?: string;
  }>;
}

传输配置类型

注意： 所有传输配置中的type字段均为可选。若未指定，将根据配置属性自动检测类型，优先级为：memory > stdio > streamableHttp > sse。

MCPStdioTransportConfig

interface MCPStdioTransportConfig {
  type?: 'stdio';  // 可选，若存在command字段则自动检测
  command: string;
  args?: string[];
  timeout?: number;
}

示例：

// type字段可选
const config = {
  command: "uvx",
  args: ["mcp-server-time"]
};

MCPSSETransportConfig

interface MCPSSETransportConfig {
  type?: 'sse';  // 可选，基于URL的配置会自动检测
  url: string;
  timeout?: number;
}

MCPSSETransportConfig

interface MCPSSETransportConfig {
  type?: 'sse';  // 可选参数，基于URL的配置会自动检测
  url: string;
  timeout?: number;
}

MCPStreamableHTTPTransportConfig

interface MCPStreamableHTTPTransportConfig {
  type?: 'streamableHttp';  // 可选参数，基于URL的配置会自动检测（默认类型）
  url: string;
  timeout?: number;
}

示例：

// type参数可选，会自动识别为streamableHttp
const config = {
  url: "https://agkit.mintlify.app/mcp"
};

MCPInMemoryTransportConfig

interface MCPInMemoryTransportConfig {
  type?: 'memory';  // 可选参数，若存在memoryId则自动检测
  memoryId: string;
  timeout?: number;
}

示例：

// type参数可选
const config = {
  memoryId: "my-server"
};

MCPCustomTransportConfig

interface MCPCustomTransportConfig {
  type?: 'custom';  // 可选参数，若存在transport则自动检测
  transport: any;  // 用户提供的传输实例
  timeout?: number;
}

自动检测优先级

当未指定type时，传输类型按以下顺序检测：

memory - 若存在memoryId
stdio - 若存在command
streamableHttp - 若存在url（基于URL配置的默认类型）
sse - 基于URL的配置需显式指定type: 'sse'
custom - 若存在transport

错误处理

McpError

MCP协议错误类。

class McpError extends Error {
  constructor(public code: number, message: string);
}

错误代码

enum ErrorCode {
  ParseError = -32700,
  InvalidRequest = -32600,
  MethodNotFound = -32601,
  InvalidParams = -32602,
  InternalError = -32603
}

常量与导出项

模块导出

// 核心类
export { AGKitMCPServer, MCPClientManager, MCPClientTool, MCPToolkit }

// 工具函数
export { 
  zodSchemaToMCPSchema, 
  convertAGKitToolToMCPMetadata,
  createAGKitMCPServer,
  createMCPToolkit
}

// 内存传输
export { MemoryTransportRegistry, memoryTransportRegistry }

// 类型定义
export type {
  AGKitMCPServerConfig,
  MCPClientConfig,
  MCPToolConfig,
  MCPAdapterConfig,
  MCPConnectionOptions,
  MCPToolMetadata,
  MCPEvent,
  MCPEventListener,
  MCPClientStatus,
  MCPTransportConfig,
  // ... 所有传输配置类型
}

全局注册表

// 全局内存传输注册表实例
export const memoryTransportRegistry: MemoryTransportRegistry

使用模式

服务端模式

import { AGKitMCPServer } from '@ag-kit/tools/mcp';

const server = new AGKitMCPServer(config);
server.registerTool(tool);
await server.run(transportConfig);

客户端模式

import { MCPClientManager } from '@ag-kit/tools/mcp';

const manager = new MCPClientManager();
await manager.addServer(serverId, clientConfig);
const tools = manager.createClientTools();

工具包模式

import { MCPToolkit } from '@ag-kit/tools/mcp';

const toolkit = new MCPToolkit();
await toolkit.addServer(serverId, config);
const tools = toolkit.getTools();

本API参考文档完整记录了AG-Kit中MCP集成的所有公共接口和方法。具体使用示例和实现模式请参阅MCP集成指南和MCP示例文档。

TypeScript SDK

Python SDK

无头 UI 组件

CLI 工具

​MCP 应用程序接口参考

​核心类

​AGKitMCPServer

​构造函数

​方法

registerTool()

registerTools()

unregisterTool()

run()

stop()

callTool()

listTools()

isServerRunning()

getStats()

addEventListener()

removeEventListener()

​MCPClientManager

​构造函数

​方法

addServer()

disconnectServer()

disconnectAll()

createClientTools()

createClientTool()

callTool()

isServerConnected()

getStats()

addEventListener()

removeEventListener()

​MCPClientTool

​构造函数

​方法

invoke()

getMCPMetadata()

isConnected()

updateConfig()

updateAdapterConfig()

​MCPToolkit

​构造函数

​方法

addServer()

removeServer()

getConnectedServers()

getServerTools()

refresh()

cleanup()

getClientManager()

getStats()

​实用函数

​zodSchemaToMCPSchema()

​convertAGKitToolToMCPMetadata()

​createAGKitMCPServer()

​createMCPToolkit()

​内存传输注册表

​MemoryTransportRegistry

​方法

getInstance()

registerServer()

unregisterServer()

getServer()

createTransportPair()

getClientTransport()

callTool()

listTools()

​类型定义

​MCPEvent

​MCPEventListener

​MCPClientStatus

​传输配置类型

​MCPStdioTransportConfig

​MCPSSETransportConfig

​MCPSSETransportConfig

​MCPStreamableHTTPTransportConfig

​MCPInMemoryTransportConfig

​MCPCustomTransportConfig

​自动检测优先级

MCP 应用程序接口参考

核心类

AGKitMCPServer

构造函数

方法

`registerTool()`

MCPClientManager

构造函数

方法

MCPClientTool

构造函数

方法

MCPToolkit

构造函数

方法

实用函数

zodSchemaToMCPSchema()

convertAGKitToolToMCPMetadata()

createAGKitMCPServer()

createMCPToolkit()

内存传输注册表

MemoryTransportRegistry

方法

类型定义

MCPEvent

MCPEventListener

MCPClientStatus

传输配置类型

MCPStdioTransportConfig

MCPSSETransportConfig

MCPSSETransportConfig

MCPStreamableHTTPTransportConfig

MCPInMemoryTransportConfig

MCPCustomTransportConfig

自动检测优先级

错误处理

McpError

错误代码

常量与导出项

模块导出

全局注册表

使用模式

服务端模式

客户端模式

工具包模式