@agentscope-ai/agentscope 0.0.2

package/src/mcp/stdio.test.ts

@@ -0,0 +1,91 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { StdioMCPClient } from './stdio';
+import { Toolkit } from '../tool';
+
+// Skip these tests on Windows due to npx/npm cache issues with MCP server packages
+const describeUnlessWindows = process.platform === 'win32' ? describe.skip : describe;
+
+describeUnlessWindows('StdIOMCPClient', () => {
+    const testDir = path.join(__dirname, 'test-data');
+    const testFilePath = path.join(testDir, 'test-file.txt');
+    const testContent = 'Hello, this is a test file for MCP filesystem server!';
+
+    beforeAll(() => {
+        // Create test directory and file
+        if (!fs.existsSync(testDir)) {
+            fs.mkdirSync(testDir, { recursive: true });
+        }
+        fs.writeFileSync(testFilePath, testContent, 'utf-8');
+    });
+
+    afterAll(() => {
+        // Clean up test directory and all its contents
+        if (fs.existsSync(testDir)) {
+            fs.rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+
+    test('Create StdIOMCPClient, list and execute tools', async () => {
+        const client = new StdioMCPClient({
+            name: 'filesystem',
+            command: 'npx',
+            args: ['-y', '@modelcontextprotocol/server-filesystem', testDir],
+        });
+
+        await client.connect();
+
+        const tools = await client.listTools();
+        expect(tools.length).toBeGreaterThan(0);
+
+        const tool = await client.getCallableFunction({ name: 'read_file' });
+        const res = await tool.call({ path: testFilePath });
+        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(testContent);
+        }
+
+        await client.close();
+
+        await client.connect();
+        const tools2 = await client.listTools();
+        expect(tools2.length).toBeGreaterThan(0);
+        await client.close();
+    }, 20000);
+
+    test('Test toolkit works with StdioMCPClient', async () => {
+        const client = new StdioMCPClient({
+            name: 'filesystem',
+            command: 'npx',
+            args: ['-y', '@modelcontextprotocol/server-filesystem', testDir],
+        });
+        await client.connect();
+
+        const toolkit = new Toolkit();
+        await toolkit.registerMCPClient({ client: client, enabledTools: ['read_file'] });
+
+        const schema = toolkit.getJSONSchemas();
+        expect(schema.length).toBe(2);
+        expect(schema[1].type).toBe('function');
+        expect(schema[1].function.name).toBe('read_file');
+        expect(schema[1].function.parameters).toBeDefined();
+
+        const res = toolkit.callToolFunction({
+            id: '123',
+            name: 'read_file',
+            type: 'tool_call',
+            input: `{"path": "${testFilePath}"}`,
+        });
+        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(testContent);
+            }
+        }
+
+        await client.close();
+    }, 30000);
+});

package/src/mcp/stdio.ts

@@ -0,0 +1,119 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import {
+    StdioClientTransport,
+    StdioServerParameters,
+} from '@modelcontextprotocol/sdk/client/stdio.js';
+import { ListToolsRequest, ListToolsResultSchema, Tool } from '@modelcontextprotocol/sdk/types.js';
+
+import { MCPTool } from './base';
+
+/**
+ * The STDIO MCP client class.
+ */
+export class StdioMCPClient {
+    name: string;
+    private stdioServerParameters: StdioServerParameters;
+    private transport?: StdioClientTransport;
+    private client?: Client;
+
+    /**
+     * Initialize the StdioMCPClient with the given Stdio parameters.
+     *
+     * @param root0
+     * @param root0.name
+     */
+    constructor({
+        name,
+        ...rest
+    }: {
+        name: string;
+    } & StdioServerParameters) {
+        this.name = name;
+        this.stdioServerParameters = rest;
+    }
+
+    /**
+     * Connect to the MCP server using Stdio transport. Note the Stdio client will start an
+     * MCP server process under the hood.
+     */
+    async connect() {
+        this.transport = new StdioClientTransport(this.stdioServerParameters);
+        this.client = new Client({
+            name: this.name,
+            version: '1.0.0',
+        });
+        await this.client.connect(this.transport);
+    }
+
+    /**
+     * Close the connection and stop the MCP server process.
+     */
+    async close() {
+        try {
+            if (this.client) {
+                await this.client.close();
+            }
+        } finally {
+            this.client = undefined;
+            this.transport = undefined;
+        }
+    }
+
+    /**
+     * 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[]> {
+        if (!this.client) {
+            throw new Error(
+                `Client not initialized, call 'connect()' method first for the MCP client named '${this.name}'`
+            );
+        }
+
+        const toolsRequest: ListToolsRequest = {
+            method: 'tools/list',
+            params: {},
+        };
+
+        const toolsResult = await this.client.request(toolsRequest, ListToolsResultSchema);
+        if (toolsResult.tools === undefined) {
+            return [];
+        }
+
+        return toolsResult.tools.map((tool: Tool) => {
+            return new MCPTool({
+                name: tool.name,
+                description: tool.description || '',
+                inputSchema: tool.inputSchema,
+                getClient: async () => this.client!,
+                releaseClient: async () => {},
+            });
+        });
+    }
+
+    /**
+     * 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.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/message/block.ts

@@ -0,0 +1,60 @@
+export interface TextBlock {
+    type: 'text';
+    text: string;
+    id: string;
+}
+
+export interface ThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+    id: string;
+}
+
+export interface HintBlock {
+    type: 'hint';
+    hint: string;
+    id: string;
+}
+
+export interface ToolCallBlock {
+    type: 'tool_call';
+    name: string;
+    id: string;
+    input: string;
+    awaitUserConfirmation?: boolean;
+}
+
+export interface ToolResultBlock {
+    type: 'tool_result';
+    id: string;
+    name: string;
+    output: string | (TextBlock | DataBlock)[];
+    state: 'success' | 'error' | 'interrupted' | 'running';
+}
+
+export interface Base64Source {
+    type: 'base64';
+    data: string;
+    mediaType: string;
+}
+
+export interface URLSource {
+    type: 'url';
+    url: string;
+    mediaType: string;
+}
+
+export interface DataBlock {
+    type: 'data';
+    source: Base64Source | URLSource;
+    id: string;
+    name?: string;
+}
+
+export type ContentBlock =
+    | TextBlock
+    | ThinkingBlock
+    | HintBlock
+    | ToolCallBlock
+    | ToolResultBlock
+    | DataBlock;

package/src/message/enums.ts

@@ -0,0 +1,4 @@
+export enum GenerateReason {
+    AWAITING_TOOL_RESULT = 'AWAITING_TOOL_RESULT',
+    AWAITING_USER_CONFIRMATION = 'AWAITING_USER_CONFIRMATION',
+}

package/src/message/index.ts

@@ -0,0 +1,12 @@
+export { Msg, createMsg, getTextContent, getContentBlocks } from './message';
+export {
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ContentBlock,
+    Base64Source,
+    URLSource,
+    DataBlock,
+} from './block';
+export { GenerateReason } from './enums';

package/src/message/message.test.ts

@@ -0,0 +1,80 @@
+import { createMsg, getContentBlocks, getTextContent } from './message';
+
+describe('Message', () => {
+    test('create message object', () => {
+        const msg = createMsg({
+            name: 'user',
+            content: [{ id: crypto.randomUUID(), type: 'text', text: 'Hello, world!' }],
+            role: 'user',
+        });
+        expect(msg.name).toBe('user');
+        expect(msg.content).toEqual([
+            { id: expect.any(String), type: 'text', text: 'Hello, world!' },
+        ]);
+        expect(msg.role).toBe('user');
+        expect(msg.metadata).toEqual({});
+        expect(msg.timestamp).toBeDefined();
+        expect(msg.id).toBeDefined();
+        expect(getTextContent(msg)).toBe('Hello, world!');
+
+        // getContentBlocks wraps a string content into a single TextBlock
+        const blocks = getContentBlocks(msg);
+        expect(blocks.length).toBe(1);
+        expect(blocks).toStrictEqual([
+            { id: expect.any(String), type: 'text', text: 'Hello, world!' },
+        ]);
+    });
+
+    test('obtain different content from message', () => {
+        const msg = createMsg({
+            name: 'user',
+            role: 'user',
+            content: [
+                { id: crypto.randomUUID(), type: 'text', text: 'Hello' },
+                { id: crypto.randomUUID(), type: 'thinking', thinking: '...' },
+                { id: crypto.randomUUID(), type: 'text', text: 'World' },
+                {
+                    type: 'tool_call',
+                    id: '1',
+                    name: 'test',
+                    input: "{ query: 'What is AI?' }",
+                },
+                {
+                    type: 'tool_result',
+                    id: '1',
+                    name: 'test',
+                    output: 'Artificial Intelligence',
+                    state: 'success',
+                },
+            ],
+        });
+
+        expect(getTextContent(msg)).toBe('Hello\nWorld');
+
+        expect(getContentBlocks(msg, 'text')).toStrictEqual([
+            { id: expect.any(String), type: 'text', text: 'Hello' },
+            { id: expect.any(String), type: 'text', text: 'World' },
+        ]);
+        expect(getContentBlocks(msg, 'thinking')).toStrictEqual([
+            { id: expect.any(String), type: 'thinking', thinking: '...' },
+        ]);
+        expect(getContentBlocks(msg, 'tool_call')).toStrictEqual([
+            {
+                type: 'tool_call',
+                id: '1',
+                name: 'test',
+                input: "{ query: 'What is AI?' }",
+            },
+        ]);
+        expect(getContentBlocks(msg, 'tool_result')).toStrictEqual([
+            {
+                type: 'tool_result',
+                id: '1',
+                name: 'test',
+                output: 'Artificial Intelligence',
+                state: 'success',
+            },
+        ]);
+        expect(getContentBlocks(msg, 'data')).toStrictEqual([]);
+    });
+});

package/src/message/message.ts

@@ -0,0 +1,131 @@
+import { JSONSerializableObject } from '../type';
+import {
+    ContentBlock,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolCallBlock,
+    DataBlock,
+} from './block';
+
+/** A chat message exchanged between agents or between an agent and a model. */
+export interface Msg {
+    /** Unique identifier for the message. */
+    id: string;
+    /** Display name of the message sender. */
+    name: string;
+    /** Conversation role of the sender. */
+    role: 'user' | 'assistant' | 'system';
+    /** Message body. */
+    content: ContentBlock[];
+    /** Arbitrary key-value metadata attached to the message. */
+    metadata: Record<string, JSONSerializableObject>;
+    /** ISO-8601 creation timestamp. */
+    timestamp: string;
+    /** Usage information for the message, such as token counts. */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+
+/**
+ * Create a new {@link Msg} object, filling in `id` and `timestamp` when omitted.
+ *
+ * @param root0
+ * @param root0.name
+ * @param root0.content
+ * @param root0.role
+ * @param root0.metadata
+ * @param root0.id
+ * @param root0.timestamp
+ * @param root0.usage
+ * @returns A fully-populated {@link Msg} object.
+ */
+export function createMsg({
+    name,
+    content,
+    role,
+    metadata = {},
+    id = crypto.randomUUID(),
+    timestamp = new Date().toISOString(),
+    usage,
+}: Omit<Msg, 'id' | 'timestamp' | 'metadata'> &
+    Partial<Pick<Msg, 'id' | 'timestamp' | 'metadata'>>): Msg {
+    return { id, name, role, content, metadata, timestamp, usage } as Msg;
+}
+
+/**
+ * Extract the plain-text content from a message.
+ *
+ * When `content` is a string it is returned as-is. When it is an array of
+ * content blocks, all {@link TextBlock} texts are joined with `separator`.
+ *
+ * @param msg - The message to read.
+ * @param separator - String inserted between consecutive text blocks. Defaults to `'\n'`.
+ * @returns The concatenated text, or `null` when no text blocks are present.
+ */
+export function getTextContent(msg: Msg, separator: string = '\n'): string | null {
+    const textBlocks = msg.content.filter(block => block.type === 'text');
+    if (textBlocks.length === 0) {
+        return null;
+    }
+    return textBlocks.map(block => (block as TextBlock).text).join(separator);
+}
+
+/**
+ * Return all content blocks from a message, regardless of type.
+ *
+ * When `content` is a plain string it is wrapped in a single {@link TextBlock}.
+ *
+ * @param msg - The message to read.
+ * @returns An array of all {@link ContentBlock} objects.
+ */
+export function getContentBlocks(msg: Msg): ContentBlock[];
+/**
+ * Return all {@link TextBlock} objects from a message.
+ *
+ * @param msg - The message to read.
+ * @param blockType - `'text'`
+ * @returns An array of {@link TextBlock} objects.
+ */
+export function getContentBlocks(msg: Msg, blockType: 'text'): TextBlock[];
+/**
+ * Return all {@link ThinkingBlock} objects from a message.
+ *
+ * @param msg - The message to read.
+ * @param blockType - `'thinking'`
+ * @returns An array of {@link ThinkingBlock} objects.
+ */
+export function getContentBlocks(msg: Msg, blockType: 'thinking'): ThinkingBlock[];
+/**
+ * Return all {@link DataBlock} objects from a message.
+ *
+ * @param msg - The message to read.
+ * @param blockType - `'video'`
+ * @returns An array of {@link DataBlock} objects.
+ */
+export function getContentBlocks(msg: Msg, blockType: 'data'): DataBlock[];
+/**
+ * Return all {@link ToolCallBlock} objects from a message.
+ *
+ * @param msg - The message to read.
+ * @param blockType - `'tool_call'`
+ * @returns An array of {@link ToolCallBlock} objects.
+ */
+export function getContentBlocks(msg: Msg, blockType: 'tool_call'): ToolCallBlock[];
+/**
+ * Return all {@link ToolResultBlock} objects from a message.
+ *
+ * @param msg - The message to read.
+ * @param blockType - `'tool_result'`
+ * @returns An array of {@link ToolResultBlock} objects.
+ */
+export function getContentBlocks(msg: Msg, blockType: 'tool_result'): ToolResultBlock[];
+export function getContentBlocks(
+    msg: Msg,
+    blockType?: 'text' | 'thinking' | 'data' | 'tool_call' | 'tool_result'
+): ContentBlock[] {
+    if (!blockType) return msg.content;
+    return msg.content.filter(block => block.type === blockType);
+}