Personal MCP Server

# 📦 MCP Server Pessoal - Sumário Executivo ## 🎯 O Que É? Um servidor MCP (Model Context Protocol) completo e funcional que permite ao Claude Desktop acessar seus recursos locais (arquivos, tarefas, calendário) de forma segura e controlada. --- ## ✨ Principais Funcionalidades ### 📁 Gerenciamento de Arquivos - ✅ Ler, escrever, listar arquivos - ✅ Buscar arquivos por padrão - ✅ Segurança com allowlist de diretórios ### ✅ Sistema de Tarefas - ✅ Criar e gerenciar tarefas - ✅ Prioridades e prazos - ✅ Notas com tags ### 📅 Google Calendar (Opcional) - ✅ Criar eventos - ✅ Consultar agenda - ✅ Buscar compromissos --- ## 🚀 Instalação em 3 Passos ```bash # 1. Execute o setup python setup.py # 2. Inicie o servidor python main.py # 3. Reinicie Claude Desktop e teste "Liste arquivos no meu Documents" ``` --- ## 📂 Estrutura de Arquivos ### 📚 Documentação (Leia Nesta Ordem) 1. **[COMO_USAR.md](COMO_USAR.md)** ⭐⭐⭐ - **COMECE POR AQUI!** - Guia passo a passo de execução - Testes práticos - Casos de uso reais 2. **[README.md](README.md)** ⭐⭐ - Visão geral do projeto - Instalação rápida - Exemplos básicos 3. **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** ⭐ - Referência rápida - Comandos mais usados - Atalhos úteis 4. **[GUIA_COMPLETO.md](GUIA_COMPLETO.md)** - Documentação detalhada - Configurações avançadas - Troubleshooting completo 5. **[TESTES.md](TESTES.md)** - Guia de testes - Validação de instalação - Testes unitários ### 🔧 Arquivos Principais ``` mcp-tools2/ │ ├── 📄 main.py # ⭐ Inicia o servidor ├── 📄 setup.py # ⭐ Setup automatizado ├── 📄 test_server.py # 🧪 Teste rápido ├── 📄 start.bat # 🪟 Iniciar no Windows ├── 📄 start.sh # 🐧 Iniciar no Linux/Mac │ ├── 📁 config/ # Configurações │ ├── settings.py # Settings com Pydantic │ └── logging.py # Setup de logs │ ├── 📁 core/ # Núcleo do servidor │ ├── server.py # Servidor MCP │ ├── registry.py # Registro de ferramentas │ └── security.py # Validações segurança │ ├── 📁 modules/ # Módulos funcionais │ ├── base.py # Classe base │ ├── filesystem/ # Sistema de arquivos │ ├── tasks/ # Tarefas e notas │ └── calendar/ # Google Calendar │ ├── 📁 utils/ # Utilitários │ └── validators.py # Validadores │ ├── 📁 tests/ # Testes unitários │ ├── test_filesystem.py │ ├── test_tasks.py │ └── test_security.py │ ├── 📁 logs/ # Logs (criado automaticamente) └── 📁 data/ # Dados (criado automaticamente) ``` --- ## 🎮 Como Usar ### Comandos Básicos no Claude ``` # Arquivos Liste arquivos em Documents Leia o arquivo README.md Crie arquivo teste.txt com "Hello" Procure arquivos .py em projetos # Tarefas Crie tarefa: "Revisar docs" prioridade alta Mostre minhas tarefas pendentes Marque tarefa #1 como concluída # Calendar (se configurado) Crie evento "Reunião" amanhã às 14h Quais meus compromissos hoje? ``` --- ## 🔒 Segurança - ✅ Acesso apenas a diretórios configurados - ✅ Validação contra path traversal - ✅ Limite de 10MB por arquivo - ✅ Timeout de 30s por operação - ✅ Todas operações são logadas --- ## 🛠️ Tecnologias - **Python 3.9+** - **MCP SDK** - Model Context Protocol - **FastMCP** - Framework MCP - **Pydantic** - Validação de dados - **aiofiles** - I/O assíncrono - **Google Calendar API** (opcional) --- ## 📊 Status do Projeto - ✅ **Completo e Funcional** - ✅ Documentação completa - ✅ Testes unitários - ✅ Setup automatizado - ✅ Segurança robusta - ✅ Pronto para produção --- ## 🎯 Casos de Uso ### Desenvolvedor - Gerenciar código e projetos - Criar documentação automaticamente - Organizar tarefas de desenvolvimento ### Estudante - Organizar materiais de estudo - Gerenciar cronograma de estudos - Criar resumos e anotações ### Profissional - Gerenciar documentos - Acompanhar agenda - Organizar tarefas e projetos ### Pesquisador - Organizar papers e referências - Gerenciar cronograma de pesquisa - Criar anotações estruturadas --- ## 🚦 Quick Start ### Primeira Vez ```bash # 1. Setup python setup.py # 2. Configurar .env (o setup ajuda) # Adicione seus diretórios permitidos # 3. Testar python test_server.py # 4. Iniciar python main.py # 5. No Claude Desktop "Liste arquivos em Documents" ``` ### Uso Diário ```bash # Iniciar servidor python main.py # ou start.bat # Windows ./start.sh # Linux/Mac # Use normalmente no Claude Desktop ``` --- ## 🐛 Problemas Comuns | Problema | Solução Rápida | |----------|----------------| | Claude não vê servidor | Reinicie Claude Desktop | | Diretório negado | Adicione em .env → ALLOWED_DIRECTORIES | | Erro importação | `pip install -r requirements.txt` | | Servidor não inicia | Veja logs/mcp_server.log | **Troubleshooting completo:** [GUIA_COMPLETO.md](GUIA_COMPLETO.md) --- ## 📈 Roadmap Futuro - [ ] Interface web de administração - [ ] Mais integrações (Gmail, Notion, Slack) - [ ] Sistema de plugins - [ ] Sincronização multi-dispositivo - [ ] Backup automático - [ ] API REST adicional --- ## 🤝 Sobre o Projeto **Versão:** 1.0.0 **Status:** Produção **Licença:** MIT **Desenvolvido com:** Model Context Protocol --- ## 📞 Suporte - 📖 **Documentação:** Arquivos .md no projeto - 📊 **Logs:** `logs/mcp_server.log` - 🐛 **Debug:** `DEBUG=true python main.py` - 🧪 **Teste:** `python test_server.py` --- ## ✅ Checklist de Instalação - [ ] Python 3.9+ instalado - [ ] Executou `python setup.py` - [ ] Arquivo `.env` configurado - [ ] Diretórios permitidos definidos - [ ] `python test_server.py` passou - [ ] Servidor iniciou sem erros - [ ] Claude Desktop reiniciado - [ ] Testou comando no Claude --- ## 🎉 Pronto para Usar! Se você: - ✅ Executou o setup - ✅ Viu o servidor inicializar - ✅ Reiniciou o Claude Desktop - ✅ Conseguiu listar arquivos no Claude **Parabéns! Seu MCP Server está funcionando! 🚀** --- <div align="center"> **📚 Documentação Completa** [Como Usar](COMO_USAR.md) • [README](README.md) • [Guia Completo](GUIA_COMPLETO.md) • [Ref. Rápida](QUICK_REFERENCE.md) • [Testes](TESTES.md) --- **Desenvolvido com ❤️ usando Model Context Protocol** </div>