run402

Instructions

Implementation Reference

• src/tools/list-versions.ts:10-62 (handler)

  The handleListVersions function executes the tool logic: retrieves project from keystore, makes authenticated API request to /admin/v1/projects/{project_id}/versions endpoint, and formats the response as a markdown table listing version details (ID, visibility, forkability, tags, creation date).

  export async function handleListVersions(args: {
    project_id: string;
  }): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
    const project = getProject(args.project_id);
    if (!project) return projectNotFound(args.project_id);
  
    const res = await apiRequest(`/admin/v1/projects/${args.project_id}/versions`, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${project.service_key}`,
      },
    });
  
    if (!res.ok) return formatApiError(res, "listing versions");
  
    const body = res.body as {
      versions: Array<{
        id: string;
        description: string | null;
        tags: string[];
        visibility: string;
        fork_allowed: boolean;
        created_at: string;
      }>;
    };
  
    if (body.versions.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `## Versions\n\n_No published versions. Use \`publish_app\` to publish one._`,
          },
        ],
      };
    }
  
    const lines = [
      `## Versions (${body.versions.length})`,
      ``,
      `| ID | Visibility | Forkable | Tags | Created |`,
      `|----|------------|----------|------|---------|`,
    ];
  
    for (const v of body.versions) {
      const tags = v.tags.length > 0 ? v.tags.join(", ") : "-";
      lines.push(
        `| \`${v.id}\` | ${v.visibility} | ${v.fork_allowed ? "Yes" : "No"} | ${tags} | ${v.created_at} |`,
      );
    }
  
    return { content: [{ type: "text", text: lines.join("\n") }] };
  }

• src/tools/list-versions.ts:6-8 (schema)

  The listVersionsSchema defines the input validation using Zod, requiring a project_id string parameter with description.

  export const listVersionsSchema = {
    project_id: z.string().describe("The project ID"),
  };

• src/index.ts:257-262 (registration)

  Registers the 'list_versions' tool with the MCP server, providing the tool name, description, schema, and handler function wrapper.

  server.tool(
    "list_versions",
    "List published versions of a project.",
    listVersionsSchema,
    async (args) => handleListVersions(args),
  );