# empresa-mcp-demo

Servidor MCP remoto de demostración para validar la arquitectura **Claude Team + MCP custom** sin construir interfaz propia.

Desarrollado por Cyanea Tech Partner como prueba de viabilidad de la Opción 1: el cliente usa `claude.ai` para interactuar con sus propios sistemas (ERP, BD, APIs) a través de MCP servers desplegados en la nube por Cyanea.

---

## Qué hace este servidor

Expone 5 tools a Claude a través del protocolo MCP (Streamable HTTP):

| Tool | Descripción |
|---|---|
| `consultar_pedidos(estado?)` | Pedidos con nombre de cliente y producto. Filtra por `pendiente`, `en camino` o `entregado`. Sin filtro devuelve todos. |
| `listar_clientes()` | Todos los clientes con empresa, email y ciudad. |
| `listar_productos()` | Todos los productos con categoría, precio EUR y stock. |
| `resumen_negocio()` | KPIs: total pedidos, desglose por estado, productos con stock < 10. |
| `tipo_de_cambio(moneda)` | Tipo de cambio EUR → divisa en tiempo real (USD, GBP, JPY, MXN, COP…). Fuente: api.frankfurter.app, sin API key. |

La base de datos (`empresa_prueba.db`) es una BD SQLite con datos ficticios de clientes, productos y pedidos de una empresa española. Se recrea automáticamente al arrancar el servidor mediante `setup_db.py`.

---

## Arquitectura

```
Empleado del cliente
        ↓
   claude.ai Team (navegador)
        ↓
   Conector custom registrado por el Owner de la organización
        ↓
   Este servidor desplegado en Render.com
        ↓                          ↓
  empresa_prueba.db         api.frankfurter.app
  (SQLite local)            (divisas, tiempo real)
```

El empleado hace preguntas en lenguaje natural. Claude llama a las tools del MCP, consulta los datos reales y responde de forma interpretada. El usuario nunca ve SQL ni JSON.

---

## Stack técnico

- **Python 3.12** (runtime.txt para Render; funciona en 3.10+)
- **FastMCP 3.x** — framework para construir MCP servers con decoradores
- **httpx** — cliente HTTP async para llamadas a la API de divisas
- **SQLite** — BD embebida, sin servidor externo
- **Render.com** — hosting free tier para el deploy

---

## Configuración local

### 1. Clonar y crear entorno virtual

```bash
git clone https://github.com/TU_USUARIO/empresa-mcp-demo.git
cd empresa-mcp-demo
python -m venv .venv
```

Activar el entorno:
- Windows: `.venv\Scripts\activate`
- Mac/Linux: `source .venv/bin/activate`

### 2. Instalar dependencias

```bash
pip install -r requirements.txt
```

### 3. Crear la base de datos

```bash
python setup_db.py
```

Genera `empresa_prueba.db` con 5 clientes, 5 productos y 10 pedidos de ejemplo. Si ya existe, la borra y la recrea (idempotente).

### 4. Arrancar el servidor

```bash
python server.py
```

El servidor queda disponible en `http://localhost:8000/mcp`.

### 5. Verificar que funciona (opcional)

Prueba rápida con curl:

```bash
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

Debe devolver las 5 tools en la respuesta.

---

## Deploy en Render.com

### Requisitos previos
- Cuenta en [render.com](https://render.com) (free tier suficiente)
- Este repo subido a GitHub

### Pasos

1. En el dashboard de Render: **New → Web Service**
2. Conectar el repo de GitHub `empresa-mcp-demo`
3. Configurar el servicio:

| Campo | Valor |
|---|---|
| Language / Environment | Python |
| Branch | main |
| Build Command | `pip install -r requirements.txt` |
| Start Command | `python setup_db.py && python server.py` |
| Instance Type | Free |

4. Hacer clic en **Deploy**. El primer deploy tarda ~2-3 minutos.
5. La URL del servidor queda en: `https://[nombre-app].onrender.com/mcp`

> **Importante:** El `Start Command` incluye `setup_db.py` antes del servidor porque el sistema de archivos de Render es efímero — la BD se pierde en cada reinicio y hay que recrearla. No elimines esa parte del comando.

### Cold start (free tier)

Render free apaga el servicio tras 15 minutos de inactividad. La primera petición después tarda ~30 segundos mientras el servidor arranca. Para una demo, abre la URL del servicio en el navegador unos minutos antes para despertarlo.

Si necesitas que esté siempre activo, el plan Starter de Render cuesta ~$7/mes y elimina el cold start.

---

## Conectar a claude.ai Team

Solo puede hacerlo el **Owner** de la organización en claude.ai.

1. Ir a `claude.ai/admin-settings/connectors`
2. Clic en **Add custom connector**
3. Pegar la URL: `https://[nombre-app].onrender.com/mcp`
4. Guardar — claude.ai verifica la conexión automáticamente

Una vez registrado, cada miembro del Team puede activarlo en sus conversaciones desde el botón **"+"** en el chat → **Connectors**.

---

## Preguntas de demo para claude.ai

Una vez conectado el conector, prueba estas preguntas:

```
¿Qué pedidos están pendientes?
Dame un resumen del estado del negocio hoy
¿Qué productos tienen poco stock?
¿Cuánto vale el euro en dólares ahora mismo?
¿Cuánto sumarían en libras esterlinas los pedidos pendientes?
¿Qué clientes tienen pedidos en camino?
```

La última pregunta combina datos de la BD con la API de divisas en una sola respuesta.

---

## Archivos del proyecto

```
├── server.py        # MCP server principal (5 tools)
├── setup_db.py      # Crea y puebla empresa_prueba.db
├── requirements.txt # Dependencias Python
├── runtime.txt      # Versión de Python para Render
└── .gitignore       # Excluye .db, .venv, __pycache__, etc.
```

La BD (`empresa_prueba.db`) no está en el repo — se genera en local y en Render al arrancar.

---

## Notas para producción real

Este servidor es una **demo con datos ficticios**. Para un cliente real:

- Reemplazar las queries SQLite por llamadas a la API del ERP del cliente (REST, GraphQL, etc.)
- Añadir autenticación OAuth al MCP server (claude.ai lo soporta vía Advanced Settings en el conector)
- Migrar a Render Starter (~$7/mes) o VPS propio para eliminar cold start
- Si los datos son sensibles y no pueden salir de la red del cliente, desplegar el servidor dentro de su infraestructura (VPN o servidor interno accesible por Anthropic)