@aiconnect/agentjobs-mcp 1.2.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/index.js

@@ -111,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/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/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/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",
@@ -30,18 +31,51 @@ export default (server) => {
             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");
@@ -58,7 +92,7 @@ export default (server) => {
             const result = {
                 content: [{
                         type: "text",
-                        text: formatJobList(jobs, meta, offset),
+                        text: formatJobList(jobs, meta, offset, { includeActivities: include_activities === true }),
                     }]
             };
             mcpDebugger.toolResponse("list_jobs", {