@agentscope-ai/agentscope 0.0.2

package/src/mcp/base.ts

@@ -0,0 +1,114 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { CallToolRequest, CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import z from 'zod';
+
+import { Tool, ToolResponse } from '../tool';
+import { createToolResponse } from '../tool/response';
+import { ToolInputSchema } from '../type';
+
+/**
+ * Type definition for getting a client instance
+ */
+type GetClient = () => Promise<Client>;
+
+/**
+ * Type definition for releasing a client instance
+ */
+type ReleaseClient = (client: Client) => Promise<void>;
+
+/**
+ * MCPTool class that wraps an MCP tool and provides a callable interface
+ */
+export class MCPTool implements Tool {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject | ToolInputSchema;
+    requireUserConfirm = false;
+    call: (input: Record<string, unknown>) => Promise<ToolResponse>;
+
+    private getClient: GetClient;
+    private releaseClient: ReleaseClient;
+
+    /**
+     * Initialize an MCPTool instance
+     * @param root0
+     * @param root0.name
+     * @param root0.description
+     * @param root0.inputSchema
+     * @param root0.getClient
+     * @param root0.releaseClient
+     */
+    constructor({
+        name,
+        description,
+        inputSchema,
+        getClient,
+        releaseClient,
+    }: {
+        name: string;
+        description: string;
+        inputSchema: z.ZodObject | ToolInputSchema;
+        getClient: GetClient;
+        releaseClient: ReleaseClient;
+    }) {
+        this.name = name;
+        this.description = description;
+        this.inputSchema = inputSchema;
+        this.getClient = getClient;
+        this.releaseClient = releaseClient;
+        this.call = this._call.bind(this);
+    }
+
+    /**
+     * Call the MCP tool with the specified input arguments. This method sends a request to the MCP server to execute
+     * the tool and returns the result as a ToolResponse.
+     *
+     * @param arguments
+     * @param input
+     * @returns A ToolResponse object containing the result of the tool execution, or an error message if the call fails.
+     */
+    async _call(input: Record<string, unknown>) {
+        const client = await this.getClient();
+        try {
+            const request: CallToolRequest = {
+                method: 'tools/call',
+                params: {
+                    name: this.name,
+                    arguments: input,
+                },
+            };
+            const result = await client.request(request, CallToolResultSchema);
+
+            const content: ToolResponse['content'] = [];
+            result.content.forEach(item => {
+                if (item.type === 'text') {
+                    content.push({ type: 'text', text: item.text, id: crypto.randomUUID() });
+                } else if (item.type === 'image' || item.type === 'audio') {
+                    content.push({
+                        id: crypto.randomUUID(),
+                        type: 'data',
+                        source: { type: 'base64', mediaType: item.mimeType, data: item.data },
+                    });
+                } else {
+                    console.warn(
+                        `Unsupported content type '${item.type}' in tool result, skipping...`
+                    );
+                }
+            });
+            return createToolResponse({ content, state: 'success' });
+        } catch (error) {
+            return createToolResponse({
+                content: [
+                    {
+                        id: crypto.randomUUID(),
+                        type: 'text',
+                        text: `Error calling tool '${this.name}': ${error}`,
+                    },
+                ],
+                state: 'error',
+            });
+        } finally {
+            await this.releaseClient(client);
+        }
+    }
+}

package/src/mcp/http.test.ts

@@ -0,0 +1,303 @@
+import * as http from 'http';
+
+import { HTTPMCPClient } from './http';
+import { Toolkit, ToolResponse } from '../tool';
+
+/**
+ * Creates a minimal MCP HTTP server for testing purposes.
+ *
+ * @param port - The port number to listen on
+ * @returns An HTTP server instance
+ */
+function createTestMCPServer(port: number): http.Server {
+    const sessions = new Map<string, Record<string, unknown>>();
+    let sessionCounter = 0;
+
+    const server = http.createServer(async (req, res) => {
+        // Handle CORS
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
+
+        if (req.method === 'OPTIONS') {
+            res.writeHead(200);
+            res.end();
+            return;
+        }
+
+        let body = '';
+        req.on('data', chunk => {
+            body += chunk.toString();
+        });
+
+        req.on('end', async () => {
+            try {
+                const message = JSON.parse(body);
+                let response: Record<string, unknown>;
+
+                switch (message.method) {
+                    case 'initialize': {
+                        sessionCounter++;
+                        const sessionId = `session-${sessionCounter}`;
+                        sessions.set(sessionId, {});
+                        response = {
+                            jsonrpc: '2.0',
+                            id: message.id,
+                            result: {
+                                protocolVersion: '2024-11-05',
+                                capabilities: { tools: {} },
+                                serverInfo: {
+                                    name: 'test-mcp-server',
+                                    version: '1.0.0',
+                                },
+                                sessionId,
+                            },
+                        };
+                        break;
+                    }
+
+                    case 'tools/list': {
+                        response = {
+                            jsonrpc: '2.0',
+                            id: message.id,
+                            result: {
+                                tools: [
+                                    {
+                                        name: 'add',
+                                        description: 'Adds two numbers together',
+                                        inputSchema: {
+                                            type: 'object',
+                                            properties: {
+                                                a: {
+                                                    type: 'number',
+                                                    description: 'First number',
+                                                },
+                                                b: {
+                                                    type: 'number',
+                                                    description: 'Second number',
+                                                },
+                                            },
+                                            required: ['a', 'b'],
+                                        },
+                                    },
+                                ],
+                            },
+                        };
+                        break;
+                    }
+
+                    case 'tools/call': {
+                        if (message.params.name === 'add') {
+                            const { a, b } = message.params.arguments;
+                            const result = a + b;
+                            response = {
+                                jsonrpc: '2.0',
+                                id: message.id,
+                                result: {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: `Result: ${a} + ${b} = ${result}`,
+                                        },
+                                    ],
+                                },
+                            };
+                        } else {
+                            response = {
+                                jsonrpc: '2.0',
+                                id: message.id,
+                                error: {
+                                    code: -32601,
+                                    message: 'Tool not found',
+                                },
+                            };
+                        }
+                        break;
+                    }
+
+                    default: {
+                        response = {
+                            jsonrpc: '2.0',
+                            id: message.id,
+                            error: {
+                                code: -32601,
+                                message: 'Method not found',
+                            },
+                        };
+                    }
+                }
+
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(response));
+            } catch {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(
+                    JSON.stringify({
+                        jsonrpc: '2.0',
+                        id: null,
+                        error: {
+                            code: -32700,
+                            message: 'Parse error',
+                        },
+                    })
+                );
+            }
+        });
+    });
+
+    server.listen(port);
+    return server;
+}
+
+describe('HTTPStatefulMCPClient', () => {
+    const TEST_PORT = 13579;
+    const TEST_URL = `http://localhost:${TEST_PORT}/mcp`;
+    let testServer: http.Server;
+
+    beforeAll(() => {
+        testServer = createTestMCPServer(TEST_PORT);
+    });
+
+    afterAll(done => {
+        testServer.close(done);
+    });
+
+    test('Create HTTP MCP client, list and execute tools', async () => {
+        const client = new HTTPMCPClient({
+            name: 'test-mcp-server',
+            transportType: 'streamable-http',
+            url: TEST_URL,
+            stateful: true,
+        });
+        await client.connect();
+
+        const tools = await client.listTools();
+        expect(tools.length).toBeGreaterThan(0);
+
+        const func = await client.getCallableFunction({ name: 'add' });
+        const res = await func.call({ a: 5, b: 3 });
+        expect(res.content.length).toBeGreaterThan(0);
+        expect(res.content[0].type).toBe('text');
+        if (res.content[0].type === 'text') {
+            expect(res.content[0].text).toContain('8');
+        }
+
+        await client.close();
+
+        // Try to reconnect and list tools again
+        await client.connect();
+        const tools2 = await client.listTools();
+        expect(tools2.length).toBeGreaterThan(0);
+
+        await client.close();
+    }, 10000);
+
+    test('Test toolkit works with HTTPStatefulMCPClient', async () => {
+        const client = new HTTPMCPClient({
+            name: 'test-mcp-server',
+            transportType: 'streamable-http',
+            url: TEST_URL,
+            stateful: true,
+        });
+        await client.connect();
+
+        const toolkit = new Toolkit();
+        await toolkit.registerMCPClient({ client, enabledTools: ['add'] });
+
+        const schema = toolkit.getJSONSchemas();
+        expect(schema.length).toBe(2);
+        expect(schema[1].type).toBe('function');
+        expect(schema[1].function.name).toBe('add');
+        expect(schema[1].function.parameters).toBeDefined();
+
+        const res = toolkit.callToolFunction({
+            id: '123',
+            name: 'add',
+            type: 'tool_call',
+            input: `{"a": 10, "b": 20}`,
+        });
+        for await (const item of res) {
+            expect(item.content.length).toBeGreaterThan(0);
+            expect(item.content[0].type).toBe('text');
+            if (item.content[0].type === 'text') {
+                expect(item.content[0].text).toContain('30');
+            }
+        }
+
+        await client.close();
+    }, 10000);
+});
+
+describe('HTTPStatelessMCPClient', () => {
+    const TEST_PORT = 13580;
+    const TEST_URL = `http://localhost:${TEST_PORT}/mcp`;
+    let testServer: http.Server;
+
+    beforeAll(() => {
+        testServer = createTestMCPServer(TEST_PORT);
+    });
+
+    afterAll(done => {
+        testServer.close(done);
+    });
+
+    test('Create stateless HTTP MCP client, list and execute tools without explicit connect/close', async () => {
+        const client = new HTTPMCPClient({
+            name: 'test-mcp-server',
+            transportType: 'streamable-http',
+            url: TEST_URL,
+            stateful: false,
+        });
+
+        // connect() and close() are no-ops for stateless clients
+        await client.connect();
+
+        const tools = await client.listTools();
+        expect(tools.length).toBeGreaterThan(0);
+
+        const func = await client.getCallableFunction({ name: 'add' });
+        const res = await func.call({ a: 7, b: 13 });
+        expect(res.content.length).toBeGreaterThan(0);
+        expect(res.content[0].type).toBe('text');
+        if (res.content[0].type === 'text') {
+            expect(res.content[0].text).toContain('20');
+        }
+
+        await client.close();
+    }, 10000);
+
+    test('Test toolkit works with HTTPStatelessMCPClient', async () => {
+        const client = new HTTPMCPClient({
+            name: 'test-mcp-server',
+            transportType: 'streamable-http',
+            url: TEST_URL,
+            stateful: false,
+        });
+
+        const toolkit = new Toolkit();
+        await toolkit.registerMCPClient({ client, enabledTools: ['add'] });
+
+        const schema = toolkit.getJSONSchemas();
+        expect(schema.length).toBe(2);
+        expect(schema[1].type).toBe('function');
+        expect(schema[1].function.name).toBe('add');
+        expect(schema[1].function.parameters).toBeDefined();
+
+        const res = toolkit.callToolFunction({
+            id: '123',
+            name: 'add',
+            type: 'tool_call',
+            input: `{"a": 15, "b": 25}`,
+        });
+        const collectedRes: ToolResponse[] = [];
+        for await (const item of res) {
+            collectedRes.push(item);
+            expect(item.content.length).toBeGreaterThan(0);
+            expect(item.content[0].type).toBe('text');
+            if (item.content[0].type === 'text') {
+                expect(item.content[0].text).toContain('40');
+            }
+        }
+        expect(collectedRes.length).toBe(1);
+    }, 10000);
+});

package/src/mcp/http.ts

@@ -0,0 +1,224 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import {
+    SSEClientTransport,
+    SSEClientTransportOptions,
+} from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { ListToolsRequest, ListToolsResultSchema, Tool } from '@modelcontextprotocol/sdk/types.js';
+
+import { MCPTool } from './base';
+
+/**
+ * The HTTP MCP client class that connects to an MCP server using either Streamable HTTP or Server-Sent Events (SSE)
+ * transport.
+ * Note the client is stateful, meaning that developers should manually call the `connect()` and `close()` methods to
+ * manage the connection lifecycle.
+ */
+export class HTTPMCPClient {
+    name: string;
+    private requestOptions?: RequestOptions;
+    private client?: Client;
+    private transport?: StreamableHTTPClientTransport | SSEClientTransport;
+    private transportType: 'streamable-http' | 'sse';
+    private url: string;
+    private transportOpts?: StreamableHTTPClientTransportOptions | SSEClientTransportOptions;
+    private stateful: boolean;
+
+    /**
+     * Initialize the HTTPStatefulMCPClient with the specified transport type, URL, and options.
+     *
+     * @param root0
+     * @param root0.name
+     * @param root0.transportType
+     * @param root0.url
+     * @param root0.stateful
+     * @param root0.transportOpts
+     * @param root0.requestOptions
+     */
+    constructor({
+        name,
+        transportType,
+        url,
+        stateful = true,
+        transportOpts,
+        requestOptions,
+    }: {
+        name: string;
+        transportType: 'streamable-http' | 'sse';
+        url: string;
+        stateful?: boolean;
+        transportOpts?: StreamableHTTPClientTransportOptions | SSEClientTransportOptions;
+        requestOptions?: RequestOptions;
+    }) {
+        this.name = name;
+        this.transportType = transportType;
+        this.transportOpts = transportOpts;
+        this.requestOptions = requestOptions;
+        this.url = url;
+        this.stateful = stateful;
+    }
+
+    /**
+     * Connect to the MCP server with the specified transport and URL. This method must be called before making any
+     * requests to the server.
+     */
+    async connect() {
+        if (!this.stateful) {
+            console.log(
+                `MCP client '${this.name}' initialized with stateful=false will connect and close the connection automatically for each request, no need to call 'connect()' method explicitly.`
+            );
+        } else {
+            await this._connect();
+        }
+    }
+
+    /**
+     * The internal method to establish the connection to the MCP server. It initializes the appropriate transport
+     * based on the specified transport type and creates a new Client instance to manage the connection and requests.
+     */
+    protected async _connect() {
+        const baseUrl = new URL(this.url);
+        if (this.transportType === 'streamable-http') {
+            this.transport = new StreamableHTTPClientTransport(baseUrl, this.transportOpts);
+        } else {
+            this.transport = new SSEClientTransport(baseUrl, this.transportOpts);
+        }
+        this.client = new Client({
+            name: this.name,
+            version: '1.0.0',
+        });
+        await this.client.connect(this.transport, this.requestOptions);
+        console.log(`MCP client '${this.name}' is connected`);
+    }
+
+    /**
+     * List all tools available on the MCP server.
+     *
+     * @returns An array of MCPTool instances representing the tools available on the server.
+     */
+    async listTools(): Promise<MCPTool[]> {
+        let listClient: Client;
+
+        if (this.stateful) {
+            if (!this.client) {
+                throw new Error(
+                    `Client not initialized, call 'connect()' method first for the MCP client named '${this.name}'`
+                );
+            }
+            listClient = this.client;
+        } else {
+            listClient = await this._createClient();
+        }
+
+        try {
+            const toolsRequest: ListToolsRequest = {
+                method: 'tools/list',
+                params: {},
+            };
+
+            const toolsResult = await listClient.request(toolsRequest, ListToolsResultSchema);
+            if (toolsResult.tools === undefined) {
+                return [];
+            }
+
+            return toolsResult.tools.map((tool: Tool) => {
+                if (this.stateful) {
+                    return new MCPTool({
+                        name: tool.name,
+                        description: tool.description || '',
+                        inputSchema: tool.inputSchema,
+                        getClient: async () => this.client!,
+                        releaseClient: async () => {},
+                    });
+                } else {
+                    return new MCPTool({
+                        name: tool.name,
+                        description: tool.description || '',
+                        inputSchema: tool.inputSchema,
+                        getClient: () => this._createClient(),
+                        releaseClient: async (c: Client) => {
+                            await c.close();
+                        },
+                    });
+                }
+            });
+        } finally {
+            if (!this.stateful) {
+                await listClient.close();
+            }
+        }
+    }
+
+    /**
+     * Close the connection to the MCP server and clean up any resources used by the client.
+     */
+    async close() {
+        if (!this.stateful) {
+            console.log(
+                `MCP client '${this.name}' initialized with stateful=false will connect and close the connection automatically for each request, no need to call 'close()' method explicitly.`
+            );
+        } else {
+            await this._close();
+        }
+    }
+
+    /**
+     * The internal method to close the connection to the MCP server.
+     */
+    protected async _close() {
+        try {
+            await this.client?.close();
+        } finally {
+            console.log(`MCP client '${this.name} is closed.'`);
+            this.client = undefined;
+            this.transport = undefined;
+        }
+    }
+
+    /**
+     * Create a new client instance without storing it in this.client.
+     * Used for stateless operations where each request needs its own client.
+     * @returns A new connected Client instance
+     */
+    protected async _createClient(): Promise<Client> {
+        const baseUrl = new URL(this.url);
+        const transport =
+            this.transportType === 'streamable-http'
+                ? new StreamableHTTPClientTransport(baseUrl, this.transportOpts)
+                : new SSEClientTransport(baseUrl, this.transportOpts);
+
+        const client = new Client({
+            name: this.name,
+            version: '1.0.0',
+        });
+        await client.connect(transport, this.requestOptions);
+        return client;
+    }
+
+    /**
+     * Get a callable function for a specific tool by its name.
+     * @param root0
+     * @param root0.name
+     * @returns An instance of MCPTool that can be called to execute the tool's functionality.
+     */
+    async getCallableFunction({ name }: { name: string }) {
+        if (this.stateful && !this.client) {
+            throw new Error(
+                `Client not initialized, call 'connect()' method first for the MCP client named '${this.name}'`
+            );
+        }
+
+        const tools = await this.listTools();
+        const targetTool = tools.find(tool => tool.name === name);
+
+        if (!targetTool) {
+            throw new Error(
+                `Tool '${name}' not found in MCP server '${this.name}'. Available tools: ${tools.map(t => t.name).join(', ')}`
+            );
+        }
+
+        return targetTool;
+    }
+}

package/src/mcp/index.ts

@@ -0,0 +1,2 @@
+export * from './http';
+export * from './stdio';