innov-mcp-tasks 1.3.0 → 1.5.0

package/README.md

@@ -52,11 +52,12 @@ Na raiz do repo existe [`.cursor/mcp.json`](../.cursor/mcp.json) com **dois** se
 
 ### Tarefas e projetos
 
-- `tasks_list` — opcional `project_id`
+- `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_status`, `task_assign`, `task_assign_to_me`
+- `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
@@ -74,6 +75,12 @@ Na raiz do repo existe [`.cursor/mcp.json`](../.cursor/mcp.json) com **dois** se
 - `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)
 

package/index.mjs

@@ -6,6 +6,7 @@ import 'dotenv/config';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { agentChat, agentsList } from './lib/agents.mjs';
 
 const base = (process.env.INNOV_API_BASE_URL || '').replace(/\/$/, '');
 const token = (process.env.INNOV_API_TOKEN || '').trim();
@@ -87,13 +88,49 @@ async function apiFetchBinary(path) {
   };
 }
 
+/** Campos de marco / cronograma (is_milestone exige project_id na API). */
+const taskMilestoneInputSchema = {
+  is_milestone: z.boolean().optional(),
+  start_date: z
+    .string()
+    .optional()
+    .describe('Data de início (YYYY-MM-DD); usada em marcos e Gantt'),
+  duration: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe('Duração em dias (marco/cronograma)'),
+};
+
+function pickDefined(fields) {
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, v]) => v !== undefined),
+  );
+}
+
+function filterTasksMilestonesOnly(data) {
+  if (!Array.isArray(data)) {
+    return data;
+  }
+  return data.filter((t) => t && t.is_milestone);
+}
+
 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() },
+    description:
+      'Lista tarefas. Com project_id usa GET /tasks?project_id=…; sem project_id usa GET /tasks/kanban. ' +
+      'Cada item inclui is_milestone, start_date e duration. Com milestones_only=true filtra só marcos (no cliente).',
+    inputSchema: {
+      project_id: z.number().int().positive().optional(),
+      milestones_only: z
+        .boolean()
+        .optional()
+        .describe('Se true, devolve apenas tarefas com is_milestone=true'),
+    },
   },
   async (args) => {
     try {
@@ -101,7 +138,10 @@ server.registerTool(
         args.project_id != null
           ? `/api/v1/tasks?project_id=${encodeURIComponent(String(args.project_id))}`
           : '/api/v1/tasks/kanban';
-      const data = await apiFetch(path);
+      let data = await apiFetch(path);
+      if (args.milestones_only) {
+        data = filterTasksMilestonesOnly(data);
+      }
       return jsonText(data);
     } catch (e) {
       return jsonError(e instanceof Error ? e.message : String(e));
@@ -129,7 +169,8 @@ server.registerTool(
 server.registerTool(
   'task_get',
   {
-    description: 'Obtém uma tarefa por id (GET /tasks/{id}).',
+    description:
+      'Obtém uma tarefa por id (GET /tasks/{id}). Inclui is_milestone, start_date e duration.',
     inputSchema: { task_id: z.number().int().positive() },
   },
   async (args) => {
@@ -233,7 +274,8 @@ server.registerTool(
 server.registerTool(
   'task_create',
   {
-    description: 'Cria tarefa (POST /tasks).',
+    description:
+      'Cria tarefa (POST /tasks). Marcos: is_milestone=true exige project_id; opcional start_date e duration (dias).',
     inputSchema: {
       title: z.string().min(1).max(255),
       project_id: z.number().int().positive().optional(),
@@ -241,18 +283,24 @@ server.registerTool(
       description: z.string().optional(),
       assigned_to: z.number().int().positive().optional(),
       priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+      due_date: z.string().optional().describe('Prazo (YYYY-MM-DD)'),
+      ...taskMilestoneInputSchema,
     },
   },
   async (args) => {
     try {
-      const body = {
+      const body = pickDefined({
         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,
+        project_id: args.project_id,
+        team_id: args.team_id,
+        description: args.description,
+        assigned_to: args.assigned_to,
         priority: args.priority ?? 'medium',
-      };
+        due_date: args.due_date,
+        is_milestone: args.is_milestone,
+        start_date: args.start_date,
+        duration: args.duration,
+      });
       const data = await apiFetch('/api/v1/tasks', {
         method: 'POST',
         body: JSON.stringify(body),
@@ -264,6 +312,41 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'task_update',
+  {
+    description:
+      'Atualiza tarefa (PATCH /tasks/{id}). Campos opcionais; marcos: is_milestone, start_date, duration (dias). ' +
+      'Marco exige projeto e não pode ser subtarefa (regras da API).',
+    inputSchema: {
+      task_id: z.number().int().positive(),
+      title: z.string().min(1).max(255).optional(),
+      description: z.string().optional(),
+      status: z
+        .enum(['pending', 'in_progress', 'in_review', 'completed', 'cancelled'])
+        .optional(),
+      priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+      due_date: z.string().optional(),
+      assigned_to: z.number().int().positive().optional(),
+      progress: z.number().int().min(0).max(100).optional(),
+      ...taskMilestoneInputSchema,
+    },
+  },
+  async (args) => {
+    try {
+      const { task_id, ...fields } = args;
+      const body = pickDefined(fields);
+      const data = await apiFetch(`/api/v1/tasks/${task_id}`, {
+        method: 'PATCH',
+        body: JSON.stringify(body),
+      });
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
 server.registerTool(
   'task_update_status',
   {
@@ -675,6 +758,40 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'annotations_semantic_search',
+  {
+    description:
+      'Busca semântica em notas e metadados de cadernos (GET /annotations/semantic-search).',
+    inputSchema: {
+      q: z.string().min(2),
+      notebook_id: z.number().int().positive().optional(),
+      limit: z.number().int().min(1).max(30).optional(),
+      min_score: z.number().min(0).max(1).optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const params = new URLSearchParams({ q: args.q });
+      if (args.notebook_id != null) {
+        params.set('notebook_id', String(args.notebook_id));
+      }
+      if (args.limit != null) {
+        params.set('limit', String(args.limit));
+      }
+      if (args.min_score != null) {
+        params.set('min_score', String(args.min_score));
+      }
+      const data = await apiFetch(
+        `/api/v1/annotations/semantic-search?${params.toString()}`,
+      );
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
 server.registerTool(
   'notebook_documentation',
   {
@@ -694,5 +811,56 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'agents_list',
+  {
+    description:
+      'Lista agentes de IA (GET /ai-agents). Padrão scope=usable — agentes que o token pode usar no chat (ACL). ' +
+      'Use scope=manageable para gestão (/agentes; requer can_manage_agents).',
+    inputSchema: {
+      scope: z
+        .enum(['usable', 'manageable'])
+        .optional()
+        .describe('Padrão: usable (selector de chat conforme ACL)'),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await agentsList(apiFetch, args.scope ?? 'usable');
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'agent_chat',
+  {
+    description:
+      'Envia mensagem a um agente de IA (POST /ai-agents/{ulid}/chat). ' +
+      'Devolve resposta do agente e citações quando ferramentas de KB forem usadas. ' +
+      'Opcional conversation_ulid para continuar conversa; project_id/notebook_id para contexto.',
+    inputSchema: {
+      agent_ulid: z.string().min(1).describe('ULID do agente (ver agents_list)'),
+      message: z.string().min(1),
+      conversation_ulid: z
+        .string()
+        .optional()
+        .describe('ULID da conversa para continuar o turno'),
+      project_id: z.number().int().positive().optional(),
+      notebook_id: z.number().int().positive().optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await agentChat(apiFetch, args);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/lib/agents.mjs

@@ -0,0 +1,97 @@
+/** Helpers e handlers testáveis para tools de agentes de IA (SPEC-015 Fase 8). */
+
+export const AGENT_SCOPES = ['usable', 'manageable'];
+
+/**
+ * @param {'usable' | 'manageable'} [scope]
+ */
+export function agentsListPath(scope = 'usable') {
+  if (!AGENT_SCOPES.includes(scope)) {
+    throw new Error(`scope inválido: ${scope}. Use manageable ou usable.`);
+  }
+  return `/api/v1/ai-agents?scope=${encodeURIComponent(scope)}`;
+}
+
+/**
+ * @param {string} ulid
+ */
+export function agentChatPath(ulid) {
+  const trimmed = String(ulid ?? '').trim();
+  if (!trimmed) {
+    throw new Error('agent_ulid é obrigatório');
+  }
+  return `/api/v1/ai-agents/${encodeURIComponent(trimmed)}/chat`;
+}
+
+/**
+ * @param {{
+ *   message: string;
+ *   conversation_ulid?: string;
+ *   project_id?: number;
+ *   notebook_id?: number;
+ * }} args
+ */
+export function buildAgentChatBody(args) {
+  const body = { message: args.message };
+  if (args.conversation_ulid != null) {
+    body.conversation_ulid = args.conversation_ulid;
+  }
+  if (args.project_id != null) {
+    body.project_id = args.project_id;
+  }
+  if (args.notebook_id != null) {
+    body.notebook_id = args.notebook_id;
+  }
+  return body;
+}
+
+/**
+ * Normaliza resposta do chat para o consumidor MCP (resposta + citações).
+ * @param {unknown} data
+ */
+export function formatAgentChatResponse(data) {
+  if (!data || typeof data !== 'object') {
+    return { response: null, citations: [] };
+  }
+  const payload = /** @type {Record<string, unknown>} */ (data);
+  return {
+    success: payload.success,
+    response:
+      typeof payload.response === 'string'
+        ? payload.response
+        : typeof payload.message === 'string'
+          ? payload.message
+          : null,
+    citations: Array.isArray(payload.citations) ? payload.citations : [],
+    conversation_ulid: payload.conversation_ulid ?? null,
+    actions: payload.actions,
+    token_usage: payload.token_usage,
+    pending_approval: payload.pending_approval ?? null,
+  };
+}
+
+/**
+ * @param {(path: string, init?: RequestInit) => Promise<unknown>} apiFetch
+ * @param {'usable' | 'manageable'} [scope]
+ */
+export async function agentsList(apiFetch, scope = 'usable') {
+  return apiFetch(agentsListPath(scope));
+}
+
+/**
+ * @param {(path: string, init?: RequestInit) => Promise<unknown>} apiFetch
+ * @param {{
+ *   agent_ulid: string;
+ *   message: string;
+ *   conversation_ulid?: string;
+ *   project_id?: number;
+ *   notebook_id?: number;
+ * }} args
+ */
+export async function agentChat(apiFetch, args) {
+  const data = await apiFetch(agentChatPath(args.agent_ulid), {
+    method: 'POST',
+    body: JSON.stringify(buildAgentChatBody(args)),
+  });
+  return formatAgentChatResponse(data);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "innov-mcp-tasks",
-  "version": "1.3.0",
-  "description": "MCP stdio — tarefas e anotações Innov (INNOV_API_BASE_URL + token Sanctum)",
+  "version": "1.5.0",
+  "description": "MCP stdio — tarefas, anotações e agentes de IA Innov (INNOV_API_BASE_URL + token Sanctum)",
   "type": "module",
   "main": "index.mjs",
   "bin": {
@@ -9,13 +9,14 @@
   },
   "files": [
     "index.mjs",
+    "lib/**",
     "README.md",
     ".env.example",
     "scripts/postinstall-notice.mjs"
   ],
   "scripts": {
     "start": "node index.mjs",
-    "test": "node --check index.mjs",
+    "test": "node --check index.mjs && node --test test/*.test.mjs",
     "prepack": "node --check index.mjs",
     "postinstall": "node ./scripts/postinstall-notice.mjs"
   },
@@ -28,6 +29,8 @@
     "tasks",
     "notes",
     "annotations",
+    "ai-agents",
+    "agents",
     "innov"
   ],
   "author": "",