Agent Jobs MCP Server

Instructions

Implementation Reference

• src/tools/list_jobs.ts:41-96 (handler)

  The core handler function for the 'list_jobs' tool. Builds query parameters from inputs, fetches jobs via agentJobsClient.getWithMeta('/services/agent-jobs'), processes data and meta, formats output using formatJobList, handles errors, and returns structured text content.

  async (params) => {
    mcpDebugger.toolCall("list_jobs", params);
  
    const endpoint = `/services/agent-jobs`;
  
    // Build query parameters object from provided params
    const queryParams: Record<string, any> = {};
    for (const [key, value] of Object.entries(params)) {
      if (value !== undefined) {
        queryParams[key] = value;
      }
    }
  
    mcpDebugger.debug("Built query parameters", { endpoint, queryParams });
  
    try {
      const apiResponse = await withTiming(
        () => agentJobsClient.getWithMeta(endpoint, queryParams),
        "list_jobs API call"
      );
  
      // Access the full API response structure
      const jobs = apiResponse.data || [];
      const meta = apiResponse.meta || {};
  
      mcpDebugger.debug("Raw API response", {
        fullResponse: apiResponse,
        jobsCount: jobs.length,
        meta,
        firstJob: jobs[0] || null
      });
  
      const result = {
        content: [{
          type: "text" as const,
          text: formatJobList(jobs, meta),
        }]
      };
  
      mcpDebugger.toolResponse("list_jobs", {
        jobsReturned: jobs.length,
        resultLength: result.content[0].text.length
      });
  
      return result;
    } catch (error: any) {
      mcpDebugger.toolError("list_jobs", error);
  
      return {
        content: [{
          type: "text" as const,
          text: `Error listing jobs: ${error.message}`,
        }],
      };
    }
  }

• src/tools/list_jobs.ts:26-39 (schema)

  Zod-based input schema defining all parameters for filtering, pagination, and sorting jobs in the list_jobs tool.

  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)."),
    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'.")
  }

• src/tools/list_jobs.ts:8-16 (schema)

  Zod enum schema for job statuses, referenced in the input schema for status filtering.

  // Define the schema for job status based on docs/agent-jobs-api.md:246-251
  const jobStatusSchema = z.enum([
    "waiting",
    "scheduled",
    "running",
    "completed",
    "failed",
    "canceled"
  ]);

• src/tools/list_jobs.ts:18-98 (registration)

  Module that registers the 'list_jobs' tool with the MCP server, including name, spec (description, annotations, inputSchema), and handler function.

  export default (server: McpServer) => {
    server.registerTool(
      "list_jobs",
      {
        description: "Retrieves a list of agent jobs, with optional filters and pagination.",
        annotations: {
          title: "List Agent Jobs"
        },
        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)."),
          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'.")
        }
      },
      async (params) => {
        mcpDebugger.toolCall("list_jobs", params);
  
        const endpoint = `/services/agent-jobs`;
  
        // Build query parameters object from provided params
        const queryParams: Record<string, any> = {};
        for (const [key, value] of Object.entries(params)) {
          if (value !== undefined) {
            queryParams[key] = value;
          }
        }
  
        mcpDebugger.debug("Built query parameters", { endpoint, queryParams });
  
        try {
          const apiResponse = await withTiming(
            () => agentJobsClient.getWithMeta(endpoint, queryParams),
            "list_jobs API call"
          );
  
          // Access the full API response structure
          const jobs = apiResponse.data || [];
          const meta = apiResponse.meta || {};
  
          mcpDebugger.debug("Raw API response", {
            fullResponse: apiResponse,
            jobsCount: jobs.length,
            meta,
            firstJob: jobs[0] || null
          });
  
          const result = {
            content: [{
              type: "text" as const,
              text: formatJobList(jobs, meta),
            }]
          };
  
          mcpDebugger.toolResponse("list_jobs", {
            jobsReturned: jobs.length,
            resultLength: result.content[0].text.length
          });
  
          return result;
        } catch (error: any) {
          mcpDebugger.toolError("list_jobs", error);
  
          return {
            content: [{
              type: "text" as const,
              text: `Error listing jobs: ${error.message}`,
            }],
          };
        }
      }
    );
  }