innov-mcp-tasks

Servidor MCP em stdio para ferramentas de tarefas na API Innov (/api/v1/..., Bearer Sanctum).

Nenhuma URL de API vai no código publicado — só o que definires em variáveis de ambiente ou num .env teu. Após npm install do pacote, o postinstall imprime um lembrete na consola.

Variáveis obrigatórias

| Variável | Descrição | |----------|-----------| | INNOV_API_BASE_URL | URL base sem /api/v1 (definida por ti: dev local, staging, produção, etc.) | | INNOV_API_TOKEN | Token pessoal Sanctum (ex.: Perfil → Tokens de API na app Innov) |

Copia .env.example para um ficheiro .env à tua escolha e preenche (esse ficheiro não vem do npm com valores; no repo monorepo, mantém .env fora do Git).

Cursor com pacote npm (npx)

Nome do pacote no npm: innov-mcp-tasks (se o nome estiver ocupado, publica como scoped, ex. @tua-org/innov-mcp-tasks, e ajusta os exemplos).

{
  "mcpServers": {
    "innov-tasks": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "innov-mcp-tasks"],
      "env": {
        "INNOV_API_BASE_URL": "https://tua-api.exemplo.com",
        "INNOV_API_TOKEN": "cole_só_em_local_seguro_ou_usa_interpolação"
      }
    }
  }
}

Segredos: prefere ${env:INNOV_API_TOKEN} apontando para variáveis já definidas no SO, ou envFile para um .env fora do repositório (ex. C:\\Users\\…\\.config\\innov\\mcp.env).

Também podes apontar o binário instalado globalmente: "command": "innov-mcp-tasks" (após npm install -g innov-mcp-tasks).

Monorepo (desenvolvimento)

Na raiz do repo existe .cursor/mcp.json com dois servidores que partilham o mesmo mcp-tasks/.env:

| Servidor | Uso | |----------|-----| | innov-tasks-local | Corre o index.mjs do clon (óptimo para alterar o MCP). | | innov-tasks-npm | Usa npx -y innov-mcp-tasks (testa o pacote publicado). |

Ativa só um em Settings → Features → Model Context Protocol (dois ao mesmo tempo duplicam ferramentas com o mesmo nome). Se publicares com scope (@org/innov-mcp-tasks), edita os args em innov-tasks-npm para esse nome.

Ferramentas

Tarefas e projetos

• tasks_list — opcional project_id, milestones_only (filtra marcos no cliente)
• my_tasks — tarefas do utilizador do token (endpoint “minhas” da API)
• projects_list — lista projetos visíveis (GET /api/v1/projects)
• project_create — cria projeto (POST /api/v1/projects)
• task_get, task_create, task_update, task_update_status, task_assign, task_assign_to_me
• task_create / task_update — marcos: is_milestone, start_date (YYYY-MM-DD), duration (dias); marco exige project_id na criação
• task_attachment_download — baixa anexo por attachment_id (conteúdo em base64; ids em task_get → attachments)

Anotações / documentação

• notes_list — lista com filtros opcionais (project_id, note_type, notebook_id)
• notes_personal — anotações pessoais
• notes_by_project — anotações de um projeto (inclui criador em user)
• note_get, note_create, note_update
• note_delete — soft delete (lixeira)
• notes_trashed, note_restore
• annotations_search — busca em cadernos, notas e fontes (q ≥ 2 caracteres)

Cadernos (notebooks)

• notebooks_list — lista com filtro opcional project_id
• notebook_get, notebook_create, notebook_update, notebook_delete
• notebook_documentation — notas + fontes do caderno
• annotations_semantic_search — busca semântica em notas e metadados (q ≥ 2 caracteres)

Agentes de IA (SPEC-015)

• agents_list — agentes utilizáveis pelo token (GET /api/v1/ai-agents?scope=usable); opcional scope=manageable para gestão
• agent_chat — envia message a um agente (POST /api/v1/ai-agents/{ulid}/chat); devolve response e citations; opcional conversation_ulid, project_id, notebook_id

Publicar no npm (mantenedor)

1. Define o nome em package.json (innov-mcp-tasks ou @scope/innov-mcp-tasks se o nome simples estiver tomado).
2. Opcional: adiciona "repository" com URL real do Git antes do primeiro publish.
3. Na pasta mcp-tasks:

npm whoami
npm test
npm publish --access public

Para scoped (@org/pkg): a primeira vez costuma precisar de --access public se for pacote OSS.

Testes

npm test