<p align="center">
  <img src="Logo.webp" alt="Alfred - Mayordomo Olfativo" width="220" style="border-radius: 16px; box-shadow: 0 4px 20px rgba(0,0,0,0.15);" />
</p>

# 🤵 Alfred: Mayordomo Olfativo Personal (`alfred-perfume-mcp`)

Servidor **Model Context Protocol (MCP)** concebido bajo la figura de **Alfred**, su mayordomo personal y curador privado de alta perfumería, construido con **FastMCP (Python)** y **SQLite**.

Diseñado bajo la **Regla de Oro de Eficiencia de Tokens (Patrón Summary vs Detail)**, Alfred asiste a modelos de lenguaje (LLMs) con la distinción, cortesía e impecable criterio de un mayordomo de tradición británica: optimiza el contexto conversacional, realiza búsquedas conceptuales por acordes ponderados y segmentos (*Diseñador*, *Nicho*, *Árabe*), evalúa la viabilidad química de combinaciones (*layering*), gestiona su colección privada y diagnostica vacíos para mantener un guardarropa aromático intachable.

---

## 🏗️ Arquitectura y Principios de Diseño

### 1. Regla de Oro de Tokens (Summary vs Detail)
- Las herramientas de búsqueda (`buscar_perfumes`) **NUNCA** devuelven pirámides completas ni descripciones extensas. Devuelven objetos ultraligeros `PerfumeSummary` (ID, nombre, casa, género, concentración y top 3-4 acordes dominantes).
- El modelo solo solicita la ficha profunda (`obtener_detalle_perfume` o el recurso dinámico `perfumeria://perfume/{id}`) para los candidatos que decida profundizar.

### 2. Búsqueda Conceptual y Sinónimos Normalizados
- Sistema de resolución de alias y variantes (`sinonimos_notas`) que traduce términos coloquiales (ej. *'tonka'* ➔ *'haba tonka'*, *'oud'* ➔ *'madera de agar'*, *'lemon'* ➔ *'limón'*).
- Ponderación real de acordes (escala 0.1 a 1.0) para ordenar coincidencias con relevancia matemática.

### 3. Persistencia Relacional Ligera (SQLite)
- Esquema relacional normalizado con integridad referencial (`PRAGMA foreign_keys = ON;`) y modo WAL para transacciones concurrentes.
- Soporte para colecciones de usuario: bitácora de fragancias poseídas, deseadas (*wishlist*), probadas y descartadas con puntuaciones y notas personales.

---

## 📁 Estructura del Proyecto

```
PerfumIA/
├── README.md                           # Documentación técnica completa
├── requirements.txt                    # Dependencias estrictas (FastMCP, Pydantic v2)
├── claude_desktop_config.json          # Configuración para Claude Desktop
├── database/
│   ├── __init__.py
│   ├── connection.py                   # Conexión SQLite optimizada y soporte WAL
│   ├── schema.sql                      # DDL de tablas e índices relacionales
│   ├── seed_data.py                    # Catálogo curado (15 fragancias icónicas y 77 sinónimos)
│   └── perfumes.db                     # Base de datos SQLite generada
├── src/
│   ├── __init__.py
│   ├── models.py                       # Esquemas Pydantic v2 (Summary, Detail, Layering)
│   ├── repository.py                   # Consultas SQL optimizadas y algoritmos de maridaje
│   ├── server.py                       # Instancia FastMCP con Tools, Resources y Prompts
│   └── guides/                         # Documentación para los recursos estáticos
│       ├── familias_y_acordes.md
│       └── concentraciones_y_rendimiento.md
└── tests/
    └── test_server.py                  # Suite de pruebas unitarias y de integración
```

---

## 🚀 Instalación y Puesta en Marcha

### Prerrequisitos
- Python 3.10 o superior (verificado con Python 3.13 / 3.14).
- `uv` (recomendado) o `pip` / `venv`.
- Node.js (opcional, para utilizar el MCP Inspector).

### 1. Clonar y preparar el entorno virtual

```bash
# Clonar el repositorio
git clone https://github.com/<TU_USUARIO>/PerfumIA.git
cd PerfumIA

# Crear entorno virtual con Python
python -m venv .venv

# Activar entorno virtual
# En Windows (PowerShell):
.venv\Scripts\Activate.ps1
# En Windows (CMD):
.venv\Scripts\activate.bat
```

### 2. Instalar dependencias

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

### 3. Inicializar y Sembrar la Base de Datos

La base de datos se inicializa automáticamente al iniciar el servidor si no existe, pero puedes forzar o verificar la siembra ejecutando:

```bash
python -m database.seed_data
```

Salida esperada:
```
[OK] Se han sembrado 15 fragancias iconicas y 77 sinonimos normalizados.
```

---

## 🧪 Pruebas Unitarias

Ejecuta la suite de pruebas integrada para verificar el catálogo, los algoritmos de *layering* y los contratos MCP:

```bash
python -m unittest tests/test_server.py
```

---

## 🔍 Probar con el Inspector de MCP

El **MCP Inspector** oficial de Anthropic permite interactuar visualmente con las herramientas, recursos y prompts del servidor:

```bash
npx @modelcontextprotocol/inspector .venv\Scripts\python.exe src\server.py
```

Al abrir la interfaz web (generalmente en `http://localhost:5173`), podrás inspeccionar:
- **Tools:** Probar `buscar_perfumes`, `obtener_detalle_perfume`, etc.
- **Resources:** Leer `perfumeria://guia/familias-y-acordes` o fichas individuales `perfumeria://perfume/1`.
- **Prompts:** Invocar `asesor_personalizado` o `duelo_fragancias`.

---

## 🖥️ Integración con Claude Desktop

Para utilizar este servidor con la aplicación de escritorio de Claude, agrega la configuración en tu archivo `claude_desktop_config.json` (ubicado usualmente en `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "alfred-perfume": {
      "command": "C:\\ruta\\a\\PerfumIA\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\ruta\\a\\PerfumIA\\src\\server.py"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONPATH": "C:\\ruta\\a\\PerfumIA",
        "PERFUME_DB_PATH": "C:\\ruta\\a\\PerfumIA\\database\\perfumes.db"
      }
    }
  }
}
```

---

## 🛠️ Catálogo de Capacidades MCP

### 1. Herramientas (MCP Tools)

| Herramienta | Parámetros | Retorno | Descripción |
| :--- | :--- | :--- | :--- |
| `buscar_perfumes` | `query`, `acordes`, `ocasion`, `estacion`, `segmento`, `max_resultados` | `List[PerfumeSummary]` | Búsqueda conceptual ponderada y ligera por texto, marca, segmento ('Diseñador', 'Nicho', 'Árabe'), acordes u ocasión. |
| `obtener_detalle_perfume` | `perfume_id` | `PerfumeDetail` | Ficha técnica profunda con desglose de pirámide (salida, corazón, fondo), segmento, horas reales de longevidad y estela. |
| `analizar_layering` | `perfume_id_1`, `perfume_id_2` | `dict` | Evaluación sommelier de combinación de perfumes, anclajes de base, sinergias y orden técnico de pulverización. |
| `gestionar_coleccion` | `accion`, `perfume_id`, `estado`, `puntuacion`, `notas_personales` | `dict` | CRUD del armario olfativo personal (`poseo`, `deseo`, `probado`, `descartado`). |
| `recomendar_segun_coleccion` | *Ninguno* | `dict` | Análisis de cobertura estacional/contextual y recomendaciones de piezas clave para completar el fondo de armario. |

### 2. Recursos (MCP Resources)

- **`perfumeria://perfume/{perfume_id}` (Dinámico):** Ficha técnica en Markdown limpio de cualquier perfume del catálogo para inspección directa en el contexto sin gastar turnos de herramientas.
- **`perfumeria://guia/familias-y-acordes` (Estático):** Compendio enciclopédico sobre familias olfativas (Cítrica, Chipre, Oriental, Fougère, Gourmand, etc.) y acordes.
- **`perfumeria://guia/concentraciones-y-rendimiento` (Estático):** Guía sobre graduación de aceites (EDC, EDT, EDP, Extrait), maceración y química en piel.

### 3. Prompts Nativos (MCP Prompts)

- **`asesor_personalizado(ocasion, clima)`:** Activa el protocolo de entrevista refinada de un sommelier de alta perfumería.
- **`duelo_fragancias(perfume_a, perfume_b)`:** Prepara un versus exhaustivo cara a cara comparando secado (*drydown*), longevidad, versatilidad y factor de exclusividad.

---

## 🌹 Catálogo de Fragancias Curadas (22 Referencias)

### 🏺 Perfumería Árabe / Medio Oriente
1. **Khamrah** *(Lattafa)* - Dátiles confitados, canela, praliné y benjuí.
2. **9 PM** *(Afnan)* - Manzana crujiente, canela, lavanda salvaje y vainilla nocturna.
3. **Club de Nuit Intense Man** *(Armaf)* - Limón explosivo, abedul ahumado y ámbar gris.
4. **Asad** *(Lattafa)* - Pimienta negra, piña, café tostado y ámbar especiado.
5. **Shaghaf Oud** *(Swiss Arabian)* - Rosa, praliné, azafrán y madera de agar (oud) emiratí.

### 👔 Perfumería de Diseñador
6. **Dior Homme Intense** *(Dior)* - Iris cosmético mantecoso, maderas y ambreta.
7. **Terre d'Hermès** *(Hermès)* - Naranja amarga, sílex mineral, cedro y vetiver.
8. **Acqua di Giò Parfum** *(Armani)* - Notas marinas, bergamota e incienso ahumado.
9. **Bleu de Chanel** *(Chanel)* - Pomelo, menta, incienso, ámbar y cedro.
10. **Le Male Elixir** *(Jean Paul Gaultier)* - Torso ardiente con miel dorada, benjuí, tonka y tabaco.
11. **Encre Noire** *(Lalique)* - Ciprés gótico, vetiver de Bourbon y cashmeran.
12. **Chanel No. 5** *(Chanel)* - Aldehídos legendarios, ylang-ylang, iris y sándalo.

### 💎 Perfumería Nicho
13. **Creed Aventus** *(Creed)* - Piña ahumada, abedul, musgo de roble y grosella.
14. **Baccarat Rouge 540** *(MFK)* - Jazmín, azafrán, amberwood y cedro.
15. **Xerjoff Naxos** *(Xerjoff)* - Miel dorada, tabaco rubio, lavanda y cítricos sicilianos.
16. **Parfums de Marly Layton** *(PdM)* - Manzana crujiente, vainilla, cardamomo y maderas nobles.
17. **Cedrat Boise** *(Mancera)* - Limón de Sicilia, grosellas negras, cuero y cedro.
18. **By the Fireplace** *(Maison Margiela)* - Castaña asada, humo crepitante y vainilla.
19. **Tobacco Vanille** *(Tom Ford)* - Tabaco de club inglés, vainilla y frutos secos.
20. **Angels' Share** *(Kilian)* - Coñac añejado en barrica de roble, canela y praliné.
21. **Grand Soir** *(MFK)* - Ámbar parisino, benjuí de Siam y haba tonka.
22. **Hacivat** *(Nishane)* - Piña jugosa, musgo de roble y maderas secas (Extrait).