graph TD
    subgraph "🚀 MCP Server App Architecture"
        subgraph "Client Layer"
            A["🤖 LangGraph Agent<br/>ChatOpenAI + ReAct"] 
            B["💻 Interactive Examples<br/>Quick Demo Mode"]
            C["🧪 Pytest Test Suite<br/>8 Comprehensive Tests"]
        end
        
        subgraph "MCP Integration"
            D["🔌 MultiServerMCPClient<br/>langchain-mcp-adapters"]
            E["📡 STDIO Transport<br/>Process Communication"]
        end
        
        subgraph "Server Layer"
            F["⚡ FastMCP Server<br/>Python MCP Framework"]
            G["🎲 Dice Roller<br/>Custom Notation Parser"]
            H["🔍 Web Search<br/>Tavily API Integration"]
            I["📱 Social Creator<br/>Unsplash + Quotable APIs"]
            M["🐙 GitHub Tools<br/>Repository & File Access"]
        end
        
        subgraph "External APIs"
            J["🌐 Tavily Search API<br/>Real-time Web Data"]
            K["📸 Unsplash API<br/>High-Quality Images"]
            L["💭 Quotable API<br/>Inspirational Quotes"]
            N["🔗 GitHub API<br/>Public Repository Data"]
        end
    end
    
    %% Connections
    A --> D
    B --> D
    C --> F
    D --> E
    E --> F
    F --> G
    F --> H
    F --> I
    F --> M
    H --> J
    I --> K
    I --> L
    M --> N
    
    %% Styling
    classDef clientStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000
    classDef mcpStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000
    classDef serverStyle fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px,color:#000
    classDef apiStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
    
    class A,B,C clientStyle
    class D,E mcpStyle
    class F,G,H,I,M serverStyle
    class J,K,L,N apiStyle

AIE7-MCP-Session/
├── 📁 server/                 # MCP Server Components
│   ├── __init__.py           # Server module initialization
│   ├── main.py              # Main MCP server entry point
│   ├── dice_roller.py       # Dice rolling tool implementation
│   ├── dice_roller_numpy.py # NumPy-based dice roller variant
│   ├── social_content_creator.py # Social media content creation tools
│   └── github_tool.py       # GitHub API integration tools
│
├── 📁 client/                # Client Components  
│   ├── __init__.py          # Client module initialization
│   └── langgraph_agent.py   # LangGraph agent implementation
│
├── 📁 tests/                 # Test Files
│   ├── __init__.py          # Tests module initialization
│   ├── test_server.py       # Basic MCP server tests
│   └── test_mcp_integration.py # Integration tests
│
├── 📁 examples/              # Usage Examples
│   ├── __init__.py          # Examples module initialization
│   └── example_langgraph_usage.py # LangGraph usage examples
│
├── 📄 run_server.py         # Convenient server entry point
├── 📄 run_client.py         # Convenient client entry point
├── 📄 pyproject.toml        # Project dependencies
├── 📄 .env.sample           # Environment variables template
└── 📄 README.md             # This documentation

git clone <repository-url>
cd AIE7-MCP-Session
cp .env.sample .env

OPENAI_API_KEY=your_openai_key_here     # Required
TAVILY_API_KEY=your_tavily_key_here     # Required  
UNSPLASH_ACCESS_KEY=your_key_here       # Optional
GITHUB_TOKEN=ghp_your_token_here        # Optional

uv sync    # Recommended
# OR: pip install -r requirements.txt

uv run tests/test_mcp_integration.py    # Test components
uv run run_client.py                    # Interactive demo
uv run run_server.py                    # Test server

# Start the MCP server
uv run run_server.py

# In another terminal, test with a simple client
uv run tests/test_server.py

uv run run_client.py

🚀 LangGraph + MCP Integration Examples
Choose what to run:
1. Quick Examples        # Automated demonstrations
2. Interactive Mode      # Chat with the agent
3. Compare ReAct vs StateGraph  # See different agent patterns

Enter choice (1-3): 1

from client.langgraph_agent import MCPLangGraphAgent

# Create and initialize agent
agent = MCPLangGraphAgent()
await agent.initialize()

# Simple tool usage
result = await agent.chat("Roll 2d20")

# Multi-tool coordination
result = await agent.chat("Roll 2d20 and create a social media post about the results")

# Complex multi-tool coordination
result = await agent.chat(
    "Search for AI news, create a LinkedIn post about it, and get a slide image"
)

# StateGraph for complex workflows
result = await agent.chat_with_state_graph(
    "Research machine learning trends and prepare presentation materials"
)

# server/main.py (line 48)
if __name__ == "__main__":
    mcp.run(transport="stdio")

# run_server.py (line 20)
main.mcp.run(transport="stdio")

self.mcp_config = {
    "my-mcp-server": {
        "command": "uv",
        "args": ["--directory", current_dir, "run", "run_server.py"],
        "transport": "stdio",  # ← STDIO specified here
    }
}

┌─────────────────┐    STDIO     ┌─────────────────┐
│  LangGraph      │◄────────────►│   FastMCP       │
│  Agent          │   (pipes)    │   Server        │
│  (Client)       │              │   (Process)     │
└─────────────────┘              └─────────────────┘

# REQUIRED: OpenAI API Key for LangGraph agent
OPENAI_API_KEY=your_openai_api_key_here

# REQUIRED: Tavily API Key for web search functionality
TAVILY_API_KEY=your_tavily_api_key_here

# OPTIONAL: Unsplash API Key for high-quality images
# If not provided, the system will use Lorem Picsum as fallback
UNSPLASH_ACCESS_KEY=your_unsplash_access_key_here

# OPTIONAL: GitHub Personal Access Token for private repository access
# Create at: https://github.com/settings/tokens
# Scopes needed: repo (for private repos), public_repo (for public repos)
GITHUB_TOKEN=ghp_your_github_personal_access_token_here

# OPTIONAL: LangChain API Key for LangSmith tracing/monitoring
# Only needed if you want to use LangSmith for debugging/monitoring
LANGCHAIN_API_KEY=your_langchain_api_key_here

{
  "mcpServers": {
    "mcp-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/AIE7-MCP-Session", "run", "run_server.py"]
    }
  }
}

🎲 Rolled: 18 (excellent!)
📱 Social Post: "Feeling lucky today! Just rolled an 18 - time to tackle that AI project! 
Innovation distinguishes between a leader and a follower. - Steve Jobs
#AI #motivation #lucky18"

# Run all tests (recommended)
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_server.py -v
uv run pytest tests/test_mcp_integration.py -v

# Run specific test method
uv run pytest tests/test_server.py::TestMCPServer::test_dice_rolling_tool -v

# Run with coverage (if available)
uv run pytest tests/ --cov=server --cov-report=term-missing

# Test server startup
uv run run_server.py

# Test client integration
uv run run_client.py

# Test specific functionality
uv run examples/example_langgraph_usage.py

# Legacy test execution (backwards compatible)
uv run tests/test_server.py

@mcp.tool()
def my_custom_tool(param: str) -> str:
    """Description of what your tool does"""
    return f"Processed: {param}"

# Server entry points
uv run server/main.py          # Direct server execution
uv run run_server.py           # Convenient wrapper

# Client entry points  
uv run examples/example_langgraph_usage.py  # Direct examples
uv run run_client.py           # Convenient wrapper

# Testing entry points
uv run tests/test_mcp_integration.py        # Integration tests
pytest tests/                               # All tests

# Clone and setup
git clone <repository-url>
cd AIE7-MCP-Session
cp .env.sample .env
# Add your OPENAI_API_KEY and TAVILY_API_KEY to .env

uv sync

# Test server works
uv run run_server.py &
sleep 2
pkill -f run_server.py
echo "✅ Server working!"

uv run run_client.py
# Choose option 1 for automated examples
# Watch the agent coordinate multiple tools

🎯 Quick LangGraph + MCP Examples
🔹 Testing: Roll a d20 for me and tell me what it means for my luck today
🔌 Connecting to MCP server...
✅ Connected! Loaded 5 tools
🤖 Agent: You rolled a 19 on a d20! That's excellent luck - great success awaits!

🔹 Testing: Search for recent AI news and create a professional social media post
🤖 Agent: Here's a professional LinkedIn post about recent AI developments:
💡 Reflecting on Recent AI Developments...
[Generated post with image and hashtags]

# Solution: Set your OpenAI API key
echo "OPENAI_API_KEY=your_key_here" >> .env

# Solution: Check server is working
uv run run_server.py

# Solution: Ensure MCP server tools are properly decorated
# Check server/main.py has @mcp.tool() decorators

# Add your own MCP tools to server/main.py
@mcp.tool()
def my_custom_tool(param: str) -> str:
    """Description of what your tool does"""
    return f"Processed: {param}"

# Agent will automatically detect and use new tools

# Create custom StateGraph workflows
from langgraph.graph import StateGraph, MessagesState

def custom_workflow():
    builder = StateGraph(MessagesState)
    # Add your custom nodes and edges
    return builder.compile()

# Different OpenAI models
agent = MCPLangGraphAgent()
agent.llm = ChatOpenAI(
    model="gpt-4",           # More powerful
    # model="gpt-4o-mini",   # Cost efficient (default)
    temperature=0.7,         # Creativity level
)