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

# 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

# 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	Empieza aquí. Qué es MCP, cómo levantar todo, ruta de aprendizaje
docs/RUTA_AI_ENGINEER.md	El plan largo: 8 fases hasta AI Engineer
docs/EMPRESA.md	La empresa, el equipo, por qué existe el proyecto
docs/PRODUCTO.md	El dominio: tickets, estados, SLA, glosario
docs/API_BACKEND.md	Contrato de la API que consume el MCP
docs/BACKLOG.md	Fase 1 — los tickets del MCP
docs/BACKLOG_FASE_2.md	Fase 2 — los tickets del copiloto
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.

Versiones

Python 3.13 · FastMCP 3.4.7 · FastAPI 0.141 · pytest 9.1