check_usage

Instructions

Implementation Reference

• src/server.ts:234-260 (handler)

  The handler for the 'check_usage' tool. It calls the Lumiclip API GET /account/usage endpoint and returns the result (plan, credits_remaining, credits_total, period_start, period_end). The handler is registered via server.tool() with an empty input schema and various intent hints.

  server.tool(
    "check_usage",
    "Returns a JSON object with plan (string), credits_remaining (number), credits_total (number), period_start (ISO date), and period_end (ISO date). Call this before generate_clips to confirm the user has enough credits.",
    {
      title: "Check Usage",
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
    async () => {
      try {
        const result = await apiCall(config, "GET", "/account/usage");
        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:237-243 (schema)

  The tool configuration/metadata for check_usage, including intent hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). No input parameters (empty object schema).

  {
    title: "Check Usage",
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: true,
  },

• src/server.ts:9-37 (helper)

  The apiCall helper function used by the check_usage handler to make the actual HTTP request to the Lumiclip API (GET /account/usage).

  async function apiCall(
    config: ApiConfig,
    method: string,
    path: string,
    body?: unknown
  ) {
    const base = config.apiBase || "https://api.lumiclip.ai";
    const url = `${base}/api/v1${path}`;
    const res = await fetch(url, {
      method,
      headers: {
        Authorization: `Bearer ${config.apiKey}`,
        "Content-Type": "application/json",
      },
      ...(body ? { body: JSON.stringify(body) } : {}),
    });
  
    const data = (await res.json()) as Record<string, unknown>;
  
    if (!res.ok) {
      throw new Error(
        (data.error as string) ||
          (data.message as string) ||
          `API error ${res.status}`
      );
    }
  
    return data;
  }

• src/server.ts:234-235 (registration)

  Registration of the 'check_usage' tool via server.tool('check_usage', ...) in the createServer function.

  server.tool(
    "check_usage",

• src/http.ts:70-74 (registration)

  Secondary registration of 'check_usage' in the HTTP server's .well-known/mcp/server-card.json tool listing, used for discovery/metadata purposes.

  {
    name: "check_usage",
    description: "Returns {plan, credits_remaining, credits_total, period_start, period_end}. Check before generate_clips to confirm enough credits.",
    inputSchema: { type: "object", properties: {} },
  },