run402

Instructions

Implementation Reference

• src/tools/subdomain.ts:19-64 (handler)

  The handleClaimSubdomain function is the main handler for the claim_subdomain tool. It accepts name, deployment_id, and optional project_id parameters. It authenticates using a service_key if project_id is provided, makes a POST request to /v1/subdomains API endpoint, and returns a formatted markdown response with the claimed subdomain details.

  export async function handleClaimSubdomain(args: {
    name: string;
    deployment_id: string;
    project_id?: string;
  }): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
    let authHeader: Record<string, string> = {};
  
    if (args.project_id) {
      const project = getProject(args.project_id);
      if (!project) return projectNotFound(args.project_id);
      authHeader = { Authorization: `Bearer ${project.service_key}` };
    }
  
    const res = await apiRequest("/v1/subdomains", {
      method: "POST",
      headers: authHeader,
      body: { name: args.name, deployment_id: args.deployment_id },
    });
  
    if (!res.ok) return formatApiError(res, "claiming subdomain");
  
    const body = res.body as {
      name: string;
      deployment_id: string;
      url: string;
      deployment_url: string;
      project_id: string | null;
      created_at: string;
      updated_at: string;
    };
  
    const lines = [
      `## Subdomain Claimed`,
      ``,
      `| Field | Value |`,
      `|-------|-------|`,
      `| subdomain | \`${body.name}\` |`,
      `| url | ${body.url} |`,
      `| deployment | \`${body.deployment_id}\` |`,
      `| deployment_url | ${body.deployment_url} |`,
      ``,
      `The site is now live at **${body.url}**`,
    ];
  
    return { content: [{ type: "text", text: lines.join("\n") }] };
  }

• src/tools/subdomain.ts:6-17 (schema)

  The claimSubdomainSchema defines the input validation using Zod. It specifies three parameters: 'name' (required string for subdomain name, 3-63 chars), 'deployment_id' (required string for the deployment to point to), and 'project_id' (optional string for ownership tracking and auth).

  export const claimSubdomainSchema = {
    name: z
      .string()
      .describe("Custom subdomain name (e.g. 'myapp' → myapp.run402.com). 3-63 chars, lowercase alphanumeric + hyphens."),
    deployment_id: z
      .string()
      .describe("Deployment ID to point this subdomain at (e.g. 'dpl_1709337600000_a1b2c3')"),
    project_id: z
      .string()
      .optional()
      .describe("Optional project ID for ownership tracking. Uses stored service_key for auth."),
  };

• src/index.ts:206-211 (registration)

  The claim_subdomain tool is registered with the MCP server using server.tool(). It's registered with name 'claim_subdomain', description explaining it claims a custom subdomain and points it at a deployment, the claimSubdomainSchema for validation, and handleClaimSubdomain as the handler.

  server.tool(
    "claim_subdomain",
    "Claim a custom subdomain (e.g. myapp.run402.com) and point it at an existing deployment. Free, requires service_key auth.",
    claimSubdomainSchema,
    async (args) => handleClaimSubdomain(args),
  );