@aiconnect/agentjobs-mcp 1.1.0 → 1.2.0

package/build/config.js

@@ -3,9 +3,11 @@ export const config = {
     apiUrl: process.env.AICONNECT_API_URL || 'https://api.aiconnect.cloud/api/v0',
     apiKey: process.env.AICONNECT_API_KEY || '',
     defaultOrgId: process.env.DEFAULT_ORG_ID || 'aiconnect',
+    defaultTimezone: process.env.DEFAULT_TIMEZONE || 'UTC',
     debugMode: process.env.DEBUG === 'true',
     // Legacy compatibility
     AICONNECT_API_URL: process.env.AICONNECT_API_URL || 'https://api.aiconnect.cloud/api/v0',
     AICONNECT_API_KEY: process.env.AICONNECT_API_KEY || '',
-    DEFAULT_ORG_ID: process.env.DEFAULT_ORG_ID || 'aiconnect'
+    DEFAULT_ORG_ID: process.env.DEFAULT_ORG_ID || 'aiconnect',
+    DEFAULT_TIMEZONE: process.env.DEFAULT_TIMEZONE || 'UTC'
 };

package/build/config.test.js

@@ -0,0 +1,22 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+describe('config.defaultTimezone', () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+    afterEach(() => {
+        vi.unstubAllEnvs();
+        vi.resetModules();
+    });
+    it('reflects DEFAULT_TIMEZONE when set', async () => {
+        vi.stubEnv('DEFAULT_TIMEZONE', 'America/Sao_Paulo');
+        const { config } = await import('./config.js');
+        expect(config.defaultTimezone).toBe('America/Sao_Paulo');
+        expect(config.DEFAULT_TIMEZONE).toBe('America/Sao_Paulo');
+    });
+    it('falls back to UTC when DEFAULT_TIMEZONE is unset', async () => {
+        vi.stubEnv('DEFAULT_TIMEZONE', '');
+        const { config } = await import('./config.js');
+        expect(config.defaultTimezone).toBe('UTC');
+        expect(config.DEFAULT_TIMEZONE).toBe('UTC');
+    });
+});

package/build/index.js

@@ -7,8 +7,11 @@ import { InitializeRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import fs from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
-// Get package version
+import { mcpServerVersion } from "./utils/version.js";
+// Get package metadata (description/homepage/author come from package.json directly;
+// version comes from the shared helper to avoid duplication).
 const packageJson = JSON.parse(await import('fs').then(fs => fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8')));
+packageJson.version = mcpServerVersion;
 // CLI argument parsing
 const args = process.argv.slice(2);
 // Help text
@@ -51,6 +54,8 @@ if (args.includes('--config') || args.includes('-c')) {
     console.log('Current Configuration:');
     console.log(`  API URL: ${process.env.AICONNECT_API_URL || 'Not set'}`);
     console.log(`  API Key: ${process.env.AICONNECT_API_KEY ? '[SET]' : 'Not set'}`);
+    console.log(`  Default Org: ${process.env.DEFAULT_ORG_ID || 'aiconnect'}`);
+    console.log(`  Default Timezone: ${process.env.DEFAULT_TIMEZONE || 'UTC'}`);
     console.log(`  Node Version: ${process.version}`);
     console.log(`  MCP Server Version: ${packageJson.version}`);
     process.exit(0);
@@ -74,7 +79,9 @@ console.error(`[DEBUG] Server version: ${packageJson.version}`);
 console.error(`[DEBUG] Default capabilities: tools, resources, prompts`);
 // Intercept initialization to detect protocol version
 const originalSetRequestHandler = server.server.setRequestHandler.bind(server.server);
-// Override initialization handler to capture protocol version
+// Override initialization handler to capture protocol version.
+// The schema is cast to `any` to short-circuit a TS2589 ("excessively deep") error
+// from generic Zod inference in @modelcontextprotocol/sdk's setRequestHandler signature.
 server.server.setRequestHandler(InitializeRequestSchema, async (request) => {
     const initParams = request.params;
     clientProtocolVersion = initParams.protocolVersion || "2024-11-05";

package/build/lib/agentJobsClient.js

@@ -31,6 +31,17 @@ class AgentJobsClient {
             this.handleError(error);
         }
     }
+    async listJobTypes(orgId, options = {}) {
+        const params = {
+            enrich: 'emoji',
+            limit: options.limit ?? 100,
+            sort: options.sort ?? 'name:asc'
+        };
+        if (options.offset !== undefined) {
+            params.offset = options.offset;
+        }
+        return (await this.getWithMeta(`/organizations/${orgId}/agent-jobs-type`, params));
+    }
     async getStats(filters = {}) {
         const params = {
             ...filters,

package/build/tools/cancel_job.js

@@ -3,6 +3,7 @@ import agentJobsClient from "../lib/agentJobsClient.js";
 import { formatJobSummary } from '../utils/formatters.js';
 import { mcpDebugger, withTiming } from '../utils/debugger.js';
 export default (server) => {
+    // @ts-expect-error TS2589: registerTool generic Zod inference exceeds TS depth limit with this schema.
     server.registerTool("cancel_job", {
         description: "Cancels an agent job by its ID.",
         annotations: {
@@ -10,9 +11,11 @@ export default (server) => {
         },
         inputSchema: {
             job_id: z.string({
-                description: "The unique identifier of the job to be canceled. Example: 'job-12345'.",
+                description: "The unique identifier of the job to be canceled. Example: 'job-12345'."
             }),
-            reason: z.string().optional().describe("An optional reason explaining why the job is being canceled."),
+            reason: z.string({
+                description: "An optional reason explaining why the job is being canceled."
+            }).optional()
         }
     }, async (params) => {
         mcpDebugger.toolCall("cancel_job", params);

package/build/tools/create_job.js

@@ -32,7 +32,7 @@ export default (server) => {
                 .record(z.any())
                 .optional()
                 .describe('Free‑form params passed to the agent'),
-            scheduled_at: flexibleDateTimeSchema
+            scheduled_at: flexibleDateTimeSchema()
                 .optional()
                 .describe('Schedule the job to run later')
         }

package/build/tools/get_context.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import agentJobsClient from '../lib/agentJobsClient.js';
+import { config } from '../config.js';
+import { formatContext } from '../utils/formatters.js';
+import { mcpServerVersion } from '../utils/version.js';
+import { mcpDebugger, withTiming } from '../utils/debugger.js';
+export default (server) => {
+    server.registerTool('get_context', {
+        description: 'Returns the MCP server runtime context: local defaults (org_id, timezone, API URL, server version) plus the list of agent job types available in the effective organization. Designed to be the first call an LLM client makes — surfaces what would otherwise be invisible env vars and avoids guessing valid job type IDs before calling create_job.',
+        annotations: {
+            title: 'Get MCP Server Runtime Context'
+        },
+        inputSchema: {
+            org_id: z
+                .string()
+                .optional()
+                .describe('Override DEFAULT_ORG_ID for this call (introspect a different org without restarting the server)')
+        }
+    }, async (params) => {
+        mcpDebugger.toolCall('get_context', params);
+        const effectiveOrgId = params.org_id || config.DEFAULT_ORG_ID;
+        const localConfig = {
+            org_id: effectiveOrgId,
+            timezone: config.DEFAULT_TIMEZONE,
+            api_url: config.AICONNECT_API_URL,
+            server_version: mcpServerVersion
+        };
+        let jobTypes;
+        let total;
+        let jobTypesError;
+        try {
+            const response = await withTiming(() => agentJobsClient.listJobTypes(effectiveOrgId), 'get_context.listJobTypes API call');
+            jobTypes = (response?.data ?? []).map((jt) => ({
+                id: jt.id,
+                name: jt.name,
+                description: jt.description,
+                emoji: jt.emoji
+            }));
+            total = response?.meta?.total ?? jobTypes.length;
+        }
+        catch (error) {
+            jobTypesError = error?.message ?? String(error);
+            mcpDebugger.toolError('get_context.listJobTypes', error);
+        }
+        const text = formatContext({ localConfig, jobTypes, total, jobTypesError });
+        mcpDebugger.toolResponse('get_context', {
+            org_id: effectiveOrgId,
+            jobTypesCount: jobTypes?.length,
+            hasError: !!jobTypesError,
+            resultLength: text.length
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text
+                }
+            ]
+        };
+    });
+};

package/build/tools/get_jobs_stats.js

@@ -3,42 +3,32 @@ 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.",
+        description: "Returns aggregated job counts broken down by status (waiting/scheduled/running/completed/failed/canceled) plus a summary (total, success rate, active, completion rate). To filter to a single status, use `list_jobs` with `status=` instead — this tool intentionally does not expose a `status` filter because the upstream stats endpoint ignores it (the breakdown is itself by status). Filters available here narrow the universe along orthogonal dimensions: `job_type_id`, `channel_code`, `tags`, `scheduled_at_*`, `created_at_*`. Result-code and duration aggregates are not yet available; for those today, fall back to `list_jobs` and aggregate client-side. 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)."),
+            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 });
+            mcpDebugger.debug("Raw API response", { stats, appliedFilters: params });
             const result = {
                 content: [{
                         type: "text",
-                        text: formatJobStats(stats, filters),
+                        text: formatJobStats(stats, params),
                     }]
             };
             mcpDebugger.toolResponse("get_jobs_stats", result);

package/build/tools/list_jobs.js

@@ -21,11 +21,11 @@ export default (server) => {
         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)."),
+            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."),
@@ -54,10 +54,11 @@ export default (server) => {
                 meta,
                 firstJob: jobs[0] || null
             });
+            const offset = typeof params.offset === 'number' ? params.offset : 0;
             const result = {
                 content: [{
                         type: "text",
-                        text: formatJobList(jobs, meta),
+                        text: formatJobList(jobs, meta, offset),
                     }]
             };
             mcpDebugger.toolResponse("list_jobs", {

package/build/utils/formatters.js

@@ -216,17 +216,33 @@ export function formatJobSummary(job) {
 }
 /**
  * Formata a resposta para a lista de jobs.
+ *
+ * `meta` é obrigatório e os três campos (`count`, `limit`, `total`) precisam
+ * ser numéricos — confirmado empiricamente que o backend sempre os retorna em
+ * `/services/agent-jobs`. Falha explícita aqui é preferível a inventar um
+ * footer com valores inferidos, pois isso recriaria a ambiguidade
+ * "page count vs total" que esta tool deveria eliminar.
+ *
  * @param jobs - Um array de jobs.
- * @param pagination - O objeto de paginação.
+ * @param meta - O objeto `meta` retornado pelo backend.
+ * @param offset - O `offset` que a tool enviou na requisição (default 0).
  * @returns Uma string formatada com a lista de resumos de jobs.
  */
-export function formatJobList(jobs, pagination) {
-    if (!jobs || jobs.length === 0) {
-        return "No jobs found for the given criteria.";
+export function formatJobList(jobs, meta, offset = 0) {
+    if (!meta || typeof meta.count !== 'number' || typeof meta.limit !== 'number' || typeof meta.total !== 'number') {
+        throw new Error('formatJobList: meta is required with numeric `count`, `limit`, and `total`. ' +
+            `Received: ${JSON.stringify(meta)}`);
     }
-    const jobSummaries = jobs.map(job => formatJobSummary(job)).join('\n\n');
-    const paginationSummary = `Page: ${Math.floor((pagination.offset || 0) / (pagination.limit || 20)) + 1} | Total Jobs: ${pagination.total}`;
-    return `Found ${jobs.length} jobs.\n\n${jobSummaries}\n\n${paginationSummary}`;
+    const safeJobs = jobs || [];
+    const { count, limit, total } = meta;
+    const hasMore = (offset + count) < total;
+    const nextOffset = hasMore ? offset + limit : null;
+    const footer = `Returned: ${count} | Total matching: ${total} | Has more: ${hasMore} | Next offset: ${nextOffset === null ? 'null' : nextOffset}`;
+    if (safeJobs.length === 0) {
+        return `Found 0 jobs.\n\n${footer}`;
+    }
+    const jobSummaries = safeJobs.map(job => formatJobSummary(job)).join('\n\n');
+    return `Found ${safeJobs.length} jobs.\n\n${jobSummaries}\n\n${footer}`;
 }
 // Schema for job type details
 const jobTypeSchema = z.object({
@@ -454,21 +470,81 @@ export function formatJobTypeSummary(jobType) {
         return JSON.stringify(jobType, null, 2);
     }
 }
-export function formatJobStats(stats, filters) {
+const DATE_FILTER_KEYS = [
+    'scheduled_at_gte',
+    'scheduled_at_lte',
+    'created_at_gte',
+    'created_at_lte',
+];
+const renderDateRange = (label, gte, lte) => {
+    if (gte === undefined && lte === undefined)
+        return null;
+    const left = gte !== undefined ? String(gte) : '(open)';
+    const right = lte !== undefined ? String(lte) : '(open)';
+    return `${label}: ${left} → ${right}`;
+};
+const CONTEXT_LABEL_WIDTH = 16; // "Server version: " == 16 chars
+const JOB_TYPE_ID_WIDTH = 22;
+const JOB_TYPE_EMOJI_WIDTH = 4;
+function padLabel(label) {
+    return (label + ':').padEnd(CONTEXT_LABEL_WIDTH, ' ');
+}
+function formatJobTypeLine(jt) {
+    const id = jt.id.padEnd(JOB_TYPE_ID_WIDTH, ' ');
+    const emoji = (jt.emoji ?? '').padEnd(JOB_TYPE_EMOJI_WIDTH, ' ');
+    const description = jt.description ? ` — ${jt.description}` : '';
+    return `  - ${id} ${emoji} ${jt.name}${description}`;
+}
+export function formatContext(input) {
+    const { localConfig, jobTypes, total, jobTypesError } = input;
+    const contextSection = [
+        'Context:',
+        `  ${padLabel('Org ID')} ${localConfig.org_id}`,
+        `  ${padLabel('Timezone')} ${localConfig.timezone}`,
+        `  ${padLabel('API URL')} ${localConfig.api_url}`,
+        `  ${padLabel('Server version')} ${localConfig.server_version}`
+    ].join('\n');
+    let jobsSection;
+    if (jobTypesError !== undefined) {
+        jobsSection = `Job types: unavailable (error: ${jobTypesError})`;
+    }
+    else if (jobTypes === undefined) {
+        jobsSection = 'Job types: unavailable (error: unknown)';
+    }
+    else {
+        const totalCount = typeof total === 'number' ? total : jobTypes.length;
+        if (totalCount === 0) {
+            jobsSection = 'Job types available (0):\n  (no job types registered for this org)';
+        }
+        else {
+            const lines = jobTypes.map(formatJobTypeLine);
+            let trailing = '';
+            if (totalCount > jobTypes.length) {
+                const missing = totalCount - jobTypes.length;
+                trailing = `\n  … and ${missing} more job types not shown`;
+            }
+            jobsSection = `Job types available (${totalCount}):\n${lines.join('\n')}${trailing}`;
+        }
+    }
+    return `${contextSection}\n\n${jobsSection}`;
+}
+export function formatJobStats(stats, appliedFilters = {}) {
     const { waiting = 0, running = 0, completed = 0, failed = 0, canceled = 0, scheduled = 0, } = stats.status;
     const totalJobs = waiting + running + completed + failed + canceled + scheduled;
     const successRate = totalJobs > 0 ? ((completed / (totalJobs - waiting - scheduled - running)) * 100).toFixed(1) : "0.0";
     const completionRate = (completed + failed) > 0 ? (completed / (completed + failed) * 100).toFixed(1) : "0.0";
     const activeJobs = running + waiting + scheduled;
-    let period = "All time";
-    if (filters) {
-        if (filters.scheduled_at_gte || filters.scheduled_at_lte) {
-            const startDate = filters.scheduled_at_gte ? new Date(filters.scheduled_at_gte).toLocaleDateString() : "";
-            const endDate = filters.scheduled_at_lte ? new Date(filters.scheduled_at_lte).toLocaleDateString() : "";
-            period = `${startDate} to ${endDate}`;
-        }
-    }
-    const org = filters?.org_id ? `Organization: ${filters.org_id}` : "";
+    const filters = appliedFilters || {};
+    const scheduledLine = renderDateRange('Scheduled', filters.scheduled_at_gte, filters.scheduled_at_lte);
+    const createdLine = renderDateRange('Created', filters.created_at_gte, filters.created_at_lte);
+    const hasAnyDateFilter = DATE_FILTER_KEYS.some((k) => filters[k] !== undefined);
+    const periodFallback = hasAnyDateFilter ? null : 'Period: All time';
+    const dateLines = [scheduledLine, createdLine, periodFallback].filter((l) => l !== null);
+    const dateFilterSet = new Set(DATE_FILTER_KEYS);
+    const otherFilterEntries = Object.entries(filters).filter(([k, v]) => !dateFilterSet.has(k) && v !== undefined && v !== null && v !== '');
+    const filtersSection = otherFilterEntries.length
+        ? `Filters:\n${otherFilterEntries.map(([k, v]) => `- ${k}: ${v}`).join('\n')}\n\n`
+        : '';
     const percentage = (value) => {
         if (totalJobs === 0)
             return "0.0";
@@ -478,10 +554,9 @@ export function formatJobStats(stats, filters) {
 Job Statistics Report
 ====================
 
-Period: ${period}
-${org}
+${dateLines.join('\n')}
 
-Status Breakdown:
+${filtersSection}Status Breakdown:
 ✓ Completed:  ${completed} jobs (${percentage(completed)}%)
 ⏳ Running:     ${running} jobs (${percentage(running)}%)
 ⏰ Scheduled:  ${scheduled} jobs (${percentage(scheduled)}%)

package/build/utils/formatters.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { formatJobDetails, formatJobStats, formatJobTypeDetails, formatJobTypeSummary } from './formatters.js';
+import { formatJobDetails, formatJobList, formatJobStats, formatJobTypeDetails, formatJobTypeSummary } from './formatters.js';
 describe('formatJobDetails', () => {
     const fullJob = {
         job_id: 'job_123',
@@ -133,6 +133,168 @@ describe('formatJobStats', () => {
         const result = formatJobStats(stats, filters);
         expect(result).toContain('Period: All time');
     });
+    describe('header — Scheduled date range', () => {
+        const stats = {
+            status: { completed: 1, running: 0, failed: 0, canceled: 0, waiting: 0, scheduled: 0 },
+        };
+        it('renders both bounds when scheduled_at_gte and scheduled_at_lte are provided', () => {
+            const result = formatJobStats(stats, {
+                scheduled_at_gte: '2026-04-30T00:00:00Z',
+                scheduled_at_lte: '2026-05-01T00:00:00Z',
+            });
+            expect(result).toContain('Scheduled: 2026-04-30T00:00:00Z → 2026-05-01T00:00:00Z');
+            expect(result).not.toContain('Period: All time');
+        });
+        it('renders "(open)" upper bound when only scheduled_at_gte is provided', () => {
+            const result = formatJobStats(stats, {
+                scheduled_at_gte: '2026-04-30T00:00:00Z',
+            });
+            expect(result).toContain('Scheduled: 2026-04-30T00:00:00Z → (open)');
+        });
+        it('renders "(open)" lower bound when only scheduled_at_lte is provided', () => {
+            const result = formatJobStats(stats, {
+                scheduled_at_lte: '2026-05-01T00:00:00Z',
+            });
+            expect(result).toContain('Scheduled: (open) → 2026-05-01T00:00:00Z');
+        });
+        it('omits the Scheduled range line entirely when no scheduled_at bound is provided', () => {
+            const result = formatJobStats(stats, { status: 'failed' });
+            // The Status Breakdown contains "⏰ Scheduled:"; we only want to assert
+            // the header-range form ("Scheduled: <bound> → ...") is absent.
+            expect(result).not.toMatch(/(^|\n)Scheduled: .+→/);
+        });
+    });
+    describe('header — Created date range', () => {
+        const stats = {
+            status: { completed: 1, running: 0, failed: 0, canceled: 0, waiting: 0, scheduled: 0 },
+        };
+        it('renders both bounds when created_at_gte and created_at_lte are provided', () => {
+            const result = formatJobStats(stats, {
+                created_at_gte: '2026-04-01T00:00:00Z',
+                created_at_lte: '2026-04-30T00:00:00Z',
+            });
+            expect(result).toContain('Created: 2026-04-01T00:00:00Z → 2026-04-30T00:00:00Z');
+        });
+        it('renders "(open)" upper bound when only created_at_gte is provided', () => {
+            const result = formatJobStats(stats, {
+                created_at_gte: '2026-04-01T00:00:00Z',
+            });
+            expect(result).toContain('Created: 2026-04-01T00:00:00Z → (open)');
+        });
+        it('renders "(open)" lower bound when only created_at_lte is provided', () => {
+            const result = formatJobStats(stats, {
+                created_at_lte: '2026-04-30T00:00:00Z',
+            });
+            expect(result).toContain('Created: (open) → 2026-04-30T00:00:00Z');
+        });
+        it('omits the Created line entirely when no created_at bound is provided', () => {
+            const result = formatJobStats(stats, { scheduled_at_gte: '2026-04-30T00:00:00Z' });
+            expect(result).not.toContain('Created:');
+        });
+        it('renders both Scheduled and Created lines when both ranges are filtered', () => {
+            const result = formatJobStats(stats, {
+                scheduled_at_gte: '2026-04-30T00:00:00Z',
+                created_at_gte: '2026-04-01T00:00:00Z',
+            });
+            expect(result).toContain('Scheduled: 2026-04-30T00:00:00Z → (open)');
+            expect(result).toContain('Created: 2026-04-01T00:00:00Z → (open)');
+        });
+    });
+    describe('header — Period: All time fallback', () => {
+        const stats = {
+            status: { completed: 1, running: 0, failed: 0, canceled: 0, waiting: 0, scheduled: 0 },
+        };
+        it('renders "Period: All time" when no date filter is provided', () => {
+            const result = formatJobStats(stats, {});
+            expect(result).toContain('Period: All time');
+        });
+        it('does not render "Period: All time" when scheduled_at_gte is set', () => {
+            const result = formatJobStats(stats, { scheduled_at_gte: '2026-04-30T00:00:00Z' });
+            expect(result).not.toContain('Period: All time');
+        });
+        it('does not render "Period: All time" when created_at_lte is set', () => {
+            const result = formatJobStats(stats, { created_at_lte: '2026-04-30T00:00:00Z' });
+            expect(result).not.toContain('Period: All time');
+        });
+    });
+    describe('header — Filters section', () => {
+        const stats = {
+            status: { completed: 1, running: 0, failed: 0, canceled: 0, waiting: 0, scheduled: 0 },
+        };
+        it('renders a single line when one non-date filter is supplied', () => {
+            const result = formatJobStats(stats, { status: 'failed' });
+            expect(result).toContain('Filters:');
+            expect(result).toContain('- status: failed');
+        });
+        it('renders multiple lines when multiple non-date filters are supplied', () => {
+            const result = formatJobStats(stats, {
+                status: 'failed',
+                job_type_id: 'woba-supplier-ai-batch',
+            });
+            expect(result).toContain('- status: failed');
+            expect(result).toContain('- job_type_id: woba-supplier-ai-batch');
+        });
+        it('omits the Filters section entirely when only date filters are supplied', () => {
+            const result = formatJobStats(stats, { scheduled_at_gte: '2026-04-30T00:00:00Z' });
+            expect(result).not.toContain('Filters:');
+        });
+    });
+});
+describe('formatJobList', () => {
+    const sampleJob = {
+        job_id: 'job_1',
+        channel_code: 'ch_1',
+        created_at: '2026-04-30T00:00:00.000Z',
+        updated_at: '2026-04-30T00:10:00.000Z',
+        scheduled_at: '2026-04-30T00:00:00.000Z',
+        job_status: 'completed',
+        result: 'ok',
+        job_type_id: 'type_1',
+    };
+    it('renders the four-field footer on first page with more pages available', () => {
+        const jobs = Array.from({ length: 20 }, (_, i) => ({ ...sampleJob, job_id: `job_${i}` }));
+        const meta = { count: 20, limit: 20, total: 40 };
+        const result = formatJobList(jobs, meta, 0);
+        expect(result).toContain('Returned: 20 | Total matching: 40 | Has more: true | Next offset: 20');
+        expect(result).not.toContain('Page:');
+        expect(result).not.toContain('Total Jobs:');
+    });
+    it('renders Has more: false and Next offset: null on the last page', () => {
+        const jobs = Array.from({ length: 20 }, (_, i) => ({ ...sampleJob, job_id: `job_${i}` }));
+        const meta = { count: 20, limit: 20, total: 40 };
+        const result = formatJobList(jobs, meta, 20);
+        expect(result).toContain('Returned: 20 | Total matching: 40 | Has more: false | Next offset: null');
+    });
+    it('handles a partial last page (count < limit)', () => {
+        const jobs = Array.from({ length: 5 }, (_, i) => ({ ...sampleJob, job_id: `job_${i}` }));
+        const meta = { count: 5, limit: 20, total: 25 };
+        const result = formatJobList(jobs, meta, 20);
+        expect(result).toContain('Returned: 5 | Total matching: 25 | Has more: false | Next offset: null');
+    });
+    it('renders the footer on an empty result on the first page', () => {
+        const meta = { count: 0, limit: 20, total: 0 };
+        const result = formatJobList([], meta, 0);
+        expect(result).toContain('Found 0 jobs.');
+        expect(result).toContain('Returned: 0 | Total matching: 0 | Has more: false | Next offset: null');
+        expect(result).not.toContain('No jobs found for the given criteria.');
+    });
+    it('renders Total matching reflecting real total when offset overflows the result set', () => {
+        const meta = { count: 0, limit: 20, total: 40 };
+        const result = formatJobList([], meta, 100);
+        expect(result).toContain('Found 0 jobs.');
+        expect(result).toContain('Returned: 0 | Total matching: 40 | Has more: false | Next offset: null');
+    });
+    describe('fail-fast on missing meta fields', () => {
+        it('throws when meta is null', () => {
+            expect(() => formatJobList([], null, 0)).toThrow(/meta is required/);
+        });
+        it('throws when meta.total is missing', () => {
+            expect(() => formatJobList([], { count: 0, limit: 20 }, 0)).toThrow(/meta is required.*count.*limit.*total/);
+        });
+        it('throws when meta.count is non-numeric', () => {
+            expect(() => formatJobList([], { count: 'oops', limit: 20, total: 0 }, 0)).toThrow(/meta is required/);
+        });
+    });
 });
 describe('formatJobTypeDetails', () => {
     const fullJobType = {
@@ -385,3 +547,83 @@ describe('formatJobTypeSummary', () => {
         expect(result).toContain('"invalid": true');
     });
 });
+import { formatContext } from './formatters.js';
+describe('formatContext', () => {
+    const localConfig = {
+        org_id: 'woba',
+        timezone: 'America/Sao_Paulo',
+        api_url: 'https://api.aiconnect.cloud/api/v0',
+        server_version: '0.4.2'
+    };
+    it('formats happy path with two job types', () => {
+        const result = formatContext({
+            localConfig,
+            total: 2,
+            jobTypes: [
+                { id: 'billing-followup', name: 'Billing Follow-up', description: 'Triage de cobrança', emoji: '💳' },
+                { id: 'support-triage', name: 'Support Triage', description: 'Roteamento de suporte', emoji: '🛠️' }
+            ]
+        });
+        expect(result).toContain('Context:');
+        expect(result).toContain('Org ID:          woba');
+        expect(result).toContain('Timezone:        America/Sao_Paulo');
+        expect(result).toContain('API URL:         https://api.aiconnect.cloud/api/v0');
+        expect(result).toContain('Server version:  0.4.2');
+        expect(result).toContain('Job types available (2):');
+        expect(result).toContain('billing-followup');
+        expect(result).toContain('💳');
+        expect(result).toContain('— Triage de cobrança');
+    });
+    it('handles zero job types', () => {
+        const result = formatContext({ localConfig, total: 0, jobTypes: [] });
+        expect(result).toContain('Job types available (0):');
+        expect(result).toContain('(no job types registered for this org)');
+    });
+    it('renders error line when jobTypesError present', () => {
+        const result = formatContext({
+            localConfig,
+            jobTypesError: 'API Error (500): Internal Server Error'
+        });
+        expect(result).toContain('Context:');
+        expect(result).toContain('Org ID:          woba');
+        expect(result).toContain('Job types: unavailable (error: API Error (500): Internal Server Error)');
+        expect(result).not.toContain('Job types available');
+    });
+    it('preserves alignment when emoji missing', () => {
+        const result = formatContext({
+            localConfig,
+            total: 2,
+            jobTypes: [
+                { id: 'with-emoji', name: 'With Emoji', emoji: '✅' },
+                { id: 'no-emoji', name: 'No Emoji' }
+            ]
+        });
+        const lines = result.split('\n');
+        const withEmojiLine = lines.find((l) => l.includes('with-emoji'));
+        const noEmojiLine = lines.find((l) => l.includes('no-emoji'));
+        const idxWith = withEmojiLine.indexOf('With Emoji');
+        const idxNo = noEmojiLine.indexOf('No Emoji');
+        expect(idxWith).toBe(idxNo);
+        expect(result).not.toContain('undefined');
+        expect(result).not.toContain('null');
+    });
+    it('shows truncation hint when total > returned items', () => {
+        const jobTypes = Array.from({ length: 100 }, (_, i) => ({
+            id: `jt-${i}`,
+            name: `JT ${i}`
+        }));
+        const result = formatContext({ localConfig, total: 247, jobTypes });
+        expect(result).toContain('Job types available (247):');
+        expect(result).toContain('… and 147 more job types not shown');
+    });
+    it('produces byte-equal output across calls with identical input', () => {
+        const input = {
+            localConfig,
+            total: 1,
+            jobTypes: [{ id: 'a', name: 'A', emoji: '🅰️' }]
+        };
+        const a = formatContext(input);
+        const b = formatContext(input);
+        expect(a).toBe(b);
+    });
+});

package/build/utils/schemas.js

@@ -1,20 +1,24 @@
 import { z } from 'zod';
 /**
- * A flexible Zod schema for validating ISO 8601 date-time strings.
+ * Factory that returns a fresh Zod schema validating ISO 8601 date-time strings.
  *
- * This schema accepts any string that can be successfully parsed by the `Date` constructor,
- * which includes formats with 'Z' (UTC) and timezone offsets (e.g., '+01:00').
- * It refines a base string schema, providing a more specific error message if the
- * date-time string is invalid.
+ * Accepts any string parseable by `new Date(value)` (full ISO 8601 with `Z` or
+ * timezone offset, and date-only forms like `2024-07-23`).
+ *
+ * IMPORTANT — why this is a factory and not a singleton: when the MCP SDK
+ * serializes a tool's input shape to JSON Schema (via `zod-to-json-schema`),
+ * reusing the same Zod *instance* across multiple fields causes the serializer
+ * to emit `$ref` from sibling fields back to the first one. Many clients/LLMs
+ * then treat those fields as `any` and send `null`, which the server rejects.
+ * Returning a new instance per call guarantees inline definitions per field.
+ *
+ * Convention for this project: every reusable Zod schema referenced by more
+ * than one tool field MUST be exported as a factory (`() => z.something(...)`),
+ * never as a singleton `const`.
  */
-export const flexibleDateTimeSchema = z.string().refine((value) => {
-    // Try to parse the date string.
-    // The Date constructor is quite flexible with ISO 8601 formats.
+export const flexibleDateTimeSchema = () => z.string().refine((value) => {
     const date = new Date(value);
-    // Check if the parsed date is valid.
-    // `isNaN(date.getTime())` is a reliable way to check for invalid dates.
     return !isNaN(date.getTime());
 }, {
-    // Custom error message for invalid date-time strings.
     message: "Invalid date-time string. Please use a valid ISO 8601 format.",
 });

package/build/utils/schemas.test.js

@@ -1,40 +1,95 @@
 import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
 import { flexibleDateTimeSchema } from './schemas.js';
 describe('flexibleDateTimeSchema', () => {
-    // Test case 1: Valid ISO 8601 with UTC 'Z'
     it('should validate a correct ISO 8601 string with Zulu time', () => {
-        const validDate = '2025-07-23T21:00:00Z';
-        const result = flexibleDateTimeSchema.safeParse(validDate);
+        const result = flexibleDateTimeSchema().safeParse('2025-07-23T21:00:00Z');
         expect(result.success).toBe(true);
     });
-    // Test case 2: Valid ISO 8601 with a positive timezone offset
     it('should validate a correct ISO 8601 string with a positive offset', () => {
-        const validDate = '2025-07-23T22:00:00+01:00';
-        const result = flexibleDateTimeSchema.safeParse(validDate);
+        const result = flexibleDateTimeSchema().safeParse('2025-07-23T22:00:00+01:00');
         expect(result.success).toBe(true);
     });
-    // Test case 3: Valid ISO 8601 with a negative timezone offset
     it('should validate a correct ISO 8601 string with a negative offset', () => {
-        const validDate = '2025-07-23T16:00:00-05:00';
-        const result = flexibleDateTimeSchema.safeParse(validDate);
+        const result = flexibleDateTimeSchema().safeParse('2025-07-23T16:00:00-05:00');
         expect(result.success).toBe(true);
     });
-    // Test case 4: Invalid date format (not ISO 8601)
     it('should not validate an incorrect date format', () => {
-        const invalidDate = '23/07/2025 21:00:00';
-        const result = flexibleDateTimeSchema.safeParse(invalidDate);
+        const result = flexibleDateTimeSchema().safeParse('23/07/2025 21:00:00');
         expect(result.success).toBe(false);
     });
-    // Test case 5: Invalid date string (gibberish)
     it('should not validate a gibberish string', () => {
-        const gibberish = 'not-a-date';
-        const result = flexibleDateTimeSchema.safeParse(gibberish);
+        const result = flexibleDateTimeSchema().safeParse('not-a-date');
         expect(result.success).toBe(false);
     });
-    // Test case 6: Empty string
     it('should not validate an empty string', () => {
-        const emptyString = '';
-        const result = flexibleDateTimeSchema.safeParse(emptyString);
+        const result = flexibleDateTimeSchema().safeParse('');
         expect(result.success).toBe(false);
     });
+    it('should validate a date-only string (no time component)', () => {
+        const result = flexibleDateTimeSchema().safeParse('2024-07-23');
+        expect(result.success).toBe(true);
+    });
+    it('should reject invalid string with the exact ISO 8601 error message', () => {
+        const result = flexibleDateTimeSchema().safeParse('not-a-date');
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error.issues[0].message).toBe('Invalid date-time string. Please use a valid ISO 8601 format.');
+        }
+    });
+    it('should reject null when used with .optional() (string | undefined, not nullable)', () => {
+        const schema = flexibleDateTimeSchema().optional();
+        expect(schema.safeParse(undefined).success).toBe(true);
+        const nullResult = schema.safeParse(null);
+        expect(nullResult.success).toBe(false);
+        if (!nullResult.success) {
+            const issue = nullResult.error.issues[0];
+            expect(issue.code).toBe('invalid_type');
+            // Zod 3: { expected: 'string', received: 'null' }
+            expect(issue.expected).toBe('string');
+            expect(issue.received).toBe('null');
+        }
+    });
+});
+describe('JSON Schema serialization', () => {
+    it('should inline each list_jobs date filter field without $ref', () => {
+        const shape = z.object({
+            scheduled_at: flexibleDateTimeSchema().optional(),
+            scheduled_at_gte: flexibleDateTimeSchema().optional(),
+            scheduled_at_lte: flexibleDateTimeSchema().optional(),
+            created_at_gte: flexibleDateTimeSchema().optional(),
+            created_at_lte: flexibleDateTimeSchema().optional(),
+        });
+        const json = zodToJsonSchema(shape);
+        const expectedFields = [
+            'scheduled_at',
+            'scheduled_at_gte',
+            'scheduled_at_lte',
+            'created_at_gte',
+            'created_at_lte',
+        ];
+        for (const field of expectedFields) {
+            const prop = json.properties[field];
+            expect(prop.$ref, `expected ${field} to be inline, got $ref ${String(prop.$ref)}`).toBeUndefined();
+            expect(prop.type, `expected ${field} to have type 'string', got ${String(prop.type)}`).toBe('string');
+        }
+    });
+    it('should produce $ref-free JSON for both list_jobs and get_jobs_stats shapes', () => {
+        const listJobsShape = z.object({
+            scheduled_at: flexibleDateTimeSchema().optional(),
+            scheduled_at_gte: flexibleDateTimeSchema().optional(),
+            scheduled_at_lte: flexibleDateTimeSchema().optional(),
+            created_at_gte: flexibleDateTimeSchema().optional(),
+            created_at_lte: flexibleDateTimeSchema().optional(),
+        });
+        const statsShape = z.object({
+            scheduled_at_gte: flexibleDateTimeSchema().optional(),
+            scheduled_at_lte: flexibleDateTimeSchema().optional(),
+            created_at_gte: flexibleDateTimeSchema().optional(),
+            created_at_lte: flexibleDateTimeSchema().optional(),
+        });
+        expect(JSON.stringify(zodToJsonSchema(listJobsShape))).not.toContain('$ref');
+        expect(JSON.stringify(zodToJsonSchema(statsShape))).not.toContain('$ref');
+    });
 });

package/build/utils/version.js

@@ -0,0 +1,12 @@
+import fs from 'fs';
+function readVersion() {
+    try {
+        const raw = fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf-8');
+        const pkg = JSON.parse(raw);
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export const mcpServerVersion = readVersion();

package/build/utils/version.test.js

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { mcpServerVersion } from './version.js';
+describe('mcpServerVersion', () => {
+    it('resolves to a non-empty string from package.json in dev tree', () => {
+        expect(typeof mcpServerVersion).toBe('string');
+        expect(mcpServerVersion.length).toBeGreaterThan(0);
+        expect(mcpServerVersion).not.toBe('unknown');
+    });
+});

package/docs/agent-jobs-api.md

@@ -239,6 +239,47 @@ Cancels a job by changing its status to CANCELED.
 - 404: Job not found
 - 409: Conflict (job is already in a terminal state)
 
+### List Job Types (`agent-jobs-type`)
+
+Lists agent job types registered for an organization. Used by `get_job_type` and `get_context` in this MCP.
+
+#### Path em uso pelas tools deste MCP hoje
+
+```http
+GET /organizations/:org_id/agent-jobs-type
+GET /organizations/:org_id/agent-jobs-type/:job_type_id
+```
+
+(Sem prefixo `/services/`.) **Toda tool nova neste repo deve usar este caminho** até a unificação descrita abaixo, para manter consistência com `get_job_type`.
+
+#### Path canônico upstream
+
+```http
+GET /services/organizations/:org_id/agent-jobs-type
+GET /services/organizations/:org_id/agent-jobs-type/:job_type_id
+```
+
+Este é o caminho documentado upstream pelo AI Connect API. O backend serve a mesma controller em ambos os mounts (legacy + atual). Uma migração futura para o caminho canônico deve ser feita em **change separado abrangendo todas as tools afetadas**: `get_job_type`, `list_jobs`, `create_job`, `get_jobs_stats` e `get_context`.
+
+#### Query parameters suportados
+
+- `enrich=emoji` — adiciona o campo `emoji` no payload (cache server-side de 1h por job_type).
+- `include=schema` — inclui `params_schema` completo de cada job type (não usado por `get_context`; pesado).
+- `limit` — número máximo de itens por página. `get_context` fixa em `100`.
+- `offset` — paginação numérica.
+- `sort` — formato `field:direction`, ex: `name:asc` (default usado por `get_context`).
+
+#### Response shape
+
+```json
+{
+  "data": [
+    { "id": "string", "name": "string", "description": "string?", "emoji": "string?" }
+  ],
+  "meta": { "total": 0, "limit": 100, "offset": 0 }
+}
+```
+
 ## Job Status Values
 
 Jobs can have the following status values:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiconnect/agentjobs-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP (Model Context Protocol) server for managing Agent Jobs in the AI Connect platform. Developed by AI Connect - Advanced AI automation and integration solutions.",
   "type": "module",
   "main": "build/index.js",
@@ -61,7 +61,8 @@
     "eslint": "^9.14.0",
     "typescript-eslint": "^8.12.2",
     "typescript": "^5.7.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod-to-json-schema": "^3.23.0"
   },
   "engines": {
     "node": ">=18.0.0"