innov-mcp-tasks 1.0.0

package/.env.example

@@ -0,0 +1,3 @@
+# Copia para .env local (não commitar). Nenhum endereço vem no pacote npm — define tu.
+INNOV_API_BASE_URL=
+INNOV_API_TOKEN=

package/README.md

@@ -0,0 +1,75 @@
+# innov-mcp-tasks
+
+Servidor [MCP](https://modelcontextprotocol.io) 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`](./.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).
+
+```json
+{
+  "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}`](https://cursor.com/docs/mcp) 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`](../.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
+
+- `tasks_list` — opcional `project_id`
+- `my_tasks` — tarefas do utilizador do token (endpoint “minhas” da API)
+- `task_get`, `task_create`, `task_update_status`, `task_assign`
+
+## 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`:
+
+```bash
+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
+
+```bash
+npm test
+```

package/index.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * MCP stdio — proxy para tarefas da API Innov (Sanctum Bearer).
+ */
+import 'dotenv/config';
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const base = (process.env.INNOV_API_BASE_URL || '').replace(/\/$/, '');
+const token = (process.env.INNOV_API_TOKEN || '').trim();
+
+function jsonText(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+
+function jsonError(message) {
+  return { isError: true, content: [{ type: 'text', text: message }] };
+}
+
+async function apiFetch(path, init = {}) {
+  if (!base || !token) {
+    throw new Error(
+      'Defina INNOV_API_BASE_URL (URL base da API, sem /api/v1) e INNOV_API_TOKEN (Bearer Sanctum) no ambiente ou num .env. O pacote npm não inclui endereço da API.',
+    );
+  }
+  const url = `${base}${path.startsWith('/') ? path : `/${path}`}`;
+  const headers = {
+    Accept: 'application/json',
+    Authorization: `Bearer ${token}`,
+    ...init.headers,
+  };
+  if (init.body && !headers['Content-Type']) {
+    headers['Content-Type'] = 'application/json';
+  }
+  const res = await fetch(url, { ...init, headers });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { _raw: text };
+  }
+  if (!res.ok) {
+    const msg = typeof data === 'object' && data && (data.message || data.error)
+      ? String(data.message || data.error)
+      : text.slice(0, 800);
+    throw new Error(`HTTP ${res.status}: ${msg}`);
+  }
+  return data;
+}
+
+const server = new McpServer({ name: 'innov-tasks', version: '1.0.0' });
+
+server.registerTool(
+  'tasks_list',
+  {
+    description: 'Lista tarefas. Com project_id usa GET /tasks?project_id=…; sem project_id usa GET /tasks/kanban.',
+    inputSchema: { project_id: z.number().int().positive().optional() },
+  },
+  async (args) => {
+    try {
+      const path =
+        args.project_id != null
+          ? `/api/v1/tasks?project_id=${encodeURIComponent(String(args.project_id))}`
+          : '/api/v1/tasks/kanban';
+      const data = await apiFetch(path);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'my_tasks',
+  {
+    description:
+      'Minhas tarefas atribuídas a mim, do utilizador do token.',
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      const data = await apiFetch('/api/v1/my-tasks');
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'task_get',
+  {
+    description: 'Obtém uma tarefa por id (GET /tasks/{id}).',
+    inputSchema: { task_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(`/api/v1/tasks/${args.task_id}`);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'task_create',
+  {
+    description: 'Cria tarefa (POST /tasks).',
+    inputSchema: {
+      title: z.string().min(1).max(255),
+      project_id: z.number().int().positive().optional(),
+      team_id: z.number().int().positive().optional(),
+      description: z.string().optional(),
+      assigned_to: z.number().int().positive().optional(),
+      priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const body = {
+        title: args.title,
+        project_id: args.project_id ?? null,
+        team_id: args.team_id ?? null,
+        description: args.description ?? null,
+        assigned_to: args.assigned_to ?? null,
+        priority: args.priority ?? 'medium',
+      };
+      const data = await apiFetch('/api/v1/tasks', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'task_update_status',
+  {
+    description: 'Atualiza apenas o status (PATCH /tasks/{id}/status).',
+    inputSchema: {
+      task_id: z.number().int().positive(),
+      status: z.enum(['pending', 'in_progress', 'in_review', 'completed', 'cancelled']),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(`/api/v1/tasks/${args.task_id}/status`, {
+        method: 'PATCH',
+        body: JSON.stringify({ status: args.status }),
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'task_assign',
+  {
+    description: 'Atribui responsável (POST /tasks/{id}/assign).',
+    inputSchema: {
+      task_id: z.number().int().positive(),
+      user_id: z.number().int().positive(),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(`/api/v1/tasks/${args.task_id}/assign`, {
+        method: 'POST',
+        body: JSON.stringify({ user_id: args.user_id }),
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "innov-mcp-tasks",
+  "version": "1.0.0",
+  "description": "MCP stdio — ferramentas de tarefas Innov (API a configurar via INNOV_API_BASE_URL + token Sanctum)",
+  "type": "module",
+  "main": "index.mjs",
+  "bin": {
+    "innov-mcp-tasks": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    ".env.example",
+    "scripts/postinstall-notice.mjs"
+  ],
+  "scripts": {
+    "start": "node index.mjs",
+    "test": "node --check index.mjs",
+    "prepack": "node --check index.mjs",
+    "postinstall": "node ./scripts/postinstall-notice.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "tasks",
+    "innov"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "zod": "^3.25.76"
+  }
+}

package/scripts/postinstall-notice.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Mensagem após npm install — não lê segredos nem imprime URLs reais.
+ */
+const name = process.env.npm_package_name ?? 'innov-mcp-tasks';
+// Evitar ruído em CI comum
+if (process.env.CI === 'true' || process.env.CONTINUOUS_INTEGRATION === 'true') {
+  process.exit(0);
+}
+console.info(`
+┌─ ${name} ───────────────────────────────────────────────
+│ Configure a API no **ambiente** (nada disso fica no pacote):
+│   INNOV_API_BASE_URL  — URL base, **sem** o sufixo /api/v1
+│   INNOV_API_TOKEN     — token Bearer Sanctum (ex.: Perfil → Tokens de API)
+│
+│ Cursor (mcp.json): use "env" ou "envFile" apontando para um .env teu.
+│ Documentação: https://www.npmjs.com/package/${name}
+└────────────────────────────────────────────────────────────
+`);