📋 Todo List MCP Server - Tutorial Completo
🎯 O que é este projeto?
Este é um servidor MCP (Model Context Protocol) completo que implementa um sistema de gerenciamento de tarefas (Todo List) com validação robusta usando TypeScript e Zod. O servidor se integra diretamente com o Claude Desktop, permitindo que você gerencie suas tarefas através de conversas naturais com o Claude.
Tutorial - Passo a Passo!
Quer aprender a desenvolver essa aplicação e aprender também sobre MCP? Está disponível o tutorial passo a passo, para você AQUI
🌟 Por que usar MCP?
O Model Context Protocol é um protocolo desenvolvido pela Anthropic que permite aos assistentes de IA se conectarem com ferramentas e recursos externos de forma padronizada. Com este projeto, você pode:
- 🤖 Conversar naturalmente com Claude sobre suas tarefas
- 🔧 Executar operações diretamente através do chat
- 📊 Obter insights inteligentes sobre sua produtividade
- 🛡️ Garantir validação robusta de todos os dados
✨ Funcionalidades
🛠️ CRUD Completo
- ✅ Criar tarefas com título, descrição, prioridade e tags
- 📖 Listar tarefas com filtros avançados e paginação
- ✏️ Atualizar tarefas (marcar como concluída, alterar prioridade, etc.)
- 🗑️ Deletar tarefas específicas
- 🔍 Buscar tarefas por texto
📊 Recursos Inteligentes
- 📈 Estatísticas em tempo real (total, concluídas, pendentes)
- 📋 Resumos personalizados das tarefas
- 🎯 Ajuda de priorização baseada em IA
- 💡 Insights de produtividade com análises detalhadas
🔒 Validação Robusta
- ✅ Zod schemas para validação em runtime
- 🛡️ Type safety completa (compile-time + runtime)
- 🚨 Mensagens de erro claras e específicas
- 🧹 Sanitização automática de dados
🏷️ Organização Avançada
- 🎯 Prioridades (baixa, média, alta)
- 🏷️ Tags personalizadas para categorização
- 📅 Timestamps automáticos (criação, conclusão)
- 🔄 Estados (pendente, concluída)
🏗️ Arquitetura do Projeto
O projeto segue os princípios SOLID para garantir código limpo, manutenível e escalável:
🏛️ Princípios SOLID Aplicados
1. Single Responsibility Principle (SRP)
Cada classe tem uma única responsabilidade:
- ToolHandlers: Apenas operações de ferramentas (CRUD)
- ResourceHandlers: Apenas recursos de dados (visualização)
- PromptHandlers: Apenas templates de prompt (análise)
- TodoMCPServer: Apenas orquestração e configuração do servidor
2. Open/Closed Principle (OCP)
- Cada handler pode ser estendido sem modificar código existente
- Novos tipos de operações podem ser adicionados facilmente
TOOL_DEFINITIONS
permite adicionar ferramentas sem tocar nos handlers
3. Liskov Substitution Principle (LSP)
- Todos os handlers implementam contratos bem definidos
- Podem ser substituídos por implementações alternativas
- Interface consistente para operações MCP
4. Interface Segregation Principle (ISP)
- Cada handler tem interface específica para sua responsabilidade
- Não há dependências desnecessárias entre componentes
- Separação clara entre tools, resources e prompts
5. Dependency Inversion Principle (DIP)
- Handlers dependem da abstração
TodoService
- Servidor principal injeta dependências nos handlers
- Facilita testes e substituição de implementações
🔄 Fluxo de Dados
🧩 Responsabilidades dos Componentes
TodoMCPServer (Orquestrador)
ToolHandlers (Operações CRUD)
ResourceHandlers (Dados)
PromptHandlers (Templates)
📋 Pré-requisitos
- Node.js 18+ instalado
- Claude Desktop (versão mais recente)
- npm ou yarn
- Editor de código (VS Code recomendado)
🚀 Instalação Passo a Passo
Passo 1: Clonar/Baixar o Projeto
Passo 2: Instalar Dependências
Dependências principais:
@modelcontextprotocol/sdk
- SDK oficial do MCPzod
- Validação de schemastypescript
- Linguagem TypeScripttsx
- Executor TypeScript para desenvolvimento
Passo 3: Compilar o Projeto
Passo 4: Testar o Servidor
Você deve ver:
Pressione Ctrl+C
para parar.
⚙️ Configuração do Claude Desktop
Passo 1: Localizar Arquivo de Configuração
Windows:
macOS:
Linux:
Passo 2: Criar/Editar Configuração
⚠️ IMPORTANTE: Use o caminho absoluto do seu projeto!
Exemplo de configuração:
Passo 3: Reiniciar Claude Desktop
- Feche completamente o Claude Desktop
- Aguarde 5 segundos
- Abra novamente
🎮 Como Usar
1. Comandos Básicos
2. Comandos Avançados
3. Recursos Inteligentes
🔧 Estrutura dos Dados
Modelo de Tarefa
Exemplo de Tarefa
🛠️ Recursos do MCP Implementados
1. Resources (Recursos)
Endpoints read-only para visualizar dados:
URI | Descrição |
---|---|
todo://all | Lista completa de tarefas |
todo://stats | Estatísticas das tarefas |
todo://completed | Apenas tarefas concluídas |
todo://pending | Apenas tarefas pendentes |
2. Tools (Ferramentas)
Operações que modificam dados:
Ferramenta | Descrição |
---|---|
create_todo | Criar nova tarefa |
update_todo | Atualizar tarefa existente |
delete_todo | Deletar tarefa |
list_todos | Listar com filtros e paginação |
get_todo | Buscar tarefa por ID |
search_todos | Busca textual |
3. Prompts (Templates)
Templates contextuais para análise:
Prompt | Descrição |
---|---|
todo_summary | Resumo personalizado |
todo_prioritization | Ajuda de priorização |
productivity_insights | Análise de produtividade |
🔍 Validação com Zod
Por que Zod?
O Zod garante que todos os dados sejam válidos tanto em compile-time quanto em runtime:
Schemas Implementados
📊 Exemplos de Uso Completos
Cenário 1: Gerenciamento de Projeto
Cenário 2: Análise de Produtividade
🔧 Desenvolvimento e Personalização
Benefícios da Arquitetura SOLID
✅ Manutenibilidade: Cada arquivo tem responsabilidade específica
✅ Testabilidade: Handlers podem ser testados independentemente
✅ Escalabilidade: Fácil adicionar novas funcionalidades
✅ Reutilização: Componentes podem ser reutilizados
✅ Debugging: Erros são isolados por responsabilidade
Estrutura para Extensão
1. Adicionando Nova Ferramenta
2. Adicionando Novo Recurso
3. Adicionando Novo Prompt
Comandos de Desenvolvimento
Testando Handlers Individualmente
🐛 Troubleshooting
Problema 1: "Server disconnected"
Causa: Erro no código TypeScript ou dependências faltando.
Solução:
Problema 2: "Cannot find module"
Causa: Caminho incorreto na configuração do Claude Desktop.
Solução:
Problema 3: Claude não reconhece ferramentas
Causa: Servidor não carregou ou configuração inválida.
Solução:
Problema 4: Erro de validação Zod
Causa: Dados inválidos sendo enviados.
Solução:
📚 Conceitos Aprendidos
1. MCP Protocol
- Resources: Dados read-only acessíveis via URIs
- Tools: Operações que modificam estado
- Prompts: Templates para interação contextual
- Comunicação: JSON-RPC via stdio transport
2. TypeScript + Zod
- Type Safety: Detecção de erros em compile-time
- Runtime Validation: Verificação em tempo de execução
- Schema-First: Definir estrutura antes da implementação
- Type Inference: Tipos automáticos a partir de schemas
3. Arquitetura Modular
- Separation of Concerns: Cada arquivo tem responsabilidade específica
- Dependency Injection: Serviços independentes e testáveis
- Error Handling: Tratamento consistente de erros
- Validation Layer: Camada de validação centralizada
🚀 Próximos Passos
1. Funcionalidades Avançadas
- 💾 Persistência: Adicionar SQLite ou PostgreSQL
- 👥 Multi-usuário: Sistema de autenticação
- 📅 Calendário: Integração com datas e prazos
- 🔔 Notificações: Lembretes automáticos
2. Integração
- 📧 Email: Criar tarefas via email
- 📱 Mobile: API REST para aplicativo móvel
- 🌐 Web: Interface web administrativa
- 📊 Analytics: Dashboards de produtividade
3. Qualidade
- 🧪 Testes: Unitários e de integração
- 📖 Documentação: API docs automática
- 🚀 Deploy: Docker e cloud deployment
- 📈 Monitoring: Logs e métricas
📄 Licença
MIT License - veja o arquivo LICENSE para detalhes.
🤝 Contribuição
- Fork o projeto
- Crie uma branch para sua feature (
git checkout -b feature/AmazingFeature
) - Commit suas mudanças (
git commit -m 'Add some AmazingFeature'
) - Push para a branch (
git push origin feature/AmazingFeature
) - Abra um Pull Request
📞 Suporte
- 🐛 Issues: GitHub Issues
- 📖 Documentação MCP: modelcontextprotocol.io
- 💬 Discussões: GitHub Discussions
Desenvolvido com ❤️ usando TypeScript, Zod e MCP Protocol
Este projeto demonstra como criar servidores MCP robustos e type-safe para integração com assistentes de IA.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A TypeScript-based MCP server that enables users to manage tasks through natural conversation with Claude. Features complete CRUD operations, priority management, tagging, search functionality, and intelligent productivity insights with robust Zod validation.
- 🎯 O que é este projeto?
- ✨ Funcionalidades
- 🏗️ Arquitetura do Projeto
- 📋 Pré-requisitos
- 🚀 Instalação Passo a Passo
- ⚙️ Configuração do Claude Desktop
- 🎮 Como Usar
- 🔧 Estrutura dos Dados
- 🛠️ Recursos do MCP Implementados
- 🔍 Validação com Zod
- 📊 Exemplos de Uso Completos
- 🔧 Desenvolvimento e Personalização
- 🐛 Troubleshooting
- 📚 Conceitos Aprendidos
- 🚀 Próximos Passos
- 📄 Licença
- 🤝 Contribuição
- 📞 Suporte
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server that integrates Claude with Todoist, enabling natural language task management including creating, updating, completing, and deleting tasks.Last updated -51,112292JavaScriptMIT License
- AsecurityFlicenseAqualityA TypeScript-based MCP server that implements a simple notes system, allowing users to create, access, and generate summaries of text notes through Claude Desktop.Last updated -15511JavaScript
- AsecurityAlicenseAqualityAn MCP server that connects Claude with Todoist for complete task and project management through natural language.Last updated -2859027TypeScriptMIT License
- -securityFlicense-qualityAn OAuth-authenticated MCP server that bridges Claude AI with a task management system, allowing users to list, create, and update tasks through natural language commands.Last updated -TypeScript