Cantrip

Instructions

Implementation Reference

• src/tools.ts:442-448 (handler)

  Tool registration with inline handler that calls client.post("meter", ["tiers"], {}) to fetch available credit pack tiers. The shape is empty {}, indicating no input parameters required.

  {
    name: "cantrip_meter_tiers",
    description:
      "View available credit packs. Shows tier name, credits included, and price.",
    shape: {},
    handler: async () => client.post("meter", ["tiers"], {}),
  },

• src/client.ts:79-125 (helper)

  CantripClient.post method that makes HTTP POST request to the Cantrip API. Constructs request envelope with command/args/flags, injects project from config, adds authentication headers, and handles error responses including insufficient credits and authentication errors.

  async post(
    command: string,
    args: string[] = [],
    flags: Record<string, string> = {},
  ): Promise<CantripResponse> {
    const url = `${this.apiUrl}/api/cantrip`;
  
    // Inject project from .cantrip.json if not provided
    if (!flags.project) {
      const project = readProjectContext();
      if (project) flags.project = project;
    }
  
    const body: CantripRequest = { command, args, flags };
  
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
    };
    if (this.apiKey) {
      headers["Authorization"] = `Bearer ${this.apiKey}`;
    }
  
    let res: Response;
    try {
      res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
    } catch (err) {
      throw new Error(
        `Cannot reach Cantrip API at ${this.apiUrl}. ` +
          `Check your network connection and CANTRIP_API_KEY.\n` +
          `(${err instanceof Error ? err.message : String(err)})`,
      );
    }
  
    const json = (await res.json()) as CantripResponse;
    if ("error" in json && typeof json.error === "string") {
      let message = json.error;
      if (/insufficient credits/i.test(message)) {
        message += "\n\nPurchase credits at https://cantrip.ai";
      }
      if (/not authenticated/i.test(message) || /unauthorized/i.test(message)) {
        message +=
          "\n\nSet CANTRIP_API_KEY in your MCP server config. Get a key at https://cantrip.ai";
      }
      throw new Error(`cantrip error: ${message}`);
    }
    return json;
  }

• src/types.ts:2-6 (schema)

  CantripRequest interface defining the request envelope structure with command (string), args (string array), and flags (record of string key-value pairs).

  export interface CantripRequest {
    command: string;
    args: string[];
    flags: Record<string, string>;
  }

• src/types.ts:9-11 (schema)

  CantripResponse type definition - either an error object with error message string, or a generic JSON object (Record<string, unknown>).

  export type CantripResponse =
    | { error: string }
    | Record<string, unknown>;