innov-mcp-tasks 1.4.0 → 1.5.0

package/README.md

@@ -75,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();
@@ -757,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',
   {
@@ -776,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.4.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": "",