Todo List Mcp Server

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

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

graph TB
    A[Claude Desktop] --> B[TodoMCPServer]
    B --> C{Request Type}
    
    C -->|Tools| D[ToolHandlers]
    C -->|Resources| E[ResourceHandlers]  
    C -->|Prompts| F[PromptHandlers]
    
    D --> G[Validation Layer - Zod]
    E --> G
    F --> G
    
    G --> H[TodoService]
    H --> I[In-Memory Storage]
    
    I --> H
    H --> G
    G --> D
    G --> E
    G --> F
    
    D --> B
    E --> B
    F --> B
    B --> A
    
    style B fill:#e1f5fe
    style D fill:#f3e5f5
    style E fill:#e8f5e8
    style F fill:#fff3e0
    style H fill:#fce4ec

🧩 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 {
    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 {
    switch (uri) {
      case "todo://all": return this.handleAllTodos(uri);
      case "todo://stats": return this.handleTodoStats(uri);
      // ...
    }
  }
}

PromptHandlers (Templates)

class PromptHandlers {
  handleGetPrompt(request): Promise {
    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 
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:

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

// ❌ 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 {
  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 comp

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [glaucia86](https://github.com/glaucia86)
- **Source:** [glaucia86/todo-list-mcp-server](https://github.com/glaucia86/todo-list-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.