<div align="center">
  <h1>FastMCP + LangGraph Webinar Demo</h1>
  <p><b>A terminal-based MCP demo that connects a FastMCP server to a LangGraph ReAct agent.</b></p>
</div>

<div align="center">
  <img alt="Python" src="https://img.shields.io/badge/-Python-3776AB?style=for-the-badge&logo=python&logoColor=white" />
  <img alt="FastMCP" src="https://img.shields.io/badge/-FastMCP-111111?style=for-the-badge&logo=fastapi&logoColor=white" />
  <img alt="LangGraph" src="https://img.shields.io/badge/-LangGraph-0B1F33?style=for-the-badge&logo=langchain&logoColor=white" />
  <img alt="OpenAI" src="https://img.shields.io/badge/-OpenAI-412991?style=for-the-badge&logo=openai&logoColor=white" />
  <img alt="Tavily" src="https://img.shields.io/badge/-Tavily-1E88E5?style=for-the-badge&logo=google-chrome&logoColor=white" />
  <img alt="httpx" src="https://img.shields.io/badge/-httpx-1C7ED6?style=for-the-badge&logo=python&logoColor=white" />
</div>

---

## What this project does

This repo is a clean CLI demo for MCP tool use.

- Starts a FastMCP server with 6 tools
- Connects the server to a LangGraph ReAct agent
- Lets you test tools manually from the terminal
- Lets the agent choose tools for multi-step tasks

## Included files

- `demo_mcp_server.py` - MCP server with all tools
- `demo_agent.py` - interactive CLI runner
- `requirements.txt` - Python dependencies
- `.env.example` - local env template

## Skills used

- Python
- FastMCP
- LangGraph
- MCP
- OpenAI API 
- Tavily search API
- HTTP requests
- Agentic workflows
- Tool calling and tool selection
- Prompt engineering for ReAct-style agents
- Multi-step reasoning with external tools
- MCP server and client orchestration
- Web search and page fetching for grounding
- Safe task-specific automation from the terminal

## Features

- `web_search` - Tavily-backed search
- `fetch_url` - fetches a URL and strips HTML
- `save_note` - writes text files under `tmp/mcp_notes/`
- `read_note` - reads saved notes back
- `list_notes` - lists saved notes and sizes
- `calculate` - safe math evaluation for expressions like `sqrt(144) + pi`

## Requirements

- Python 3.10+
- `OPENAI_API_KEY` for the agent section
- `TAVILY_API_KEY` for `web_search`

## Setup

```bash
pip install -r requirements.txt
```

Create a `.env` file in the project root with:

```env
OPENAI_API_KEY=your_openai_key
OPENAI_MODEL=gpt-4o-mini
TAVILY_API_KEY=your_tavily_key
```

If you only want to test the tools and skip the agent, `OPENAI_API_KEY` is not required.

## Run

```bash
python demo_agent.py
```

Tools-only mode:

```bash
python demo_agent.py --tools-only
```

## How the demo works

1. The runner starts the MCP server over stdio.
2. It discovers the available tools.
3. You can call tools manually from the terminal.
4. If `OPENAI_API_KEY` is set, the LangGraph agent runs preset or custom prompts.

## Environment variables

- `OPENAI_API_KEY` - required for the agent
- `OPENAI_MODEL` - optional, defaults to `gpt-4o-mini`
- `TAVILY_API_KEY` - enables `web_search`

## Notes

- `web_search` fails cleanly if `TAVILY_API_KEY` is missing.
- Saved notes live in `tmp/mcp_notes/` next to the scripts.
- `save_note` sanitizes filenames before writing.

## Troubleshooting

- If imports fail, run `pip install -r requirements.txt` again.
- If the server file is missing, keep `demo_agent.py` and `demo_mcp_server.py` in the same folder.
- If the agent section is skipped, set `OPENAI_API_KEY` in `.env`.

## License

No license file is included in this repo.