MIST

Un servidor asistente de IA para gestionar notas, Gmail, Calendar, Tasks y Git.

Documentación

MIST - Sistema de Inteligencia de Modelos para Tareas

MIST es un servidor MCP (Protocolo de Contexto de Modelo) integral que brinda a los asistentes de IA capacidades del mundo real para la gestión de notas, Gmail, Calendario, Tareas e integración con Git. Une la brecha entre los asistentes de IA y las herramientas externas, permitiéndoles interactuar con tus datos y servicios a través de un protocolo estandarizado.

Descripción General

MIST permite a los asistentes de IA:

Gestionar notas: Crear, editar, buscar y organizar notas con almacenamiento persistente
Interactuar con Gmail: Buscar correos, leer mensajes, enviar correos, gestionar etiquetas
Gestionar eventos de calendario: Ver, crear, actualizar y eliminar eventos de Google Calendar
Organizar tareas: Crear listas de tareas, agregar tareas, marcar tareas como completadas
Trabajar con repositorios Git: Realizar operaciones de Git como estado, diff, commit, gestión de ramas

Al implementar el Protocolo de Contexto de Modelo (MCP), MIST permite a los asistentes de IA realizar acciones en sistemas externos, acceder a información en tiempo real y mantener el contexto a lo largo de las interacciones.

Características Clave

Gestión de Notas

Crear y almacenar notas con formato de texto enriquecido
Buscar notas por contenido, etiquetas o metadatos
Generar resúmenes de notas o colecciones
Organizar notas por tema, fecha o categorías personalizadas
Almacenar notas localmente en tu sistema de archivos

Integración con Gmail

Buscar correos con opciones de filtrado avanzadas
Leer el contenido completo de los correos
Redactar y enviar correos
Gestionar etiquetas de correo y organización
Marcar mensajes como leídos/no leídos
Operaciones por lotes para múltiples mensajes

Integración con Calendario

Listar todos los calendarios disponibles
Crear y gestionar eventos de calendario
Actualizar eventos existentes
Buscar eventos por palabra clave o rango de fechas
Ver información detallada de eventos

Integración con Tareas

Listar y gestionar listas de tareas
Crear tareas con títulos, notas y fechas de vencimiento
Marcar tareas como completadas
Eliminar tareas completadas
Organizar tareas en diferentes listas

Integración con Git

Realizar operaciones de Git en repositorios locales
Ver estado, diferencias e historial de commits
Confirmar cambios y gestionar ramas
Crear, cambiar y fusionar ramas
Gestionar repositorios remotos
Mostrar detalles de commits y cambios

Hoja de Ruta Futura

MIST está en continua evolución para ofrecer más integraciones y características. Esto es lo que planeamos agregar:

Gestión de Documentos y Archivos

Integración con Google Drive: Acceder y gestionar archivos, buscar documentos y analizar contenido
Integración con Google Sheets: Crear, leer y actualizar hojas de cálculo para análisis de datos

Búsqueda y Acceso a Información

Búsqueda Personalizada de Google: Habilitar capacidades de búsqueda web para investigación y recuperación de información
Base de Conocimiento: Construir repositorios locales de información para acceso sin conexión

Herramientas de Colaboración

Google Classroom: Acceder a cursos, tareas y materiales educativos
Google Chat: Interactuar con espacios de chat y mensajes para colaboración en equipo

Servicios de Datos y Ubicación

Google Forms: Crear y gestionar formularios para recopilación de datos
Google Maps: Agregar servicios basados en ubicación, incluidos geocodificación e indicaciones

Mejoras de Plataforma

Caché Mejorada: Mejorar el rendimiento para datos de acceso frecuente
Soporte Multi-Usuario: Agregar perfiles de usuario y gestión de permisos
Compatibilidad Ampliada con Asistentes de IA: Soporte para más asistentes y modelos de IA

¡Agradecemos contribuciones en cualquiera de estas áreas! Consulta nuestras Pautas de Contribución para obtener más información sobre cómo participar.

Arquitectura del Sistema

MIST opera como un servidor MCP que conecta asistentes de IA a varios servicios. Maneja la autenticación, recuperación de datos y acciones con los servicios apropiados, devolviendo datos estructurados al asistente de IA.

flowchart TB
    User[User] -->|Requests action| AI[AI Assistant]
    AI -->|Sends MCP request| MIST[MIST Server]

    subgraph "MIST Server Components"
        Router[MCP Request Router]
        NoteMgr[Note Manager]
        GmailMgr[Gmail Manager]
        TasksMgr[Tasks Manager]
        CalendarMgr[Calendar Manager]
        GitMgr[Git Manager]
        Auth[Authentication]
    end

    MIST --> Router
    Router -->|Note requests| NoteMgr
    Router -->|Gmail requests| GmailMgr
    Router -->|Tasks requests| TasksMgr
    Router -->|Calendar requests| CalendarMgr
    Router -->|Git requests| GitMgr
    GmailMgr -->|Auth requests| Auth
    TasksMgr -->|Auth requests| Auth
    CalendarMgr -->|Auth requests| Auth

    NoteMgr -->|Store/Retrieve| NoteDB[(Note Storage)]
    GmailMgr -->|API Calls| Gmail[(Gmail API)]
    TasksMgr -->|API Calls| Tasks[(Tasks API)]
    CalendarMgr -->|API Calls| Calendar[(Calendar API)]
    GitMgr -->|Git Operations| GitRepos[(Git Repositories)]

    MIST -->|Returns response| AI
    AI -->|Presents result| User

Flujo de Comunicación

sequenceDiagram
    participant User
    participant AI as AI Assistant
    participant MIST as MIST Server
    participant Services as External Services

    User->>AI: "Send an email to John"
    AI->>MIST: MCP Request (action: sendEmail)
    MIST->>Services: Authenticate & API Call
    Services->>MIST: Response
    MIST->>AI: Structured Response
    AI->>User: "Email sent to John"

    User->>AI: "Take notes about my project"
    AI->>MIST: MCP Request (action: createNote)
    MIST->>Services: Store Note
    Services->>MIST: Confirmation
    MIST->>AI: Success Response
    AI->>User: "Notes saved successfully"

Instalación

Requisitos Previos

Python 3.13 o más reciente
Gestor de paquetes UV (recomendado) o pip
Cuenta de Google (para integración con Gmail/Calendario/Tareas)
Git (para funciones de integración con Git)

Configuración

Clona este repositorio:

git clone https://github.com/cloaky233/mist.git
cd mist

Instala las dependencias:

Con UV (recomendado):
```
uv install
```
Con pip:
```
pip install -e .
```

Configura tu entorno:

# Create a .env file with your configuration
echo "MIST_NOTES_DIR=/path/to/your/notes/directory" > .env
echo "MIST_GOOGLE_CREDENTIALS_PATH=./credentials.json" >> .env
echo "MIST_GOOGLE_TOKEN_PATH=./token.json" >> .env

Edita el archivo .env para establecer las rutas correctas para tu entorno.

Configuración del Entorno

Las siguientes variables de entorno se pueden configurar en tu archivo .env:

# Notes storage configuration
MIST_NOTES_DIR=/path/to/notes/directory

# Google API configuration
MIST_GOOGLE_CREDENTIALS_PATH=./credentials.json
MIST_GOOGLE_TOKEN_PATH=./token.json

Configuración de la API de Google

Configuración de las APIs de Gmail, Calendario y Tareas

flowchart TD
    A[Start] --> B[Create Google Cloud Project]
    B --> C[Enable Required APIs]
    C --> D[Configure OAuth Consent Screen]
    D --> E[Create OAuth Credentials]
    E --> F[Download credentials.json]
    F --> G[Run MIST First Time]
    G --> H[Complete OAuth Flow]
    H --> I[OAuth Token Saved]
    I --> J[MIST Ready for Google Integration]

Crea un Proyecto en Google Cloud
- Navega a la Consola de Google Cloud
- Crea un nuevo proyecto o selecciona uno existente
- Dale un nombre descriptivo (por ejemplo, "Integración MIST")
Habilita las APIs Requeridas
- Ve a "APIs y Servicios" > "Biblioteca"
- Busca y habilita:
  - API de Gmail
  - API de Calendario
  - API de Tareas
Configura la Pantalla de Consentimiento de OAuth
- Ve a "APIs y Servicios" > "Pantalla de consentimiento de OAuth"
- Selecciona el tipo de usuario "Externo" (o "Interno" para Google Workspace)
- Completa la información requerida:
  - Nombre de la aplicación: "Integración MIST"
  - Correo de soporte al usuario: Tu dirección de correo
  - Información de contacto del desarrollador: Tu dirección de correo
- Haz clic en "Guardar y continuar"
- Agrega los alcances necesarios para cada API
- Agrega tu cuenta de Google como usuario de prueba
Crea Credenciales de OAuth
- Ve a "APIs y Servicios" > "Credenciales"
- Haz clic en "Crear credenciales" > "ID de cliente de OAuth"
- Selecciona "Aplicación de escritorio" como tipo de aplicación
- Ingresa un nombre (por ejemplo, "Cliente de escritorio MIST")
- Descarga el archivo JSON y guárdalo como credentials.json en el directorio de tu proyecto

Uso

Ejecutar el Servidor MCP

Inicia el servidor MCP con:

uv run --with mcp[cli] --with-editable . mcp run mist/server.py

Para uso en producción, es posible que desees usar un gestor de procesos como systemd, supervisor o pm2.

Conexión a Asistentes de IA

Claude Desktop

Agrega lo siguiente a la configuración de Claude Desktop:

{
  "mcpServers": {
    "M.I.S.T.": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/mist",
        "mcp",
        "run",
        "/path/to/mist/server.py"
      ],
      "env": {
        "MIST_GOOGLE_CREDENTIALS_PATH": "/path/to/mist/credentials.json",
        "MIST_GOOGLE_TOKEN_PATH": "/path/to/mist/token.json",
        "MIST_NOTES_DIR": "/path/to/notes"
      }
    }
  }
}

Editor Zed

Agrega lo siguiente a la configuración del editor Zed:

"context_servers": {
  "mist-server": {
    "command": {
      "path": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/mist",
        "mcp",
        "run",
        "/path/to/mist/server.py"
      ],
      "env": {
        "MIST_GOOGLE_CREDENTIALS_PATH": "/path/to/mist/credentials.json",
        "MIST_GOOGLE_TOKEN_PATH": "/path/to/mist/token.json",
        "MIST_NOTES_DIR": "/path/to/notes"
      }
    },
    "settings": {
      "enable_server": true
    }
  }
}

Autenticación en el Primer Uso

Cuando ejecutes el servidor por primera vez, deberás autenticarte con Google:

Se abrirá una ventana del navegador con la página de autenticación de Google
Inicia sesión con tu cuenta de Google
Concede los permisos solicitados
El código de autorización se capturará automáticamente
MIST guardará el token de autenticación para uso futuro

Referencia de la API

API de Gestión de Notas

Función	Descripción	Parámetros
`add_note`	Crear una nueva nota	`title`, `content`, `subject` (opcional)
`read_note`	Leer una nota por ID o título	`note_id` o `title`
`list_notes`	Listar notas con filtros	`subject`, `tag`, `limit`
`search_notes`	Buscar notas por contenido	`query`
`edit_note`	Actualizar una nota existente	`note_id`, `new_content`
`delete_note`	Eliminar una nota	`note_id`

API de Gmail

Función	Descripción	Parámetros
`search_emails`	Encontrar correos por criterios	Varios filtros
`get_emails`	Obtener contenido de correos por IDs	`message_ids`
`send_email`	Enviar un nuevo correo	`to`, `subject`, `body`, etc.
`list_available_labels`	Obtener etiquetas de Gmail	Ninguno

API de Calendario

Función	Descripción	Parámetros
`list_calendars_tool`	Listar todos los calendarios	Ninguno
`create_event_tool`	Crear un evento de calendario	`calendar_id`, `title`, etc.
`search_events_tool`	Buscar eventos de calendario	`calendar_id`, `query`, etc.

API de Tareas

Función	Descripción	Parámetros
`list_task_lists_tool`	Listar todas las listas de tareas	Ninguno
`create_task_tool`	Crear una nueva tarea	`task_list_id`, `title`, etc.
`complete_task_tool`	Marcar tarea como completada	`task_list_id`, `task_id`

API de Git

A continuación se muestra una selección de herramientas de Git de uso común. Para obtener una lista completa y parámetros detallados, consulta la Referencia de la API.

Función	Descripción	Parámetros Clave
`status_tool`	Mostrar estado del árbol de trabajo	`repo_path`
`diff_unstaged_tool`	Mostrar cambios no preparados	`repo_path`
`diff_staged_tool`	Mostrar cambios preparados	`repo_path`
`add_tool`	Preparar archivos para commit	`repo_path`, `files`
`reset_tool`	Restablecer HEAD actual o quitar archivos de la preparación	`repo_path`, `commit_ish` (opcional), `mode` (opcional)
`commit_tool`	Confirmar cambios preparados	`repo_path`, `message`
`log_tool`	Mostrar historial de commits	`repo_path`, `max_count` (opcional)
`branch_list_tool`	Listar todas las ramas	`repo_path`
`create_branch_tool`	Crear una nueva rama	`repo_path`, `branch_name`, `base_branch` (opcional)
`checkout_tool`	Cambiar de rama	`repo_path`, `branch_name`
`merge_tool`	Fusionar una rama o gestionar estado de fusión	`repo_path`, `branch` (opcional), `abort` (opcional)
`rebase_tool`	Rebasear la rama actual o gestionar estado de rebase	`repo_path`, `branch_or_commit` (opcional), `interactive` (opcional), `abort` (opcional), `continue_rebase` (opcional)
`stash_save_tool`	Guardar cambios actuales en stash	`repo_path`, `message` (opcional)
`pull_tool`	Extraer cambios de un remoto	`repo_path`, `remote` (opcional), `branch` (opcional)
`push_tool`	Enviar cambios a un remoto	`repo_path`, `remote` (opcional), `branch` (opcional), `force` (opcional), `tags` (opcional)

Estructura del Proyecto

mist/
├── __init__.py               # Package initialization with version info
├── server.py                 # Main MCP server entry point
├── tools/                    # Tool implementations
│   ├── note_tools/           # Note management
│   │   ├── __init__.py
│   │   └── tool.py           # Note tool implementations
│   ├── gmail_tools/          # Gmail integration
│   │   ├── __init__.py
│   │   ├── config.py         # Gmail-specific config
│   │   ├── gmail.py          # Gmail API utilities
│   │   └── tool.py           # Gmail tool implementations
│   ├── calendar_tools/       # Calendar integration
│   │   ├── __init__.py
│   │   ├── calendar.py       # Calendar API utilities
│   │   ├── config.py         # Calendar-specific config
│   │   └── tool.py           # Calendar tool implementations
│   ├── tasks_tools/          # Tasks integration
│   │   ├── __init__.py
│   │   ├── config.py         # Tasks-specific config
│   │   ├── tasks.py          # Tasks API utilities
│   │   └── tool.py           # Tasks tool implementations
│   ├── git_tools/            # Git operations
│   │   ├── __init__.py
│   │   ├── config.py         # Git-specific config (imports from google_api)
│   │   ├── gitapi.py         # Core Git command implementations
│   │   └── tool.py           # Git tool functions exposed to MCP
│   ├── google_api/           # Common Google API utilities
│   │   ├── __init__.py
│   │   ├── client.py         # Google API client
│   │   └── config.py         # Shared Google API config
│   └── __init__.py           # Tools package init
├── config_docs/              # Configuration documentation
│   ├── api_reference.md      # API reference documentation
│   ├── configs.md            # Example configuration templates
│   ├── configuration_guide.md# Detailed configuration guide
│   └── troubleshooting_guide.md # Troubleshooting guide
├── .github/                  # GitHub configuration
│   └── ISSUE_TEMPLATE/       # Issue templates for bug reports, etc.
├── LICENSE                   # MIT License
├── CONTRIBUTING.md           # Contributing guidelines
├── README.md                 # Project documentation
├── pyproject.toml            # Project metadata and dependencies
├── uv.lock                   # UV lock file for dependencies
├── credentials.json          # Google API credentials (should be user-provided)
└── .env                      # Environment configuration (user-created)

Consideraciones de Seguridad

Las claves de API y tokens se almacenan en el archivo .env o en variables de entorno
Los tokens de OAuth se gestionan de forma segura mediante el flujo de autenticación de Google
Tus datos permanecen en tu propio dispositivo o dentro de tus propias cuentas
No se envían datos a servicios de terceros a menos que se configuren explícitamente

Solución de Problemas

Problemas de Autenticación

Credenciales que no funcionan: Elimina token.json y vuelve a autenticarte
Errores de permisos: Verifica la pantalla de consentimiento de OAuth para los alcances adecuados
Token expirado: MIST debería renovar los tokens automáticamente, pero es posible que debas volver a autenticarte si la renovación falla

Problemas de Conexión

El asistente de IA no puede conectarse: Verifica que las rutas en la configuración sean correctas
El servidor no se inicia: Verifica la versión de Python (se requiere 3.13+)
Errores de API: Verifica que las claves de API y credenciales estén configuradas correctamente

Problemas de Datos

Las notas no se guardan: Verifica que la ruta MIST_NOTES_DIR exista y sea escribible

Desarrollo

Linting y Formato

ruff check .
ruff format .

Contribuciones

¡Las contribuciones son bienvenidas! Consulta nuestras Pautas de Contribución para obtener detalles sobre cómo comenzar.

Haz un fork del repositorio
Crea una rama de características: git checkout -b feature/amazing-feature
Realiza tus cambios y confírmalos: git commit -m 'Add amazing feature'
Envía a tu rama: git push origin feature/amazing-feature
Abre una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para obtener detalles.

Agradecimientos

Protocolo de Contexto de Modelo por la especificación del protocolo
APIs de Google para la integración con Gmail, Calendario y Tareas

Hecho con ❤️ por CLoaKY