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);
    }