innov-mcp-tasks 1.1.0 → 1.3.0

package/README.md

@@ -6,18 +6,16 @@ Servidor [MCP](https://modelcontextprotocol.io) em **stdio** para ferramentas de
 
 ## Variáveis obrigatórias
 
-
-| Variável             | Descrição                                                                        |
-| -------------------- | -------------------------------------------------------------------------------- |
+| 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)             |
-
+| `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).
+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).
+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
 {
@@ -35,20 +33,18 @@ Nome do pacote no npm: `**innov-mcp-tasks`** (se o nome estiver ocupado, publica
 }
 ```
 
-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`).
+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`:
+Na raiz do repo existe [`.cursor/mcp.json`](../.cursor/mcp.json) com **dois** servidores que partilham o mesmo `mcp-tasks/.env`:
 
-
-| Servidor            | Uso                                                      |
-| ------------------- | -------------------------------------------------------- |
+| 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). |
-
+| `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.
 
@@ -61,6 +57,7 @@ Na raiz do repo existe `[.cursor/mcp.json](../.cursor/mcp.json)` com **dois** se
 - `projects_list` — lista projetos visíveis (`GET /api/v1/projects`)
 - `project_create` — cria projeto (`POST /api/v1/projects`)
 - `task_get`, `task_create`, `task_update_status`, `task_assign`, `task_assign_to_me`
+- `task_attachment_download` — baixa anexo por `attachment_id` (conteúdo em base64; ids em `task_get` → `attachments`)
 
 ### Anotações / documentação
 
@@ -72,6 +69,12 @@ Na raiz do repo existe `[.cursor/mcp.json](../.cursor/mcp.json)` com **dois** se
 - `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
+
 ## 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).
@@ -84,16 +87,6 @@ npm test
 npm publish --access public
 ```
 
-
-
-Se estiver deslogado para logar faça o comando
-
-```bash
-npm login
-```
-
-
-
 Para **scoped** (`@org/pkg`): a primeira vez costuma precisar de `--access public` se for pacote OSS.
 
 ## Testes
@@ -101,4 +94,3 @@ Para **scoped** (`@org/pkg`): a primeira vez costuma precisar de `--access publi
 ```bash
 npm test
 ```
-

package/index.mjs

@@ -50,6 +50,43 @@ async function apiFetch(path, init = {}) {
   return data;
 }
 
+async function apiFetchBinary(path) {
+  if (!base || !token) {
+    throw new Error(
+      'Defina INNOV_API_BASE_URL e INNOV_API_TOKEN no ambiente ou num .env.',
+    );
+  }
+  const url = `${base}${path.startsWith('/') ? path : `/${path}`}`;
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    let msg = text.slice(0, 800);
+    try {
+      const data = text ? JSON.parse(text) : null;
+      if (data && (data.message || data.error)) {
+        msg = String(data.message || data.error);
+      }
+    } catch {
+      /* texto bruto */
+    }
+    throw new Error(`HTTP ${res.status}: ${msg}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  const disposition = res.headers.get('content-disposition') || '';
+  const filenameMatch = disposition.match(/filename="?([^";\n]+)"?/i);
+  const filename = filenameMatch?.[1]?.trim() || 'attachment';
+  return {
+    buffer,
+    contentType: res.headers.get('content-type') || 'application/octet-stream',
+    filename,
+    size: buffer.length,
+  };
+}
+
 const server = new McpServer({ name: 'innov-tasks', version: '1.0.0' });
 
 server.registerTool(
@@ -105,6 +142,34 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'task_attachment_download',
+  {
+    description:
+      'Baixa anexo de tarefa (GET /task-attachments/{id}/download). Requer Bearer Sanctum. ' +
+      'Retorna metadados e conteúdo em base64 (útil para zip, pdf, docx, txt, srt, etc.). ' +
+      'Use task_get para listar attachments[].id da tarefa.',
+    inputSchema: { attachment_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const file = await apiFetchBinary(
+        `/api/v1/task-attachments/${args.attachment_id}/download`,
+      );
+      return jsonText({
+        attachment_id: args.attachment_id,
+        filename: file.filename,
+        content_type: file.contentType,
+        size_bytes: file.size,
+        content_base64: file.buffer.toString('base64'),
+        hint: 'Decodifique content_base64 para gravar o ficheiro localmente.',
+      });
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
 server.registerTool(
   'projects_list',
   {
@@ -496,5 +561,138 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'notebooks_list',
+  {
+    description:
+      'Lista cadernos visíveis ao utilizador do token (GET /notebooks). Filtro opcional project_id.',
+    inputSchema: {
+      project_id: z.number().int().positive().optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const qs =
+        args.project_id != null
+          ? `?project_id=${encodeURIComponent(String(args.project_id))}`
+          : '';
+      const data = await apiFetch(`/api/v1/notebooks${qs}`);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'notebook_get',
+  {
+    description: 'Obtém um caderno por id (GET /notebooks/{id}).',
+    inputSchema: { notebook_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(`/api/v1/notebooks/${args.notebook_id}`);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'notebook_create',
+  {
+    description:
+      'Cria caderno (POST /notebooks). Pessoal sem project_id; de projeto com project_id. name obrigatório.',
+    inputSchema: {
+      name: z.string().min(1).max(255),
+      description: z.string().optional(),
+      project_id: z.number().int().positive().optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const body = {
+        name: args.name,
+        description: args.description ?? null,
+        project_id: args.project_id ?? null,
+      };
+      const data = await apiFetch('/api/v1/notebooks', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'notebook_update',
+  {
+    description: 'Atualiza caderno (PATCH /notebooks/{id}). Só cadernos do utilizador.',
+    inputSchema: {
+      notebook_id: z.number().int().positive(),
+      name: z.string().min(1).max(255).optional(),
+      description: z.string().optional(),
+      project_id: z.number().int().positive().optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const { notebook_id, ...fields } = args;
+      const body = Object.fromEntries(
+        Object.entries(fields).filter(([, v]) => v !== undefined),
+      );
+      const data = await apiFetch(`/api/v1/notebooks/${notebook_id}`, {
+        method: 'PATCH',
+        body: JSON.stringify(body),
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'notebook_delete',
+  {
+    description: 'Apaga caderno (DELETE /notebooks/{id}). Só cadernos do utilizador.',
+    inputSchema: { notebook_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(`/api/v1/notebooks/${args.notebook_id}`, {
+        method: 'DELETE',
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'notebook_documentation',
+  {
+    description:
+      'Documentação agregada do caderno: notas do utilizador + fontes (GET /notebooks/{id}/documentation).',
+    inputSchema: { notebook_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(
+        `/api/v1/notebooks/${args.notebook_id}/documentation`,
+      );
+      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

@@ -1,6 +1,6 @@
 {
   "name": "innov-mcp-tasks",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "MCP stdio — tarefas e anotações Innov (INNOV_API_BASE_URL + token Sanctum)",
   "type": "module",
   "main": "index.mjs",