list_projects

Instructions

Implementation Reference

• src/server.ts:177-200 (handler)

  The handler function for the list_projects tool. It accepts optional limit and status parameters, constructs a query string, calls the GET /projects API endpoing, and returns the JSON result. On error, it returns an isError response.

  async ({ limit, status }) => {
    try {
      const params = new URLSearchParams();
      if (limit) params.set("limit", String(limit));
      if (status) params.set("status", status);
      const qs = params.toString();
      const result = await apiCall(
        config,
        "GET",
        `/projects${qs ? `?${qs}` : ""}`
      );
      return {
        content: [
          { type: "text" as const, text: JSON.stringify(result, null, 2) },
        ],
      };
    } catch (err: unknown) {
      const message = err instanceof Error ? err.message : String(err);
      return {
        content: [{ type: "text" as const, text: `Error: ${message}` }],
        isError: true,
      };
    }
  }

• src/server.ts:151-201 (registration)

  Registration of the list_projects tool using server.tool() with name 'list_projects', description, Zod schema for input validation (limit: optional number, status: optional enum), and metadata hints.

  server.tool(
    "list_projects",
    "Returns a JSON object with projects (array), total, limit, and offset. Each project has: id, name, status, step, expected_clips, clips_count, duration, created_at. Use the status filter to find only completed or failed projects.",
    {
      limit: z
        .number()
        .optional()
        .describe("Maximum number of projects to return. Defaults to 20, maximum 100."),
      status: z
        .enum([
          "pending",
          "processing",
          "completed",
          "completed_no_clips",
          "failed",
        ])
        .optional()
        .describe("Filter results to only projects with this status."),
    },
    {
      title: "List Projects",
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
    async ({ limit, status }) => {
      try {
        const params = new URLSearchParams();
        if (limit) params.set("limit", String(limit));
        if (status) params.set("status", status);
        const qs = params.toString();
        const result = await apiCall(
          config,
          "GET",
          `/projects${qs ? `?${qs}` : ""}`
        );
        return {
          content: [
            { type: "text" as const, text: JSON.stringify(result, null, 2) },
          ],
        };
      } catch (err: unknown) {
        const message = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    }
  );

• src/server.ts:154-168 (schema)

  Input schema definition for list_projects using Zod. Defines optional 'limit' (number, max 100) and optional 'status' (enum: pending, processing, completed, completed_no_clips, failed).

  {
    limit: z
      .number()
      .optional()
      .describe("Maximum number of projects to return. Defaults to 20, maximum 100."),
    status: z
      .enum([
        "pending",
        "processing",
        "completed",
        "completed_no_clips",
        "failed",
      ])
      .optional()
      .describe("Filter results to only projects with this status."),

• src/http.ts:50-60 (registration)

  Static listing of the list_projects tool in the MCP server card JSON at /.well-known/mcp/server-card.json, providing name, description and inputSchema for tool discovery.

  {
    name: "list_projects",
    description: "Returns {projects[], total, limit, offset}. Each project has id, name, status, step, expected_clips, clips_count, duration, created_at.",
    inputSchema: {
      type: "object",
      properties: {
        limit: { type: "number", description: "Maximum projects to return. Defaults to 20, max 100." },
        status: { type: "string", enum: ["pending", "processing", "completed", "completed_no_clips", "failed"], description: "Filter by status." },
      },
    },
  },