Skip to main content
Glama

upsprint-mcp

Servidor MCP 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.

Related MCP server: EverHour MCP Server

Instalação

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):

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

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):

{
  "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 para Ollama, ou um agente próprio com o SDK MCP.

Testar sem cliente

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

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

Available Tools

5 tools
assign_taskAtribuir task (webhook)C

Atribui uma task a um usuário específico (action assignTask).

Inputs: task_id (required), user_id (required).

create_taskCriar task (webhook)B

Cria uma nova task em um projeto via webhook (action createTask). Suporta campos personalizados de formulário via metadata.

Inputs: title (required), project_id (required), value, column, +8 more.

move_taskMover task (webhook)B

Move uma task para outra coluna do board (action moveTask). A coluna atual é detectada automaticamente.

Inputs: task_id (required), to_column_id (required), position.

move_task_and_updateMover e atualizar task (webhook)B

Move uma task para outra coluna e atualiza campos na mesma operação (action moveTaskAndUpdate).

Inputs: task_id (required), to_column_id (required), title, value, +10 more.

update_taskAtualizar task (webhook)A

Atualiza campos de uma task existente sem movê-la (action updateTask). Pelo menos um campo em "updates" é obrigatório. Útil para anexar o SDD gerado na descrição.

Inputs: task_id (required), updates (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool targets a distinct operation (create, update, move, combine move+update, assign), but move_task and move_task_and_update could cause minor confusion for agents deciding between separate calls or a combined operation.

    Naming Consistency5/5

    All tool names follow a strict verb_noun pattern using snake_case (create_task, update_task, move_task, etc.), making the naming highly predictable and consistent.

    Tool Count5/5

    With 5 tools covering core task actions, the count is well-scoped for a focused task management server, neither too sparse nor excessive.

    Completeness3/5

    The set covers create, update, move, and assign operations, but lacks delete and any retrieval/list functionality, which may leave agents unable to fully manage the task lifecycle.

    Related MCP Connectors

    Related MCP Servers