@aiconnect/agentjobs-mcp 1.0.9 → 1.1.0

package/build/tools/create_job.js

@@ -1,71 +1,56 @@
 import { z } from 'zod';
-import axios from 'axios';
+import agentJobsClient from '../lib/agentJobsClient.js';
 import { config } from '../config.js';
-/**
- * Lightweight Agent‑Jobs creator.
- * Only the essentials are required to keep the contract LLM‑friendly.
- */
+import { flexibleDateTimeSchema } from '../utils/schemas.js';
+import { mcpDebugger, withTiming } from '../utils/debugger.js';
 export default (server) => {
-    server.tool('create_job', 'Create a new Agent Job with the minimal set of fields.', {
-        // ─────────────────────────────────────────────────────────────────────────┐
-        // Required
-        // ─────────────────────────────────────────────────────────────────────────┘
-        job_type_id: z
-            .string()
-            .describe('ID of the job type (e.g. "mood-monitor")'),
-        target_channel: z
-            .object({
-            platform: z
-                .enum(['whatsapp', 'slack', 'web'])
-                .describe('Destination platform.'),
-            code: z
-                .string()
-                .describe('Channel identifier, phone number, or user ID.'),
-            org_id: z
+    server.registerTool('create_job', {
+        description: 'Create a new Agent Job with the minimal set of fields.',
+        annotations: {
+            title: 'Create Agent Job'
+        },
+        inputSchema: {
+            // Required fields
+            job_type_id: z
                 .string()
+                .describe('ID of the job type (e.g. "mood-monitor")'),
+            target_channel: z
+                .object({
+                platform: z
+                    .enum(['whatsapp', 'slack', 'web'])
+                    .describe('Destination platform.'),
+                code: z
+                    .string()
+                    .describe('Channel identifier, phone number, or user ID.'),
+                org_id: z
+                    .string()
+                    .optional()
+                    .describe('Org ID – defaults to config.DEFAULT_ORG_ID')
+            })
+                .describe('Where the agent will communicate.'),
+            params: z
+                .record(z.any())
                 .optional()
-                .describe('Org ID – defaults to config.DEFAULT_ORG_ID')
-        })
-            .describe('Where the agent will communicate.'),
-        params: z
-            .record(z.any())
-            .optional()
-            .describe('Free‑form params passed to the agent'),
-        scheduled_at: z
-            .string()
-            .datetime({ message: 'Use ISO‑8601' })
-            .optional()
-            .describe('Schedule the job to run later')
-    }, 
-    // ───────────────────────────────────────────────────────────────────────────┐
-    // Implementation                                                             │
-    // ───────────────────────────────────────────────────────────────────────────┘
-    async (params) => {
-        const { AICONNECT_API_URL: apiUrl, AICONNECT_API_KEY: apiKey, DEFAULT_ORG_ID } = config;
-        if (!apiUrl) {
-            return {
-                content: [{
-                        type: "text",
-                        text: "Error: API URL is not configured. Please set AICONNECT_API_URL environment variable."
-                    }]
-            };
-        }
-        if (!apiKey) {
-            return {
-                content: [{
-                        type: "text",
-                        text: "Error: API Key is not configured. Please set AICONNECT_API_KEY environment variable."
-                    }]
-            };
+                .describe('Free‑form params passed to the agent'),
+            scheduled_at: flexibleDateTimeSchema
+                .optional()
+                .describe('Schedule the job to run later')
         }
+    }, async (params) => {
+        mcpDebugger.toolCall("create_job", params);
         // Fall back to default org if none supplied.
-        params.target_channel.org_id ??= DEFAULT_ORG_ID;
+        params.target_channel.org_id ??= config.DEFAULT_ORG_ID;
+        mcpDebugger.debug("Job creation payload", {
+            job_type_id: params.job_type_id,
+            target_channel: params.target_channel,
+            scheduled_at: params.scheduled_at,
+            paramsCount: params.params ? Object.keys(params.params).length : 0
+        });
         try {
-            const res = await axios.post(`${apiUrl}/services/agent-jobs`, params, {
-                headers: { Authorization: `Bearer ${apiKey}` }
-            });
-            const jobId = res.data?.data?.id ?? res.data?.id ?? 'unknown';
-            return {
+            const res = await withTiming(() => agentJobsClient.post('/services/agent-jobs', params), "create_job API call");
+            const jobId = res.id ?? 'unknown';
+            mcpDebugger.debug("Job creation response", { jobId, fullResponse: res });
+            const result = {
                 content: [
                     {
                         type: 'text',
@@ -73,21 +58,16 @@ export default (server) => {
                     }
                 ]
             };
+            mcpDebugger.toolResponse("create_job", { jobId });
+            return result;
         }
         catch (error) {
-            let errorMessage = `Failed to create job.`;
-            if (axios.isAxiosError(error) && error.response) {
-                const apiError = error.response.data?.message || error.response.data?.error || JSON.stringify(error.response.data);
-                errorMessage = `API Error (${error.response.status}): ${apiError || error.message}`;
-            }
-            else if (error instanceof Error) {
-                errorMessage = `Error: ${error.message}`;
-            }
+            mcpDebugger.toolError("create_job", error);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: errorMessage
+                        text: `Error creating job: ${error.message}`
                     }
                 ]
             };

package/build/tools/get_job.js

@@ -1,51 +1,32 @@
 import { z } from 'zod';
-import axios from 'axios';
-import { config } from '../config.js';
+import agentJobsClient from '../lib/agentJobsClient.js';
 import { formatJobDetails } from '../utils/formatters.js';
+import { mcpDebugger, withTiming } from '../utils/debugger.js';
 export default (server) => {
-    server.tool('get_job', 'Retrieves an agent job by its ID.', {
-        job_id: z.string({
-            description: "The unique identifier of the job you want to retrieve. Example: 'job-12345'."
-        }),
-        org_id: z
-            .string({
-            description: "The organization ID. Example: 'aiconnect'."
-        })
-            .optional()
+    server.registerTool('get_job', {
+        description: 'Retrieves an agent job by its ID.',
+        annotations: {
+            title: 'Get Agent Job'
+        },
+        inputSchema: {
+            job_id: z.string({
+                description: "The unique identifier of the job you want to retrieve. Example: 'job-12345'."
+            }),
+            org_id: z
+                .string({
+                description: "The organization ID. Example: 'aiconnect'."
+            })
+                .optional()
+        }
     }, async (params) => {
+        mcpDebugger.toolCall("get_job", params);
         const { job_id } = params;
-        const apiUrl = config.AICONNECT_API_URL;
-        const apiKey = config.AICONNECT_API_KEY;
-        if (!apiUrl) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: 'Error: API URL is not configured. Please set AICONNECT_API_URL environment variable.'
-                    }
-                ]
-            };
-        }
-        if (!apiKey) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: 'Error: API Key is not configured. Please set AICONNECT_API_KEY environment variable.'
-                    }
-                ]
-            };
-        }
-        const endpoint = `${apiUrl}/services/agent-jobs/${job_id}${params.org_id ? `?org_id=${params.org_id}` : ''}`;
-        const headers = {
-            Authorization: `Bearer ${apiKey}`
-        };
+        const endpoint = `/services/agent-jobs/${job_id}${params.org_id ? `?org_id=${params.org_id}` : ''}`;
+        mcpDebugger.debug("Built endpoint", { endpoint, job_id, org_id: params.org_id });
         try {
-            const response = await axios.get(endpoint, {
-                headers
-            });
-            const job = response.data?.data || response.data;
-            return {
+            const job = await withTiming(() => agentJobsClient.get(endpoint), "get_job API call");
+            mcpDebugger.debug("Raw API response", { job });
+            const result = {
                 content: [
                     {
                         type: 'text',
@@ -53,28 +34,19 @@ export default (server) => {
                     }
                 ]
             };
+            mcpDebugger.toolResponse("get_job", {
+                jobId: job_id,
+                resultLength: result.content[0].text.length
+            });
+            return result;
         }
         catch (error) {
-            let errorMessage = `Failed to retrieve job ${job_id}.`;
-            let errorDetails = {};
-            if (axios.isAxiosError(error) && error.response) {
-                const apiError = error.response.data?.message ||
-                    error.response.data?.error ||
-                    JSON.stringify(error.response.data);
-                errorMessage = `API Error (${error.response.status}): ${apiError || error.message}`;
-                errorDetails = {
-                    status: error.response.status,
-                    data: error.response.data
-                };
-            }
-            else if (error instanceof Error) {
-                errorMessage = `Error: ${error.message}`;
-            }
+            mcpDebugger.toolError("get_job", error);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: errorMessage
+                        text: `Error getting job: ${error.message}`
                     }
                 ]
             };

package/build/tools/get_job_type.js

@@ -1,79 +1,63 @@
 import { z } from 'zod';
-import axios from 'axios';
+import agentJobsClient from '../lib/agentJobsClient.js';
 import { config } from '../config.js';
 import { formatJobTypeDetails } from '../utils/formatters.js';
+import { mcpDebugger, withTiming } from '../utils/debugger.js';
 export default (server) => {
-    server.tool('get_job_type', 'Retrieves an agent job type by its ID.', {
-        job_type_id: z.string({
-            description: "The unique identifier of the job type you want to retrieve. Example: 'mood-monitor'."
-        }),
-        org_id: z.string({
-            description: "The organization ID. Example: 'aiconnect'."
-        }).optional()
+    server.registerTool('get_job_type', {
+        description: 'Retrieves an agent job type by its ID.',
+        annotations: {
+            title: 'Get Job Type Configuration'
+        },
+        inputSchema: {
+            job_type_id: z.string({
+                description: "The unique identifier of the job type you want to retrieve. Example: 'mood-monitor'."
+            }),
+            org_id: z.string({
+                description: "The organization ID. Example: 'aiconnect'."
+            }).optional()
+        }
     }, async (params) => {
+        mcpDebugger.toolCall("get_job_type", params);
         const { job_type_id } = params;
         const org_id = params.org_id || config.DEFAULT_ORG_ID;
-        const apiUrl = config.AICONNECT_API_URL;
-        const apiKey = config.AICONNECT_API_KEY;
-        if (!apiUrl) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: 'Error: API URL is not configured. Please set AICONNECT_API_URL environment variable.'
-                    }
-                ]
-            };
-        }
-        if (!apiKey) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: 'Error: API Key is not configured. Please set AICONNECT_API_KEY environment variable.'
-                    }
-                ]
-            };
-        }
-        const endpoint = `${apiUrl}/organizations/${org_id}/agent-jobs-type/${job_type_id}`;
-        const headers = {
-            Authorization: `Bearer ${apiKey}`
-        };
+        const endpoint = `/organizations/${org_id}/agent-jobs-type/${job_type_id}`;
+        mcpDebugger.debug("Job type request", {
+            endpoint,
+            job_type_id,
+            org_id,
+            usingDefaultOrg: !params.org_id
+        });
         try {
-            const response = await axios.get(endpoint, {
-                headers
-            });
-            const jobType = response.data?.data || response.data;
-            return {
+            const response = await withTiming(() => agentJobsClient.get(endpoint), "get_job_type API call");
+            mcpDebugger.debug("Job type raw response", { response });
+            // The API returns { data: {...}, meta: {...} } but agentJobsClient should extract data
+            // However, let's be defensive and handle both cases
+            const jobTypeData = response?.data ? response.data : response;
+            mcpDebugger.debug("Job type extracted data", { jobTypeData });
+            const result = {
                 content: [
                     {
                         type: 'text',
-                        text: formatJobTypeDetails(jobType)
+                        text: formatJobTypeDetails(jobTypeData)
                     }
                 ]
             };
+            mcpDebugger.toolResponse("get_job_type", {
+                job_type_id,
+                org_id,
+                resultLength: result.content[0].text.length,
+                hasData: !!jobTypeData
+            });
+            return result;
         }
         catch (error) {
-            let errorMessage = `Failed to retrieve job type ${job_type_id}.`;
-            let errorDetails = {};
-            if (axios.isAxiosError(error) && error.response) {
-                const apiError = error.response.data?.message ||
-                    error.response.data?.error ||
-                    JSON.stringify(error.response.data);
-                errorMessage = `API Error (${error.response.status}): ${apiError || error.message}`;
-                errorDetails = {
-                    status: error.response.status,
-                    data: error.response.data
-                };
-            }
-            else if (error instanceof Error) {
-                errorMessage = `Error: ${error.message}`;
-            }
+            mcpDebugger.toolError("get_job_type", error);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: errorMessage
+                        text: `Error getting job type: ${error.message}`
                     }
                 ]
             };

package/build/tools/get_jobs_stats.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import agentJobsClient from "../lib/agentJobsClient.js";
+import { formatJobStats } from "../utils/formatters.js";
+import { flexibleDateTimeSchema } from "../utils/schemas.js";
+import { mcpDebugger, withTiming } from "../utils/debugger.js";
+const jobStatusSchema = z.enum([
+    "waiting",
+    "scheduled",
+    "running",
+    "completed",
+    "failed",
+    "canceled"
+]);
+export default (server) => {
+    server.registerTool("get_jobs_stats", {
+        description: "Get aggregated statistics for agent jobs without retrieving individual job data. Optimized for dashboards and monitoring with minimal network overhead.",
+        annotations: {
+            title: "Get Job Statistics"
+        },
+        inputSchema: {
+            org_id: z.string().optional().describe("Filter by organization ID."),
+            scheduled_at_gte: flexibleDateTimeSchema.optional().describe("Start of period (ISO 8601)"),
+            scheduled_at_lte: flexibleDateTimeSchema.optional().describe("End of period (ISO 8601)"),
+            created_at_gte: flexibleDateTimeSchema.optional().describe("Filter for jobs created at or after a specific time (ISO 8601)."),
+            created_at_lte: flexibleDateTimeSchema.optional().describe("Filter for jobs created at or before a specific time (ISO 8601)."),
+            job_type_id: z.string().optional().describe("Job type filter"),
+            channel_code: z.string().optional().describe("Channel filter"),
+            tags: z.string().optional().describe("Tags filter (comma-separated)"),
+            status: jobStatusSchema.optional().describe("Status filter"),
+        }
+    }, async (params) => {
+        mcpDebugger.toolCall("get_jobs_stats", params);
+        try {
+            const response = await withTiming(() => agentJobsClient.getStats(params), "get_jobs_stats API call");
+            const stats = response.meta?.stats || {};
+            const filters = response.meta?.filters || {};
+            mcpDebugger.debug("Raw API response", { stats, filters });
+            const result = {
+                content: [{
+                        type: "text",
+                        text: formatJobStats(stats, filters),
+                    }]
+            };
+            mcpDebugger.toolResponse("get_jobs_stats", result);
+            return result;
+        }
+        catch (error) {
+            mcpDebugger.toolError("get_jobs_stats", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error getting job stats: ${error.message}`,
+                    }],
+            };
+        }
+    });
+};

package/build/tools/list_jobs.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
-import axios from 'axios';
-import { config } from '../config.js';
+import agentJobsClient from "../lib/agentJobsClient.js";
 import { formatJobList } from "../utils/formatters.js";
+import { flexibleDateTimeSchema } from "../utils/schemas.js";
+import { mcpDebugger, withTiming } from "../utils/debugger.js";
 // Define the schema for job status based on docs/agent-jobs-api.md:246-251
 const jobStatusSchema = z.enum([
     "waiting",
@@ -12,42 +13,28 @@ const jobStatusSchema = z.enum([
     "canceled"
 ]);
 export default (server) => {
-    server.tool("list_jobs", "Retrieves a list of agent jobs, with optional filters and pagination.", {
-        org_id: z.string().optional().describe("Filter by organization ID. If not provided, the default from the environment is used."),
-        status: jobStatusSchema.optional().describe("Filter by job status. Possible values are: 'waiting', 'scheduled', 'running', 'completed', 'failed', 'canceled'."),
-        scheduled_at: z.string().datetime().optional().describe("Filter by the exact scheduled time in ISO 8601 format (e.g., '2024-07-23T10:00:00Z')."),
-        scheduled_at_gte: z.string().datetime().optional().describe("Filter for jobs scheduled at or after a specific time (ISO 8601)."),
-        scheduled_at_lte: z.string().datetime().optional().describe("Filter for jobs scheduled at or before a specific time (ISO 8601)."),
-        created_at_gte: z.string().datetime().optional().describe("Filter for jobs created at or after a specific time (ISO 8601)."),
-        created_at_lte: z.string().datetime().optional().describe("Filter for jobs created at or before a specific time (ISO 8601)."),
-        job_type_id: z.string().optional().describe("Filter by the specific job type ID (e.g., 'daily-report')."),
-        channel_code: z.string().optional().describe("Filter by the channel code (e.g., 'C123456' for a Slack channel)."),
-        limit: z.number().int().positive().optional().describe("Maximum number of jobs to return (e.g.,20). Default is 20."),
-        offset: z.number().int().nonnegative().optional().describe("Number of jobs to skip, used for pagination. Default is 0."),
-        sort: z.string().optional().describe("Field to sort by and direction. Format is 'field:direction'. Example: 'created_at:desc'."),
-    }, async (params) => {
-        const apiUrl = config.AICONNECT_API_URL;
-        const apiKey = config.AICONNECT_API_KEY;
-        if (!apiUrl) {
-            return {
-                content: [{
-                        type: "text",
-                        text: "Error: API URL is not configured. Please set AICONNECT_API_URL environment variable."
-                    }]
-            };
+    server.registerTool("list_jobs", {
+        description: "Retrieves a list of agent jobs, with optional filters and pagination.",
+        annotations: {
+            title: "List Agent Jobs"
+        },
+        inputSchema: {
+            org_id: z.string().optional().describe("Filter by organization ID. If not provided, the default from the environment is used."),
+            status: jobStatusSchema.optional().describe("Filter by job status. Possible values are: 'waiting', 'scheduled', 'running', 'completed', 'failed', 'canceled'."),
+            scheduled_at: flexibleDateTimeSchema.optional().describe("Filter by the exact scheduled time in ISO 8601 format (e.g., '2024-07-23T10:00:00Z')."),
+            scheduled_at_gte: flexibleDateTimeSchema.optional().describe("Filter for jobs scheduled at or after a specific time (ISO 8601)."),
+            scheduled_at_lte: flexibleDateTimeSchema.optional().describe("Filter for jobs scheduled at or before a specific time (ISO 8601)."),
+            created_at_gte: flexibleDateTimeSchema.optional().describe("Filter for jobs created at or after a specific time (ISO 8601)."),
+            created_at_lte: flexibleDateTimeSchema.optional().describe("Filter for jobs created at or before a specific time (ISO 8601)."),
+            job_type_id: z.string().optional().describe("Filter by the specific job type ID (e.g., 'daily-report')."),
+            channel_code: z.string().optional().describe("Filter by the channel code (e.g., 'C123456' for a Slack channel)."),
+            limit: z.number().int().positive().optional().describe("Maximum number of jobs to return (e.g.,20). Default is 20."),
+            offset: z.number().int().nonnegative().optional().describe("Number of jobs to skip, used for pagination. Default is 0."),
+            sort: z.string().optional().describe("Field to sort by and direction. Format is 'field:direction'. Example: 'created_at:desc'.")
         }
-        if (!apiKey) {
-            return {
-                content: [{
-                        type: "text",
-                        text: "Error: API Key is not configured. Please set AICONNECT_API_KEY environment variable."
-                    }]
-            };
-        }
-        const endpoint = `${apiUrl}/services/agent-jobs`;
-        const headers = {
-            "Authorization": `Bearer ${apiKey}`,
-        };
+    }, async (params) => {
+        mcpDebugger.toolCall("list_jobs", params);
+        const endpoint = `/services/agent-jobs`;
         // Build query parameters object from provided params
         const queryParams = {};
         for (const [key, value] of Object.entries(params)) {
@@ -55,38 +42,36 @@ export default (server) => {
                 queryParams[key] = value;
             }
         }
+        mcpDebugger.debug("Built query parameters", { endpoint, queryParams });
         try {
-            const response = await axios.get(endpoint, {
-                headers,
-                params: queryParams,
+            const apiResponse = await withTiming(() => agentJobsClient.getWithMeta(endpoint, queryParams), "list_jobs API call");
+            // Access the full API response structure
+            const jobs = apiResponse.data || [];
+            const meta = apiResponse.meta || {};
+            mcpDebugger.debug("Raw API response", {
+                fullResponse: apiResponse,
+                jobsCount: jobs.length,
+                meta,
+                firstJob: jobs[0] || null
             });
-            const jobs = response.data?.data || [];
-            const meta = response.data?.meta || {};
-            return {
+            const result = {
                 content: [{
                         type: "text",
                         text: formatJobList(jobs, meta),
                     }]
             };
+            mcpDebugger.toolResponse("list_jobs", {
+                jobsReturned: jobs.length,
+                resultLength: result.content[0].text.length
+            });
+            return result;
         }
         catch (error) {
-            let errorMessage = `Failed to list jobs.`;
-            let errorDetails = {};
-            if (axios.isAxiosError(error) && error.response) {
-                const apiError = error.response.data?.message || error.response.data?.error || JSON.stringify(error.response.data);
-                errorMessage = `API Error (${error.response.status}): ${apiError || error.message}`;
-                errorDetails = {
-                    status: error.response.status,
-                    data: error.response.data
-                };
-            }
-            else if (error instanceof Error) {
-                errorMessage = `Error: ${error.message}`;
-            }
+            mcpDebugger.toolError("list_jobs", error);
             return {
                 content: [{
                         type: "text",
-                        text: errorMessage,
+                        text: `Error listing jobs: ${error.message}`,
                     }],
             };
         }

package/build/utils/debugger.js

@@ -0,0 +1,74 @@
+export class MCPDebugger {
+    isDebugEnabled;
+    constructor(enabled = process.env.MCP_DEBUG === 'true') {
+        this.isDebugEnabled = enabled;
+    }
+    formatLog(level, message, data) {
+        if (!this.isDebugEnabled)
+            return;
+        const timestamp = new Date().toISOString();
+        const prefix = `[MCP-DEBUG ${timestamp}] [${level.toUpperCase()}]`;
+        console.error(`${prefix} ${message}`);
+        if (data !== undefined) {
+            console.error(`${prefix} Data:`, JSON.stringify(data, null, 2));
+        }
+    }
+    info(message, data) {
+        this.formatLog('info', message, data);
+    }
+    warn(message, data) {
+        this.formatLog('warn', message, data);
+    }
+    error(message, data) {
+        this.formatLog('error', message, data);
+    }
+    debug(message, data) {
+        this.formatLog('debug', message, data);
+    }
+    // Helper para debugar chamadas de tools
+    toolCall(toolName, args) {
+        this.info(`Tool called: ${toolName}`, { args });
+    }
+    toolResponse(toolName, response, duration) {
+        this.info(`Tool response: ${toolName}`, {
+            response: typeof response === 'object' ? response : { value: response },
+            duration: duration ? `${duration}ms` : undefined
+        });
+    }
+    toolError(toolName, error) {
+        this.error(`Tool error: ${toolName}`, {
+            error: error.message || error,
+            stack: error.stack
+        });
+    }
+    // Helper para debugar requisições HTTP
+    httpRequest(method, url, data) {
+        this.debug(`HTTP ${method.toUpperCase()} ${url}`, data);
+    }
+    httpResponse(method, url, status, data) {
+        this.debug(`HTTP Response ${method.toUpperCase()} ${url} [${status}]`, data);
+    }
+    httpError(method, url, error) {
+        this.error(`HTTP Error ${method.toUpperCase()} ${url}`, error);
+    }
+}
+// Instância global do debugger
+export const mcpDebugger = new MCPDebugger();
+// Helper function para medir tempo de execução
+export function withTiming(fn, name) {
+    return new Promise(async (resolve, reject) => {
+        const start = Date.now();
+        mcpDebugger.debug(`Starting ${name}`);
+        try {
+            const result = await fn();
+            const duration = Date.now() - start;
+            mcpDebugger.debug(`Completed ${name} in ${duration}ms`);
+            resolve(result);
+        }
+        catch (error) {
+            const duration = Date.now() - start;
+            mcpDebugger.error(`Failed ${name} after ${duration}ms`, error);
+            reject(error);
+        }
+    });
+}