init

functionality/mcp/README.md

@@ -0,0 +1,61 @@
+# MCP in AgentScope
+
+This example demonstrates how to
+
+- create MCP client with different transports (SSE and Streamable HTTP) and type (Stateless and Stateful),
+- register MCP tool functions and use them in a ReAct agent, and
+- get MCP tool function as a local callable object from the MCP client.
+
+
+## Prerequisites
+
+- Python 3.10 or higher
+- DashScope API key from Alibaba Cloud
+
+## Installation
+
+### Install from PyPI (Recommended)
+
+### Install AgentScope
+
+```bash
+# Install from source
+cd {PATH_TO_AGENTSCOPE}
+pip install -e .
+```
+
+## QuickStart
+
+Install agentscope and ensure you have a valid DashScope API key in your environment variables.
+
+> Note: The example is built with DashScope chat model. If you want to change the model in this example, don't forget
+> to change the formatter at the same time! The corresponding relationship between built-in models and formatters are
+> list in [our tutorial](https://doc.agentscope.io/tutorial/task_prompt.html#id1)
+
+```bash
+pip install agentscope
+```
+
+Start the MCP servers by the following commands in two separate terminals:
+
+```bash
+# In one terminal, run:
+python mcp_add.py
+
+# In another terminal, run:
+python mcp_multiply.py
+```
+
+Two MCP servers will be started on `http://127.0.0.1:8001` (SSE server) and `http://127.0.0.1:8002` (streamable
+HTTP server).
+
+After starting the MCP servers, you can run the agent example:
+
+```bash
+python main.py
+```
+
+The agent will:
+1. Register the MCP tools from the servers
+2. Use a ReAct agent to solve a calculation problem (multiplying two numbers and then adding another number)
+3. Return structured output with the final result

functionality/mcp/main.py

@@ -0,0 +1,109 @@
+# -*- coding: utf-8 -*-
+"""
+Demo showcasing ReAct agent with MCP tools using different transports.
+
+This example demonstrates:
+- Registering MCP tools with different transports (sse and streamable_http)
+- Using a ReAct agent with registered MCP tools
+- Getting structured output from the agent
+
+Before running this demo, please execute:
+    python mcp_servers.py
+"""
+
+import asyncio
+import json
+import os
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.mcp import HttpStatefulClient, HttpStatelessClient
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit
+from pydantic import BaseModel, Field
+
+
+class NumberResult(BaseModel):
+    """A simple number result model for structured output."""
+
+    result: int = Field(description="The result of the calculation")
+
+
+async def main() -> None:
+    """The main entry of the MCP example."""
+
+    toolkit = Toolkit()
+
+    # Create a stateful MCP client to connect to the SSE MCP server
+    # note you can also use the stateless client
+    add_mcp_client = HttpStatefulClient(
+        name="add_mcp",
+        transport="sse",
+        url="http://127.0.0.1:8001/sse",
+    )
+
+    # Create a stateless MCP client to connect to the StreamableHTTP MCP server
+    # note you can also use the stateful client
+    multiply_mcp_client = HttpStatelessClient(
+        name="multiply_mcp",
+        transport="streamable_http",
+        url="http://127.0.0.1:8002/mcp",
+    )
+
+    # The stateful client must be connected before using
+    await add_mcp_client.connect()
+
+    # Register the MCP clients to the toolkit
+    await toolkit.register_mcp_client(add_mcp_client)
+    await toolkit.register_mcp_client(multiply_mcp_client)
+
+    # Initialize the agent
+    agent = ReActAgent(
+        name="Jarvis",
+        sys_prompt="You're a helpful assistant named Jarvis.",
+        model=DashScopeChatModel(
+            model_name="qwen-max",
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        formatter=DashScopeChatFormatter(),
+        toolkit=toolkit,
+    )
+
+    # Run the agent with a calculation task
+    res = await agent(
+        Msg(
+            "user",
+            "Calculate 2345 multiplied by 3456, then add 4567 to the result,"
+            " what is the final outcome?",
+            "user",
+        ),
+        structured_model=NumberResult,
+    )
+
+    print(
+        "Structured Output:\n"
+        "```\n"
+        f"{json.dumps(res.metadata, indent=4, ensure_ascii=False)}\n"
+        "```",
+    )
+
+    # AgentScope also allows developers to obtain the MCP tool as a local
+    #  callable object, and use it directly.
+    add_tool_function = await add_mcp_client.get_callable_function(
+        "add",
+        # If wrap the MCP tool result into the ToolResponse object in
+        #  AgentScope
+        wrap_tool_result=True,
+    )
+
+    # Call it manually
+    manual_res = await add_tool_function(a=5, b=10)
+    print("When manually calling the MCP tool function:")
+    print(manual_res)
+
+    # The stateful client should be disconnected manually!
+    await add_mcp_client.close()
+
+
+asyncio.run(main())

functionality/mcp/mcp_add.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+"""An SSE MCP server with a simple add tool function."""
+
+from mcp.server import FastMCP
+
+mcp = FastMCP("Add", port=8001)
+
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+
+mcp.run(transport="sse")

functionality/mcp/mcp_multiply.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+"""An SSE MCP server with a simple multiply tool function."""
+
+from mcp.server import FastMCP
+
+mcp = FastMCP("Multiply", port=8002)
+
+
+@mcp.tool()
+def multiply(c: int, d: int) -> int:
+    """Multiply two numbers."""
+    return c * d
+
+
+mcp.run(transport="streamable-http")

functionality/mcp/requirements.txt

@@ -0,0 +1 @@
+agentscope[full]>=1.0.5