AIE8-MCP Session Server

<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:

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

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

Installation

Clone the repository:

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

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

Set up the environment:

   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:

# 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