Tavily Web Search MCP Server

## Activities ### 🏗️ Activity #1: Build an MCP server for a chosen API - **What I chose**: Cal.com API - **What I built**: An MCP server that exposes Cal.com scheduling as tools you can call from any MCP client. - **Capabilities**: - **cal_list_event_types**: List available meeting types - **cal_list_bookings**: View bookings by status (upcoming, cancelled, all) - **cal_get_availability**: Get slots for a given event type and date in a specific time zone - **cal_create_booking**: Create a booking (safely converts local date/time to UTC and computes end time) - **cal_cancel_booking**: Cancel by UID - **cal_cancel_booking_by_details**: Cancel by human-friendly details (date + attendee) - **Notes on design**: - Auth via `CALCOM_API_KEY` from `.env` - Time handling with `zoneinfo`; `/slots` uses UTC window for the local date - Tool docstrings clearly label read-only vs. destructive actions - Graceful error handling surfaces helpful hints ### 🏗️ Activity #2: Build a simple LangGraph app that interacts with the MCP server - **What I built**: A small LangGraph-based agent that connects to the MCP server and uses the Cal.com tools conversationally. - **Capabilities**: - Loads MCP tools from the local server via stdio - Uses a ReAct-style agent to decide which Cal.com tool to call - Interactive mode or demo mode (predefined queries) --- ## File guide (what files do what) - `myserver.py`: Primary MCP server exposing Cal.com tools plus `web_search` and `roll_dice`. Includes HTTP helpers, key checks, time conversions, and safety-focused tool interfaces. - `improved_server.py`: Variant MCP server with stronger guardrails and verbose docstrings for safer tool use (read-only vs destructive made explicit). - `server.py`: Original baseline MCP server (Tavily web search, dice, and example tools). Useful reference starting point. - `cal_langgraph_app.py`: Standalone LangGraph application. Starts an MCP client that launches `myserver.py`, loads tools, and runs an agent (interactive, demo, or single-query modes). - `debug_agent.py`: Debug-focused LangGraph runner showing tool decisions/results to understand what the agent called and why. - `test_server.py`: Minimal sample client that connects to an MCP script and exercises a tool call. - `pyproject.toml`: Project dependencies (MCP, LangGraph, OpenAI, Tavily, requests, etc.). - `ARCHITECTURE.md`: High-level explanation of the MCP + LangGraph architecture, request flow, and how components fit together. - `README.md`: Setup instructions, environment requirements, and assignment context. ## How to run 1) Create `.env` with required keys: ```bash OPENAI_API_KEY=your_openai_key CALCOM_API_KEY=your_calcom_key ``` 2) Start the LangGraph app (talks to the MCP server): ```bash python cal_langgraph_app.py ``` 3) Example queries in the interactive session: - "List my event types" - "Show my upcoming bookings" - "What availability do I have on 2025-08-12?" - "Schedule a 15 minute meeting at 10:00 AM with Red Fred (red@fred.com)" ## What’s working end-to-end - **Query bookings and availability** via MCP tools - **Create and cancel bookings** with safety checks and clear prompts - **Conversational orchestration** using LangGraph’s ReAct agent