# LangGraph FastAPI MCP Server & Agent Platform

A robust, enterprise-grade integration framework that combines **LangGraph** (agentic workflows) with **FastAPI MCP Servers** (Model Context Protocol). This architecture enables LLM-powered agents to communicate securely and dynamically with downstream microservices via Server-Sent Events (SSE) transport.

[![Watch the video](docs/project-image.png)](docs/project-video.mp4)

## Technology Stack

- **[FastAPI](https://fastapi.tiangolo.com/)**: A modern, high-performance web framework for building APIs with Python 3.11+.
- **[FastAPI-MCP](https://fastapi-mcp.tadata.com/)**: An open-source library that exposes FastAPI endpoints as Model Context Protocol (MCP) tools.
- **[MCP (Model Context Protocol)](https://www.anthropic.com/news/model-context-protocol)**: An open standard that facilitates seamless interaction between LLMs and external data/tools.
- **[LangChain](https://langchain.com/)**: An open-source framework for building applications powered by large language models.
- **[LangGraph](https://langgraph.dev/)**: A framework for building stateful, multi-actor applications with LLMs, ideal for agentic loops.
- **[Gradio](https://gradio.app/)**: An open-source library used to build the high-fidelity web chat interface.
- **[LangSmith](https://smith.langchain.com/)**: An observability platform for tracing, debugging, and monitoring LLM applications.
- **[uv](https://github.com/astral-sh/uv)**: An extremely fast Python package manager and resolver.

## 📊 System Architecture

The diagram below details the integration between the chatbot agent UI, the LangGraph orchestration engine, the MCP client gateway, and the FastAPI service backend.

```mermaid
graph TD
    User([User / Operator]) <-->|Chat Interface| Gradio[Gradio Web UI]
    Gradio <-->|Interacts with| LangGraphAgent[LangGraph ReAct Agent]
    LangGraphAgent <-->|Invokes Tools via| MCPClient[MCP Multi-Server Client]
    MCPClient <-->|SSE Transport| FastAPIMCP[FastAPI MCP Server]
    FastAPIMCP <-->|Resolves Routes| APIRoutes[FastAPI Endpoints]
    APIRoutes <-->|CRUD Operations| SQLASession[SQLAlchemy AsyncSession]
    SQLASession <-->|Reads/Writes| SQLite[(SQLite Database)]
```

## 🚀 Getting Started

### 1. Installation

Ensure you have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed.

Clone the repository and install all dependencies:
```bash
git clone https://github.com/gilish-tech/ai-shopping-assistant-mcp-server.git
cd ai-shopping-assistant-mcp-server
uv sync
```

### 2. Environment Configuration

Create a `.env` file in the project root:
```bash
# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key-here

# Optional: LangSmith Tracing & Observability
LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=your-langsmith-api-key-here
LANGCHAIN_PROJECT=langgraph-fastapi-mcp-server
```

### 3. Start the FastAPI MCP Service
Launch the FastAPI server which auto-exposes its routes as MCP tools:
```bash
uv run uvicorn server.main:app --host 0.0.0.0 --port 8000 --reload
```
- **Interactive Swagger Docs**: [http://localhost:8000/docs](http://localhost:8000/docs)
- **MCP Endpoint**: [http://localhost:8000/mcp](http://localhost:8000/mcp)

### 4. Start the Agent Client
Launch the Gradio chat interface to interact with the LangGraph agent:
```bash
uv run chatbot.py
```
- **Chat Web UI**: [http://localhost:7860](http://localhost:7860)

## 🛠️ Production Readiness & Deployment

To move this system into a production environment, follow these best practices:

1. **Database Migrations**: Apply changes to the schema using Alembic:
   ```bash
   uv run alembic upgrade head
   ```
2. **Production Web Server**: Run the FastAPI application using `uvicorn` with multiple workers or behind a reverse proxy (e.g., Nginx).
3. **Security and Auth**: Implement auth middleware in FastAPI and pass tokens through the SSE connection headers for tool execution control.
4. **Persistent Memory**: Replace the default in-memory SQLite checkpointer in LangGraph with a persistent store (e.g., PostgreSQL Checkpointer) for durable chat histories.

## 📄 License

Distributed under the MIT License. See `LICENSE` for details.

---
Maintained by **gilbert** (@gilish-tech).