Amazing Marvin AI Assistant

🚀 Integración del Asistente de IA de Amazing Marvin

Conecta tu sistema de productividad Amazing Marvin con asistentes de IA para una gestión de tareas más inteligente

📋 Tabla de Contenidos

• ¿Qué es esto?
• Inicio rápido (2 minutos)
• ¿Qué puedes hacer con esto?
• Instalación
• Configuración
• Ejemplos de uso
• Solución de problemas
• Preguntas frecuentes
• Desarrollo
• Privacidad y seguridad

🎯 ¿Qué es esto?

Esto conecta tu sistema de productividad Amazing Marvin con asistentes de IA como Claude, Cursor y otros. En lugar de copiar manualmente tus tareas y proyectos en el chat, tu asistente de IA puede ver y ayudarte con tus datos reales de Amazing Marvin.

✨ Beneficios Clave

• 🔄 Mantente sincronizado - Tu asistente de IA siempre ve tus tareas, proyectos y metas actuales
• 📋 Ayuda inteligente - Recibe consejos personalizados basados en tu carga de trabajo y prioridades reales
• ⚡ Ahorra tiempo - No más copiar y pegar listas de tareas ni explicar tus proyectos
• 🎯 Mejor enfoque - La IA te ayuda a identificar qué es lo más importante en este momento
• 🔒 Privado - Tus datos permanecen entre Amazing Marvin y tu asistente de IA

⚡ Inicio rápido (2 minutos)

Paso 1: Obtén tu clave de API de Amazing Marvin

1. Abre Amazing Marvin → Configuración → API (navegar aquí puede ser más fácil en móvil)
2. Activa la API y copia tu token
3. ¡Tenlo a mano! 🔑

Paso 2: Instalación

Forma fácil (Smithery):

npx -y @smithery/cli mcp add @bgheneti/amazing-marvin-mcp --client claude

Pega la clave de API cuando se te solicite

Alternativa (pip):

pip install amazing-marvin-mcp

Luego añádelo a la configuración de tu cliente de IA (consulta la guía de instalación)

Paso 3: Verifica que funciona

Pregunta a tu IA: "¿Qué tareas tengo hoy?"

🎉 ¡Eso es todo! Tu IA ahora puede ver tus datos de Amazing Marvin.

💡 ¿Qué puedes hacer con esto?

Una vez conectado, tu asistente de IA se convierte en tu entrenador personal de productividad con acceso a tus datos reales de Amazing Marvin:

📅 Ayuda para la planificación diaria

"¿En qué debería centrarme hoy?" - Obtén recomendaciones personalizadas basadas en tus fechas límite y prioridades reales

"Me siento abrumado - ¿qué es lo más importante?" - La IA te ayuda a cortar el ruido e identificar lo que realmente importa

🎯 Información de proyectos

"¿Cómo va mi proyecto de rediseño del sitio web?" - Ve el progreso, las tareas completadas y lo que queda por hacer

"Muéstrame todo lo relacionado con el trabajo de clientes esta semana" - Obtén vistas organizadas de tus tareas por proyecto o categoría

📊 Seguimiento de progreso

"¿Qué logré esta semana?" - Revisa tus patrones de productividad y celebra los logros

"¿Qué días soy más productivo?" - Comprende tus patrones para planificar mejor

⏰ Programación inteligente

"¿Qué está vencido y necesita atención?" - Nunca pierdas de vista las fechas límite importantes

"Ayúdame a planificar mañana según lo que tengo programado" - Obtén planes diarios realistas que funcionen

⏱️ Seguimiento de tiempo

"Empieza a registrar el tiempo en esta tarea" - Gestiona el seguimiento de tiempo sin problemas desde tu chat de IA

"¿En qué he estado trabajando hoy?" - Revisa tu asignación de tiempo y enfoque

Por qué esto es mejor que los consejos genéricos de productividad: Tu IA ve tus tareas, fechas límite y progreso reales, por lo que la ayuda que recibes está personalizada a tu situación real, no son consejos genéricos.

Nota: Esto cubre la mayoría de las funciones de Amazing Marvin, aunque algunas personalizaciones avanzadas y estrategias tienen acceso limitado a la API.

📦 Instalación

Opción 1: Smithery (la más fácil)

npx -y @smithery/cli install @bgheneti/amazing-marvin-mcp --client claude

Visita el Registro de Smithery para otros clientes.

Opción 2: Pip + Configuración manual

Por qué elegir esta opción:

• ✅ Funciona con cualquier cliente de IA compatible con MCP
• ✅ Fácil de actualizar: solo pip install --upgrade amazing-marvin-mcp

Requisitos previos

• ✅ Python 3.10+
• ✅ Claude Desktop, Cursor, Windsurf, VS Code u otro cliente MCP
• ✅ Cuenta de Amazing Marvin con acceso a la API

Instalación

# Install from PyPI (recommended)
pip install amazing-marvin-mcp

📱 Configuración del cliente

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

💡 Ejemplos de uso

El MCP proporciona herramientas específicas que tu IA puede usar. Simplemente pide a tu IA que te ayude con tareas de productividad y usará las herramientas adecuadas:

📁 Cómo entiende tu configuración

Tu asistente de IA entiende automáticamente tu estructura de Amazing Marvin:

• Proyectos de trabajo y personales - Mantiene organizadas tus tareas profesionales y personales
• Categorías y etiquetas - Sabe cómo has organizado tu sistema de productividad
• Fechas límite y prioridades - Entiende qué es urgente vs. importante
• Completadas vs. pendientes - Hace seguimiento de tu progreso y impulso

No necesitas explicar tu sistema: ¡tu IA simplemente lo entiende!

🔧 Solución de problemas

❌ Problemas comunes

❓ Preguntas frecuentes

👨‍💻 Desarrollo

🛠️ Configuración

git clone https://github.com/bgheneti/Amazing-Marvin-MCP.git
cd Amazing-Marvin-MCP
pip install -e ".[dev]"
pre-commit install

🔑 Configura tu clave de API

Opción A: Variable de entorno

export AMAZING_MARVIN_API_KEY="your-api-key-here"

Opción B: Crea un archivo .env

AMAZING_MARVIN_API_KEY=your-api-key-here

🧪 Pruebas

pytest tests/ -v

⚠️ Nota: Las pruebas crean elementos temporales en tu cuenta de Amazing Marvin con prefijos [TEST]. Pueden requerir limpieza manual debido a las limitaciones de la API.

📋 Calidad del código

# Run all checks
pre-commit run --all-files

# Individual tools
ruff check .          # Linting
ruff format .         # Formatting
mypy .               # Type checking
pytest tests/        # Tests

🔄 Herramientas disponibles

El MCP proporciona 28 herramientas completas a los asistentes de IA: 📖 Operaciones de Lectura:

• get_daily_productivity_overview() - PRINCIPAL vista diaria completa (tareas de hoy, atrasadas, completadas, información de planificación)
• get_tasks() - Solo elementos programados para hoy
• get_projects() - Todos los proyectos
• get_categories() - Todas las categorías
• get_due_items() - Solo elementos atrasados/vencidos
• get_child_tasks( parent_id: str, recursive: bool = False ) - Subtareas de una tarea/proyecto padre
• get_all_tasks( label: str = None ) - Encuentra todas las tareas con filtro opcional por etiqueta (búsqueda exhaustiva)
• get_labels() - Etiquetas de tareas
• get_goals() - Metas y objetivos
• get_account_info() - Detalles de la cuenta
• get_completed_tasks() - Elementos completados con categorización por fecha (por defecto, últimos 7 días)
• get_completed_tasks_for_date( date: str ) - Elementos completados para una fecha específica (formato AAAA-MM-DD)
• get_productivity_summary_for_time_range( days: int = 7, start_date: str = None, end_date: str = None ) - Análisis de productividad flexible
• get_currently_tracked_item() - Seguimiento de tiempo activo

✏️ Operaciones de Escritura:

• create_task( title: str, project_id: str = None, category_id: str = None, due_date: str = None, note: str = None ) - Crear nuevas tareas
• mark_task_done( item_id: str, timezone_offset: int = 0 ) - Completar tareas
• create_project( title: str, project_type: str = "project" ) - Crear nuevos proyectos
• start_time_tracking( task_id: str ) - Iniciar seguimiento de tiempo
• stop_time_tracking( task_id: str ) - Finalizar seguimiento de tiempo
• batch_mark_done( task_ids: list[str] ) - Completar múltiples tareas
• batch_create_tasks( task_list: list[str], project_id: str = None, category_id: str = None ) - Crear múltiples tareas
• claim_reward_points( points: int, item_id: str, date: str ) - Reclamar puntos de reconocimiento
• get_kudos_info() - Obtener información del sistema de recompensas y puntos

🔧 Operaciones de Utilidad:

• test_api_connection() - Verificar conectividad de la API
• get_project_overview( project_id: str ) - Análisis de proyectos
• get_daily_focus() - Prioridades diarias
• get_productivity_summary() - Métricas de rendimiento
• time_tracking_summary() - Análisis de tiempo
• quick_daily_planning() - Asistencia de planificación
• create_project_with_tasks( project_title: str, task_titles: list[str], project_type: str = "project" ) - Configuración de proyectos
• get_time_tracks( task_ids: list[str] ) - Historial de seguimiento de tiempo

🤝 Contribuciones

🚀 Publicación de Nuevas Versiones

Este proyecto utiliza publicación automatizada en PyPI mediante GitHub Actions.

Para mantenedores:

# Make your changes and test them
pytest tests/ -v
ruff check src/
mypy src/amazing_marvin_mcp/

# Use the release script to bump version and create tag
python scripts/release.py patch   # for bug fixes
python scripts/release.py minor   # for new features
python scripts/release.py major   # for breaking changes

# Push to trigger CI and PyPI publish
git push origin main
git push origin v1.x.x

El flujo de trabajo:

1. ✅ Las pruebas se ejecutan en Python 3.8-3.12
2. ✅ El linting y la verificación de tipos pasan
3. 📦 El paquete se compila y verifica
4. 🚀 Se publica en PyPI automáticamente con las etiquetas de versión

🔧 Configuración de Desarrollo Local

git clone https://github.com/bgheneti/Amazing-Marvin-MCP.git
cd Amazing-Marvin-MCP
pip install -e ".[dev]"
pre-commit install

🧪 Pruebas

También puedes publicar manualmente en Test PyPI ejecutando el flujo de trabajo manualmente en GitHub.

🔒 Privacidad y Seguridad

🛡️ Protección de tus Datos

• Procesamiento Local: MCP se ejecuta completamente en tu máquina
• Conexión Directa: Los datos van directamente de Amazing Marvin a tu IA
• Sin Almacenamiento en la Nube: Nada se guarda en servidores externos
• Seguridad de la Clave API: Guarda tu clave de forma segura usando variables de entorno

🔐 Mejores Prácticas

• ✅ Usa variables de entorno para las claves API (no archivos de configuración)
• ✅ No compartas tu clave API en capturas de pantalla o registros
• ✅ Mantén tu clave API segura y trátala como una contraseña

⚖️ Rendimiento y Limitaciones

Qué esperar:

• Tu asistente de IA obtiene datos frescos de Amazing Marvin cuando haces preguntas
• Los datos históricos se almacenan en caché brevemente para evitar solicitudes repetidas
• El tiempo de respuesta depende de tu conexión a internet con Amazing Marvin
• Las solicitudes muy frecuentes podrían ocasionalmente alcanzar límites de velocidad (solo espera un momento)

Detalles técnicos:

• Los datos se obtienen en tiempo real para mayor precisión
• Algunos datos se almacenan en caché durante 10 minutos para mejorar la velocidad
• Las operaciones por lotes funcionan eficientemente para múltiples tareas
• Todas las funciones principales de Amazing Marvin están soportadas

📄 Licencia

Licencia MIT - consulta LICENSE para más detalles.