WorkHub Monterrey - SpotOn — BackEnd y MCP Server

Servidor de herramientas de inteligencia artificial para la plataforma SpaceBook. Implementado con LangChain + LangGraph sobre el protocolo MCP (Model Context Protocol), usando Gemini Flash 2.0 como modelo base para generar sugerencias personalizadas de espacios de trabajo.

Este README cubre la arquitectura general y la integración con el sistema. Para instrucciones de uso interno y configuración de herramientas, consulta el README técnico incluido en el repositorio.

---

Índice

• Arquitectura
• Uso del sistema
• Variables de entorno
• Scripts disponibles
• Dependencias clave
• Enlaces clave

---

Arquitectura

Frontend / Postman
      │
      │  POST /suggest  { query, user_id, today }
      ▼
┌─────────────────────┐
│  FastAPI  (port 8001)│   Client/api.py
│  /suggest            │
│  /suggest/stream     │
└────────┬────────────┘
         │  LangGraph agent (ainvoke / astream_events)
         ▼
┌─────────────────────┐
│   LangGraph Graph   │   Graph/graph.py + Graph/nodes.py
│   call_model ──────►│──► Gemini (gemini-3.1-flash-lite-preview)
│       │  ▲          │
│   call_tools        │
└────────┬────────────┘
         │  MCP tools via langchain-mcp-adapters
         ▼
┌─────────────────────┐
│  FastMCP Server     │   Server/mcp_server.py  (port 8000)
│  get_user_preferences│
│  get_availability   │
│  get_reservation_   │
│    history          │
└────────┬────────────┘
         │  HTTP
         ▼
  WorkHub REST API  (port 5500)

Estructura del proyecto

reservations/
├── Client/
│   ├── api.py          # FastAPI app — /suggest and /suggest/stream endpoints
│   └── main.py         # CLI entry point for direct agent queries
├── Graph/
│   ├── graph.py        # LangGraph StateGraph definition and MCP client setup
│   └── nodes.py        # Agent nodes, system prompt loader, routing logic
├── Server/
│   └── mcp_server.py   # FastMCP server — WorkHub MCP tools + injection sanitizer
├── prompts/
│   └── system_prompt.txt  # NOT committed — contains the agent's instruction strategy
├── pyproject.toml
└── .env                # NOT committed — contains GEMINI_API_KEY

---

Uso del sistema

Qué hace este servidor

El servidor MCP expone un conjunto de herramientas que el modelo de IA puede invocar para acceder a datos reales antes de generar una respuesta. Esto le permite:

• Analizar el historial de reservas del usuario para detectar patrones de comportamiento.
• Consultar la disponibilidad actual de espacios de oficina y estacionamiento.
• Obtener información sobre los espacios más frecuentados por el usuario o su equipo.
• Generar sugerencias de ruta hacia los espacios recomendados usando la API de TomTom.

El resultado es una recomendación contextualizada, no genérica, basada en datos reales de la empresa.

---

Variables de entorno

# Modelo de IA
GEMINI_MODEL=Modelo de gemini
GOOGLE_API_KEY=tu_api_key_de_gemini

#Servidor MCP
MCP_SERVER_URL

#API REST
WORKHUB_API_BASE=url del backend de la plataforma

# TomTom MCP
TOMTOM_API_KEY=tu_api_key_de_tomtom
TOMTOM_MOVE_PORTAL_KEY=https://api.tomtom.com/mcp

---

Scripts disponibles

uv sync
uv run Server/mcp_server.py                                # Iniciar el servidor mcp
uv run uvicorn Client.api:app --reload --port 8001         # Iniciar la API de FastAPI

---

Dependencias clave

Paquete	Uso
fastapi	Framework para APIs REST de fastAPI
fastmcp	Framework de mcp
langchain-google-genai	Conector con el modelo de Gemini
langchain-core	Base abstracta de LangChain
langchain-mcp-adapters	Adaptador para uso de mcp
langgraph	Orquestación del grafo de ejecución del agente
mcp[cli]	Protocolo de herramientas (Model Context Protocol)
uvicorn	Servidor web ASGI

---

Enlaces clave

• Repositorio Frontend → github.com/Eldeibit97/WorkHub_SpotOn
• Repositorio Backend → github.com/Eldeibit97/WorkHub_Backend
• TomTom Developer Portal → developer.tomtom.com
• Google AI Studio (Gemini) → aistudio.google.com
• LangChain Docs → python.langchain.com
• LangGraph Docs → langchain-ai.github.io/langgraph
• MCP Protocol → modelcontextprotocol.io