Agent Jobs MCP Server

Instructions

Implementation Reference

• src/tools/get_jobs_stats.ts:37-70 (handler)

  The main handler function for the 'get_jobs_stats' MCP tool. It logs the tool call, fetches stats via agentJobsClient.getStats, extracts stats and filters from response.meta, formats them into a text response using formatJobStats, logs the response, and handles errors gracefully.
  async (params) => { mcpDebugger.toolCall("get_jobs_stats", params); try { const response = await withTiming( () => agentJobsClient.getStats(params), "get_jobs_stats API call" ); const stats = response.meta?.stats || {}; const filters = response.meta?.filters || {}; mcpDebugger.debug("Raw API response", { stats, filters }); const result = { content: [{ type: "text" as const, text: formatJobStats(stats, filters), }] }; mcpDebugger.toolResponse("get_jobs_stats", result); return result; } catch (error: any) { mcpDebugger.toolError("get_jobs_stats", error); return { content: [{ type: "text" as const, text: `Error getting job stats: ${error.message}`, }], }; } }
• src/tools/get_jobs_stats.ts:8-36 (schema)

  Zod-based input schema validation for the 'get_jobs_stats' tool, defining optional filters such as org_id, date ranges (using flexibleDateTimeSchema), job_type_id, channel_code, tags, and status (from jobStatusSchema enum). Includes tool description and annotations.
  const jobStatusSchema = z.enum([ "waiting", "scheduled", "running", "completed", "failed", "canceled" ]); export default (server: McpServer) => { server.registerTool( "get_jobs_stats", { description: "Get aggregated statistics for agent jobs without retrieving individual job data. Optimized for dashboards and monitoring with minimal network overhead.", annotations: { title: "Get Job Statistics" }, inputSchema: { org_id: z.string().optional().describe("Filter by organization ID."), scheduled_at_gte: flexibleDateTimeSchema.optional().describe("Start of period (ISO 8601)"), scheduled_at_lte: flexibleDateTimeSchema.optional().describe("End of period (ISO 8601)"), created_at_gte: flexibleDateTimeSchema.optional().describe("Filter for jobs created at or after a specific time (ISO 8601)."), created_at_lte: flexibleDateTimeSchema.optional().describe("Filter for jobs created at or before a specific time (ISO 8601)."), job_type_id: z.string().optional().describe("Job type filter"), channel_code: z.string().optional().describe("Channel filter"), tags: z.string().optional().describe("Tags filter (comma-separated)"), status: jobStatusSchema.optional().describe("Status filter"), } },
• src/tools/get_jobs_stats.ts:17-72 (registration)

  The module registration function that attaches the 'get_jobs_stats' tool to the MCP server, specifying the tool name, input schema, and handler function.
  export default (server: McpServer) => { server.registerTool( "get_jobs_stats", { description: "Get aggregated statistics for agent jobs without retrieving individual job data. Optimized for dashboards and monitoring with minimal network overhead.", annotations: { title: "Get Job Statistics" }, inputSchema: { org_id: z.string().optional().describe("Filter by organization ID."), scheduled_at_gte: flexibleDateTimeSchema.optional().describe("Start of period (ISO 8601)"), scheduled_at_lte: flexibleDateTimeSchema.optional().describe("End of period (ISO 8601)"), created_at_gte: flexibleDateTimeSchema.optional().describe("Filter for jobs created at or after a specific time (ISO 8601)."), created_at_lte: flexibleDateTimeSchema.optional().describe("Filter for jobs created at or before a specific time (ISO 8601)."), job_type_id: z.string().optional().describe("Job type filter"), channel_code: z.string().optional().describe("Channel filter"), tags: z.string().optional().describe("Tags filter (comma-separated)"), status: jobStatusSchema.optional().describe("Status filter"), } }, async (params) => { mcpDebugger.toolCall("get_jobs_stats", params); try { const response = await withTiming( () => agentJobsClient.getStats(params), "get_jobs_stats API call" ); const stats = response.meta?.stats || {}; const filters = response.meta?.filters || {}; mcpDebugger.debug("Raw API response", { stats, filters }); const result = { content: [{ type: "text" as const, text: formatJobStats(stats, filters), }] }; mcpDebugger.toolResponse("get_jobs_stats", result); return result; } catch (error: any) { mcpDebugger.toolError("get_jobs_stats", error); return { content: [{ type: "text" as const, text: `Error getting job stats: ${error.message}`, }], }; } } ); }
• src/lib/agentJobsClient.ts:42-50 (helper)

  Helper method in AgentJobsClient that prepares parameters for fetching job statistics (adds include='stats' and limit=1) and calls the GET endpoint '/services/agent-jobs'. This is invoked by the tool handler.
  async getStats(filters: Record<string, any> = {}) { const params = { ...filters, include: 'stats', limit: 1 }; return this.get('/services/agent-jobs', params); }