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.
438 lines • 15 kB
TypeScript
import type { CallToolResult, Notification, Root, Tool } from "@modelcontextprotocol/sdk/types.js";
import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
import type { BaseConnector, NotificationHandler } from "./connectors/base.js";
export declare class MCPSession {
readonly connector: BaseConnector;
private autoConnect;
constructor(connector: BaseConnector, autoConnect?: boolean);
connect(): Promise<void>;
disconnect(): Promise<void>;
initialize(): Promise<void>;
get isConnected(): boolean;
/**
* Register an event handler for session events
*
* @param event - The event type to listen for
* @param handler - The handler function to call when the event occurs
*
* @example
* ```typescript
* session.on("notification", async (notification) => {
* console.log(`Received: ${notification.method}`, notification.params);
*
* if (notification.method === "notifications/tools/list_changed") {
* // Refresh tools list
* }
* });
* ```
*/
on(event: "notification", handler: NotificationHandler): void;
/**
* Set roots and notify the server.
* Roots represent directories or files that the client has access to.
*
* @param roots - Array of Root objects with `uri` (must start with "file://") and optional `name`
*
* @example
* ```typescript
* await session.setRoots([
* { uri: "file:///home/user/project", name: "My Project" },
* { uri: "file:///home/user/data" }
* ]);
* ```
*/
setRoots(roots: Root[]): Promise<void>;
/**
* Get the current roots.
*/
getRoots(): Root[];
/**
* Get the cached list of tools from the server.
*
* @returns Array of available tools
*
* @example
* ```typescript
* const tools = session.tools;
* console.log(`Available tools: ${tools.map(t => t.name).join(", ")}`);
* ```
*/
get tools(): Tool[];
/**
* List all available tools from the MCP server.
* This method fetches fresh tools from the server, unlike the `tools` getter which returns cached tools.
*
* @param options - Optional request options
* @returns Array of available tools
*
* @example
* ```typescript
* const tools = await session.listTools();
* console.log(`Available tools: ${tools.map(t => t.name).join(", ")}`);
* ```
*/
listTools(options?: RequestOptions): Promise<Tool[]>;
/**
* Get the server capabilities advertised during initialization.
*
* @returns Server capabilities object
*/
get serverCapabilities(): Record<string, unknown>;
/**
* Get the server information (name and version).
*
* @returns Server info object or null if not available
*/
get serverInfo(): {
name: string;
version?: string;
} | null;
/**
* Call a tool on the server.
*
* @param name - Name of the tool to call
* @param args - Arguments to pass to the tool (defaults to empty object)
* @param options - Optional request options (timeout, progress handlers, etc.)
* @returns Result from the tool execution
*
* @example
* ```typescript
* const result = await session.callTool("add", { a: 5, b: 3 });
* console.log(`Result: ${result.content[0].text}`);
* ```
*/
callTool(name: string, args?: Record<string, any>, options?: RequestOptions): Promise<CallToolResult>;
/**
* List resources from the server with optional pagination.
*
* @param cursor - Optional cursor for pagination
* @param options - Request options
* @returns Resource list with optional nextCursor for pagination
*
* @example
* ```typescript
* const result = await session.listResources();
* console.log(`Found ${result.resources.length} resources`);
* ```
*/
listResources(cursor?: string, options?: RequestOptions): Promise<{
[x: string]: unknown;
resources: {
uri: string;
name: string;
description?: string | undefined;
mimeType?: string | undefined;
annotations?: {
audience?: ("user" | "assistant")[] | undefined;
priority?: number | undefined;
lastModified?: string | undefined;
} | undefined;
_meta?: {
[x: string]: unknown;
} | undefined;
icons?: {
src: string;
mimeType?: string | undefined;
sizes?: string[] | undefined;
theme?: "light" | "dark" | undefined;
}[] | undefined;
title?: string | undefined;
}[];
_meta?: {
[x: string]: unknown;
progressToken?: string | number | undefined;
"io.modelcontextprotocol/related-task"?: {
taskId: string;
} | undefined;
} | undefined;
nextCursor?: string | undefined;
}>;
/**
* List all resources from the server, automatically handling pagination.
*
* @param options - Request options
* @returns Complete list of all resources
*
* @example
* ```typescript
* const result = await session.listAllResources();
* console.log(`Total resources: ${result.resources.length}`);
* ```
*/
listAllResources(options?: RequestOptions): Promise<{
resources: any[];
}>;
/**
* List resource templates from the server.
*
* @param options - Request options
* @returns List of available resource templates
*
* @example
* ```typescript
* const result = await session.listResourceTemplates();
* console.log(`Available templates: ${result.resourceTemplates.length}`);
* ```
*/
listResourceTemplates(options?: RequestOptions): Promise<{
[x: string]: unknown;
resourceTemplates: {
uriTemplate: string;
name: string;
description?: string | undefined;
mimeType?: string | undefined;
annotations?: {
audience?: ("user" | "assistant")[] | undefined;
priority?: number | undefined;
lastModified?: string | undefined;
} | undefined;
_meta?: {
[x: string]: unknown;
} | undefined;
icons?: {
src: string;
mimeType?: string | undefined;
sizes?: string[] | undefined;
theme?: "light" | "dark" | undefined;
}[] | undefined;
title?: string | undefined;
}[];
_meta?: {
[x: string]: unknown;
progressToken?: string | number | undefined;
"io.modelcontextprotocol/related-task"?: {
taskId: string;
} | undefined;
} | undefined;
nextCursor?: string | undefined;
}>;
/**
* Read a resource by URI.
*
* @param uri - URI of the resource to read
* @param options - Request options
* @returns Resource content
*
* @example
* ```typescript
* const resource = await session.readResource("file:///path/to/file.txt");
* console.log(resource.contents);
* ```
*/
readResource(uri: string, options?: RequestOptions): Promise<{
[x: string]: unknown;
contents: ({
uri: string;
text: string;
mimeType?: string | undefined;
_meta?: Record<string, unknown> | undefined;
} | {
uri: string;
blob: string;
mimeType?: string | undefined;
_meta?: Record<string, unknown> | undefined;
})[];
_meta?: {
[x: string]: unknown;
progressToken?: string | number | undefined;
"io.modelcontextprotocol/related-task"?: {
taskId: string;
} | undefined;
} | undefined;
}>;
/**
* Subscribe to resource updates.
*
* @param uri - URI of the resource to subscribe to
* @param options - Request options
*
* @example
* ```typescript
* await session.subscribeToResource("file:///path/to/file.txt");
* // Now you'll receive notifications when this resource changes
* ```
*/
subscribeToResource(uri: string, options?: RequestOptions): Promise<{
_meta?: {
[x: string]: unknown;
progressToken?: string | number | undefined;
"io.modelcontextprotocol/related-task"?: {
taskId: string;
} | undefined;
} | undefined;
}>;
/**
* Unsubscribe from resource updates.
*
* @param uri - URI of the resource to unsubscribe from
* @param options - Request options
*
* @example
* ```typescript
* await session.unsubscribeFromResource("file:///path/to/file.txt");
* ```
*/
unsubscribeFromResource(uri: string, options?: RequestOptions): Promise<{
_meta?: {
[x: string]: unknown;
progressToken?: string | number | undefined;
"io.modelcontextprotocol/related-task"?: {
taskId: string;
} | undefined;
} | undefined;
}>;
/**
* List available prompts from the server.
*
* @returns List of available prompts
*
* @example
* ```typescript
* const result = await session.listPrompts();
* console.log(`Available prompts: ${result.prompts.length}`);
* ```
*/
listPrompts(): Promise<{
[x: string]: unknown;
prompts: {
name: string;
description?: string | undefined;
arguments?: {
name: string;
description?: string | undefined;
required?: boolean | undefined;
}[] | undefined;
_meta?: {
[x: string]: unknown;
} | undefined;
icons?: {
src: string;
mimeType?: string | undefined;
sizes?: string[] | undefined;
theme?: "light" | "dark" | undefined;
}[] | undefined;
title?: string | undefined;
}[];
_meta?: {
[x: string]: unknown;
progressToken?: string | number | undefined;
"io.modelcontextprotocol/related-task"?: {
taskId: string;
} | undefined;
} | undefined;
nextCursor?: string | undefined;
}>;
/**
* Get a specific prompt with arguments.
*
* @param name - Name of the prompt to get
* @param args - Arguments for the prompt
* @returns Prompt result
*
* @example
* ```typescript
* const prompt = await session.getPrompt("greeting", { name: "Alice" });
* console.log(prompt.messages);
* ```
*/
getPrompt(name: string, args: Record<string, any>): Promise<{
[x: string]: unknown;
messages: {
role: "user" | "assistant";
content: {
type: "text";
text: string;
annotations?: {
audience?: ("user" | "assistant")[] | undefined;
priority?: number | undefined;
lastModified?: string | undefined;
} | undefined;
_meta?: Record<string, unknown> | undefined;
} | {
type: "image";
data: string;
mimeType: string;
annotations?: {
audience?: ("user" | "assistant")[] | undefined;
priority?: number | undefined;
lastModified?: string | undefined;
} | undefined;
_meta?: Record<string, unknown> | undefined;
} | {
type: "audio";
data: string;
mimeType: string;
annotations?: {
audience?: ("user" | "assistant")[] | undefined;
priority?: number | undefined;
lastModified?: string | undefined;
} | undefined;
_meta?: Record<string, unknown> | undefined;
} | {
type: "resource";
resource: {
uri: string;
text: string;
mimeType?: string | undefined;
_meta?: Record<string, unknown> | undefined;
} | {
uri: string;
blob: string;
mimeType?: string | undefined;
_meta?: Record<string, unknown> | undefined;
};
annotations?: {
audience?: ("user" | "assistant")[] | undefined;
priority?: number | undefined;
lastModified?: string | undefined;
} | undefined;
_meta?: Record<string, unknown> | undefined;
} | {
uri: string;
name: string;
type: "resource_link";
description?: string | undefined;
mimeType?: string | undefined;
annotations?: {
audience?: ("user" | "assistant")[] | undefined;
priority?: number | undefined;
lastModified?: string | undefined;
} | undefined;
_meta?: {
[x: string]: unknown;
} | undefined;
icons?: {
src: string;
mimeType?: string | undefined;
sizes?: string[] | undefined;
theme?: "light" | "dark" | undefined;
}[] | undefined;
title?: string | undefined;
};
}[];
_meta?: {
[x: string]: unknown;
progressToken?: string | number | undefined;
"io.modelcontextprotocol/related-task"?: {
taskId: string;
} | undefined;
} | undefined;
description?: string | undefined;
}>;
/**
* Send a raw request through the client.
*
* @param method - MCP method name
* @param params - Request parameters
* @param options - Request options
* @returns Response from the server
*
* @example
* ```typescript
* const result = await session.request("custom/method", { key: "value" });
* ```
*/
request(method: string, params?: Record<string, any> | null, options?: RequestOptions): Promise<any>;
}
export type { CallToolResult, Notification, Root, Tool };
//# sourceMappingURL=session.d.ts.map