innov-mcp-tasks 1.0.2 → 1.1.0

package/README.md

@@ -6,16 +6,18 @@ 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
 {
@@ -33,28 +35,43 @@ 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.
 
 ## Ferramentas
 
+### Tarefas e projetos
+
 - `tasks_list` — opcional `project_id`
 - `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_status`, `task_assign`, `task_assign_to_me`
 
+### 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)
+
 ## 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).
@@ -67,6 +84,16 @@ 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
@@ -74,3 +101,4 @@ Para **scoped** (`@org/pkg`): a primeira vez costuma precisar de `--access publi
 ```bash
 npm test
 ```
+

package/index.mjs

@@ -105,6 +105,23 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'projects_list',
+  {
+    description:
+      'Lista projetos visíveis ao utilizador do token (GET /projects). Inclui creator, tasks, team e allowedUsers.',
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      const data = await apiFetch('/api/v1/projects');
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
 server.registerTool(
   'project_create',
   {
@@ -248,5 +265,236 @@ server.registerTool(
   },
 );
 
+function notesQueryString(filters) {
+  const params = new URLSearchParams();
+  if (filters.project_id != null) {
+    params.set('project_id', String(filters.project_id));
+  }
+  if (filters.note_type != null) {
+    params.set('note_type', filters.note_type);
+  }
+  if (filters.notebook_id != null) {
+    params.set('notebook_id', String(filters.notebook_id));
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : '';
+}
+
+server.registerTool(
+  'notes_list',
+  {
+    description:
+      'Lista anotações do utilizador do token (GET /notes). Filtros opcionais: project_id, note_type (personal|project), notebook_id.',
+    inputSchema: {
+      project_id: z.number().int().positive().optional(),
+      note_type: z.enum(['personal', 'project']).optional(),
+      notebook_id: z.number().int().positive().optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(`/api/v1/notes${notesQueryString(args)}`);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'notes_personal',
+  {
+    description: 'Anotações pessoais do utilizador do token (GET /notes/personal).',
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      const data = await apiFetch('/api/v1/notes/personal');
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'notes_by_project',
+  {
+    description:
+      'Anotações de um projeto visível (GET /notes/project/{project_id}). Inclui user (criador).',
+    inputSchema: { project_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(
+        `/api/v1/notes/project/${args.project_id}`,
+      );
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'note_get',
+  {
+    description: 'Obtém uma anotação por id (GET /notes/{id}). Só o autor.',
+    inputSchema: { note_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(`/api/v1/notes/${args.note_id}`);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'note_create',
+  {
+    description:
+      'Cria anotação (POST /notes). Pessoal sem project_id; de projeto com note_type project + project_id; opcional notebook_id.',
+    inputSchema: {
+      content: z.string().min(1),
+      title: z.string().max(255).optional(),
+      note_type: z.enum(['personal', 'project']).optional(),
+      project_id: z.number().int().positive().optional(),
+      notebook_id: z.number().int().positive().optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const body = {
+        content: args.content,
+        title: args.title ?? null,
+        note_type: args.note_type ?? null,
+        project_id: args.project_id ?? null,
+        notebook_id: args.notebook_id ?? null,
+      };
+      const data = await apiFetch('/api/v1/notes', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'note_update',
+  {
+    description: 'Atualiza anotação (PUT /notes/{id}). Só o autor.',
+    inputSchema: {
+      note_id: z.number().int().positive(),
+      title: z.string().max(255).optional(),
+      content: z.string().optional(),
+      note_type: z.enum(['personal', 'project']).optional(),
+      project_id: z.number().int().positive().optional(),
+      notebook_id: z.number().int().positive().optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const { note_id, ...fields } = args;
+      const body = Object.fromEntries(
+        Object.entries(fields).filter(([, v]) => v !== undefined),
+      );
+      const data = await apiFetch(`/api/v1/notes/${note_id}`, {
+        method: 'PUT',
+        body: JSON.stringify(body),
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'note_delete',
+  {
+    description:
+      'Remove anotação para a lixeira — soft delete (DELETE /notes/{id}). Só o autor.',
+    inputSchema: { note_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(`/api/v1/notes/${args.note_id}`, {
+        method: 'DELETE',
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'notes_trashed',
+  {
+    description:
+      'Lista anotações na lixeira do utilizador (GET /notes/trashed). Filtros opcionais como notes_list.',
+    inputSchema: {
+      project_id: z.number().int().positive().optional(),
+      note_type: z.enum(['personal', 'project']).optional(),
+      notebook_id: z.number().int().positive().optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(
+        `/api/v1/notes/trashed${notesQueryString(args)}`,
+      );
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'note_restore',
+  {
+    description:
+      'Restaura anotação da lixeira (POST /notes/{id}/restore). Só o autor.',
+    inputSchema: { note_id: z.number().int().positive() },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(
+        `/api/v1/notes/${args.note_id}/restore`,
+        { method: 'POST' },
+      );
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'annotations_search',
+  {
+    description:
+      'Busca em cadernos, anotações e fontes (GET /annotations/search?q=). Mínimo 2 caracteres.',
+    inputSchema: { q: z.string().min(2) },
+  },
+  async (args) => {
+    try {
+      const data = await apiFetch(
+        `/api/v1/annotations/search?q=${encodeURIComponent(args.q)}`,
+      );
+      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,7 +1,7 @@
 {
   "name": "innov-mcp-tasks",
-  "version": "1.0.2",
-  "description": "MCP stdio — ferramentas de tarefas Innov (API a configurar via INNOV_API_BASE_URL + token Sanctum)",
+  "version": "1.1.0",
+  "description": "MCP stdio — tarefas e anotações Innov (INNOV_API_BASE_URL + token Sanctum)",
   "type": "module",
   "main": "index.mjs",
   "bin": {
@@ -26,6 +26,8 @@
     "mcp",
     "modelcontextprotocol",
     "tasks",
+    "notes",
+    "annotations",
     "innov"
   ],
   "author": "",