MIST

Um servidor assistente de IA para gerenciar notas, Gmail, Calendário, Tarefas e Git.

Documentação

MIST - Sistema de Inteligência de Modelos para Tarefas

O MIST é um servidor MCP (Model Context Protocol) abrangente que capacita assistentes de IA com capacidades do mundo real para gerenciamento de notas, integração com Gmail, Google Calendar, Google Tasks e Git. Ele preenche a lacuna entre assistentes de IA e ferramentas externas, permitindo que interajam com seus dados e serviços por meio de um protocolo padronizado.

Visão Geral

O MIST permite que assistentes de IA:

Gerenciem notas: Criar, editar, pesquisar e organizar notas com armazenamento persistente
Interajam com o Gmail: Pesquisar e-mails, ler mensagens, enviar e-mails, gerenciar rótulos
Gerenciem eventos da agenda: Visualizar, criar, atualizar e excluir eventos do Google Calendar
Organizem tarefas: Criar listas de tarefas, adicionar tarefas, marcar tarefas como concluídas
Trabalhem com repositórios Git: Executar operações Git como status, diff, commit e gerenciamento de branches

Ao implementar o Model Context Protocol (MCP), o MIST permite que assistentes de IA executem ações em sistemas externos, acessem informações em tempo real e mantenham contexto entre interações.

Principais Recursos

Gerenciamento de Notas

Crie e armazene notas com formatação de texto rico
Pesquise notas por conteúdo, tags ou metadados
Gere resumos de notas ou coleções
Organize notas por assunto, data ou categorias personalizadas
Armazene notas localmente no seu sistema de arquivos

Integração com Gmail

Pesquise e-mails com opções avançadas de filtro
Leia o conteúdo completo do e-mail
Componha e envie e-mails
Gerencie rótulos e organização de e-mails
Marque mensagens como lidas/não lidas
Operações em lote para múltiplas mensagens

Integração com Google Calendar

Liste todas as agendas disponíveis
Crie e gerencie eventos da agenda
Atualize eventos existentes
Pesquise eventos por palavra-chave ou intervalo de datas
Visualize informações detalhadas do evento

Integração com Google Tasks

Liste e gerencie listas de tarefas
Crie tarefas com títulos, notas e datas de vencimento
Marque tarefas como concluídas
Exclua tarefas concluídas
Organize tarefas em diferentes listas

Integração com Git

Execute operações Git em repositórios locais
Visualize status, diffs e histórico de commits
Faça commit de alterações e gerencie branches
Crie, alterne e mescle branches
Gerencie repositórios remotos
Exiba detalhes e alterações de commits

Roteiro Futuro

O MIST está em constante evolução para oferecer mais integrações e recursos. Veja o que planejamos adicionar:

Gerenciamento de Documentos e Arquivos

Integração com Google Drive: Acesse e gerencie arquivos, pesquise documentos e analise conteúdo
Integração com Google Sheets: Crie, leia e atualize planilhas para análise de dados

Busca e Acesso a Informações

Google Custom Search: Ative recursos de pesquisa na web para pesquisa e recuperação de informações
Base de Conhecimento: Crie repositórios locais de informações para acesso offline

Ferramentas de Colaboração

Google Classroom: Acesse cursos, tarefas e materiais educacionais
Google Chat: Interaja com espaços de chat e mensagens para colaboração em equipe

Serviços de Dados e Localização

Google Forms: Crie e gerencie formulários para coleta de dados
Google Maps: Adicione serviços baseados em localização, incluindo geocodificação e rotas

Melhorias de Plataforma

Cache Aprimorado: Melhore o desempenho para dados acessados com frequência
Suporte a Múltiplos Usuários: Adicione perfis de usuário e gerenciamento de permissões
Compatibilidade Expandida com Assistentes de IA: Suporte a mais assistentes e modelos de IA

Aceitamos contribuições em qualquer uma dessas áreas! Consulte nossas Diretrizes de Contribuição para obter mais informações sobre como participar.

Arquitetura do Sistema

O MIST opera como um servidor MCP que conecta assistentes de IA a vários serviços. Ele lida com autenticação, recuperação de dados e ações com os serviços apropriados, retornando dados estruturados ao assistente 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

Fluxo de Comunicação

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"

Instalação

Pré-requisitos

Python 3.13 ou mais recente
Gerenciador de pacotes UV (recomendado) ou pip
Conta do Google (para integração com Gmail/Google Calendar/Google Tasks)
Git (para recursos de integração com Git)

Configuração

Clone este repositório:

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

Instale as dependências:

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

Configure seu ambiente:

# 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

Edite o arquivo .env para definir os caminhos corretos para seu ambiente.

Configuração de Ambiente

As seguintes variáveis de ambiente podem ser definidas no seu arquivo .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

Configuração da API do Google

Configurando as APIs do Gmail, Google Calendar e Google Tasks

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]

Crie um projeto no Google Cloud
- Navegue até o Google Cloud Console
- Crie um novo projeto ou selecione um existente
- Dê a ele um nome descritivo (por exemplo, "Integração MIST")
Ative as APIs necessárias
- Vá em "APIs e Serviços" > "Biblioteca"
- Pesquise e ative:
  - Gmail API
  - Calendar API
  - Tasks API
Configure a tela de consentimento OAuth
- Vá em "APIs e Serviços" > "Tela de consentimento OAuth"
- Selecione o tipo de usuário "Externo" (ou "Interno" para Google Workspace)
- Preencha as informações necessárias:
  - Nome do aplicativo: "Integração MIST"
  - E-mail de suporte ao usuário: Seu endereço de e-mail
  - Informações de contato do desenvolvedor: Seu endereço de e-mail
- Clique em "Salvar e Continuar"
- Adicione os escopos necessários para cada API
- Adicione sua conta do Google como usuário de teste
Crie credenciais OAuth
- Vá em "APIs e Serviços" > "Credenciais"
- Clique em "Criar Credenciais" > "ID do cliente OAuth"
- Selecione "Aplicativo de desktop" como tipo de aplicativo
- Digite um nome (por exemplo, "Cliente Desktop MIST")
- Baixe o arquivo JSON e salve-o como credentials.json no diretório do seu projeto

Uso

Executando o Servidor MCP

Inicie o servidor MCP com:

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

Para uso em produção, você pode querer usar um gerenciador de processos como systemd, supervisor ou pm2.

Conectando a Assistentes de IA

Claude Desktop

Adicione o seguinte às configurações do 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

Adicione o seguinte às configurações do 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
    }
  }
}

Autenticação na Primeira Execução

Ao executar o servidor pela primeira vez, você precisará autenticar com o Google:

Uma janela do navegador será aberta com a página de autenticação do Google
Faça login com sua conta do Google
Conceda as permissões solicitadas
O código de autorização será capturado automaticamente
O MIST salvará o token de autenticação para uso futuro

Referência da API

API de Gerenciamento de Notas

Função	Descrição	Parâmetros
`add_note`	Criar uma nova nota	`title`, `content`, `subject` (opcional)
`read_note`	Ler uma nota por ID ou título	`note_id` ou `title`
`list_notes`	Listar notas com filtros	`subject`, `tag`, `limit`
`search_notes`	Pesquisar notas por conteúdo	`query`
`edit_note`	Atualizar uma nota existente	`note_id`, `new_content`
`delete_note`	Excluir uma nota	`note_id`

API do Gmail

Função	Descrição	Parâmetros
`search_emails`	Encontrar e-mails por critérios	Vários filtros
`get_emails`	Obter conteúdo de e-mail por IDs	`message_ids`
`send_email`	Enviar um novo e-mail	`to`, `subject`, `body`, etc.
`list_available_labels`	Obter rótulos do Gmail	Nenhum

API do Google Calendar

Função	Descrição	Parâmetros
`list_calendars_tool`	Listar todas as agendas	Nenhum
`create_event_tool`	Criar um evento na agenda	`calendar_id`, `title`, etc.
`search_events_tool`	Pesquisar eventos na agenda	`calendar_id`, `query`, etc.

API do Google Tasks

Função	Descrição	Parâmetros
`list_task_lists_tool`	Listar todas as listas de tarefas	Nenhum
`create_task_tool`	Criar uma nova tarefa	`task_list_id`, `title`, etc.
`complete_task_tool`	Marcar tarefa como concluída	`task_list_id`, `task_id`

API do Git

Abaixo está uma seleção de ferramentas Git comumente usadas. Para uma lista completa e parâmetros detalhados, consulte a Referência da API.

Função	Descrição	Principais Parâmetros
`status_tool`	Mostrar status da árvore de trabalho	`repo_path`
`diff_unstaged_tool`	Mostrar alterações não preparadas	`repo_path`
`diff_staged_tool`	Mostrar alterações preparadas	`repo_path`
`add_tool`	Preparar arquivos para commit	`repo_path`, `files`
`reset_tool`	Redefinir HEAD atual ou desfazer preparação de arquivos	`repo_path`, `commit_ish` (opcional), `mode` (opcional)
`commit_tool`	Fazer commit das alterações preparadas	`repo_path`, `message`
`log_tool`	Mostrar histórico de commits	`repo_path`, `max_count` (opcional)
`branch_list_tool`	Listar todas as branches	`repo_path`
`create_branch_tool`	Criar uma nova branch	`repo_path`, `branch_name`, `base_branch` (opcional)
`checkout_tool`	Alternar branches	`repo_path`, `branch_name`
`merge_tool`	Mesclar uma branch ou gerenciar estado de merge	`repo_path`, `branch` (opcional), `abort` (opcional)
`rebase_tool`	Fazer rebase da branch atual ou gerenciar estado de rebase	`repo_path`, `branch_or_commit` (opcional), `interactive` (opcional), `abort` (opcional), `continue_rebase` (opcional)
`stash_save_tool`	Guardar alterações atuais (stash)	`repo_path`, `message` (opcional)
`pull_tool`	Puxar alterações de um remoto	`repo_path`, `remote` (opcional), `branch` (opcional)
`push_tool`	Enviar alterações para um remoto	`repo_path`, `remote` (opcional), `branch` (opcional), `force` (opcional), `tags` (opcional)

Estrutura do Projeto

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)

Considerações de Segurança

Chaves de API e tokens são armazenados no arquivo .env ou em variáveis de ambiente
Os tokens OAuth são gerenciados com segurança pelo fluxo de autenticação do Google
Seus dados permanecem no seu próprio dispositivo ou dentro das suas próprias contas
Nenhum dado é enviado a serviços de terceiros, a menos que seja explicitamente configurado

Solução de Problemas

Problemas de Autenticação

Credenciais não funcionando: Exclua token.json e autentique-se novamente
Erros de permissão: Verifique a tela de consentimento OAuth para escopos adequados
Token expirado: O MIST deve atualizar os tokens automaticamente, mas você pode precisar autenticar novamente se a atualização falhar

Problemas de Conexão

O assistente de IA não consegue conectar: Verifique se os caminhos na configuração estão corretos
O servidor não inicia: Verifique a versão do Python (3.13+ necessária)
Erros de API: Verifique se as chaves de API e credenciais estão configuradas corretamente

Problemas de Dados

Notas não estão sendo salvas: Verifique se o caminho MIST_NOTES_DIR existe e é gravável

Desenvolvimento

Linting e Formatação

ruff check .
ruff format .

Contribuição

Contribuições são bem-vindas! Consulte nossas Diretrizes de Contribuição para obter detalhes sobre como começar.

Faça um fork do repositório
Crie uma branch de recurso: git checkout -b feature/amazing-feature
Faça suas alterações e faça commit delas: git commit -m 'Add amazing feature'
Envie para sua branch: git push origin feature/amazing-feature
Abra um pull request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Model Context Protocol pela especificação do protocolo
APIs do Google para integração com Gmail, Google Calendar e Google Tasks

Feito com ❤️ por CLoaKY