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.

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