# Nimbus Copiloto — Servidor MCP del Helpdesk

Servidor MCP para **Helpdesk Nimbus**, la plataforma de tickets de soporte de
Nimbus S.A.S. Permite que un asistente de IA opere el helpdesk: buscar casos,
consultar historial, escalar, responder y medir cumplimiento de SLA.

> **Este es un entorno de aprendizaje.** Nimbus S.A.S. es una empresa ficticia.
> El repositorio existe para aprender FastMCP construyendo un proyecto con la
> forma y las exigencias de uno real.

---

## Arranque rápido

```bash
# 1. Dependencias
uv sync

# 2. Sembrar la base de datos
uv run python -m backend.seed

# 3. Levantar el backend de la empresa (terminal aparte, déjalo corriendo)
uv run uvicorn backend.main:app --reload --port 8000

# 4. Correr las pruebas
uv run pytest -v
```

Con el backend arriba: http://127.0.0.1:8000/docs

## El servidor MCP

```bash
# Correrlo
uv run python -m nimbus_mcp.server

# Inspeccionarlo en el navegador
uv run fastmcp dev src/nimbus_mcp/server.py
```

También queda disponible dentro de Claude Code gracias a `.mcp.json`.
Verificar con `/mcp`.

---

## Estructura

```
mcp-test/
├── backend/              # API interna de Nimbus — NO SE TOCA
│   ├── main.py           #   FastAPI: tickets, clientes, agentes, KB, métricas
│   ├── db.py             #   Esquema SQLite
│   └── seed.py           #   Generador de datos de prueba
├── src/nimbus_mcp/       # El servidor MCP — aquí trabajas
│   └── server.py
├── tests/                # Pruebas
├── data/nimbus.db        # Base sembrada (regenerable)
└── docs/                 # Documentación del proyecto
```

## Documentación

| Documento | Para qué |
|---|---|
| [docs/ONBOARDING.md](docs/ONBOARDING.md) | **Empieza aquí.** Qué es MCP, cómo levantar todo, ruta de aprendizaje |
| [docs/RUTA_AI_ENGINEER.md](docs/RUTA_AI_ENGINEER.md) | El plan largo: 8 fases hasta AI Engineer |
| [docs/EMPRESA.md](docs/EMPRESA.md) | La empresa, el equipo, por qué existe el proyecto |
| [docs/PRODUCTO.md](docs/PRODUCTO.md) | El dominio: tickets, estados, SLA, glosario |
| [docs/API_BACKEND.md](docs/API_BACKEND.md) | Contrato de la API que consume el MCP |
| [docs/BACKLOG.md](docs/BACKLOG.md) | Fase 1 — los tickets del MCP |
| [docs/BACKLOG_FASE_2.md](docs/BACKLOG_FASE_2.md) | Fase 2 — los tickets del copiloto |
| [docs/BITACORA.md](docs/BITACORA.md) | Dónde quedó la última sesión |

## El plan

Este repositorio es la Fase 1 de ocho. El sistema crece por capas: MCP →
copiloto → evals → RAG → guardrails → observabilidad → modelos propios →
producción. El mapa completo está en
[docs/RUTA_AI_ENGINEER.md](docs/RUTA_AI_ENGINEER.md).

## Versiones

Python 3.13 · FastMCP 3.4.7 · FastAPI 0.141 · pytest 9.1