patch: update mcp sample and add readme

Author: maxkahan

examples/mcp/README.md

@@ -1,24 +1,105 @@
-# MCP Client Example
+# Stream × FastMCP Demo
 
-This example shows the *minimal* wiring needed to
-use GetStream's optional **MCP** support (`getstream[mcp]`).
+This folder contains a **complete Stream × FastMCP demo**. Running a *single* script spins up everything you need – the MCP server, the LLM agent and a Stream-Video call bot – and shows the whole tool-calling loop end-to-end.
 
-It does **not** implement any custom tools or resources yet –
-that will be added once the `fastmcp`-based implementation lands.
+Run it, talk, and the bot will answer – possibly after calling a tool.
 
-## Running
+> The supporting files (`server.py`, `agent.py`) are here mostly to show how
+> MCP tools are defined and how the agent lets the LLM call them. You don't
+> run them directly; `main.py` orchestrates the whole thing for you.
+
+---
+
+## 1 — Prerequisites
+
+• Python ≥ 3.10 (⁠we use `pyproject.toml` to pin the packages)  
+• A Stream account with API key/secret  
+• An OpenAI API key  
+• Deepgram + ElevenLabs keys if you want speech-to-text **and** text-to-speech
+
+Create an `.env` file in this directory (or export the variables any other way):
+
+```env
+OPENAI_API_KEY=sk-…
+
+# stream.io credentials
+STREAM_API_KEY=…
+STREAM_API_SECRET=…
+
+# optional – only needed if you run `main.py`
+DEEPGRAM_API_KEY=…
+ELEVENLABS_API_KEY=…
+```
+
+---
+
+## 2 — Install deps into an isolated venv
+
+We recommend [uv](https://github.com/astral-sh/uv):
 
 ```bash
+# create a fresh virtual-env in .venv and install everything from pyproject.toml
+uv venv .venv
+uv pip install -r <(uv pip compile examples/mcp/pyproject.toml)
+
+# or, if you already have uv 0.1.26+
 uv sync -q --all-packages -p examples/mcp/pyproject.toml
-uv run examples/mcp/main.py
 ```
 
-Requirements: Python ≥ 3.10 and `getstream[mcp]` extra installed
-(the `pyproject.toml` here declares it for you).
+Feel free to use `pip`/`poetry`/`pip-tools` instead; the TOML lists the same deps.
+
+---
+
+## 3 — Run the demo (1-liner)
+
+```bash
+uv run examples/mcp/main.py   # or: python examples/mcp/main.py
+```
+
+`main.py` will
+
+1. launch the tiny MCP server defined in `server.py`,
+2. create a temporary Stream call and open it in your browser,
+3. join the call as a bot participant, and
+4. feed speech → text → LLM → tools → speech.
+
+Speak in the browser tab. The Deepgram STT engine turns your voice into
+text; the LLM decides whether it should answer directly or call a tool (see
+the `get_forecast` sample); if it does, the result is fed back to the LLM and
+finally read out loud via ElevenLabs.
+
+Stop with `Ctrl-C`. The script tears everything down and removes the temporary
+users from your Stream instance.
+
+---
+
+## 4 — Anatomy of the example
+
+| File | Role |
+|------|------|
+| `server.py` | Shows how to **define MCP tools** with the `@mcp.tool()` decorator. (Launched automatically by `main.py`.) |
+| `agent.py` | Very small helper that lets the LLM call tools and loops the results back. Imported by `main.py`. |
+| `main.py` | The only file you *run*. Orchestrates the video call, launches the MCP server as a subprocess and drives the agent. |
+
+---
+
+## 5 — Adding your own tools
+
+1.  Edit `server.py` and drop in a regular Python function. Annotate the
+    parameters and return type — those become the tool's schema.
 
-## What's inside?
+   ```python
+   @mcp.tool()
+   def table_availability(restaurant: str, date: str, seats: int) -> str:
+       """Check if *restaurant* has a free table for *seats* people on *date*."""
+       # Imagine this hits the booking API for the venue.
+       resp = httpx.get(
+           "https://api.example.com/availability",
+           params={"restaurant": restaurant, "date": date, "seats": seats},
+           timeout=5,
+       )
+       return resp.json()["status"]  # e.g. "available" / "fully booked"
+   ```
 
-* `main.py` – placeholder async script that will eventually
-  connect to an MCP server.
-* `pyproject.toml` – isolated env spec that pulls in the
-  `getstream[mcp]` extra. 
+2.  Restart the demo.  The agent advertises the new tool automatically; the LLM
+    can now call `table_availability[{"restaurant": "Pasta Place", "date": "2025-07-01", "seats": 4}]`.

examples/mcp/agent.py

@@ -9,6 +9,7 @@
 You are a friendly AI assistant.  When the user asks for real-world data, look through the
 available MCP tools and call the one that matches.  Reply with plain text.
 If you call a tool, use  "tool_name"["argument_key": "argument_value"]  on its own line.
+You can make up to 3 tool calls in a row.
 """
 
 def call_llm(messages):
@@ -33,6 +34,7 @@ async def chat_with_tools(prompt: str, client: fastmcp.Client) -> str:
     ]
 
     while True:
+        tool_calls = 0
         reply = call_llm(history)
         m = re.match(r"^(\w[\w\.]+)\[(.*)\]$", reply.strip())
 
@@ -45,6 +47,12 @@ async def chat_with_tools(prompt: str, client: fastmcp.Client) -> str:
             for result in results:
                 history.append({"role": "assistant",
                                 "content": f"(result) {result.text}"})
+            tool_calls += 1
+            if tool_calls == 2:
+                history.append({"role": "assistant",
+                                "content": "You can make up to 3 tool calls in a row.  You have already made 2 tool calls.  Please answer the user's question directly."})
+            if tool_calls >= 3:
+                return reply
             continue
         else:
             return reply

examples/mcp/main.py

@@ -1,5 +1,4 @@
 import logging
-import time
 
 from dotenv import load_dotenv
 from getstream.stream import Stream

examples/mcp/server.py

@@ -3,9 +3,6 @@
 
 mcp = FastMCP("Stream MCP Server")
 
-@mcp.tool()
-def greet(name: str) -> str:
-    return f"Hello, {name}!"
 
 @mcp.tool()
 def get_forecast(city: str) -> str: