todo-list-mcp-server by glaucia86 - 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<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

Feche completamente o Claude Desktop
Aguarde 5 segundos
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<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 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.