MCP client-server agent

MCPAgent.ts

/**
 * This interface describes an MCPAgent that extends the Agent class to function
 * as both an MCP client and an MCP server. It can consume and produce MCP
 * requests/notifications in adherence to the MCP specification.
 *
 * By handling both Client and Server message forms, this interface enables
 * both connecting to MCP clients, and receiving connections from other MCP servers.
 * Methods with a `handle...` prefix receive incoming requests/notifications, while methods with
 * a `send...` prefix dispatch messages to a peer.
 *
 * The union types (ClientRequest, ClientNotification, etc.) correspond precisely
 * to those defined in the MCP specification. Implementations can match on the
 * `method` field (or other criteria) to customise handling for each method type
 * (e.g., "initialize", "tools/call", "ping", etc.).
 *
 * @template Env   The environment bindings type, supplied by the Agent SDK.
 * @template State The Agent’s persisted state type.
 */

import {
  Agent,
  type AgentContext,
  type Connection,
  // ...other imports as needed from your Agent SDK...
} from "./agent_sdk_path";

/** These imports reflect the MCP specification’s consolidated types. */
import {
  ClientRequest,
  ClientNotification,
  ClientResult,
  ServerRequest,
  ServerNotification,
  ServerResult,
  JSONRPCError,
} from "./mcp_spec_types_path";

export interface MCPAgent<Env = unknown, State = unknown>
  extends Agent<Env, State> {
  /**
   * Handle an incoming MCP request originating from an MCP client.
   * @param request The request from the client (e.g. "initialize", "tools/call").
   * @returns A promise resolving to either a successful result or an MCP error.
   */
  handleClientRequest(
    request: ClientRequest
  ): Promise<ClientResult | JSONRPCError>;

  /**
   * Handle an incoming MCP notification originating from an MCP client.
   * @param notification The notification from the client (e.g. "notifications/cancelled").
   */
  handleClientNotification(notification: ClientNotification): void;

  /**
   * Handle an incoming MCP request originating from an MCP server.
   * @param request The request from the server (e.g. "sampling/createMessage", "ping").
   * @returns A promise resolving to either a successful result or an MCP error.
   */
  handleServerRequest(
    request: ServerRequest
  ): Promise<ServerResult | JSONRPCError>;

  /**
   * Handle an incoming MCP notification originating from an MCP server.
   * @param notification The notification from the server (e.g. "notifications/progress").
   */
  handleServerNotification(notification: ServerNotification): void;

  /**
   * Send an MCP request to a peer playing the client role (i.e. this agent acts as server).
   * @param request A valid ClientRequest from the MCP specification.
   * @returns A promise resolving to a ClientResult or JSONRPCError.
   */
  sendClientRequest(
    request: ClientRequest
  ): Promise<ClientResult | JSONRPCError>;

  /**
   * Send an MCP notification to a peer playing the client role (i.e. this agent acts as server).
   * Notifications do not expect a response.
   * @param notification A valid ClientNotification from the MCP specification.
   */
  sendClientNotification(notification: ClientNotification): void;

  /**
   * Send an MCP request to a peer playing the server role (i.e. this agent acts as client).
   * @param request A valid ServerRequest from the MCP specification.
   * @returns A promise resolving to a ServerResult or JSONRPCError.
   */
  sendServerRequest(
    request: ServerRequest
  ): Promise<ServerResult | JSONRPCError>;

  /**
   * Send an MCP notification to a peer playing the server role (i.e. this agent acts as client).
   * Notifications do not expect a response.
   * @param notification A valid ServerNotification from the MCP specification.
   */
  sendServerNotification(notification: ServerNotification): void;
}