mcp-use
Version:
Opinionated MCP Framework for TypeScript (@modelcontextprotocol/sdk compatible) - Build MCP Agents, Clients and Servers with support for ChatGPT Apps, Code Mode, OAuth, Notifications, Sampling, Observability and more.
211 lines • 7.71 kB
TypeScript
import type { CreateMessageRequest, CreateMessageResult, ElicitRequestFormParams, ElicitRequestURLParams, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
import React, { type ReactNode } from "react";
import type { StorageProvider } from "./storage/StorageProvider.js";
import type { UseMcpOptions, UseMcpResult } from "./types.js";
/**
* MCP notification received from a server
*/
export interface McpNotification {
id: string;
method: string;
params?: Record<string, unknown>;
timestamp: number;
read: boolean;
}
/**
* Pending sampling request from a server
*/
export interface PendingSamplingRequest {
id: string;
request: {
method: "sampling/createMessage";
params: CreateMessageRequest["params"];
};
timestamp: number;
serverName: string;
}
/**
* Pending elicitation request from a server
*/
export interface PendingElicitationRequest {
id: string;
request: ElicitRequestFormParams | ElicitRequestURLParams;
timestamp: number;
serverName: string;
}
/**
* Enhanced MCP server connection with notification, sampling, and elicitation management
*/
export interface McpServer extends UseMcpResult {
id: string;
url: string;
name: string;
notifications: McpNotification[];
unreadNotificationCount: number;
markNotificationRead: (id: string) => void;
markAllNotificationsRead: () => void;
clearNotifications: () => void;
pendingSamplingRequests: PendingSamplingRequest[];
approveSampling: (requestId: string, result: CreateMessageResult) => void;
rejectSampling: (requestId: string, error?: string) => void;
pendingElicitationRequests: PendingElicitationRequest[];
approveElicitation: (requestId: string, result: ElicitResult) => void;
rejectElicitation: (requestId: string, error?: string) => void;
}
/**
* Options for adding a server to the provider
* Extends UseMcpOptions but handles callbacks internally
*/
export interface McpServerOptions extends Omit<UseMcpOptions, "samplingCallback" | "onElicitation" | "onNotification"> {
name?: string;
onSamplingRequest?: (request: PendingSamplingRequest) => void;
onElicitationRequest?: (request: PendingElicitationRequest) => void;
onNotificationReceived?: (notification: McpNotification) => void;
}
/**
* Context value for multi-server management
*/
export interface McpClientContextType {
servers: McpServer[];
addServer: (id: string, options: McpServerOptions) => void;
removeServer: (id: string) => void;
updateServer: (id: string, options: Partial<McpServerOptions>) => Promise<void>;
getServer: (id: string) => McpServer | undefined;
/** Whether storage has finished loading (true if no storage provider) */
storageLoaded: boolean;
}
/**
* Props for McpClientProvider
*/
export interface McpClientProviderProps {
children: ReactNode;
/**
* Initial servers configuration (like Python MCPClient.from_dict)
* Servers defined here will be auto-connected on mount
*/
mcpServers?: Record<string, McpServerOptions>;
/**
* Default proxy configuration for all servers
* Can be overridden per-server in addServer() options
*/
defaultProxyConfig?: {
proxyAddress?: string;
headers?: Record<string, string>;
};
/**
* Enable automatic proxy fallback for all servers by default
* When enabled, if a direct connection fails with FastMCP or CORS errors,
* automatically retries using proxy configuration
* @default true
*/
defaultAutoProxyFallback?: boolean | {
enabled?: boolean;
proxyAddress?: string;
};
/**
* Storage provider for persisting server configurations
* When provided, automatically loads servers on mount and saves on changes
*/
storageProvider?: StorageProvider;
/**
* Enable RPC logging for debugging (browser only)
* Logs all MCP protocol messages to console
*/
enableRpcLogging?: boolean;
/**
* Callback when a server is added
*/
onServerAdded?: (id: string, server: McpServer) => void;
/**
* Callback when a server is removed
*/
onServerRemoved?: (id: string) => void;
/**
* Callback when a server's state changes
*/
onServerStateChange?: (id: string, state: McpServer["state"]) => void;
/**
* Callback when a sampling request is received from any server
* @param request The sampling request details
* @param serverId The ID of the server that sent the request
* @param serverName The name of the server
* @param approve Function to approve the request
* @param reject Function to reject the request
*/
onSamplingRequest?: (request: PendingSamplingRequest, serverId: string, serverName: string, approve: (requestId: string, result: CreateMessageResult) => void, reject: (requestId: string, error?: string) => void) => void;
/**
* Callback when an elicitation request is received from any server
* @param request The elicitation request details
* @param serverId The ID of the server that sent the request
* @param serverName The name of the server
* @param approve Function to approve the request
* @param reject Function to reject the request
*/
onElicitationRequest?: (request: PendingElicitationRequest, serverId: string, serverName: string, approve: (requestId: string, result: ElicitResult) => void, reject: (requestId: string, error?: string) => void) => void;
}
/**
* Provider for managing multiple MCP server connections
*
* Provides a context for adding/removing servers and accessing their state.
* Each server maintains its own connection, notification history, and
* pending sampling/elicitation requests.
*
* Supports:
* - Initial server configuration via `mcpServers` prop
* - Persistence via pluggable `storageProvider`
* - RPC logging for debugging
* - Lifecycle callbacks for state changes
*
* @example
* ```tsx
* // With initial servers
* <McpClientProvider
* mcpServers={{
* linear: { url: "https://mcp.linear.app/sse" },
* github: { url: "https://mcp.github.com/mcp" }
* }}
* >
* <MyApp />
* </McpClientProvider>
*
* // With persistence
* <McpClientProvider
* storageProvider={new LocalStorageProvider("my-servers")}
* enableRpcLogging={true}
* >
* <MyApp />
* </McpClientProvider>
* ```
*/
export declare function McpClientProvider({ children, mcpServers, defaultProxyConfig, defaultAutoProxyFallback, storageProvider, enableRpcLogging, onServerAdded, onServerRemoved, onServerStateChange, onSamplingRequest, onElicitationRequest, }: McpClientProviderProps): React.JSX.Element;
/**
* Hook to access the MCP client context
*
* Provides access to all servers and management functions.
* Must be used within a McpClientProvider.
*
* @example
* ```tsx
* const { servers, addServer, removeServer, updateServer } = useMcpClient();
*
* // Add a server
* addServer("linear", { url: "https://mcp.linear.app/sse" });
*
* // Update a server's configuration
* await updateServer("linear", { name: "Linear Production" });
*
* // Access servers
* servers.forEach(server => {
* console.log(server.id, server.state);
* });
* ```
*/
export declare function useMcpClient(): McpClientContextType;
/**
* Retrieve the McpServer object for a given server id.
*
* @returns The `McpServer` for the provided `id`, or `undefined` if no matching server is registered.
* @throws If called outside of a `McpClientProvider` (context not available).
*/
export declare function useMcpServer(id: string): McpServer | undefined;
//# sourceMappingURL=McpClientProvider.d.ts.map