AI Makerspace: MCP Session Repo for Session 13

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

1. Clone the repository:

   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:

   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