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

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

**Retorno (sucesso):**
```json
{
  "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):**
```json
{
  "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:**

```json
// 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):**
```json
[
  {
    "Task ID": "TASK-001",
    "Contexto": "Backend",
    "Descrição": "...",
    ...
  },
  ...
]
```

**Retorno (com paginação):**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "batch": {
    "updates": [
      {
        "task_id": "TASK-001",
        "fields": {"Status": "Concluído"}
      },
      {
        "task_id": "TASK-002",
        "fields": {"Prioridade": "Alta"}
      }
    ]
  }
}
```

**Retorno:**
```json
{
  "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:**
```json
{
  "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
```python
{
  "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
```python
{
  "tasks": List[Task]      # Lista de tarefas a serem adicionadas
}
```

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

Onde **TaskUpdate** é:
```python
{
  "task_id": str,          # ID da tarefa
  "fields": dict           # Campos a atualizar
}
```

### SearchFilters
```python
{
  "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
```python
{
  "page": int,           # Número da página (mínimo: 1)
  "page_size": int       # Itens por página (1-500)
}
```

### PaginatedResponse
```python
{
  "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:

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

### Instalação

```bash
# Instalar dependências
uv sync

# Executar servidor
uv run main.py
```

### Configuração do Cliente MCP

Adicione ao seu cliente MCP:

```json
{
  "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

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

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

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

### Buscar tarefas impedidas ou pausadas

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

### Buscar por palavra-chave na descrição

```json
{
  "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

```bash
# 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

```bash
# 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

```python
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](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](PYDANTIC_MIGRATION.md)
- [Google Sheets API](https://developers.google.com/sheets/api)
- [Model Context Protocol](https://modelcontextprotocol.io)

---

## Licença

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