🤵 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.

Related MCP server: Promptibus MCP

📁 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

# 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

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:

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:

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:

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):

{
  "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)

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).