From ab606d8de7bcd199022c3a26ab8d4b8b6cfa440b Mon Sep 17 00:00:00 2001 From: Rohan Mehta Date: Tue, 25 Mar 2025 12:51:40 -0400 Subject: [PATCH 1/2] [3/n] Add an MCP stdio example ### Summary: Spins up a stdio server with some local files, then asks the model questions. ### Test Plan: Run the example, see it work. --- examples/mcp/filesystem_example/README.md | 26 +++++++++ examples/mcp/filesystem_example/main.py | 54 +++++++++++++++++++ .../sample_files/favorite_books.txt | 20 +++++++ .../sample_files/favorite_cities.txt | 4 ++ .../sample_files/favorite_songs.txt | 10 ++++ 5 files changed, 114 insertions(+) create mode 100644 examples/mcp/filesystem_example/README.md create mode 100644 examples/mcp/filesystem_example/main.py create mode 100644 examples/mcp/filesystem_example/sample_files/favorite_books.txt create mode 100644 examples/mcp/filesystem_example/sample_files/favorite_cities.txt create mode 100644 examples/mcp/filesystem_example/sample_files/favorite_songs.txt diff --git a/examples/mcp/filesystem_example/README.md b/examples/mcp/filesystem_example/README.md new file mode 100644 index 00000000..682afc83 --- /dev/null +++ b/examples/mcp/filesystem_example/README.md @@ -0,0 +1,26 @@ +# MCP Filesystem Example + +This example uses the [fileystem MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), running locally via `npx`. + +Run it via: + +``` +uv run python python examples/mcp/filesystem_example/main.py +``` + +## Details + +The example uses the `MCPServerStdio` class from `agents`, with the command: + +```bash +npx -y "@modelcontextprotocol/server-filesystem" +``` + +It's only given access to the `sample_files` directory adjacent to the example, which contains some sample data. + +Under the hood: + +1. The server is spun up in a subprocess, and exposes a bunch of tools like `list_directory()`, `read_file()`, etc. +2. We add the server instance to the Agent via `mcp_agents`. +3. Each time the agent runs, we call out to the MCP server to fetch the list of tools via `server.list_tools()`. +4. If the LLM chooses to use an MCP tool, we call the MCP server to run the tool via `server.run_tool()`. diff --git a/examples/mcp/filesystem_example/main.py b/examples/mcp/filesystem_example/main.py new file mode 100644 index 00000000..0ba2b675 --- /dev/null +++ b/examples/mcp/filesystem_example/main.py @@ -0,0 +1,54 @@ +import asyncio +import os +import shutil + +from agents import Agent, Runner, trace +from agents.mcp import MCPServer, MCPServerStdio + + +async def run(mcp_server: MCPServer): + agent = Agent( + name="Assistant", + instructions="Use the tools to read the filesystem and answer questions based on those files.", + mcp_servers=[mcp_server], + ) + + # List the files it can read + message = "Read the files and list them." + print(f"Running: {message}") + result = await Runner.run(starting_agent=agent, input=message) + print(result.final_output) + + # Ask about books + message = "What is my #1 favorite book?" + print(f"\n\nRunning: {message}") + result = await Runner.run(starting_agent=agent, input=message) + print(result.final_output) + + # Ask a question that reads then reasons. + message = "Look at my favorite songs. Suggest one new song that I might like." + print(f"\n\nRunning: {message}") + result = await Runner.run(starting_agent=agent, input=message) + print(result.final_output) + + +async def main(): + current_dir = os.path.dirname(os.path.abspath(__file__)) + samples_dir = os.path.join(current_dir, "sample_files") + + async with MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + } + ) as server: + with trace(workflow_name="MCP Filesystem Example"): + await run(server) + + +if __name__ == "__main__": + # Let's make sure the user has npx installed + if not shutil.which("npx"): + raise RuntimeError("npx is not installed. Please install it with `npm install -g npx`.") + + asyncio.run(main()) diff --git a/examples/mcp/filesystem_example/sample_files/favorite_books.txt b/examples/mcp/filesystem_example/sample_files/favorite_books.txt new file mode 100644 index 00000000..c55f457e --- /dev/null +++ b/examples/mcp/filesystem_example/sample_files/favorite_books.txt @@ -0,0 +1,20 @@ +1. To Kill a Mockingbird – Harper Lee +2. Pride and Prejudice – Jane Austen +3. 1984 – George Orwell +4. The Hobbit – J.R.R. Tolkien +5. Harry Potter and the Sorcerer’s Stone – J.K. Rowling +6. The Great Gatsby – F. Scott Fitzgerald +7. Charlotte’s Web – E.B. White +8. Anne of Green Gables – Lucy Maud Montgomery +9. The Alchemist – Paulo Coelho +10. Little Women – Louisa May Alcott +11. The Catcher in the Rye – J.D. Salinger +12. Animal Farm – George Orwell +13. The Chronicles of Narnia: The Lion, the Witch, and the Wardrobe – C.S. Lewis +14. The Book Thief – Markus Zusak +15. A Wrinkle in Time – Madeleine L’Engle +16. The Secret Garden – Frances Hodgson Burnett +17. Moby-Dick – Herman Melville +18. Fahrenheit 451 – Ray Bradbury +19. Jane Eyre – Charlotte Brontë +20. The Little Prince – Antoine de Saint-Exupéry \ No newline at end of file diff --git a/examples/mcp/filesystem_example/sample_files/favorite_cities.txt b/examples/mcp/filesystem_example/sample_files/favorite_cities.txt new file mode 100644 index 00000000..1d3354f2 --- /dev/null +++ b/examples/mcp/filesystem_example/sample_files/favorite_cities.txt @@ -0,0 +1,4 @@ +- In the summer, I love visiting London. +- In the winter, Tokyo is great. +- In the spring, San Francisco. +- In the fall, New York is the best. \ No newline at end of file diff --git a/examples/mcp/filesystem_example/sample_files/favorite_songs.txt b/examples/mcp/filesystem_example/sample_files/favorite_songs.txt new file mode 100644 index 00000000..d659bb58 --- /dev/null +++ b/examples/mcp/filesystem_example/sample_files/favorite_songs.txt @@ -0,0 +1,10 @@ +1. "Here Comes the Sun" – The Beatles +2. "Imagine" – John Lennon +3. "Bohemian Rhapsody" – Queen +4. "Shake It Off" – Taylor Swift +5. "Billie Jean" – Michael Jackson +6. "Uptown Funk" – Mark Ronson ft. Bruno Mars +7. "Don’t Stop Believin’" – Journey +8. "Dancing Queen" – ABBA +9. "Happy" – Pharrell Williams +10. "Wonderwall" – Oasis From 363eb515302b4afdcef46e14e77d0b11eca5ed97 Mon Sep 17 00:00:00 2001 From: Rohan Mehta Date: Tue, 25 Mar 2025 12:54:57 -0400 Subject: [PATCH 2/2] [4/n] Add docs for MCP Just adding docs. - --- docs/mcp.md | 51 +++++++++++++++++++++ docs/ref/mcp/server.md | 3 ++ docs/ref/mcp/util.md | 3 ++ mkdocs.yml | 5 ++ src/agents/mcp/mcp_util.py | 94 -------------------------------------- src/agents/mcp/server.py | 16 +++---- 6 files changed, 69 insertions(+), 103 deletions(-) create mode 100644 docs/mcp.md create mode 100644 docs/ref/mcp/server.md create mode 100644 docs/ref/mcp/util.md delete mode 100644 src/agents/mcp/mcp_util.py diff --git a/docs/mcp.md b/docs/mcp.md new file mode 100644 index 00000000..7ec11c16 --- /dev/null +++ b/docs/mcp.md @@ -0,0 +1,51 @@ +# Model context protocol + +The [Model context protocol](https://modelcontextprotocol.io/introduction) (aka MCP) is a way to provide tools and context to the LLM. From the MCP docs: + +> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. + +The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools to your Agents. + +## MCP servers + +Currently, the MCP spec defines two kinds of servers, based on the transport mechanism they use: + +1. **stdio** servers run as a subprocess of your application. You can think of them as running "locally". +2. **HTTP over SSE** servers run remotely. You connect to them via a URL. + +You can use the [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse] classes to connect to these servers. + +For example, this is how you'd use the [official MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem). + +```python +async with MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + } +) as server: + tools = await server.list_tools() +``` + +## Using MCP servers + +MCP servers can be added to Agents. The Agents SDK will call `list_tools()` on the MCP servers each time the Agent is run. This makes the LLM aware of the MCP server's tools. When the LLM calls a tool from an MCP server, the SDK calls `call_tool()` on that server. + +```python + +agent=Agent( + name="Assistant", + instructions="Use the tools to achieve the task", + mcp_servers=[mcp_server_1, mcp_server_2] +) +``` + +## Caching + +Every time an Agent runs, it calls `list_tools()` on the MCP server. This can be a latency hit, especially if the server is a remote server. To automatically cache the list of tools, you can pass `cache_tools_list=True` to both [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse]. You should only do this if you're certain the tool list will not change. + +If you want to invalidate the cache, you can call `invalidate_tools_cache()` on the servers. + +## End-to-end example + +View complete working examples at [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp). diff --git a/docs/ref/mcp/server.md b/docs/ref/mcp/server.md new file mode 100644 index 00000000..e58efab2 --- /dev/null +++ b/docs/ref/mcp/server.md @@ -0,0 +1,3 @@ +# `MCP Servers` + +::: agents.mcp.server diff --git a/docs/ref/mcp/util.md b/docs/ref/mcp/util.md new file mode 100644 index 00000000..b3f7db25 --- /dev/null +++ b/docs/ref/mcp/util.md @@ -0,0 +1,3 @@ +# `MCP Util` + +::: agents.mcp.util diff --git a/mkdocs.yml b/mkdocs.yml index 941f29ed..454d881a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,6 +28,7 @@ nav: - results.md - streaming.md - tools.md + - mcp.md - handoffs.md - tracing.md - context.md @@ -60,6 +61,8 @@ nav: - ref/models/interface.md - ref/models/openai_chatcompletions.md - ref/models/openai_responses.md + - ref/mcp/server.md + - ref/mcp/util.md - Tracing: - ref/tracing/index.md - ref/tracing/create.md @@ -107,6 +110,8 @@ plugins: show_signature_annotations: true # Makes the font sizes nicer heading_level: 3 + # Show inherited members + inherited_members: true extra: # Remove material generation message in footer diff --git a/src/agents/mcp/mcp_util.py b/src/agents/mcp/mcp_util.py deleted file mode 100644 index 41b4c521..00000000 --- a/src/agents/mcp/mcp_util.py +++ /dev/null @@ -1,94 +0,0 @@ -import functools -import json -from typing import Any - -from mcp.types import Tool as MCPTool - -from .. import _debug -from ..exceptions import AgentsException, ModelBehaviorError, UserError -from ..logger import logger -from ..run_context import RunContextWrapper -from ..tool import FunctionTool, Tool -from .server import MCPServer - - -class MCPUtil: - """Set of utilities for interop between MCP and Agents SDK tools.""" - - @classmethod - async def get_all_function_tools(cls, servers: list[MCPServer]) -> list[Tool]: - """Get all function tools from a list of MCP servers.""" - tools = [] - tool_names: set[str] = set() - for server in servers: - server_tools = await cls.get_function_tools(server) - server_tool_names = {tool.name for tool in server_tools} - if len(server_tool_names & tool_names) > 0: - raise UserError( - f"Duplicate tool names found across MCP servers: " - f"{server_tool_names & tool_names}" - ) - tool_names.update(server_tool_names) - tools.extend(server_tools) - - return tools - - @classmethod - async def get_function_tools(cls, server: MCPServer) -> list[Tool]: - """Get all function tools from a single MCP server.""" - tools = await server.list_tools() - return [cls.to_function_tool(tool, server) for tool in tools] - - @classmethod - def to_function_tool(cls, tool: MCPTool, server: MCPServer) -> FunctionTool: - """Convert an MCP tool to an Agents SDK function tool.""" - invoke_func = functools.partial(cls.invoke_mcp_tool, server, tool) - return FunctionTool( - name=tool.name, - description=tool.description or "", - params_json_schema=tool.inputSchema, - on_invoke_tool=invoke_func, - strict_json_schema=False, - ) - - @classmethod - async def invoke_mcp_tool( - cls, server: MCPServer, tool: MCPTool, context: RunContextWrapper[Any], input_json: str - ) -> str: - """Invoke an MCP tool and return the result as a string.""" - try: - json_data: dict[str, Any] = json.loads(input_json) if input_json else {} - except Exception as e: - if _debug.DONT_LOG_TOOL_DATA: - logger.debug(f"Invalid JSON input for tool {tool.name}") - else: - logger.debug(f"Invalid JSON input for tool {tool.name}: {input_json}") - raise ModelBehaviorError( - f"Invalid JSON input for tool {tool.name}: {input_json}" - ) from e - - if _debug.DONT_LOG_TOOL_DATA: - logger.debug(f"Invoking MCP tool {tool.name}") - else: - logger.debug(f"Invoking MCP tool {tool.name} with input {input_json}") - - try: - result = await server.call_tool(tool.name, json_data) - except Exception as e: - logger.error(f"Error invoking MCP tool {tool.name}: {e}") - raise AgentsException(f"Error invoking MCP tool {tool.name}: {e}") from e - - if _debug.DONT_LOG_TOOL_DATA: - logger.debug(f"MCP tool {tool.name} completed.") - else: - logger.debug(f"MCP tool {tool.name} returned {result}") - - # The MCP tool result is a list of content items, whereas OpenAI tool outputs are a single - # string. We'll try to convert. - if len(result.content) == 1: - return result.content[0].model_dump_json() - elif len(result.content) > 1: - return json.dumps([item.model_dump() for item in result.content]) - else: - logger.error(f"Errored MCP tool result: {result}") - return "Error running tool." diff --git a/src/agents/mcp/server.py b/src/agents/mcp/server.py index e19e686a..91af31db 100644 --- a/src/agents/mcp/server.py +++ b/src/agents/mcp/server.py @@ -175,10 +175,10 @@ def __init__(self, params: MCPServerStdioParams, cache_tools_list: bool = False) """Create a new MCP server based on the stdio transport. Args: - params: The params that configure the server. This includes: - - The command (e.g. `python` or `node`) that starts the server. - - The args to pass to the server command (e.g. `foo.py` or `server.js`). - - The environment variables to set for the server. + params: The params that configure the server. This includes the command to run to + start the server, the args to pass to the command, the environment variables to + set for the server, the working directory to use when spawning the process, and + the text encoding used when sending/receiving messages to the server. cache_tools_list: Whether to cache the tools list. If `True`, the tools list will be cached and only fetched from the server once. If `False`, the tools list will be fetched from the server on each call to `list_tools()`. The cache can be @@ -235,11 +235,9 @@ def __init__(self, params: MCPServerSseParams, cache_tools_list: bool = False): """Create a new MCP server based on the HTTP with SSE transport. Args: - params: The params that configure the server. This includes: - - The URL of the server. - - The headers to send to the server. - - The timeout for the HTTP request. - - The timeout for the SSE connection. + params: The params that configure the server. This includes the URL of the server, + the headers to send to the server, the timeout for the HTTP request, and the + timeout for the SSE connection. cache_tools_list: Whether to cache the tools list. If `True`, the tools list will be cached and only fetched from the server once. If `False`, the tools list will be