innov-mcp-tasks 1.4.0 → 1.6.0

package/README.md

@@ -75,6 +75,20 @@ 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`
+
+### Infraestrutura / servidores (SPEC-022)
+
+- `servers_dashboard` — resumo online/offline, alertas e aplicações (`GET /server-monitoring/dashboard`)
+- `servers_list` — lista servidores com métricas; filtros opcionais `status`, `search`
+- `server_get` — detalhe por `server_ulid` (métricas + aplicações com tipo/versão)
+- `server_alerts` — alertas ativos de CPU, RAM, disco e aplicações
+- `server_applications_search` — busca apps (`search`, `type`, `server_ulid`, `env_production`, `debug_enabled`, paginação)
 
 ## Publicar no npm (mantenedor)
 

package/index.mjs

@@ -6,6 +6,14 @@ 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';
+import {
+  serverAlerts,
+  serverApplicationsSearch,
+  serverGet,
+  serversDashboard,
+  serversList,
+} from './lib/serverMonitoring.mjs';
 
 const base = (process.env.INNOV_API_BASE_URL || '').replace(/\/$/, '');
 const token = (process.env.INNOV_API_TOKEN || '').trim();
@@ -757,6 +765,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 +818,154 @@ 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));
+    }
+  },
+);
+
+server.registerTool(
+  'servers_dashboard',
+  {
+    description:
+      'Resumo do monitoramento de servidores (GET /server-monitoring/dashboard): online/offline, alertas e aplicações.',
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      const data = await serversDashboard(apiFetch);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'servers_list',
+  {
+    description:
+      'Lista servidores monitorados com métricas recentes (GET /server-monitoring/servers).',
+    inputSchema: {
+      status: z.enum(['active', 'inactive']).optional(),
+      search: z.string().optional().describe('Hostname, IP ou descrição'),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await serversList(apiFetch, args);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'server_get',
+  {
+    description:
+      'Detalhe de um servidor: métricas, histórico e aplicações detectadas (GET /server-monitoring/servers/{ulid}).',
+    inputSchema: {
+      server_ulid: z.string().min(1).describe('ULID do servidor'),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await serverGet(apiFetch, args);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'server_alerts',
+  {
+    description:
+      'Alertas ativos de infraestrutura: CPU, RAM, disco e aplicações (GET /server-monitoring/alerts).',
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      const data = await serverAlerts(apiFetch);
+      return jsonText(data);
+    } catch (e) {
+      return jsonError(e instanceof Error ? e.message : String(e));
+    }
+  },
+);
+
+server.registerTool(
+  'server_applications_search',
+  {
+    description:
+      'Busca aplicações nos servidores: stack (laravel, vuejs…), versão, ambiente (GET /server-monitoring/applications/search).',
+    inputSchema: {
+      search: z.string().optional(),
+      type: z.string().optional().describe('laravel, vuejs, symfony, wordpress, etc.'),
+      server_ulid: z.string().optional(),
+      env_production: z.boolean().optional(),
+      debug_enabled: z.boolean().optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+      page: z.number().int().min(1).optional(),
+    },
+  },
+  async (args) => {
+    try {
+      const data = await serverApplicationsSearch(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/lib/serverMonitoring.mjs

@@ -0,0 +1,98 @@
+/** Helpers e handlers para ferramentas de monitoramento de servidores (SPEC-022). */
+
+/**
+ * @param {Record<string, string | number | boolean | undefined | null>} [params]
+ */
+export function serverMonitoringQueryString(params = {}) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    search.set(key, String(value));
+  }
+  const qs = search.toString();
+  return qs ? `?${qs}` : '';
+}
+
+export function serversDashboardPath() {
+  return '/api/v1/server-monitoring/dashboard';
+}
+
+/**
+ * @param {{ status?: string, search?: string }} [args]
+ */
+export function serversListPath(args = {}) {
+  return `/api/v1/server-monitoring/servers${serverMonitoringQueryString({
+    status: args.status,
+    search: args.search,
+  })}`;
+}
+
+/**
+ * @param {string} serverUlid
+ */
+export function serverGetPath(serverUlid) {
+  const trimmed = String(serverUlid ?? '').trim();
+  if (!trimmed) {
+    throw new Error('server_ulid é obrigatório');
+  }
+  return `/api/v1/server-monitoring/servers/${encodeURIComponent(trimmed)}`;
+}
+
+export function serverAlertsPath() {
+  return '/api/v1/server-monitoring/alerts';
+}
+
+/**
+ * @param {Record<string, string | number | boolean | undefined | null>} [args]
+ */
+export function serverApplicationsSearchPath(args = {}) {
+  const { limit, page, ...rest } = args;
+  return `/api/v1/server-monitoring/applications/search${serverMonitoringQueryString({
+    ...rest,
+    per_page: limit ?? rest.per_page,
+    page,
+  })}`;
+}
+
+/**
+ * @param {(path: string, init?: RequestInit) => Promise<unknown>} apiFetch
+ */
+export async function serversDashboard(apiFetch) {
+  return apiFetch(serversDashboardPath());
+}
+
+/**
+ * @param {(path: string, init?: RequestInit) => Promise<unknown>} apiFetch
+ * @param {{ status?: string, search?: string }} [args]
+ */
+export async function serversList(apiFetch, args = {}) {
+  const data = await apiFetch(serversListPath(args));
+  return data?.data ?? data;
+}
+
+/**
+ * @param {(path: string, init?: RequestInit) => Promise<unknown>} apiFetch
+ * @param {{ server_ulid: string }} args
+ */
+export async function serverGet(apiFetch, args) {
+  const data = await apiFetch(serverGetPath(args.server_ulid));
+  return data?.data ?? data;
+}
+
+/**
+ * @param {(path: string, init?: RequestInit) => Promise<unknown>} apiFetch
+ */
+export async function serverAlerts(apiFetch) {
+  const data = await apiFetch(serverAlertsPath());
+  return data?.data ?? data;
+}
+
+/**
+ * @param {(path: string, init?: RequestInit) => Promise<unknown>} apiFetch
+ * @param {Record<string, string | number | boolean | undefined | null>} [args]
+ */
+export async function serverApplicationsSearch(apiFetch, args = {}) {
+  return apiFetch(serverApplicationsSearchPath(args));
+}

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.6.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": "",