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:

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:

$env:GOOGLE_API_KEY="your-gemini-key"
$env:GITHUB_PERSONAL_ACCESS_TOKEN="your-github-token"

3. Run the App

Launch the Streamlit UI:

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!