chore: import upstream snapshot with attribution

examples/mcp/sse_example/README.md

@@ -0,0 +1,13 @@
+# MCP SSE Example
+
+This example uses a local SSE server in [server.py](server.py).
+
+Run the example via:
+
+```
+uv run python examples/mcp/sse_example/main.py
+```
+
+## Details
+
+The example uses the `MCPServerSse` class from `agents.mcp`. The server runs in a sub-process at `https://localhost:8000/sse`.

examples/mcp/sse_example/main.py

@@ -0,0 +1,104 @@
+import asyncio
+import os
+import shutil
+import socket
+import subprocess
+import time
+from typing import Any, cast
+
+from agents import Agent, Runner, gen_trace_id, trace
+from agents.mcp import MCPServer, MCPServerSse
+from agents.model_settings import ModelSettings
+
+SSE_HOST = os.getenv("SSE_HOST", "127.0.0.1")
+
+
+def _choose_port() -> int:
+    env_port = os.getenv("SSE_PORT")
+    if env_port:
+        return int(env_port)
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind((SSE_HOST, 0))
+        address = cast(tuple[str, int], s.getsockname())
+        return address[1]
+
+
+SSE_PORT = _choose_port()
+os.environ.setdefault("SSE_PORT", str(SSE_PORT))
+SSE_URL = f"http://{SSE_HOST}:{SSE_PORT}/sse"
+
+
+async def run(mcp_server: MCPServer):
+    agent = Agent(
+        name="Assistant",
+        instructions="Use the tools to answer the questions.",
+        mcp_servers=[mcp_server],
+        model_settings=ModelSettings(tool_choice="required"),
+    )
+
+    # Use the `add` tool to add two numbers
+    message = "Add these numbers: 7 and 22."
+    print(f"Running: {message}")
+    result = await Runner.run(starting_agent=agent, input=message)
+    print(result.final_output)
+
+    # Run the `get_weather` tool
+    message = "What's the weather in Tokyo?"
+    print(f"\n\nRunning: {message}")
+    result = await Runner.run(starting_agent=agent, input=message)
+    print(result.final_output)
+
+    # Run the `get_secret_word` tool
+    message = "What's the secret word?"
+    print(f"\n\nRunning: {message}")
+    result = await Runner.run(starting_agent=agent, input=message)
+    print(result.final_output)
+
+
+async def main():
+    async with MCPServerSse(
+        name="SSE Python Server",
+        params={
+            "url": SSE_URL,
+        },
+    ) as server:
+        trace_id = gen_trace_id()
+        with trace(workflow_name="SSE Example", trace_id=trace_id):
+            print(f"View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}\n")
+            await run(server)
+
+
+if __name__ == "__main__":
+    # Let's make sure the user has uv installed
+    if not shutil.which("uv"):
+        raise RuntimeError(
+            "uv is not installed. Please install it: https://docs.astral.sh/uv/getting-started/installation/"
+        )
+
+    # We'll run the SSE server in a subprocess. Usually this would be a remote server, but for this
+    # demo, we'll run it locally at SSE_URL.
+    process: subprocess.Popen[Any] | None = None
+    try:
+        this_dir = os.path.dirname(os.path.abspath(__file__))
+        server_file = os.path.join(this_dir, "server.py")
+
+        print(f"Starting SSE server at {SSE_URL} ...")
+
+        # Run `uv run server.py` to start the SSE server
+        env = os.environ.copy()
+        env.setdefault("SSE_HOST", SSE_HOST)
+        env.setdefault("SSE_PORT", str(SSE_PORT))
+        process = subprocess.Popen(["uv", "run", server_file], env=env)
+        # Give it 3 seconds to start
+        time.sleep(3)
+
+        print("SSE server started. Running example...\n\n")
+    except Exception as e:
+        print(f"Error starting SSE server: {e}")
+        exit(1)
+
+    try:
+        asyncio.run(main())
+    finally:
+        if process:
+            process.terminate()

examples/mcp/sse_example/server.py

@@ -0,0 +1,42 @@
+import os
+import random
+
+from mcp.server.fastmcp import FastMCP
+
+SSE_HOST = os.getenv("SSE_HOST", "127.0.0.1")
+SSE_PORT = int(os.getenv("SSE_PORT", "8000"))
+
+# Create server
+mcp = FastMCP("Echo Server", host=SSE_HOST, port=SSE_PORT)
+
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    print(f"[debug-server] add({a}, {b})")
+    return a + b
+
+
+@mcp.tool()
+def get_secret_word() -> str:
+    print("[debug-server] get_secret_word()")
+    return random.choice(["apple", "banana", "cherry"])
+
+
+@mcp.tool()
+def get_current_weather(city: str) -> str:
+    print(f"[debug-server] get_current_weather({city})")
+    # Keep tool output deterministic so this example is stable in CI and offline environments.
+    weather_by_city = {
+        "tokyo": "sunny with a light breeze and 20°C",
+        "san francisco": "cool and foggy with 14°C",
+        "new york": "partly cloudy with 18°C",
+    }
+    forecast = weather_by_city.get(city.strip().lower())
+    if forecast:
+        return f"The weather in {city} is {forecast}."
+    return f"The weather data for {city} is unavailable in this demo."
+
+
+if __name__ == "__main__":
+    mcp.run(transport="sse")