# Tech Spirit Animal (Multi-MCP Server Example)

This project is a powerful demonstration of the **Model Context Protocol (MCP)** using LangChain and Streamlit. It uses an AI agent powered by Google's Gemini that dynamically routes requests across **four distinct MCP Servers** to discover a user's "Tech Spirit Animal" based on their GitHub footprint.

## Architecture

The AI is orchestrated by a LangGraph agent (`community_mcp/agent.py`) which connects to the following four MCP servers simultaneously:

1. **GitHub MCP Server** (Community): Fetches the user's repositories, bio, and recent activity directly from GitHub.
2. **DuckDuckGo Web Search Server** (`ddg_server.py`): A custom-built Python MCP server that provides robust web search tools.
3. **Wikipedia Image Search Server** (`wiki_server.py`): A custom-built Python MCP server used to fetch high-quality images of the resulting Spirit Animal without running into bot rate limits.
4. **Custom Python Server** (`first.py`): A basic custom Python server exposing simple data processing tools.

### Real-Time Observability
This project implements a transparent observability layer using LangGraph's `.astream(stream_mode="updates")`. As the ReAct agent loops through its reasoning steps, tool calls and execution statuses are intercepted and streamed directly to the Streamlit UI in real-time. This allows users to watch the agent "think" and act without blocking on a final response.

## Setup Instructions

### 1. Install Dependencies
You need `uv` installed, as well as Node.js (for `npx`). 
Run the following in the project root:
```bash
uv pip install -r community_mcp/requirements.txt
uv add duckduckgo-search fastmcp
```

### 2. Set Environment Variables
You need two API keys for the agent to function:
```powershell
$env:GOOGLE_API_KEY="your-gemini-key"
$env:GITHUB_PERSONAL_ACCESS_TOKEN="your-github-token"
```

### 3. Run the App
Launch the Streamlit UI:
```powershell
uv run streamlit run community_mcp/app.py
```

## How It Works
When you enter a GitHub username, the Streamlit app asks the Gemini agent to determine their Tech Spirit Animal.
1. The Agent calls the **GitHub MCP Server** to analyze the user's repos.
2. The Agent calls the **Custom Python Server** to prove the dual-server setup works.
3. The Agent calls the **Wikipedia Image Search Server** to fetch an image of the chosen animal.
4. The final result (with the image) is rendered in the Streamlit UI!