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: Freshrelease MCP Server

Instalação

cd upsprint-mcp
npm install
npm run build

Configuração

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

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)

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

Leitura (API JWT — requer email/senha)

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