run402

Instructions

Implementation Reference

• src/tools/get-usage.ts:10-57 (handler)

  The handleGetUsage function is the main handler for the get_usage tool. It retrieves project info from the keystore, makes an API request to /admin/v1/projects/{project_id}/usage, and formats the response as a markdown table showing API calls, storage usage, limits, tier, status, and lease expiry.

  export async function handleGetUsage(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}/usage`, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${project.service_key}`,
      },
    });
  
    if (!res.ok) return formatApiError(res, "fetching usage");
  
    const body = res.body as {
      project_id: string;
      tier: string;
      api_calls: number;
      api_calls_limit: number;
      storage_bytes: number;
      storage_limit_bytes: number;
      lease_expires_at: string;
      status: string;
    };
  
    const storageMB = (body.storage_bytes / (1024 * 1024)).toFixed(1);
    const storageLimitMB = (body.storage_limit_bytes / (1024 * 1024)).toFixed(0);
    const apiPct = ((body.api_calls / body.api_calls_limit) * 100).toFixed(1);
    const storagePct = ((body.storage_bytes / body.storage_limit_bytes) * 100).toFixed(1);
  
    const lines = [
      `## Usage: \`${body.project_id}\``,
      ``,
      `| Metric | Used | Limit | % |`,
      `|--------|------|-------|---|`,
      `| API calls | ${body.api_calls.toLocaleString()} | ${body.api_calls_limit.toLocaleString()} | ${apiPct}% |`,
      `| Storage | ${storageMB}MB | ${storageLimitMB}MB | ${storagePct}% |`,
      ``,
      `| Field | Value |`,
      `|-------|-------|`,
      `| tier | ${body.tier} |`,
      `| status | ${body.status} |`,
      `| expires | ${body.lease_expires_at} |`,
    ];
  
    return { content: [{ type: "text", text: lines.join("\n") }] };
  }

• src/tools/get-usage.ts:6-8 (schema)

  The getUsageSchema defines the input validation schema using Zod, requiring a project_id string parameter.

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

• src/index.ts:100-105 (registration)

  The get_usage tool is registered with the MCP server with name 'get_usage', description 'Get project usage report — API calls, storage usage, limits, and lease expiry.', and the handler and schema imported from get-usage.js.

  server.tool(
    "get_usage",
    "Get project usage report — API calls, storage usage, limits, and lease expiry.",
    getUsageSchema,
    async (args) => handleGetUsage(args),
  );

• src/client.ts:18-63 (helper)

  The apiRequest helper function makes HTTP requests to the API. It handles JSON/text responses, network errors, and returns a standardized ApiResponse object with ok, status, is402, and body fields.

  export async function apiRequest(
    path: string,
    opts: ApiRequestOptions = {},
  ): Promise<ApiResponse> {
    const { method = "GET", headers = {}, body, rawBody } = opts;
    const url = `${getApiBase()}${path}`;
  
    const fetchHeaders: Record<string, string> = { ...headers };
    let fetchBody: string | undefined;
  
    if (rawBody !== undefined) {
      fetchBody = rawBody;
    } else if (body !== undefined) {
      fetchHeaders["Content-Type"] = fetchHeaders["Content-Type"] || "application/json";
      fetchBody = JSON.stringify(body);
    }
  
    let res: Response;
    try {
      res = await fetch(url, {
        method,
        headers: fetchHeaders,
        body: fetchBody,
      });
    } catch (err) {
      return {
        ok: false,
        status: 0,
        body: { error: `Network error: ${(err as Error).message}` },
      };
    }
  
    let resBody: unknown;
    const contentType = res.headers.get("content-type") || "";
    if (contentType.includes("application/json")) {
      resBody = await res.json();
    } else {
      resBody = await res.text();
    }
  
    if (res.status === 402) {
      return { ok: false, is402: true, status: 402, body: resBody };
    }
  
    return { ok: res.ok, status: res.status, body: resBody };
  }

• src/keystore.ts:42-48 (helper)

  The getProject helper function retrieves stored project credentials (anon_key, service_key, tier, expires_at) from the local keystore by project ID.

  export function getProject(
    projectId: string,
    path?: string,
  ): StoredProject | undefined {
    const store = loadKeyStore(path);
    return store.projects[projectId];
  }