add playwright fastmcp mcp server

README.md

@@ -26,7 +26,7 @@
   </p>
 
   <p>
-    📚 <a href="https://cryxnet.github.io/deepmcpagent/">Documentation</a> • 🛠 <a href="https://github.com/cryxnet/deepmcpagent/issues">Issues</a>
+    📚 <a href="https://cryxnet.github.io/deepmcpagent/">Documentation</a> • 🛠 <a href="https://github.com/cryxnet/deepmcpagent/issues">Issues</a> • 🎭 <a href="docs/PLAYWRIGHT_MCP_SETUP.md">Playwright Setup</a>
   </p>
 </div>
 
@@ -89,10 +89,24 @@ This serves an MCP endpoint at: **[http://127.0.0.1:8000/mcp](http://127.0.0.1:8
 python examples/use_agent.py
 ```
 
-**What you’ll see:**
+**What you'll see:**
 
 ![screenshot](/docs/images/screenshot_output.png)
 
+### 3) Browser Automation with Playwright MCP (Optional)
+
+DeepMCPAgent also supports [Playwright MCP](https://github.com/microsoft/playwright-mcp) via `langchain-mcp-adapters` for browser automation:
+
+```bash
+# Single server example (Playwright only)
+python examples/use_playwright_mcp.py
+
+# Multi-server example (Math + Playwright)
+python examples/use_multi_server_mcp.py
+```
+
+See [Playwright MCP Setup Guide](docs/PLAYWRIGHT_MCP_SETUP.md) for installation instructions.
+
 ---
 
 ## 🧑‍💻 Bring-Your-Own Model (BYOM)

examples/README.md

@@ -0,0 +1,291 @@
+# DeepMCPAgent Examples
+
+This directory contains example scripts demonstrating various DeepMCPAgent features and integrations.
+
+## 📁 Directory Structure
+
+```
+examples/
+├── servers/                    # Sample MCP servers
+│   └── math_server.py         # Simple math operations server (HTTP)
+├── use_agent.py               # Basic DeepMCPAgent usage (native API)
+├── use_playwright_mcp.py      # Browser automation with Playwright MCP
+├── use_multi_server_mcp.py    # Multi-server setup (Math + Playwright)
+└── README.md                  # This file
+```
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+1. Install DeepMCPAgent with dependencies:
+   ```bash
+   pip install "deepmcpagent[deep]"
+   ```
+
+2. Set up your environment variables in `.env`:
+   ```bash
+   AZURE_OPENAI_ENDPOINT=your-endpoint
+   AZURE_OPENAI_API_KEY=your-api-key
+   AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment
+   # Or for OpenAI:
+   # OPENAI_API_KEY=your-api-key
+   ```
+
+3. For Playwright examples, install Node.js and ensure `npx` is available.
+
+## 📋 Examples Overview
+
+### 1. Basic Agent (`use_agent.py`)
+
+**Purpose**: Demonstrates core DeepMCPAgent functionality with HTTP MCP server.
+
+**What it does**:
+- Connects to the math server over HTTP
+- Discovers available tools dynamically
+- Executes a math query using MCP tools
+- Displays results with rich console output
+
+**Run**:
+```bash
+# Terminal 1: Start the math server
+python examples/servers/math_server.py
+
+# Terminal 2: Run the agent
+python examples/use_agent.py
+```
+
+**Key Features**:
+- Native DeepMCPAgent API (`build_deep_agent`)
+- Automatic tool discovery
+- Console tracing with Rich library
+- Works with any LangChain-compatible model
+
+### 2. Playwright MCP (`use_playwright_mcp.py`)
+
+**Purpose**: Browser automation using Microsoft's Playwright MCP server.
+
+**What it does**:
+- Connects to Playwright MCP via stdio transport
+- Lists available browser automation tools
+- Performs web navigation and screenshots
+- Uses langchain-mcp-adapters for integration
+
+**Run**:
+```bash
+python examples/use_playwright_mcp.py
+```
+
+**Key Features**:
+- Stdio transport (process-based communication)
+- langchain-mcp-adapters integration
+- Browser automation capabilities
+- Screenshot and page interaction
+
+**Prerequisites**:
+- Node.js and npm installed
+- Playwright browsers installed (done automatically via npx)
+
+See [Playwright MCP Setup Guide](../docs/PLAYWRIGHT_MCP_SETUP.md) for details.
+
+### 3. Multi-Server Setup (`use_multi_server_mcp.py`)
+
+**Purpose**: Demonstrates connecting to multiple MCP servers simultaneously.
+
+**What it does**:
+- Connects to Math server (HTTP) and Playwright server (stdio)
+- Aggregates tools from both servers
+- Routes tool calls to the appropriate server
+- Shows unified tool discovery
+
+**Run**:
+```bash
+# Terminal 1: Start the math server
+python examples/servers/math_server.py
+
+# Terminal 2: Run the multi-server example
+python examples/use_multi_server_mcp.py
+```
+
+**Key Features**:
+- Multiple transports (HTTP + stdio)
+- Unified tool interface
+- Server-specific tool routing
+- Demonstrates real-world multi-server patterns
+
+## 🔧 Server Examples
+
+### Math Server (`servers/math_server.py`)
+
+A simple FastMCP server providing basic arithmetic operations:
+
+- `add(a, b)` - Add two integers
+- `multiply(a, b)` - Multiply two integers
+
+**Start the server**:
+```bash
+python examples/servers/math_server.py
+```
+
+**Access**:
+- HTTP endpoint: `http://127.0.0.1:8000/mcp`
+
+## 📝 Example Workflows
+
+### Workflow 1: Basic Math Operations
+
+```bash
+# Start server
+python examples/servers/math_server.py
+
+# In another terminal
+python examples/use_agent.py
+```
+
+Expected output:
+1. Tool discovery (add, multiply)
+2. Agent plans to use tools
+3. Tool execution traces
+4. Final calculated answer
+
+### Workflow 2: Web Scraping with AI
+
+```bash
+python examples/use_playwright_mcp.py
+```
+
+Expected behavior:
+1. Playwright tools discovered
+2. Agent navigates to a URL
+3. Takes screenshot or extracts content
+4. Returns structured information
+
+### Workflow 3: Hybrid Operations
+
+```bash
+# Start math server
+python examples/servers/math_server.py
+
+# Run multi-server example
+python examples/use_multi_server_mcp.py
+```
+
+Expected behavior:
+1. Tools from both servers discovered
+2. Agent uses math tools for calculations
+3. Agent uses Playwright for web tasks
+4. Seamless switching between servers
+
+## 🎨 Customization
+
+### Using Different Models
+
+All examples support any LangChain-compatible model:
+
+```python
+# OpenAI
+from langchain_openai import ChatOpenAI
+model = ChatOpenAI(model="gpt-4")
+
+# Anthropic
+from langchain_anthropic import ChatAnthropic
+model = ChatAnthropic(model="claude-3-5-sonnet-latest")
+
+# Ollama (local)
+from langchain_community.chat_models import ChatOllama
+model = ChatOllama(model="llama3.1")
+```
+
+### Adding Custom Servers
+
+1. Create your MCP server using FastMCP
+2. Add server configuration to the examples
+3. Run and discover tools automatically
+
+Example:
+```python
+servers = {
+    "math": HTTPServerSpec(url="http://127.0.0.1:8000/mcp"),
+    "weather": HTTPServerSpec(url="http://127.0.0.1:9000/mcp"),
+    "custom": HTTPServerSpec(url="https://api.example.com/mcp"),
+}
+```
+
+## 🐛 Troubleshooting
+
+### Math Server Connection Failed
+
+**Error**: `Connection refused`
+
+**Solution**:
+```bash
+# Make sure the server is running
+python examples/servers/math_server.py
+
+# Check if port 8000 is free
+lsof -i :8000
+```
+
+### Playwright MCP Not Working
+
+**Error**: `Command not found: npx`
+
+**Solution**:
+```bash
+# Install Node.js
+brew install node  # macOS
+# or
+sudo apt-get install nodejs npm  # Linux
+```
+
+**Error**: `Browser not found`
+
+**Solution**:
+```bash
+# Install Playwright browsers
+npx playwright install chromium
+```
+
+### Model API Errors
+
+**Error**: `OpenAI API key not found`
+
+**Solution**:
+```bash
+# Create .env file in project root
+echo "OPENAI_API_KEY=your-key-here" > .env
+```
+
+## 📚 Learn More
+
+- [DeepMCPAgent Documentation](https://cryxnet.github.io/deepmcpagent/)
+- [Playwright MCP Setup](../docs/PLAYWRIGHT_MCP_SETUP.md)
+- [LangChain MCP Integration](../docs/langchain-mcp-integration.md)
+- [FastMCP Documentation](https://gofastmcp.com/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+
+## 🤝 Contributing
+
+Want to add more examples? Please:
+
+1. Follow the existing code style
+2. Include clear docstrings
+3. Add entry to this README
+4. Test with multiple models
+5. Submit a PR!
+
+## 💡 Example Ideas
+
+Potential examples we'd love to see:
+
+- [ ] Database query agent (SQL MCP server)
+- [ ] File system operations
+- [ ] API integration examples
+- [ ] Multi-agent collaboration
+- [ ] Custom tool creation
+- [ ] Error handling patterns
+- [ ] Streaming responses
+- [ ] Session management
+
+Feel free to contribute! 🚀
+