# upsprint-mcp

Servidor [MCP](https://modelcontextprotocol.io) para a API **Upsprints**. Permite que qualquer modelo de IA compatível com MCP (Claude, Cursor, modelos locais via Ollama/LM Studio + clientes MCP, etc.) acesse o usuário, companies, projetos e tarefas — e gere SDDs (Software Design Documents) a partir das tarefas.

Funciona por **stdio**, então roda local e não expõe porta nenhuma.

## Como funciona

Há dois modos, que podem ser usados juntos ou separados:

- **Escrita via Webhook** (`UPSPRINT_WEBHOOK_TOKEN`): usa `POST /webhooks/upsprint` com header `x-upsprint-token`. Habilita as tools `create_task`, `update_task`, `move_task`, `move_task_and_update` e `assign_task` — exatamente as 5 ações permitidas do token.
- **Leitura via API JWT** (`UPSPRINT_API_URL` + `UPSPRINT_EMAIL` + `UPSPRINT_PASSWORD`): login em 2 etapas (`/auth/login` → `/auth/select-company`), JWT em memória com refresh automático. Habilita as tools de leitura (`get_me`, `list_my_tasks`, `get_task`, `generate_sdd_context`, etc.). Usuários **MASTER** trocam de company com `select_company`.

Se só o webhook estiver configurado, o servidor sobe apenas com as tools de escrita.

## Instalação

```bash
cd upsprint-mcp
npm install
npm run build
```

## Configuração

Variáveis de ambiente (veja `.env.example`):

| Variável | Modo | Descrição |
|---|---|---|
| `UPSPRINT_WEBHOOK_TOKEN` | escrita | Token `ups_...` da aba Webhooks > Tokens |
| `UPSPRINT_WEBHOOK_URL` | escrita | Endpoint do webhook (default `https://api.upsprints.com.br/webhooks/upsprint`) |
| `UPSPRINT_API_URL` | leitura | URL base da API (ex.: `http://localhost:9002` ou produção) |
| `UPSPRINT_EMAIL` | leitura | E-mail do usuário |
| `UPSPRINT_PASSWORD` | leitura | Senha do usuário |
| `UPSPRINT_COMPANY_ID` | leitura (opcional) | Company selecionada automaticamente no login |

Pelo menos um dos dois modos precisa estar configurado.

### Claude Desktop / Cowork

Em `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "upsprint": {
      "command": "node",
      "args": ["/caminho/para/Upsprints/upsprint-mcp/dist/index.js"],
      "env": {
        "UPSPRINT_WEBHOOK_TOKEN": "ups_seu_token_aqui",
        "UPSPRINT_API_URL": "http://localhost:9002",
        "UPSPRINT_EMAIL": "seu-email@exemplo.com",
        "UPSPRINT_PASSWORD": "sua-senha"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add upsprint \
  -e UPSPRINT_API_URL=http://localhost:9002 \
  -e UPSPRINT_EMAIL=seu-email@exemplo.com \
  -e UPSPRINT_PASSWORD=sua-senha \
  -- node /caminho/para/Upsprints/upsprint-mcp/dist/index.js
```

### Cursor / Windsurf / Cline

Mesmo formato JSON em `.cursor/mcp.json` (ou equivalente do cliente):

```json
{
  "mcpServers": {
    "upsprint": {
      "command": "node",
      "args": ["/caminho/para/Upsprints/upsprint-mcp/dist/index.js"],
      "env": {
        "UPSPRINT_API_URL": "http://localhost:9002",
        "UPSPRINT_EMAIL": "seu-email@exemplo.com",
        "UPSPRINT_PASSWORD": "sua-senha"
      }
    }
  }
}
```

### Modelos locais (Ollama, LM Studio, etc.)

Qualquer cliente que implemente MCP por stdio funciona — basta apontar `command`/`args`/`env` como acima. Exemplos: LM Studio (`mcp.json` nas configurações), [oterm](https://github.com/ggozad/oterm) para Ollama, ou um agente próprio com o SDK MCP.

### Testar sem cliente

```bash
UPSPRINT_API_URL=http://localhost:9002 \
UPSPRINT_EMAIL=... UPSPRINT_PASSWORD=... \
npm run inspect
```

Abre o MCP Inspector no navegador para chamar as tools manualmente.

## Tools disponíveis

### Escrita (webhook — requer `UPSPRINT_WEBHOOK_TOKEN`)

| Tool | Ação webhook | Descrição |
|---|---|---|
| `create_task` | `createTask` | Cria task em um projeto (suporta `metadata` para form binding) |
| `update_task` | `updateTask` | Atualiza campos (`updates`: title, description, priority, status, due_date...) |
| `move_task` | `moveTask` | Move para outra coluna (`to_column_id`) |
| `move_task_and_update` | `moveTaskAndUpdate` | Move e atualiza campos em uma operação |
| `assign_task` | `assignTask` | Atribui a task a um usuário (`user_id`) |

Enums: prioridade `VERY_LOW | LOW | MEDIUM | HIGH | URGENT`; status `TODO | DOING | IN_PROGRESS | REVIEW | DONE | BLOCKED`.

### Leitura (API JWT — requer email/senha)

| Tool | Descrição |
|---|---|
| `get_me` | Perfil do usuário autenticado (role, company ativa) |
| `list_companies` | Companies do usuário; com `all: true`, todas (somente MASTER) |
| `select_company` | Troca a company ativa do token |
| `list_my_tasks` | Tarefas atribuídas ao usuário na company ativa |
| `list_projects` | Projetos da company ativa |
| `list_project_tasks` | Tarefas de um projeto (filtros: busca, responsável, coluna, prioridade) |
| `get_task` | Detalhes completos de uma tarefa (subtarefas, checklists, sprint, release) |
| `get_task_activities` | Histórico de atividades de uma tarefa |
| `generate_sdd_context` | Monta o contexto completo da tarefa + template de SDD para o modelo escrever |

Também há o **prompt** `create-sdd` (aparece como comando no cliente MCP), que executa o fluxo completo de geração de SDD para uma tarefa.

## Fluxo típico: gerar SDDs das minhas tarefas

1. `get_me` — confirma usuário e role.
2. (MASTER) `list_companies` com `all: true` → `select_company` na company desejada.
3. `list_my_tasks` — vê as tarefas pendentes.
4. Para cada tarefa que vira feature: `generate_sdd_context` → o modelo escreve o `SDD-<feature>.md`.
5. (Opcional) `update_task` para anexar o SDD na descrição da tarefa, e `move_task` para movê-la no board.

Exemplo de pedido ao modelo:

> "Liste minhas tarefas na Upsprints e gere um SDD para a tarefa X do projeto Y, salvando como SDD-x.md."

## Segurança

- As credenciais ficam só na configuração local do cliente MCP; nada é gravado em disco pelo servidor.
- O token JWT vive em memória e é renovado automaticamente.
- Prefira um usuário dedicado/da conta com o menor privilégio necessário; use MASTER apenas se precisar atravessar companies.

## Desenvolvimento

```bash
npm run dev      # roda com tsx (sem build)
npm run build    # compila para dist/
```

Estrutura:

```
upsprint-mcp/
├── src/
│   ├── index.ts       # servidor MCP e definição das tools
│   ├── api-client.ts  # cliente HTTP + autenticação automática
│   └── sdd.ts         # montagem do contexto e template do SDD
├── .env.example
└── README.md
```