diff --git a/CLAUDE.md b/CLAUDE.md index 09c031b..bc47513 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,16 +8,16 @@ WebCat is a **Model Context Protocol (MCP) server** that provides web search and 1. **Web Search Tool**: Search the web using Serper API or DuckDuckGo fallback 2. **Content Extraction**: Full webpage scraping with markdown conversion using Readability -3. **MCP Compliance**: SSE transport for compatibility with Claude Desktop and LiteLLM +3. **MCP Compliance**: Streamable HTTP transport with JSON-RPC 2.0 for compatibility with all MCP clients -**Tech Stack**: Python, FastAPI, FastMCP, BeautifulSoup, Readability, html2text, Serper/DuckDuckGo +**Tech Stack**: Python, FastMCP, BeautifulSoup, Readability, html2text, Serper/DuckDuckGo ## Architecture ### High-Level Flow ``` -MCP Client → FastMCP Server (SSE) → Search Tool Decision +MCP Client → FastMCP Server (Streamable HTTP + JSON-RPC 2.0) → Search Tool Decision │ ├─ Serper API (premium): Google-powered search with better ranking │ @@ -28,8 +28,8 @@ MCP Client → FastMCP Server (SSE) → Search Tool Decision ### Key Components -**MCP Server (Python/FastAPI)**: -- `docker/mcp_server.py` - FastMCP server with SSE transport +**MCP Server (Python/FastMCP)**: +- `docker/mcp_server.py` - FastMCP server with Streamable HTTP transport - `docker/health.py` - Health check and status endpoints - `docker/demo_server.py` - Demo client interface - `docker/api_tools.py` - Additional API tooling @@ -418,8 +418,8 @@ def fetch_newsource_search_results(query: str) -> List[Dict[str, Any]]: ## Important Notes -- **MCP Protocol**: Uses SSE (Server-Sent Events) transport for LiteLLM compatibility -- **No Authentication**: Simplified setup - no API keys required for basic functionality +- **MCP Protocol**: Uses Streamable HTTP transport with JSON-RPC 2.0 (modern, future-proof) +- **Optional Authentication**: Bearer token auth available but not required for basic functionality - **Automatic Fallback**: Serper API → DuckDuckGo if no key or if Serper fails - **Content Processing**: Readability + html2text for clean markdown conversion - **Rate Limiting**: Default 10 requests per 60 seconds (configurable via env vars) diff --git a/README.md b/README.md index 2c574c4..725c510 100644 --- a/README.md +++ b/README.md @@ -41,10 +41,10 @@ python mcp_server.py WebCat is an **MCP (Model Context Protocol) server** that provides AI models with: - 🔍 **Web Search** - Serper API (premium) or DuckDuckGo (free fallback) - 📄 **Content Extraction** - Clean markdown conversion with Readability + html2text -- 🌐 **SSE Streaming** - Real-time results via Server-Sent Events +- 🌐 **Modern HTTP Transport** - Streamable HTTP with JSON-RPC 2.0 - 🐳 **Multi-Platform Docker** - Works on Intel, ARM, and Apple Silicon -Built with **FastAPI**, **FastMCP**, and **Readability** for seamless AI integration. +Built with **FastMCP**, **Readability**, and **html2text** for seamless AI integration. ## Features @@ -96,8 +96,7 @@ make mcp # Start MCP server |----------|-------------| | `http://localhost:8000/health` | 💗 Health check | | `http://localhost:8000/status` | 📊 Server status | -| `http://localhost:8000/mcp` | 🛠️ MCP protocol endpoint | -| `http://localhost:8000/sse` | 🔗 SSE streaming | +| `http://localhost:8000/mcp` | 🛠️ MCP protocol endpoint (Streamable HTTP with JSON-RPC 2.0) | ## Configuration @@ -144,7 +143,7 @@ WebCat exposes these tools via MCP: ``` MCP Client (Claude, LiteLLM) ↓ -FastMCP Server (SSE Transport) +FastMCP Server (Streamable HTTP with JSON-RPC 2.0) ↓ Authentication (optional bearer token) ↓ @@ -158,8 +157,8 @@ Search Decision ``` **Tech Stack:** -- **FastAPI** - High-performance async web framework -- **FastMCP** - MCP protocol implementation with SSE transport +- **FastMCP** - MCP protocol implementation with modern HTTP transport +- **JSON-RPC 2.0** - Standard protocol for client-server communication - **Readability** - Content extraction (removes navigation/ads) - **html2text** - HTML to markdown conversion - **Serper/DuckDuckGo** - Search APIs with automatic fallback diff --git a/docker/cli.py b/docker/cli.py index 4432287..4babc12 100644 --- a/docker/cli.py +++ b/docker/cli.py @@ -78,8 +78,10 @@ def main(): print(f"📡 WebCat MCP Server: http://{args.host}:{args.port}/mcp") print("✨ Ready for MCP connections!") - # Run the FastMCP server - mcp_server.run(transport="sse", host=args.host, port=args.port, path="/mcp") + # Run the FastMCP server with modern HTTP transport + mcp_server.run( + transport="http", host=args.host, port=args.port, path="/mcp" + ) except ImportError as e: print(f"❌ Error importing MCP server: {e}") print("Make sure all dependencies are installed.") diff --git a/docker/mcp_server.py b/docker/mcp_server.py index 70a5cfa..1d52ee1 100644 --- a/docker/mcp_server.py +++ b/docker/mcp_server.py @@ -79,9 +79,9 @@ async def search_tool() -> dict: port = int(os.environ.get("PORT", 8000)) logging.info(f"Starting FastMCP server on port {port}") - # Run the server with SSE transport for LiteLLM compatibility + # Run the server with modern HTTP transport (Streamable HTTP with JSON-RPC 2.0) mcp_server.run( - transport="sse", + transport="http", host="0.0.0.0", port=port, path="/mcp", # Explicit path for MCP endpoint