Skip to main content
Glama

Todo List MCP Server

by glaucia86

📋 Todo List MCP Server - Tutorial Completo

TypeScript Node.js Zod MCP

🎯 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:

src/ ├── config/ # ⚙️ Configurações │ └── toolDefinitions.ts # 📋 Definições centralizadas das ferramentas MCP ├── handlers/ # 🎯 Handlers especializados (SOLID) │ ├── toolHandlers.ts # 🔧 Gerencia operações de ferramentas │ ├── resourceHandlers.ts # 📊 Gerencia recursos de dados │ └── promptHandlers.ts # 💡 Gerencia templates de prompt ├── schemas/ # 📋 Validações Zod │ ├── common.schemas.ts # Schemas base (UUID, Date, etc.) │ └── todo.schemas.ts # Schemas específicos de tarefas ├── services/ # 🔧 Lógica de negócio │ └── todo.services.ts # Gerenciamento das tarefas ├── utils/ # 🛠️ Utilitários │ └── validation.ts # Helpers de validação ├── types.ts # 📝 Tipos TypeScript ├── server.ts # 🖥️ Servidor MCP principal (orquestração) └── index.ts # 🚀 Ponto de entrada

🏛️ 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)
class TodoMCPServer { private toolHandlers: ToolHandlers; // Delega operações CRUD private resourceHandlers: ResourceHandlers; // Delega recursos private promptHandlers: PromptHandlers; // Delega prompts // Apenas configura e roteia requisições setupHandlers(): void { this.server.setRequestHandler(CallToolRequestSchema, (req) => this.toolHandlers.handleCallTool(req)); // ... } }
ToolHandlers (Operações CRUD)
class ToolHandlers { handleCallTool(request): Promise<CallToolResult> { switch (name) { case "create_todo": return this.handleCreateTodo(request); case "update_todo": return this.handleUpdateTodo(request); case "delete_todo": return this.handleDeleteTodo(request); // ... } } }
ResourceHandlers (Dados)
class ResourceHandlers { handleReadResource(request): Promise<ReadResourceResult> { switch (uri) { case "todo://all": return this.handleAllTodos(uri); case "todo://stats": return this.handleTodoStats(uri); // ... } } }
PromptHandlers (Templates)
class PromptHandlers { handleGetPrompt(request): Promise<GetPromptResult> { switch (name) { case "todo-summary": return this.handleTodoSummary(args); case "todo-prioritization": return this.handleTodoPrioritization(args); // ... } } }

📋 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

# Se usando Git git clone <seu-repositorio> cd todo-list-mcp-server # Ou criar nova pasta mkdir todo-list-mcp-server cd todo-list-mcp-server

Passo 2: Instalar Dependências

# Instalar todas as dependências npm install # Verificar se instalou corretamente npm list --depth=0

Dependências principais:

  • @modelcontextprotocol/sdk - SDK oficial do MCP
  • zod - Validação de schemas
  • typescript - Linguagem TypeScript
  • tsx - Executor TypeScript para desenvolvimento

Passo 3: Compilar o Projeto

# Compilar TypeScript para JavaScript npm run build # Verificar se compilou corretamente ls dist/

Passo 4: Testar o Servidor

# Testar se o servidor inicia corretamente npm start

Você deve ver:

🔧 Inicializando MCP Todo Server com Zod... 🚀 MCP Todo Server com Zod iniciado ✅ Validação robusta ativada 🔒 Type safety garantida

Pressione Ctrl+C para parar.

⚙️ Configuração do Claude Desktop

Passo 1: Localizar Arquivo de Configuração

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Passo 2: Criar/Editar Configuração

⚠️ IMPORTANTE: Use o caminho absoluto do seu projeto!

# Descobrir o caminho absoluto # Windows: echo %cd% # macOS/Linux: pwd

Exemplo de configuração:

{ "mcpServers": { "todo-server": { "command": "node", "args": ["C:/Users/SeuUsuario/caminho/para/todo-list-mcp-server/dist/index.js"] } } }

Passo 3: Reiniciar Claude Desktop

  1. Feche completamente o Claude Desktop
  2. Aguarde 5 segundos
  3. Abra novamente

🎮 Como Usar

1. Comandos Básicos

# Listar todas as tarefas "Liste todas as minhas tarefas" # Criar nova tarefa "Crie uma tarefa: 'Estudar TypeScript' com prioridade alta" # Buscar tarefas "Procure por tarefas que contenham 'estudo'" # Marcar como concluída "Marque a tarefa com ID [uuid] como concluída"

2. Comandos Avançados

# Criar tarefa completa "Crie uma tarefa: 'Implementar autenticação' com descrição 'Adicionar login OAuth', prioridade alta e tags 'backend', 'segurança'" # Filtrar por status "Mostre apenas as tarefas pendentes" # Filtrar por prioridade "Liste todas as tarefas de prioridade alta" # Obter estatísticas "Mostre as estatísticas das minhas tarefas"

3. Recursos Inteligentes

# Resumo personalizado "Gere um resumo das minhas tarefas agrupadas por prioridade" # Ajuda de priorização "Me ajude a priorizar minhas tarefas pendentes" # Insights de produtividade "Analise minha produtividade e dê sugestões"

🔧 Estrutura dos Dados

Modelo de Tarefa

interface Todo { id: string; // UUID único title: string; // Título (1-200 caracteres) description?: string; // Descrição opcional (max 500 chars) completed: boolean; // Status de conclusão createdAt: Date; // Data de criação completedAt?: Date; // Data de conclusão (se aplicável) priority: 'low' | 'medium' | 'high'; // Prioridade tags: string[]; // Tags para organização (max 10) }

Exemplo de Tarefa

{ "id": "550e8400-e29b-41d4-a716-446655440000", "title": "Estudar MCP Protocol", "description": "Aprender sobre Model Context Protocol com TypeScript e Zod", "completed": false, "createdAt": "2024-01-15T10:30:00.000Z", "priority": "high", "tags": ["estudo", "typescript", "mcp"] }

🛠️ Recursos do MCP Implementados

1. Resources (Recursos)

Endpoints read-only para visualizar dados:

URIDescrição
todo://allLista completa de tarefas
todo://statsEstatísticas das tarefas
todo://completedApenas tarefas concluídas
todo://pendingApenas tarefas pendentes

2. Tools (Ferramentas)

Operações que modificam dados:

FerramentaDescrição
create_todoCriar nova tarefa
update_todoAtualizar tarefa existente
delete_todoDeletar tarefa
list_todosListar com filtros e paginação
get_todoBuscar tarefa por ID
search_todosBusca textual

3. Prompts (Templates)

Templates contextuais para análise:

PromptDescrição
todo_summaryResumo personalizado
todo_prioritizationAjuda de priorização
productivity_insightsAná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:

// ❌ SEM Zod - Perigoso function createTodo(data: any) { return { title: data.title, // Pode ser undefined, null, ou vazio! priority: data.priority, // Pode ser qualquer string! }; } // ✅ COM Zod - Seguro function createTodo(data: unknown) { const validatedData = validateData(CreateTodoSchema, data); return { title: validatedData.title, // ✅ String válida (1-200 chars) priority: validatedData.priority, // ✅ 'low' | 'medium' | 'high' }; }

Schemas Implementados

// Schema base de tarefa export const TodoSchema = z.object({ id: UuidSchema, title: NonEmptyStringSchema.max(200), description: z.string().max(500).optional(), completed: z.boolean().default(false), createdAt: DateSchema, completedAt: DateSchema.optional(), priority: z.enum(['low', 'medium', 'high']).default('medium'), tags: z.array(z.string().min(1).max(50)).max(10).default([]) }); // Schema para criar tarefa export const CreateTodoSchema = z.object({ title: NonEmptyStringSchema.max(200), description: z.string().max(500).optional(), priority: z.enum(['low', 'medium', 'high']).default('medium'), tags: z.array(z.string().min(1).max(50)).max(10).default([]) });

📊 Exemplos de Uso Completos

Cenário 1: Gerenciamento de Projeto

Usuário: "Crie as seguintes tarefas para meu projeto: 1. 'Setup inicial do projeto' - prioridade alta 2. 'Implementar autenticação' - prioridade média 3. 'Escrever testes' - prioridade baixa" Claude: [Cria as 3 tarefas usando a ferramenta create_todo] Usuário: "Me ajude a priorizar essas tarefas" Claude: [Usa o prompt todo_prioritization para análise] Usuário: "Marque a primeira tarefa como concluída" Claude: [Usa update_todo para marcar como completed: true]

Cenário 2: Análise de Produtividade

Usuário: "Gere um relatório da minha produtividade" Claude: [Usa productivity_insights para análise completa] - Taxa de conclusão: 75% - Tarefas de alta prioridade: 80% concluídas - Tags mais utilizadas: frontend (60%), backend (40%) - Sugestões de melhoria... Usuário: "Mostre apenas tarefas pendentes de alta prioridade" Claude: [Usa list_todos com filtros status=pending, priority=high]

🔧 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
// 1. Definir em config/toolDefinitions.ts { name: "set_deadline", description: "Definir prazo para tarefa", inputSchema: { type: "object", properties: { id: { type: "string", format: "uuid" }, deadline: { type: "string", format: "date" } }, required: ["id", "deadline"] } } // 2. Implementar em handlers/toolHandlers.ts private async handleSetDeadline(request: CallToolRequest): Promise<CallToolResult> { const { args } = request.params; const validatedData = validateData(SetDeadlineSchema, args); // Implementar lógica... } // 3. Adicionar no switch do handleCallTool case "set_deadline": return this.handleSetDeadline(request);
2. Adicionando Novo Recurso
// 1. Adicionar definição em resourceHandlers.ts { uri: "todo://overdue", mimeType: "application/json", name: "Overdue Todos", description: "Tasks past their deadline" } // 2. Implementar handler case "todo://overdue": const overdueTodos = this.todoService.getOverdueTodos(); return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(overdueTodos, null, 2) }] };
3. Adicionando Novo Prompt
// 1. Definir em promptHandlers.ts { name: "deadline-analysis", description: "Analisa prazos das tarefas", arguments: [ { name: "timeframe", description: "Período de análise", required: false } ] } // 2. Implementar handler case "deadline-analysis": const analysis = this.generateDeadlineAnalysis(args); return { messages: [{ role: "user", content: { type: "text", text: analysis }}] };

Comandos de Desenvolvimento

# Desenvolvimento com hot-reload npm run dev # Compilar apenas npm run build # Validar TypeScript sem compilar npm run validate # Testar servidor npm start # Executar testes unitários (quando implementados) npm test

Testando Handlers Individualmente

// Exemplo de teste para ToolHandlers import { ToolHandlers } from '../src/handlers/toolHandlers'; import { TodoService } from '../src/services/todo.services'; describe('ToolHandlers', () => { let toolHandlers: ToolHandlers; let todoService: TodoService; beforeEach(() => { todoService = new TodoService(); toolHandlers = new ToolHandlers(todoService); }); test('should create todo successfully', async () => { const request = { params: { name: 'create_todo', arguments: { title: 'Test Todo', priority: 'high' } } }; const result = await toolHandlers.handleCallTool(request); expect(result.content[0].text).toContain('Todo criado com sucesso'); }); });

🐛 Troubleshooting

Problema 1: "Server disconnected"

Causa: Erro no código TypeScript ou dependências faltando.

Solução:

# 1. Verificar se compila npm run build # 2. Testar manualmente npm start # 3. Verificar logs # Windows: %APPDATA%\Claude\logs\ # macOS: ~/Library/Logs/Claude/

Problema 2: "Cannot find module"

Causa: Caminho incorreto na configuração do Claude Desktop.

Solução:

# 1. Verificar caminho absoluto pwd # macOS/Linux echo %cd% # Windows # 2. Usar caminho completo na configuração { "mcpServers": { "todo-server": { "command": "node", "args": ["/caminho/absoluto/completo/dist/index.js"] } } }

Problema 3: Claude não reconhece ferramentas

Causa: Servidor não carregou ou configuração inválida.

Solução:

# 1. Verificar sintaxe JSON # Use um validador JSON online # 2. Reiniciar Claude Desktop completamente # Fechar > Aguardar > Abrir # 3. Testar comando específico "Use a ferramenta list_todos"

Problema 4: Erro de validação Zod

Causa: Dados inválidos sendo enviados.

Solução:

// Verificar schema correspondente console.log(CreateTodoSchema.parse(data)); // Adicionar logs para debug console.error('Dados recebidos:', JSON.stringify(data, null, 2));

📚 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

  1. Fork o projeto
  2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
  3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
  4. Push para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

📞 Suporte


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.

-
security - not tested
A
license - permissive license
-
quality - not tested

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.

  1. 🎯 O que é este projeto?
    1. Tutorial - Passo a Passo!
    2. 🌟 Por que usar MCP?
  2. ✨ Funcionalidades
    1. 🛠️ CRUD Completo
    2. 📊 Recursos Inteligentes
    3. 🔒 Validação Robusta
    4. 🏷️ Organização Avançada
  3. 🏗️ Arquitetura do Projeto
    1. 🏛️ Princípios SOLID Aplicados
    2. 🔄 Fluxo de Dados
    3. 🧩 Responsabilidades dos Componentes
  4. 📋 Pré-requisitos
    1. 🚀 Instalação Passo a Passo
      1. Passo 1: Clonar/Baixar o Projeto
      2. Passo 2: Instalar Dependências
      3. Passo 3: Compilar o Projeto
      4. Passo 4: Testar o Servidor
    2. ⚙️ Configuração do Claude Desktop
      1. Passo 1: Localizar Arquivo de Configuração
      2. Passo 2: Criar/Editar Configuração
      3. Passo 3: Reiniciar Claude Desktop
    3. 🎮 Como Usar
      1. 1\. Comandos Básicos
      2. 2\. Comandos Avançados
      3. 3\. Recursos Inteligentes
    4. 🔧 Estrutura dos Dados
      1. Modelo de Tarefa
      2. Exemplo de Tarefa
    5. 🛠️ Recursos do MCP Implementados
      1. 1\. Resources (Recursos)
      2. 2\. Tools (Ferramentas)
      3. 3\. Prompts (Templates)
    6. 🔍 Validação com Zod
      1. Por que Zod?
      2. Schemas Implementados
    7. 📊 Exemplos de Uso Completos
      1. Cenário 1: Gerenciamento de Projeto
      2. Cenário 2: Análise de Produtividade
    8. 🔧 Desenvolvimento e Personalização
      1. Benefícios da Arquitetura SOLID
      2. Estrutura para Extensão
      3. Comandos de Desenvolvimento
      4. Testando Handlers Individualmente
    9. 🐛 Troubleshooting
      1. Problema 1: "Server disconnected"
      2. Problema 2: "Cannot find module"
      3. Problema 3: Claude não reconhece ferramentas
      4. Problema 4: Erro de validação Zod
    10. 📚 Conceitos Aprendidos
      1. 1\. MCP Protocol
      2. 2\. TypeScript + Zod
      3. 3\. Arquitetura Modular
    11. 🚀 Próximos Passos
      1. 1\. Funcionalidades Avançadas
      2. 2\. Integração
      3. 3\. Qualidade
    12. 📄 Licença
      1. 🤝 Contribuição
        1. 📞 Suporte

          Related MCP Servers

          • A
            security
            A
            license
            A
            quality
            An MCP server that integrates Claude with Todoist, enabling natural language task management including creating, updating, completing, and deleting tasks.
            Last updated -
            5
            1,112
            292
            JavaScript
            MIT License
          • A
            security
            F
            license
            A
            quality
            A 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 -
            1
            551
            1
            JavaScript
            • Apple
          • A
            security
            A
            license
            A
            quality
            An MCP server that connects Claude with Todoist for complete task and project management through natural language.
            Last updated -
            28
            590
            27
            TypeScript
            MIT License
            • Apple
            • Linux
          • -
            security
            F
            license
            -
            quality
            An 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

          View all related MCP servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/glaucia86/todo-list-mcp-server'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server