@aiconnect/agentjobs-mcp 1.1.0 → 1.3.0

package/.env.example

@@ -10,6 +10,10 @@ AICONNECT_API_KEY=your-api-key-here
 # Optional: Default organization ID (defaults to 'aiconnect' if not set)
 # DEFAULT_ORG_ID=your-organization-id
 
+# Optional: Preferred timezone surfaced by the `get_context` tool (defaults to 'UTC' if not set).
+# Informational only — does not change timestamp behavior of other tools.
+# DEFAULT_TIMEZONE=America/Sao_Paulo
+
 # Debug Settings
 MCP_DEBUG=false
 NODE_ENV=development

package/README.md

@@ -59,12 +59,14 @@ Edit the `.env` file with your credentials:
 DEFAULT_ORG_ID=your-organization     # Default: aiconnect
 AICONNECT_API_KEY=your-api-key       # Required: Must be provided
 AICONNECT_API_URL=https://api.aiconnect.cloud/api/v0  # Default
+DEFAULT_TIMEZONE=America/Sao_Paulo   # Default: UTC (informational only, surfaced via get_context)
 ```
 
 **Important**: If no environment variables are provided, the server will use these defaults:
 - `DEFAULT_ORG_ID`: `aiconnect`
 - `AICONNECT_API_URL`: `https://api.aiconnect.cloud/api/v0`
 - `AICONNECT_API_KEY`: empty (must be provided for API calls to work)
+- `DEFAULT_TIMEZONE`: `UTC`
 
 4. **Build the project:**
 ```bash
@@ -108,6 +110,11 @@ npx @aiconnect/agentjobs-mcp
 - `AICONNECT_API_URL`: API endpoint URL (e.g., https://api.aiconnect.cloud/api/v0)
 - `AICONNECT_API_KEY`: Your API authentication key
 
+**Optional Environment Variables:**
+
+- `DEFAULT_ORG_ID`: Fallback organization ID when a tool's `org_id` parameter is omitted (default: `aiconnect`)
+- `DEFAULT_TIMEZONE`: Preferred timezone surfaced by the `get_context` tool so LLM clients can format timestamps. Informational only — does not change behavior of other tools, which continue to emit timestamps in UTC (default: `UTC`)
+
 **CLI Command Examples:**
 ```bash
 # Quick help
@@ -148,14 +155,18 @@ This MCP server is designed to work out-of-the-box with minimal configuration. I
 3. **Partial configuration**: Mix of environment variables and defaults
 
 **Default Values (when no env vars are set):**
+
 - `DEFAULT_ORG_ID`: `"aiconnect"`
 - `AICONNECT_API_URL`: `"https://api.aiconnect.cloud/api/v0"`
 - `AICONNECT_API_KEY`: `""` (empty - you must provide this)
+- `DEFAULT_TIMEZONE`: `"UTC"`
 
 **Error Handling:**
+
 - The server will always start, even if environment variables are missing.
 - If `AICONNECT_API_KEY` or `AICONNECT_API_URL` are not provided, each tool will return a clear error message upon execution, guiding the user to configure the environment correctly.
 - If `DEFAULT_ORG_ID` is not set, it defaults to "aiconnect".
+- If `DEFAULT_TIMEZONE` is not set, it defaults to "UTC". This value is purely informational (returned by the `get_context` tool) and does not affect timestamp parsing or formatting in other tools.
 
 ### Running the MCP server
 
@@ -178,7 +189,8 @@ To use this MCP server with Claude Desktop, add the following configuration to y
       "env": {
         "DEFAULT_ORG_ID": "your-organization",
         "AICONNECT_API_KEY": "your-api-key",
-        "AICONNECT_API_URL": "https://api.aiconnect.cloud/api/v0"
+        "AICONNECT_API_URL": "https://api.aiconnect.cloud/api/v0",
+        "DEFAULT_TIMEZONE": "America/Sao_Paulo"
       }
     }
   }
@@ -228,12 +240,32 @@ Lists all jobs with filtering and pagination options.
 - `limit` (optional): Result limit (default: 50)
 - `offset` (optional): Pagination offset
 - `sort` (optional): Field and direction for sorting
+- `include_activities` (optional): Attach recent activities to each job (default: false)
+- `activities_limit_per_job` (optional): Max activities per job (1–100, default 15)
+- `activities_total_limit` (optional): Global cap across the response (1–3000, default 500)
+- `activities_sort` (optional): `created_at` or `-created_at` (default `-created_at`)
 
 ### 🔍 `get_job`
 Gets details of a specific job.
 
 **Parameters:**
 - `job_id` (required): ID of the job to query
+- `include_activities` (optional): Attach recent activities as an inline overlay (default: false)
+- `include_limit` (optional): Max activities to attach (1–100, default 50)
+- `include_sort` (optional): `created_at` or `-created_at` (default `-created_at`)
+
+### 🧾 `get_job_activities`
+Retrieves the audit activity trail for a specific agent job via the dedicated `/services/activities` endpoint. Supports real pagination (no truncation) and server-side filtering. Use this for focused investigation of a job's activity log; for a quick overlay of recent activities, use `get_job` with `include_activities=true`.
+
+**Parameters:**
+- `job_id` (required): ID of the agent job
+- `org_id` (optional): Organization scope
+- `status` (optional): `submitted`, `completed`, or `canceled`
+- `activity_type_code` (optional): Open-string code (e.g., `ai_completion`)
+- `source_type` (optional): `dispatch`, `process_module`, or `direct`
+- `limit` (optional): Page size (default 50)
+- `offset` (optional): Pagination offset (default 0)
+- `sort` (optional): Sort field/direction (default `-created_at`)
 
 ### ✅ `create_job`
 Creates a new job for execution.
@@ -294,11 +326,12 @@ agentjobs-mcp/
 │   ├── index.ts           # Main MCP server entry point
 │   ├── config.ts          # Configuration loader
 │   └── tools/             # Directory for all MCP tools
-│       ├── get_jobs_stats.ts # Tool for getting job statistics
-│       ├── list_jobs.ts   # Tool for listing jobs
-│       ├── get_job.ts     # Tool for getting a job
-│       ├── create_job.ts  # Tool for creating a job
-│       └── cancel_job.ts  # Tool for canceling a job
+│       ├── get_jobs_stats.ts     # Tool for getting job statistics
+│       ├── list_jobs.ts          # Tool for listing jobs
+│       ├── get_job.ts            # Tool for getting a job
+│       ├── get_job_activities.ts # Tool for getting a job's activity trail
+│       ├── create_job.ts         # Tool for creating a job
+│       └── cancel_job.ts         # Tool for canceling a job
 ├── build/                 # Compiled JavaScript code
 ├── docs/                  # Documentation
 │   └── agent-jobs-api.md  # API documentation

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/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";
@@ -104,7 +111,7 @@ const toolsDir = path.join(__dirname, 'tools');
 try {
     const toolFiles = await fs.readdir(toolsDir);
     for (const file of toolFiles) {
-        if (file.endsWith('.js')) { // In production, files will be .js
+        if (file.endsWith('.js') && !file.endsWith('.test.js')) { // In production, files will be .js (exclude colocated tests)
             try {
                 const toolModule = await import(`./tools/${file}`);
                 if (typeof toolModule.default === 'function') {

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/test-tools.js

@@ -21,7 +21,7 @@ async function testTools() {
         const toolFiles = await fs.readdir(toolsDir);
         console.log(`📁 Found ${toolFiles.length} tool files`);
         for (const file of toolFiles) {
-            if (file.endsWith('.js')) {
+            if (file.endsWith('.js') && !file.endsWith('.test.js')) {
                 try {
                     console.log(`⚙️  Loading tool: ${file}`);
                     const toolModule = await import(`./tools/${file}`);

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_job.js

@@ -2,35 +2,65 @@ import { z } from 'zod';
 import agentJobsClient from '../lib/agentJobsClient.js';
 import { formatJobDetails } from '../utils/formatters.js';
 import { mcpDebugger, withTiming } from '../utils/debugger.js';
+const ACTIVITIES_SORT_VALUES = ['created_at', '-created_at'];
 export default (server) => {
     server.registerTool('get_job', {
-        description: 'Retrieves an agent job by its ID.',
+        description: 'Retrieves an agent job by its ID. Optionally includes recent activity records as an inline overlay (use include_activities=true).',
         annotations: {
             title: 'Get Agent Job'
         },
         inputSchema: {
             job_id: z.string({
                 description: "The unique identifier of the job you want to retrieve. Example: 'job-12345'."
-            }),
+            }).min(1, { message: 'job_id must be a non-empty string' }),
             org_id: z
                 .string({
                 description: "The organization ID. Example: 'aiconnect'."
             })
-                .optional()
+                .optional(),
+            include_activities: z.boolean().optional().describe("When true, attaches recent activities as an overlay (?include=activities). For full pagination of activities use the get_job_activities tool."),
+            include_limit: z.number().int().optional().describe("Max activities to attach when include_activities=true. Range 1-100, default 50. Silently ignored when include_activities is false/omitted."),
+            include_sort: z.string().optional().describe("Sort order for attached activities when include_activities=true. 'created_at' or '-created_at' (default). Silently ignored when include_activities is false/omitted.")
         }
     }, async (params) => {
         mcpDebugger.toolCall("get_job", params);
-        const { job_id } = params;
-        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 });
+        const { job_id, include_activities } = params;
+        const endpoint = `/services/agent-jobs/${job_id}`;
+        const queryParams = {};
+        if (params.org_id)
+            queryParams.org_id = params.org_id;
+        if (include_activities) {
+            // Per spec, range/enum on the overlay-only params are validated here
+            // (not in the Zod input schema) so that flag-off callers carrying stale
+            // configuration are silently tolerated. With the flag on, invalid
+            // values short-circuit before any HTTP call.
+            if (params.include_limit !== undefined) {
+                if (!Number.isInteger(params.include_limit) || params.include_limit < 1 || params.include_limit > 100) {
+                    return {
+                        content: [{ type: 'text', text: 'Error getting job: include_limit must be an integer in [1, 100]' }],
+                    };
+                }
+            }
+            if (params.include_sort !== undefined && !ACTIVITIES_SORT_VALUES.includes(params.include_sort)) {
+                return {
+                    content: [{ type: 'text', text: "Error getting job: include_sort must be 'created_at' or '-created_at'" }],
+                };
+            }
+            queryParams.include = 'activities';
+            queryParams.include_limit = params.include_limit ?? 50;
+            queryParams.include_sort = params.include_sort ?? '-created_at';
+        }
+        mcpDebugger.debug("Built endpoint", { endpoint, queryParams });
         try {
-            const job = await withTiming(() => agentJobsClient.get(endpoint), "get_job API call");
-            mcpDebugger.debug("Raw API response", { job });
+            const apiResponse = await withTiming(() => agentJobsClient.getWithMeta(endpoint, queryParams), "get_job API call");
+            const job = apiResponse?.data ?? apiResponse;
+            const meta = apiResponse?.meta;
+            mcpDebugger.debug("Raw API response", { job, meta });
             const result = {
                 content: [
                     {
                         type: 'text',
-                        text: formatJobDetails(job)
+                        text: formatJobDetails(job, meta)
                     }
                 ]
             };

package/build/tools/get_job_activities.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import agentJobsClient from '../lib/agentJobsClient.js';
+import { formatJobActivitiesList } from '../utils/formatters.js';
+import { activityStatusSchema, activitySourceTypeSchema, } from '../utils/schemas.js';
+import { mcpDebugger, withTiming } from '../utils/debugger.js';
+export default (server) => {
+    server.registerTool('get_job_activities', {
+        description: "Retrieves the audit activity trail for a specific agent job via the dedicated /services/activities endpoint. Supports real pagination (no truncation) and server-side filters by status, type and source. Use this for focused investigation of a job's activity log; for a quick overlay of recent activities on the job detail, use get_job with include_activities=true.",
+        annotations: {
+            title: 'Get Agent Job Activities'
+        },
+        inputSchema: {
+            job_id: z.string().min(1).describe("The unique identifier of the agent job whose activities you want to retrieve. Required."),
+            org_id: z.string().optional().describe("The organization ID. If omitted, the default from the environment is used."),
+            status: activityStatusSchema().optional().describe("Filter by activity status. Possible values: 'submitted', 'completed', 'canceled'."),
+            activity_type_code: z.string().optional().describe("Filter by activity type code (open string, e.g., 'ai_completion')."),
+            source_type: activitySourceTypeSchema().optional().describe("Filter by source type. Possible values: 'dispatch', 'process_module', 'direct'."),
+            limit: z.number().int().positive().optional().describe("Maximum number of activities to return per page. Default 50."),
+            offset: z.number().int().nonnegative().optional().describe("Number of activities to skip, used for pagination. Default 0."),
+            sort: z.string().optional().describe("Field and direction to sort by. Default '-created_at' (newest first).")
+        }
+    }, async (params) => {
+        mcpDebugger.toolCall('get_job_activities', params);
+        const endpoint = '/services/activities';
+        const queryParams = {
+            job_id: params.job_id,
+            limit: params.limit ?? 50,
+            offset: params.offset ?? 0,
+            sort: params.sort ?? '-created_at',
+        };
+        if (params.org_id)
+            queryParams.org_id = params.org_id;
+        if (params.status)
+            queryParams.status = params.status;
+        if (params.activity_type_code)
+            queryParams.activity_type_code = params.activity_type_code;
+        if (params.source_type)
+            queryParams.source_type = params.source_type;
+        mcpDebugger.debug('Built query parameters', { endpoint, queryParams });
+        try {
+            const apiResponse = await withTiming(() => agentJobsClient.getWithMeta(endpoint, queryParams), 'get_job_activities API call');
+            const activities = apiResponse?.data ?? [];
+            const meta = apiResponse?.meta ?? {};
+            const offset = queryParams.offset;
+            const result = {
+                content: [{
+                        type: 'text',
+                        text: formatJobActivitiesList(params.job_id, activities, meta, offset),
+                    }]
+            };
+            mcpDebugger.toolResponse('get_job_activities', {
+                jobId: params.job_id,
+                activitiesReturned: activities.length,
+                resultLength: result.content[0].text.length
+            });
+            return result;
+        }
+        catch (error) {
+            mcpDebugger.toolError('get_job_activities', error);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error getting job activities: ${error.message}`,
+                    }],
+            };
+        }
+    });
+};

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

@@ -3,6 +3,7 @@ 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";
+const ACTIVITIES_SORT_VALUES = ['created_at', '-created_at'];
 // Define the schema for job status based on docs/agent-jobs-api.md:246-251
 const jobStatusSchema = z.enum([
     "waiting",
@@ -21,27 +22,60 @@ 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."),
             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'.")
+            sort: z.string().optional().describe("Field to sort by and direction. Format is 'field:direction'. Example: 'created_at:desc'."),
+            include_activities: z.boolean().optional().describe("When true, attaches activities to each job in the list (?include=activities). For full pagination of a single job's activities use the get_job_activities tool."),
+            activities_limit_per_job: z.number().int().optional().describe("Max activities per job when include_activities=true. Range 1-100, default 15. Silently ignored when include_activities is false/omitted."),
+            activities_total_limit: z.number().int().optional().describe("Global cap on total activities returned across all jobs in the response when include_activities=true. Range 1-3000, default 500. Silently ignored when include_activities is false/omitted."),
+            activities_sort: z.string().optional().describe("Sort order for attached activities when include_activities=true. 'created_at' or '-created_at' (default). Silently ignored when include_activities is false/omitted.")
         }
     }, async (params) => {
         mcpDebugger.toolCall("list_jobs", params);
         const endpoint = `/services/agent-jobs`;
-        // Build query parameters object from provided params
+        const { include_activities, activities_limit_per_job, activities_total_limit, activities_sort, ...rest } = params;
         const queryParams = {};
-        for (const [key, value] of Object.entries(params)) {
+        for (const [key, value] of Object.entries(rest)) {
             if (value !== undefined) {
                 queryParams[key] = value;
             }
         }
+        if (include_activities) {
+            // Per spec, range/enum on the overlay-only params are validated here
+            // (not in the Zod input schema) so that flag-off callers carrying stale
+            // configuration are silently tolerated. With the flag on, invalid
+            // values short-circuit before any HTTP call.
+            if (activities_limit_per_job !== undefined) {
+                if (!Number.isInteger(activities_limit_per_job) || activities_limit_per_job < 1 || activities_limit_per_job > 100) {
+                    return {
+                        content: [{ type: 'text', text: 'Error listing jobs: activities_limit_per_job must be an integer in [1, 100]' }],
+                    };
+                }
+            }
+            if (activities_total_limit !== undefined) {
+                if (!Number.isInteger(activities_total_limit) || activities_total_limit < 1 || activities_total_limit > 3000) {
+                    return {
+                        content: [{ type: 'text', text: 'Error listing jobs: activities_total_limit must be an integer in [1, 3000]' }],
+                    };
+                }
+            }
+            if (activities_sort !== undefined && !ACTIVITIES_SORT_VALUES.includes(activities_sort)) {
+                return {
+                    content: [{ type: 'text', text: "Error listing jobs: activities_sort must be 'created_at' or '-created_at'" }],
+                };
+            }
+            queryParams.include = 'activities';
+            queryParams.activities_limit_per_job = activities_limit_per_job ?? 15;
+            queryParams.activities_total_limit = activities_total_limit ?? 500;
+            queryParams.activities_sort = activities_sort ?? '-created_at';
+        }
         mcpDebugger.debug("Built query parameters", { endpoint, queryParams });
         try {
             const apiResponse = await withTiming(() => agentJobsClient.getWithMeta(endpoint, queryParams), "list_jobs API call");
@@ -54,10 +88,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, { includeActivities: include_activities === true }),
                     }]
             };
             mcpDebugger.toolResponse("list_jobs", {