github_agent_tasks_list_tasks

Instructions

Implementation Reference

• src/tools/agent-tasks.ts:49-64 (handler)

  The handler function for the 'github_agent_tasks_list_tasks' tool. Makes a GET request to `/agents/tasks` with optional query parameters (per_page, page, sort, direction, state, is_archived, since).

  {
    name: "github_agent_tasks_list_tasks",
    description: "List tasks",
    inputSchema: z.object({
      per_page: z.number().optional().describe("The number of results per page (max 100)."),
      page: z.number().optional().describe("The page number of the results to fetch."),
      sort: z.enum(["updated_at", "created_at"]).optional().describe("The field to sort results by. Can be `updated_at` or `created_at`."),
      direction: z.enum(["asc", "desc"]).optional().describe("The direction to sort results. Can be `asc` or `desc`."),
      state: z.string().optional().describe("Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`."),
      is_archived: z.boolean().optional().describe("Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`."),
      since: z.string().optional().describe("Only show tasks updated at or after this time (ISO 8601 timestamp)")
    }),
    handler: async (args: Record<string, any>) => {
      return githubRequest("GET", `/agents/tasks`, undefined, { per_page: args.per_page, page: args.page, sort: args.sort, direction: args.direction, state: args.state, is_archived: args.is_archived, since: args.since });
    },
  },

• src/tools/agent-tasks.ts:49-64 (schema)

  The input schema (Zod object) for the tool, defining optional parameters: per_page, page, sort, direction, state, is_archived, since.

  {
    name: "github_agent_tasks_list_tasks",
    description: "List tasks",
    inputSchema: z.object({
      per_page: z.number().optional().describe("The number of results per page (max 100)."),
      page: z.number().optional().describe("The page number of the results to fetch."),
      sort: z.enum(["updated_at", "created_at"]).optional().describe("The field to sort results by. Can be `updated_at` or `created_at`."),
      direction: z.enum(["asc", "desc"]).optional().describe("The direction to sort results. Can be `asc` or `desc`."),
      state: z.string().optional().describe("Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`."),
      is_archived: z.boolean().optional().describe("Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`."),
      since: z.string().optional().describe("Only show tasks updated at or after this time (ISO 8601 timestamp)")
    }),
    handler: async (args: Record<string, any>) => {
      return githubRequest("GET", `/agents/tasks`, undefined, { per_page: args.per_page, page: args.page, sort: args.sort, direction: args.direction, state: args.state, is_archived: args.is_archived, since: args.since });
    },
  },

• src/tools/agent-tasks.ts:5-75 (registration)

  The tool is part of the `agentTasksTools` array exported from src/tools/agent-tasks.ts. The array is re-exported via src/tools/index.ts (line 4) and imported in src/index.ts (line 7) where it's included in the `allToolModules` array under category 'agent-tasks' (line 58). The actual registration to the MCP server happens at src/index.ts lines 110-130 via server.tool().

  export const agentTasksTools = [
    {
      name: "github_agent_tasks_list_tasks_for_repo",
      description: "List tasks for repository",
      inputSchema: z.object({
        owner: z.string().describe("owner"),
        repo: z.string().describe("repo"),
        per_page: z.number().optional().describe("The number of results per page (max 100)."),
        page: z.number().optional().describe("The page number of the results to fetch."),
        sort: z.enum(["updated_at", "created_at"]).optional().describe("The field to sort results by. Can be `updated_at` or `created_at`."),
        direction: z.enum(["asc", "desc"]).optional().describe("The direction to sort results. Can be `asc` or `desc`."),
        state: z.string().optional().describe("Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`."),
        is_archived: z.boolean().optional().describe("Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`."),
        since: z.string().optional().describe("Only show tasks updated at or after this time (ISO 8601 timestamp)"),
        creator_id: z.number().optional().describe("Filter tasks by creator user ID")
      }),
      handler: async (args: Record<string, any>) => {
        return githubRequest("GET", `/agents/repos/${args.owner}/${args.repo}/tasks`, undefined, { per_page: args.per_page, page: args.page, sort: args.sort, direction: args.direction, state: args.state, is_archived: args.is_archived, since: args.since, creator_id: args.creator_id });
      },
    },
    {
      name: "github_agent_tasks_create_task",
      description: "Create a task",
      inputSchema: z.object({
        owner: z.string().describe("owner"),
        repo: z.string().describe("repo"),
        body: z.record(z.string(), z.unknown()).optional().describe("Request body (JSON object)")
      }),
      handler: async (args: Record<string, any>) => {
        return githubRequest("POST", `/agents/repos/${args.owner}/${args.repo}/tasks`, args.body, undefined);
      },
    },
    {
      name: "github_agent_tasks_get_task_by_repo_and_id",
      description: "Get a task by repo",
      inputSchema: z.object({
        owner: z.string().describe("owner"),
        repo: z.string().describe("repo"),
        task_id: z.string().describe("task_id")
      }),
      handler: async (args: Record<string, any>) => {
        return githubRequest("GET", `/agents/repos/${args.owner}/${args.repo}/tasks/${args.task_id}`, undefined, undefined);
      },
    },
    {
      name: "github_agent_tasks_list_tasks",
      description: "List tasks",
      inputSchema: z.object({
        per_page: z.number().optional().describe("The number of results per page (max 100)."),
        page: z.number().optional().describe("The page number of the results to fetch."),
        sort: z.enum(["updated_at", "created_at"]).optional().describe("The field to sort results by. Can be `updated_at` or `created_at`."),
        direction: z.enum(["asc", "desc"]).optional().describe("The direction to sort results. Can be `asc` or `desc`."),
        state: z.string().optional().describe("Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`."),
        is_archived: z.boolean().optional().describe("Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`."),
        since: z.string().optional().describe("Only show tasks updated at or after this time (ISO 8601 timestamp)")
      }),
      handler: async (args: Record<string, any>) => {
        return githubRequest("GET", `/agents/tasks`, undefined, { per_page: args.per_page, page: args.page, sort: args.sort, direction: args.direction, state: args.state, is_archived: args.is_archived, since: args.since });
      },
    },
    {
      name: "github_agent_tasks_get_task_by_id",
      description: "Get a task by ID",
      inputSchema: z.object({
        task_id: z.string().describe("task_id")
      }),
      handler: async (args: Record<string, any>) => {
        return githubRequest("GET", `/agents/tasks/${args.task_id}`, undefined, undefined);
      },
    },
  ];

• src/client.ts:9-59 (helper)

  The `githubRequest` helper function used by the handler to make authenticated HTTP requests to the GitHub API.

  export async function githubRequest<T>(
    method: string,
    path: string,
    body?: Record<string, unknown>,
    params?: Record<string, string | number | boolean | string[] | undefined>
  ): Promise<T> {
    const url = new URL(`${BASE_URL}${path}`);
  
    if (params) {
      for (const [key, value] of Object.entries(params)) {
        if (value === undefined || value === null || value === "") continue;
        if (Array.isArray(value)) {
          url.searchParams.set(key, value.join(","));
        } else {
          url.searchParams.set(key, String(value));
        }
      }
    }
  
    const headers: Record<string, string> = {
      Authorization: `Bearer ${getToken()}`,
      Accept: "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      "User-Agent": "github-mcp/1.0.0",
    };
  
    if (body) {
      headers["Content-Type"] = "application/json";
    }
  
    const res = await fetch(url.toString(), {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    });
  
    if (!res.ok) {
      const text = await res.text().catch(() => "");
      let detail = text;
      try {
        const json = JSON.parse(text);
        detail = json.message || text;
        if (json.errors) detail += ` -- ${JSON.stringify(json.errors)}`;
      } catch {}
      throw new Error(`GitHub API error ${res.status}: ${detail}`);
    }
  
    if (res.status === 204) return {} as T;
  
    return res.json() as Promise<T>;
  }

• src/index.ts:110-130 (registration)

  The MCP server registration loop - iterates over all tools and calls server.tool() with the tool's name, description, schema, and handler, wrapping the handler result in a text content response.

  for (const tool of allTools) {
    server.tool(
      tool.name,
      tool.description,
      tool.inputSchema.shape as any,
      async (args: any) => {
        try {
          const result = await tool.handler(args as any);
          return {
            content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
          };
        } catch (err) {
          const message = err instanceof Error ? err.message : String(err);
          return {
            content: [{ type: "text" as const, text: `Error: ${message}` }],
            isError: true,
          };
        }
      }
    );
  }