MCP Server - Google Sheets Kanban

Servidor MCP (Model Context Protocol) para gerenciamento de tarefas em um quadro Kanban utilizando Google Sheets como backend.

Características

• Integração com Google Sheets: Usa Google Sheets API v4 para armazenamento de dados
• Modelos Pydantic: Validação de dados com Pydantic v2
• Operações em Lote: Suporte para adicionar e atualizar múltiplas tarefas de uma vez
• Busca Avançada: Filtros por prioridade, status, contexto, projeto e texto
• Paginação: Suporte completo para navegação paginada de resultados
• Protocolo MCP: Compatível com clientes MCP via STDIO

Configuração

Claude

Executar o seguinte comando na pasta do projeto:

claude mcp add --transport stdio kanban-sheets -- uv run -- --directory "caminho\projeto\sua\maquina" python main.py

Ferramentas Disponíveis

1. get_one_task - Buscar Tarefa Específica

Busca uma tarefa específica pelo ID da tarefa e nome do projeto.

Parâmetros:

• project (obrigatório): Nome do projeto
• task_id (obrigatório): ID único da tarefa

Exemplo:

{
  "project": "MCP Server Sheets",
  "task_id": "TASK-001"
}

Retorno (sucesso):

{
  "Projeto": "MCP Server Sheets",
  "Task ID": "TASK-001",
  "Task ID Root": "TASK-001",
  "Sprint": "Sprint 1",
  "Contexto": "Backend",
  "Descrição": "Implementar busca avançada",
  "Detalhado": "Adicionar filtros por prioridade, status e contexto",
  "Prioridade": "Alta",
  "Status": "Em Desenvolvimento",
  "Data Criação": "2025-10-24 10:30:00",
  "Data Solução": ""
}

Retorno (não encontrada):

{
  "error": "Tarefa 'TASK-999' não encontrada no projeto 'MCP Server'"
}

---

2. list_tasks - Listar e Buscar Tarefas

Lista e busca tarefas da planilha com filtros avançados e paginação opcional.

Parâmetros:

• filters (opcional): Objeto com critérios de busca
  • prioridade: Lista de prioridades (Baixa, Normal, Alta, Urgente)
  • status: Lista de status para filtrar
  • contexto: Filtro por contexto (busca parcial, case-insensitive)
  • projeto: Filtro por projeto (busca parcial, case-insensitive)
  • texto_busca: Busca em Descrição e Detalhado (case-insensitive)
  • task_id: Busca por Task ID específico
  • sprint: Filtro por Sprint
• pagination (opcional): Objeto com page (número da página) e page_size (itens por página)

Exemplos:

// 1. Listar todas as tarefas (comportamento legado)
{}

// 2. Com paginação
{
  "pagination": {
    "page": 1,
    "page_size": 20
  }
}

// 3. Buscar tarefas de alta prioridade
{
  "filters": {
    "prioridade": ["Alta", "Urgente"]
  }
}

// 4. Buscar tarefas em desenvolvimento com paginação
{
  "filters": {
    "status": ["Em Desenvolvimento"]
  },
  "pagination": {
    "page": 1,
    "page_size": 10
  }
}

// 5. Buscar por texto na descrição
{
  "filters": {
    "texto_busca": "implementar API"
  }
}

// 6. Combinar múltiplos filtros
{
  "filters": {
    "prioridade": ["Alta"],
    "status": ["Todo", "Em Desenvolvimento"],
    "contexto": "Backend",
    "projeto": "MCP Server"
  },
  "pagination": {
    "page": 1,
    "page_size": 25
  }
}

Retorno (sem paginação):

[
  {
    "Task ID": "TASK-001",
    "Contexto": "Backend",
    "Descrição": "...",
    ...
  },
  ...
]

Retorno (com paginação):

{
  "tasks": [...],
  "total_count": 45,
  "page": 1,
  "page_size": 25,
  "total_pages": 2,
  "has_next": true,
  "has_previous": false
}

---

3. add_task - Adicionar Tarefa

Adiciona uma nova tarefa na planilha.

Parâmetros:

• task: Objeto Task com todos os campos

Exemplo:

{
  "task": {
    "project": "MCP Server Sheets",
    "task_id": "TASK-001",
    "contexto": "Backend",
    "descricao": "Implementar busca avançada",
    "prioridade": "Alta",
    "status": "Todo",
    "task_id_root": "",
    "sprint": "Sprint 1",
    "detalhado": "Adicionar filtros por prioridade, status e contexto",
    "data_criacao": "2025-10-24",
    "data_solucao": ""
  }
}

---

4. update_task - Atualizar Tarefa

Atualiza uma tarefa existente pelo Task ID.

Parâmetros:

• task_id: ID da tarefa a ser atualizada
• updates: Dicionário com campos a atualizar

Exemplo:

{
  "task_id": "TASK-001",
  "updates": {
    "Status": "Concluído",
    "Data Solução": "2025-10-24"
  }
}

---

5. batch_add_tasks - Adicionar Múltiplas Tarefas

Adiciona múltiplas tarefas em uma única operação.

Parâmetros:

• batch: Objeto BatchTaskAdd contendo lista de tarefas

Exemplo:

{
  "batch": {
    "tasks": [
      {
        "project": "MCP Server",
        "task_id": "TASK-001",
        "contexto": "Backend",
        "descricao": "Tarefa 1",
        "prioridade": "Alta",
        "status": "Todo"
      },
      {
        "project": "MCP Server",
        "task_id": "TASK-002",
        "contexto": "Frontend",
        "descricao": "Tarefa 2",
        "prioridade": "Normal",
        "status": "Todo"
      }
    ]
  }
}

Retorno:

{
  "success_count": 2,
  "error_count": 0,
  "details": [
    {
      "task_id": "TASK-001",
      "status": "success",
      "message": "Tarefa adicionada com sucesso"
    },
    {
      "task_id": "TASK-002",
      "status": "success",
      "message": "Tarefa adicionada com sucesso"
    }
  ]
}

---

6. batch_update_tasks - Atualizar Múltiplas Tarefas

Atualiza múltiplas tarefas em uma única operação.

Parâmetros:

• batch: Objeto BatchTaskUpdate contendo lista de atualizações

Exemplo:

{
  "batch": {
    "updates": [
      {
        "task_id": "TASK-001",
        "fields": {"Status": "Concluído"}
      },
      {
        "task_id": "TASK-002",
        "fields": {"Prioridade": "Alta"}
      }
    ]
  }
}

Retorno:

{
  "success_count": 2,
  "error_count": 0,
  "details": [
    {
      "task_id": "TASK-001",
      "status": "success",
      "message": "Tarefa atualizada com sucesso"
    },
    {
      "task_id": "TASK-002",
      "status": "success",
      "message": "Tarefa atualizada com sucesso"
    }
  ]
}

---

7. get_valid_configs - Obter Configurações Válidas

Retorna os valores válidos para Status e Prioridade.

Retorno:

{
  "valid_task_status": [
    "Todo",
    "Em Desenvolvimento",
    "Impedido",
    "Concluído",
    "Cancelado",
    "Não Relacionado",
    "Pausado"
  ],
  "valid_task_priorities": [
    "Baixa",
    "Normal",
    "Alta",
    "Urgente"
  ]
}

---

Modelos de Dados

Task

{
  "project": str,          # Nome do Projeto (obrigatório)
  "task_id": str,          # ID único da tarefa (obrigatório)
  "contexto": str,         # Contexto da tarefa (obrigatório)
  "descricao": str,        # Descrição breve (obrigatório)
  "prioridade": str,       # Prioridade (obrigatório)
  "status": str,           # Status atual (obrigatório)
  "task_id_root": str,     # ID da tarefa raiz (opcional)
  "sprint": str,           # Sprint associada (opcional)
  "detalhado": str,        # Descrição detalhada (opcional)
  "data_criacao": str,     # Data de criação (opcional)
  "data_solucao": str      # Data de solução (opcional)
}

BatchTaskAdd

{
  "tasks": List[Task]      # Lista de tarefas a serem adicionadas
}

BatchTaskUpdate

{
  "updates": List[TaskUpdate]  # Lista de atualizações
}

Onde TaskUpdate é:

{
  "task_id": str,          # ID da tarefa
  "fields": dict           # Campos a atualizar
}

SearchFilters

{
  "prioridade": List[str],      # Lista de prioridades
  "status": List[str],          # Lista de status
  "contexto": str,              # Filtro de contexto
  "projeto": str,               # Filtro de projeto
  "texto_busca": str,           # Busca de texto
  "task_id": str,               # ID específico
  "sprint": str                 # Filtro de sprint
}

PaginationParams

{
  "page": int,           # Número da página (mínimo: 1)
  "page_size": int       # Itens por página (1-500)
}

PaginatedResponse

{
  "tasks": List[Dict],   # Tarefas da página
  "total_count": int,    # Total de tarefas
  "page": int,           # Página atual
  "page_size": int,      # Itens por página
  "total_pages": int,    # Total de páginas
  "has_next": bool,      # Existe próxima página
  "has_previous": bool   # Existe página anterior
}

---

Configuração

Pré-requisitos

1. Python 3.13.5 ou superior
2. Conta Google Cloud com Google Sheets API habilitada
3. Arquivo credentials.json com credenciais de Service Account

Variáveis de Ambiente

Crie um arquivo .env com:

KANBAN_SHEET_ID=seu_id_da_planilha_aqui
KANBAN_SHEET_NAME=Back-End  # Nome da aba (padrão: "Back-End")

Instalação

# Instalar dependências
uv sync

# Executar servidor
uv run main.py

Configuração do Cliente MCP

Adicione ao seu cliente MCP:

{
  "mcpServers": {
    "kanban-sheets": {
      "command": "uv",
      "args": ["run", "main.py"]
    }
  }
}

---

Estrutura da Planilha

A planilha deve ter as seguintes colunas (A até K):

Coluna	Nome	Descrição
A	Projeto	Nome do Projeto
B	Task ID	ID único da tarefa
C	Task ID Root	ID da tarefa raiz
D	Sprint	Sprint associada
E	Contexto	Contexto da tarefa
F	Descrição	Descrição breve
G	Detalhado	Descrição detalhada
H	Prioridade	Prioridade da tarefa
I	Status	Status atual
J	Data Criação	Data de criação
K	Data Solução	Data de solução

---

Exemplos de Uso Avançado

Buscar todas as tarefas urgentes pendentes

{
  "filters": {
    "prioridade": ["Urgente"],
    "status": ["Todo", "Em Desenvolvimento"]
  }
}

Listar tarefas de um projeto específico com paginação

{
  "filters": {
    "projeto": "MCP Server"
  },
  "pagination": {
    "page": 1,
    "page_size": 50
  }
}

Buscar tarefas impedidas ou pausadas

{
  "filters": {
    "status": ["Impedido", "Pausado"]
  }
}

Buscar por palavra-chave na descrição

{
  "filters": {
    "texto_busca": "API REST"
  }
}

---

Tecnologias Utilizadas

• FastMCP: Framework para servidores MCP
• Pydantic: Validação de dados (v2.12.3)
• Google API Python Client: Integração com Google Sheets
• google-auth: Autenticação com Google Cloud

---

Testes

O projeto inclui uma suíte completa de testes usando pytest.

Estrutura de Testes

tests/
├── __init__.py
├── conftest.py              # Fixtures compartilhadas
├── test_list_tasks.py       # Testes para listagem e busca
├── test_add_task.py         # Testes para adição de tarefas
├── test_update_task.py      # Testes para atualização
└── test_batch_operations.py # Testes para operações em lote

Instalação das Dependências de Teste

# Instalar dependências de desenvolvimento
uv pip install -r requirements-dev.txt

As dependências incluem:

• pytest: Framework de testes
• pytest-asyncio: Suporte para testes assíncronos
• pytest-cov: Cobertura de código
• pytest-mock: Mocking facilitado

Executar Testes

# Executar todos os testes
uv run pytest

# Executar com cobertura de código
uv run pytest --cov

# Executar testes específicos
uv run pytest tests/test_list_tasks.py

# Executar testes com saída verbosa
uv run pytest -v

# Executar apenas testes de uma função específica
uv run pytest tests/test_list_tasks.py::test_list_tasks_all

# Gerar relatório de cobertura em HTML
uv run pytest --cov --cov-report=html
# O relatório será criado em htmlcov/index.html

Estrutura dos Testes

Os testes utilizam mocks do Google Sheets API para não depender de conexões reais. As principais fixtures incluem:

• mock_env_vars: Variáveis de ambiente mockadas
• mock_sheets_service: Mock do serviço Google Sheets
• mock_credentials: Mock das credenciais do Google
• sample_sheet_data: Dados de exemplo para testes
• empty_sheet_data: Dados de planilha vazia

Cobertura de Testes

Os testes cobrem:

1. list_tasks:

   • Listagem sem filtros
   • Filtros individuais (prioridade, status, contexto, etc.)
   • Múltiplos filtros combinados
   • Paginação
   • Casos de erro

2. add_task:

   • Adição com todos os campos
   • Adição com campos mínimos
   • Diferentes prioridades e status
   • Validação de campos
   • Tratamento de erros

3. update_task:

   • Atualização de campos individuais
   • Atualização de múltiplos campos
   • Validação de status e prioridade
   • Tarefa não encontrada
   • Tratamento de erros

4. batch_add_tasks e batch_update_tasks:

   • Operações em lote bem-sucedidas
   • Operações parcialmente bem-sucedidas
   • Validações em lote
   • Tratamento de erros

5. get_valid_configs:

   • Retorno de configurações válidas
   • Estrutura do retorno

Exemplo de Teste

def test_list_tasks_with_priority_filter(mock_env_vars, mock_credentials_file,
                                         mock_credentials, mock_get_sheets_service):
    """Testa filtro por prioridade."""
    filters = SearchFilters(prioridade=["Alta"])
    result = list_tasks(filters=filters)

    assert isinstance(result, list)
    assert len(result) == 1
    assert result[0]["Task ID"] == "TASK-001"
    assert result[0]["Prioridade"] == "Alta"

Configuração do pytest

O arquivo pytest.ini contém as configurações padrão, incluindo:

• Padrões de descoberta de testes
• Opções de saída
• Configuração de cobertura de código
• Marcadores customizados

---

Documentação Adicional

• Migração para Pydantic
• Google Sheets API
• Model Context Protocol

---

Licença

Este projeto é um servidor MCP para gerenciamento de tarefas em Google Sheets.