How do I use Todo List MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Todo List MCP Server add a high priority task to finish the quarterly report by Friday" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Todo List MCP Server

by glaucia86

Overview Schema Related Servers Score Discussions

TypeScript

Local

📋 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

Related MCP server: Browser-use MCP Server

✨ 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 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.

Available Tools

6 tools

create_todoC

Create a new todo item with validation

ParametersJSON Schema

Name	Required	Description	Default
`title`	Yes	Title of the todo (1-200 characters)
`description`	No	Optional description (max 1000 characters)
`priority`	No	Priority level	medium
`tags`	No	Tags for categorization

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'validation' but doesn't specify what validation entails (e.g., format checks, uniqueness, permissions). For a creation tool with mutation implications, this lack of detail about behavior, error handling, or side effects is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function. It's front-loaded with the core purpose and avoids unnecessary words, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with no annotations and no output schema, the description is incomplete. It lacks details on what happens after creation (e.g., returns an ID, error responses), validation specifics, and how it fits with sibling tools, leaving critical context gaps for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, providing detailed documentation for all parameters. The description adds no additional parameter semantics beyond what's in the schema, so it meets the baseline but doesn't enhance understanding of the inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Create a new todo item') and resource ('todo item'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'update_todo' or specify what kind of validation occurs, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'update_todo' or 'list_todos'. There's no mention of prerequisites, context for creation, or comparison with sibling tools, leaving usage decisions ambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_todoC

Delete a todo item

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	UUID of the todo to delete

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Delete' implies a destructive mutation, it doesn't specify whether deletion is permanent or reversible, what permissions are required, whether it affects related data, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves critical behavioral traits undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and appropriately sized for the tool's simple function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation tool with no annotations and no output schema, the description is insufficiently complete. It lacks critical context about behavioral consequences, error handling, return values, and differentiation from sibling tools, leaving significant gaps for an agent to safely and correctly invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with the single parameter 'id' documented as 'UUID of the todo to delete'. The description adds no additional parameter semantics beyond what the schema already provides, so it meets the baseline for adequate but unenriched parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Delete') and target resource ('a todo item'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'update_todo' which could also modify or remove todos, nor does it specify whether this is a soft or hard deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With siblings like 'update_todo' that might handle status changes to 'completed' instead of deletion, and 'get_todo'/'list_todos' for verification, there's no indication of appropriate contexts, prerequisites, or exclusions for this destructive operation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_todoC

Get a specific todo by ID

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	UUID of the todo to retrieve

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits such as error handling (e.g., what happens if the ID is invalid), performance aspects (e.g., speed, rate limits), or response format. This leaves gaps for an AI agent to understand operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste. It's front-loaded and directly states the tool's purpose without unnecessary words, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is minimal but incomplete. It lacks context on usage scenarios, error cases, or output expectations, which could hinder an AI agent's ability to invoke it correctly without additional inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the parameter 'id' fully documented as a UUID. The description adds minimal value beyond the schema by implying the parameter is for retrieval, but doesn't provide additional context like format examples or constraints. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('a specific todo by ID'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_todos' or 'search_todos' beyond the 'by ID' specification, which is implied but not contrasted directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid todo ID), exclusions, or compare it to siblings like 'list_todos' for multiple todos or 'search_todos' for queries. The description assumes context without stating it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_todosC

List todos with filtering and pagination

ParametersJSON Schema

Name	Required	Description	Default
`status`	No	Filter by completion status	all
`priority`	No	Filter by priority
`tags`	No	Filter by tags (OR logic)
`limit`	No	Maximum number of results
`offset`	No	Number of results to skip

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While 'List todos' implies a read operation, the description doesn't address important behavioral aspects like whether this requires authentication, rate limits, what format the results come in, or how pagination works beyond mentioning it exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at just 6 words, front-loading the core purpose ('List todos') and efficiently mentioning key capabilities ('with filtering and pagination'). Every word earns its place with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 5 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tool returns, how results are structured, or provide context about the filtering logic beyond what's in the schema. The agent would need to guess about the output format and behavioral characteristics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond confirming filtering and pagination capabilities, which the schema already details through parameter descriptions and enums. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List todos') and mentions key capabilities ('with filtering and pagination'), which provides a specific verb+resource combination. However, it doesn't explicitly distinguish this tool from its sibling 'search_todos', which appears to be a similar listing/search tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'search_todos' or 'get_todo'. It mentions filtering capabilities but doesn't specify when this filtering approach is preferred over other tools in the server.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_todosC

Search todos by title or description

ParametersJSON Schema

Name	Required	Description	Default
`searchTerm`	Yes	Search term for title or description
`status`	No	Filter by status	all
`priority`	No	Filter by priority

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It doesn't describe whether this is a read-only operation, how results are returned (format, pagination), performance characteristics, or error conditions. The description only states what the tool does at a high level without operational details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at just 5 words with zero wasted language. It's front-loaded with the core functionality and uses efficient phrasing. Every word serves a purpose in conveying the tool's basic function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with 3 parameters and no output schema, the description is inadequate. It doesn't explain what constitutes a match (exact, partial, case-sensitive), how multiple parameters interact, what the return format looks like, or any limitations. The description provides only the most basic functional statement without necessary operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions searching by title or description, which aligns with the 'searchTerm' parameter but doesn't add meaningful context beyond what the schema already provides. With 100% schema description coverage that includes clear parameter descriptions and enum values, the description adds minimal value. The baseline of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as searching todos by title or description, which is a specific verb+resource combination. However, it doesn't distinguish this tool from the sibling 'list_todos' tool, which might offer different filtering capabilities or scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'list_todos' or 'get_todo'. There's no mention of prerequisites, performance considerations, or appropriate contexts for choosing this search functionality over other todo-related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_todoC

Update an existing todo item

ParametersJSON Schema

Name	Required	Description
`id`	Yes	UUID of the todo to update
`title`	No	New title
`description`	No	New description
`completed`	No	Mark as completed or not
`priority`	No	New priority level
`tags`	No	New tags

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. 'Update an existing todo item' implies a mutation operation but reveals nothing about permissions, side effects, error handling, or response format. It doesn't indicate whether all fields are optional (beyond required 'id'), if updates are atomic, or what happens with invalid data. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable. Every word earns its place by establishing the tool's fundamental purpose without unnecessary elaboration or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (mutation with 6 parameters), lack of annotations, and absence of an output schema, the description is insufficiently complete. It doesn't address behavioral aspects like error conditions, idempotency, or response structure, nor does it clarify parameter interactions (e.g., partial updates). For a mutation tool in this context, more comprehensive guidance is needed to support reliable agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter well-documented in the schema (e.g., 'id' as UUID, 'priority' with enum values). The description adds no parameter-specific information beyond the generic 'update' context, so it doesn't enhance understanding of individual parameters. This meets the baseline of 3 for high schema coverage, but doesn't compensate with additional semantic context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update') and resource ('an existing todo item'), making the purpose immediately understandable. It distinguishes from siblings like 'create_todo' (new items) and 'delete_todo' (removal), though it doesn't explicitly differentiate from other update-like operations since none exist in the sibling list. The verb+resource combination is specific but lacks nuance about what aspects can be updated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing todo ID), contrast with 'create_todo' for new items, or specify scenarios where partial updates are allowed. With siblings like 'get_todo' and 'list_todos' available, the absence of usage context leaves the agent to infer appropriate application.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

6 tool updatesAug 15, 2025
- First observedcreate_todo
- First observeddelete_todo
- First observedget_todo
- First observedlist_todos
- First observedsearch_todos
- First observedupdate_todo

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose with no ambiguity. The tools cover specific operations: create, delete, get, list, search, and update, with no overlap in functionality. The descriptions reinforce distinct roles, such as 'list_todos' for filtering/pagination versus 'search_todos' for title/description searches.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with 'todo' as the noun, using snake_case uniformly (e.g., create_todo, delete_todo). There are no deviations in naming conventions, making the set predictable and easy to understand at a glance.

Tool Count5/5

With 6 tools, the count is well-scoped for a todo list server, covering essential CRUD operations and additional utilities like search. Each tool earns its place without redundancy, fitting a typical range of 3-15 tools for such a domain.

Completeness5/5

The tool surface provides complete CRUD/lifecycle coverage for todo items, including create, read (get/list/search), update, and delete. There are no obvious gaps; agents can perform all core operations without dead ends, ensuring smooth workflows.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Remote Desktop CommanderOAuth
app.desktopcommander
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Shell Access OS Automation
214
mcpOAuth
net.todoist
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
App Automation Workplace & Productivity Project Management
2
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
DuckHub QR Menu AOAuth
com.duck-hub
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
E-commerce & Retail Content Management Systems
3

Related MCP Servers

Scrapbox MCP Server
Note Taking Text Summarization
YuheiNakasaka
F
license
B
quality
D
maintenance
A simple TypeScript-based MCP server that implements a notes system, allowing users to create, list, and generate summaries of text notes via Claude.
Updated 2 years ago (2025-03-06 00:17 UTC)
1
3
-
Browser-use MCP Server
Note Taking Text Summarization Knowledge & Memory
win4r
A
license
C
quality
F
maintenance
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.
Updated a year ago (2025-03-17 00:39 UTC)
1
1,941
1
MIT
Image Processor MCP Server
Note Taking Text Summarization
sanliunanjue
A
license
B
quality
D
maintenance
A TypeScript-based MCP server that implements a simple notes system, allowing users to create, access, and generate summaries of notes via Claude Desktop integration.
Updated a year ago (2025-05-15 09:29 UTC)
2
4
ISC
Procrastinator MCP Server
Project Management Workplace & Productivity Communication
mateusjunges
F
license
Not graded
quality
D
maintenance
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.
Updated a year ago (2025-06-25 00:45 UTC)
1
-

Appeared in Searches

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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