<p align = "center" draggable="false" ><img src="https://github.com/AI-Maker-Space/LLM-Dev-101/assets/37101144/d1343317-fa2f-41e1-8af1-1dbb18399719" 
     width="200px"
     height="auto"/>
</p>

## <h1 align="center" id="heading">AI Makerspace: MCP Session Repo for Session 13</h1>

This project demonstrates an MCP (Model Context Protocol) server with LangGraph integration, utilizing the Tavily API for web search capabilities and other useful tools.

## Project Overview

The MCP server provides multiple tools and is integrated with a LangGraph application for intelligent workflow orchestration.

## Prerequisites

- Python 3.13 or higher
- A valid Tavily API key
- A valid OpenAI API key

## ⚠️NOTE FOR WINDOWS:⚠️

You'll need to install this on the _Windows_ side of your OS.

This will require getting two CLI tool for Powershell, which you can do as follows:

- `winget install astral-sh.uv`
- `winget install --id Git.Git -e --source winget`

After you have those CLI tools, please open Cursor _into Windows_.

Then, you can clone the repository using the following command in your Cursor terminal:

```bash
git clone https://AI-Maker-Space/AIE8-MCP-Session.git
```

After that, you can follow from Step 2. below!

## Installation

1. **Clone the repository**:

   ```bash
   git clone <repository-url>
   cd <repository-directory>
   ```

2. **Configure environment variables**:
   Copy the `.env.sample` to `.env` and add your API keys:

   ```
   TAVILY_API_KEY=your_tavily_api_key_here
   OPENAI_API_KEY=your_openai_api_key_here
   ```

3. **Set up the environment**:
   ```bash
   uv run python setup_env.py
   ```

## Running the MCP Server

To start the MCP server, you will need to add the following to your MCP Profile in Cursor:

> NOTE: To get to your MCP config. you can use the Command Pallete (CMD/CTRL+SHIFT+P) and select "View: Open MCP Settings" and replace the contents with the JSON blob below.

```
{
    "mcpServers":  {
        "mcp-server": {
            "command" : "uv",
            "args" : ["--directory", "/PATH/TO/REPOSITORY", "run", "server.py"]
        }
    }
}
```

The server will start and listen for commands via standard input/output.

## Activities:

### 🏗️ Activity #1: ✅ COMPLETED

Choose an API that you enjoy using - and build an MCP server for it!

**MCP Server Features:**

- Web search using Tavily API
- Dice rolling with custom notation
- Text processing utilities
- Random dad jokes

### 🏗️ Activity #2: ✅ COMPLETED

Build a simple LangGraph application that interacts with your MCP Server.

**Simple Solution:**

- **`langgraph_simple_final.py`** - The complete LangGraph application
- **`setup_env.py`** - Helper script for environment setup
- **`SIMPLE_SOLUTION.md`** - Complete documentation

**Quick Start:**

```bash
# 1. Set up environment
uv run python setup_env.py

# 2. Add your OpenAI API key to .env file
# 3. Run the application
uv run python langgraph_simple_final.py

# Or run interactive mode
uv run python langgraph_simple_final.py --interactive
```

**Features:**

- ✅ **Single file solution** - Everything in one Python file
- ✅ **LLM-powered** - Uses OpenAI GPT-4o-mini with API key
- ✅ **All MCP tools integrated** - Web search, dice rolling, text processing, jokes
- ✅ **Automatic tool selection** - LLM chooses appropriate tools based on input
- ✅ **Interactive mode** - Real-time conversation with the system
- ✅ **Type-safe state management** - Uses TypedDict for reliability

**Architecture:**

- Single LangGraph node that processes user input
- Direct MCP function imports (no subprocess complexity)
- LangChain tool binding for seamless integration
- OpenAI API integration for intelligent responses

## Usage

The LangGraph application provides an intelligent interface to all MCP server tools. Simply run the application and ask it to:

- Search the web for information
- Roll dice with custom notation
- Process text (uppercase, lowercase, reverse, etc.)
- Tell you a joke

The LLM will automatically choose the appropriate tools and provide intelligent responses based on your requests.

## Additional Files

### Testing

- **`test_server.py`** - Comprehensive test script for the MCP server
  - Tests all MCP functions directly
  - Tests MCP server via subprocess communication
  - Run with: `uv run python test_server.py`

### Advanced Features

- **`dice_roller_numpy.py`** - Advanced dice rolling utility using NumPy
  - Better performance for large numbers of dice
  - Statistical analysis of rolls
  - Supports complex notation (e.g., "3d8+2", "1d20-1")
  - Run with: `uv run python dice_roller_numpy.py`

## Project Structure

```
AIE8-MCP-Session/
├── langgraph_simple_final.py    # Main LangGraph application
├── setup_env.py                 # Environment setup helper
├── server.py                    # MCP server (Activity #1)
├── dice_roller.py              # Basic dice rolling utility
├── dice_roller_numpy.py        # Advanced NumPy dice roller
├── test_server.py              # Test script for MCP server
├── pyproject.toml              # Dependencies
├── README.md                   # Main documentation
├── SIMPLE_SOLUTION.md          # Simple solution guide
└── uv.lock                     # Lock file
```