MCP Calendar Assistant

MCP Calendar Assistant

Um poderoso servidor Model Context Protocol (MCP) que fornece recursos inteligentes de gerenciamento de calendário e tarefas. Este servidor permite que assistentes de IA interajam com seu calendário por meio de linguagem natural, lidando com tudo, desde criação simples de eventos até análises complexas de agendamento.

🌟 Recursos

Operações Principais de Calendário

• Suporte a Múltiplos Calendários: Google Calendar (com Outlook/Apple Calendar planejados)
• Gerenciamento de Eventos: Criar, ler, atualizar e excluir eventos de calendário
• Agendamento Inteligente: Encontre intervalos de tempo livres em vários calendários
• Verificação de Disponibilidade: Verifique se as pessoas estão disponíveis para reuniões
• Sugestões de Reuniões: Recomendações de horários ideais para reuniões com IA

Gerenciamento de Tarefas e Lembretes

• Lembretes Inteligentes: Crie e gerencie tarefas com prioridades e datas de vencimento
• Linguagem Natural: Processe tarefas a partir de entrada de texto não estruturado
• Análises: Acompanhe taxas de conclusão e padrões de produtividade

Recursos de Inteligência

• Análise de Agenda: Entenda seus padrões e hábitos de agendamento
• Sugestões de Contatos: Sugira automaticamente colaboradores frequentes
• Eventos Semelhantes: Encontre eventos relacionados para contexto
• Horário de Trabalho: Respeite preferências e restrições do usuário

Desempenho e Confiabilidade

• Cache Inteligente: Cache com Redis e TTLs configuráveis
• Operações em Lote: Operações eficientes em massa no calendário
• Tratamento de Erros: Mecanismos robustos de recuperação e nova tentativa
• Limitação de Taxa: Proteção integrada contra abuso de API

🏗️ Arquitetura

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │────│  MCP Calendar    │────│  Calendar APIs  │
│   (Claude, etc) │    │     Server       │    │ (Google, etc)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                       ┌──────────────────┐
                       │  PostgreSQL +    │
                       │     Redis        │
                       └──────────────────┘

🚀 Início Rápido

Pré-requisitos

• Node.js 18+
• PostgreSQL 12+
• Redis 6+ (opcional, mas recomendado)
• Projeto Google Cloud com API do Calendar habilitada

1. Clonar e Instalar

git clone <repository-url>
cd mcp-calendar-server
npm install

2. Configuração do Ambiente

cp .env.example .env
# Edit .env with your configuration

3. Configuração do Google Calendar

1. Acesse o Google Cloud Console
2. Crie um novo projeto ou selecione um existente
3. Habilite a API do Google Calendar
4. Crie credenciais OAuth 2.0
5. Adicione suas credenciais ao .env

4. Configuração do Banco de Dados

# Start PostgreSQL and Redis (using Docker)
docker-compose up -d postgres redis

# Or install locally and create database
createdb calendar_assistant

5. Compilar e Iniciar

npm run build
npm start

# Or for development
npm run dev

🔧 Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
DATABASE_URL	String de conexão PostgreSQL	postgresql://localhost:5432/calendar_assistant
REDIS_URL	String de conexão Redis	redis://localhost:6379
GOOGLE_CLIENT_ID	ID do cliente OAuth do Google	Obrigatório
GOOGLE_CLIENT_SECRET	Segredo do cliente OAuth do Google	Obrigatório
JWT_SECRET	Segredo para tokens JWT	Obrigatório

Flags de Recursos

FEATURE_CACHING=true          # Enable Redis caching
FEATURE_BATCHING=true         # Enable batch operations
FEATURE_PREFETCHING=true      # Enable predictive data loading
FEATURE_ANALYTICS=false       # Enable usage analytics
FEATURE_MULTI_PROVIDER=false  # Enable multiple calendar providers

📋 Ferramentas Disponíveis

Operações de Calendário

• get_calendars - Listar calendários disponíveis
• get_calendar_events - Recuperar eventos de um calendário
• create_calendar_event - Criar novos eventos
• update_calendar_event - Modificar eventos existentes
• delete_calendar_event - Remover eventos
• find_free_time - Encontrar intervalos de tempo disponíveis
• check_availability - Verificar se as pessoas estão livres
• suggest_meeting_times - Sugestões de reuniões com IA

Gerenciamento de Tarefas

• create_reminder - Criar tarefas e lembretes
• get_reminders - Recuperar tarefas com filtros
• update_reminder - Modificar tarefas existentes
• complete_reminder - Marcar tarefas como concluídas

Análises e Insights

• analyze_schedule_patterns - Entender hábitos de agendamento
• get_working_hours - Recuperar preferências de horário de trabalho
• get_recent_similar_events - Encontrar eventos relacionados
• get_contact_suggestions - Sugerir contatos automaticamente

💬 Exemplos de Uso

Criando Eventos

// AI Assistant can process:
"Schedule a dentist appointment next Tuesday at 2pm"
"Book a team meeting with John and Sarah for next week, 1 hour duration"
"Create a recurring weekly standup every Monday at 9am"

Encontrando Tempo Livre

// AI Assistant can process:
"When are we all free next week for a 2-hour workshop?"
"Find time for a 30-minute call with the marketing team"
"What's my availability on Friday afternoon?"

Gerenciamento de Tarefas

// AI Assistant can process:
"Remind me to call mom this weekend"
"Add a high-priority task to review the Q4 budget by Friday"
"Show me all my overdue tasks"

🔌 Integração MCP

Com o Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "calendar-assistant": {
      "command": "node",
      "args": ["/path/to/mcp-calendar-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/calendar_assistant",
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Com Aplicações Personalizadas

import { CalendarMCPServer } from 'mcp-calendar-server';

const server = new CalendarMCPServer();
await server.start();

🐳 Implantação com Docker

Usando Docker Compose

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start all services
docker-compose up -d

# Check logs
docker-compose logs -f mcp-calendar-server

Implantação em Produção

# Build production image
docker build -f docker/Dockerfile -t mcp-calendar-server .

# Run with external database
docker run -d \
  --name calendar-server \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/db" \
  -e REDIS_URL="redis://host:6379" \
  -e GOOGLE_CLIENT_ID="your-id" \
  -e GOOGLE_CLIENT_SECRET="your-secret" \
  mcp-calendar-server

🔒 Segurança

Autenticação

• Gerenciamento de sessão baseado em JWT
• OAuth 2.0 com Google Calendar
• Tratamento seguro de renovação de tokens
• Limpeza e expiração de sessões

Proteção de Dados

• Criptografia de variáveis de ambiente
• Criptografia de conexão com banco de dados
• Limitação de taxa de API
• Validação e sanitização de entrada

Melhores Práticas

• Execução de contêiner sem usuário root
• Superfície de ataque mínima
• Atualizações regulares de segurança
• Registro de auditoria

📊 Monitoramento

Verificações de Saúde

# Check server health
curl http://localhost:3000/health

# Check database connectivity
curl http://localhost:3000/health/db

# Check cache connectivity
curl http://localhost:3000/health/cache

Registros

Registro estruturado em JSON com níveis configuráveis:

• Rastreamento de erros e alertas
• Métricas de desempenho
• Registro de eventos de segurança
• Informações de depuração para desenvolvimento

🤝 Contribuindo

1. Faça um fork do repositório
2. Crie um branch de recurso (git checkout -b feature/amazing-feature)
3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
4. Envie para o branch (git push origin feature/amazing-feature)
5. Abra um Pull Request

Configuração de Desenvolvimento

# Install dependencies
npm install

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run format

# Start development server
npm run dev

🗺️ Roadmap

Fase 1 (Atual)

• ✅ Integração com Google Calendar
• ✅ Operações CRUD básicas
• ✅ Encontrar tempo livre
• ✅ Gerenciamento de tarefas
• ✅ Camada de cache

Fase 2 (Em Andamento)

• 🔄 Integração com Outlook Calendar
• 🔄 Algoritmos avançados de agendamento
• 🔄 Análise de tempo em linguagem natural
• 🔄 Suporte a webhooks para atualizações em tempo real

Fase 3 (Planejado)

• 📅 Integração com Apple Calendar
• 📅 Suporte a CalDAV
• 📅 Reserva de salas de reunião
• 📅 Integração de tempo de deslocamento
• 📅 Resolução inteligente de conflitos

Fase 4 (Futuro)

• 🔮 Insights de aprendizado de máquina
• 🔮 Agendamento preditivo
• 🔮 Integração com outras ferramentas de produtividade
• 🔮 Aplicativo complementar para celular

📄 Licença

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

🙏 Agradecimentos

• Model Context Protocol da Anthropic
• Google Calendar API
• PostgreSQL para armazenamento confiável de dados
• Redis para cache de alto desempenho

📞 Suporte

• 📧 E-mail: support@example.com
• 💬 Discord: Junte-se à nossa comunidade
• 📖 Documentação: docs.example.com
• 🐛 Problemas: GitHub Issues

---

Feito com ❤️ para a comunidade MCP