mathter-mcp 0.1.0 → 0.2.0

package/README.md

@@ -69,6 +69,7 @@ so the first start takes a little longer than later ones. You need Node 18 or ne
 > "What math skills can Mathter do for grade 3?"
 > "Make a 5-page grade 3 subtraction pack called Warm-Ups, easy difficulty."
 > "A blank multiplication chart for grade 4."
+> "How many Mathter packs do I have left this month?"
 > "Ten worksheets of grade 6 fractions, hard, with worked solutions."
 
 The assistant replies with the path to the PDF. Open it and print.
@@ -83,6 +84,11 @@ Asks mathter.ca which skills exist right now and which grades each one covers. Y
 should call this before generating, so it picks a real skill rather than guessing. No key is sent
 — that list is public.
 
+### `check_allowance`
+
+Tells you how many packs your account has left, which plan it is on, and the date the allowance
+resets. It uses nothing, so ask any time: "How many Mathter packs do I have left?"
+
 ### `generate_worksheet_pack`
 
 Makes the pack. Only `skill` and `grade` are required; everything else has a sensible default.

package/dist/index.d.ts

@@ -76,6 +76,7 @@ export declare function buildGenerateBody(args: Args): Record<string, unknown>;
 export declare function packFilename(skill: string, grade: number, now?: Date): string;
 export declare function generateWorksheetPack(args: Args, cfg: MathterConfig): Promise<string>;
 export declare function listSkills(cfg: MathterConfig): Promise<string>;
+export declare function checkAllowance(cfg: MathterConfig): Promise<string>;
 export declare function handleCallTool(name: string, args: Args, cfg: MathterConfig): Promise<CallToolResult>;
 export declare function createMcpServer(cfg: MathterConfig): Server;
 export interface MainIO {

package/dist/index.js

@@ -32,7 +32,7 @@ import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 /** Kept in step with package.json by hand; it is only ever reported, never compared. */
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const DEFAULT_BASE_URL = "https://mathter.ca";
 /**
  * A pack render drives headless Chrome on the server, so it is slow by nature — minutes, not
@@ -230,16 +230,26 @@ export const TOOLS = [
         name: "generate_worksheet_pack",
         title: "Generate a Mathter worksheet pack",
         description: "Generate a printable math worksheet pack as a PDF and save it to this computer, then " +
-            "return the file path. The pack is billed to the Mathter account that owns MATHTER_API_KEY, " +
-            "under that account's normal monthly allowance — the same as making it on mathter.ca. " +
-            "Call list_skills first to choose a valid skill for the grade. Logo and branding come from " +
-            "the account itself and cannot be set here.",
+            "return the file path. Each pack uses one pack from the monthly allowance of the Mathter " +
+            "account that owns MATHTER_API_KEY, the same as making it on mathter.ca; call " +
+            "check_allowance to see how many are left. Call list_skills first to choose a valid skill " +
+            "for the grade. A Premium account's logo prints automatically: the teacher uploads it once " +
+            "at https://mathter.ca/account, so there is nothing to pass here for it.",
         // `as const` above keeps the literal types (so a typo in an enum value is a compile error
         // here rather than a silent runtime oddity); the SDK's Tool type wants a mutable JSON Schema
         // object, hence the one cast.
         inputSchema: GENERATE_SCHEMA,
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
+    {
+        name: "check_allowance",
+        title: "Check the Mathter allowance",
+        description: "How many worksheet packs the account that owns MATHTER_API_KEY has left this period, its " +
+            "plan, and the date the allowance resets. Free to call; it uses nothing. Check it before " +
+            "making several packs, or when the teacher asks how many they have left.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
     {
         name: "list_skills",
         title: "List Mathter skills",
@@ -522,6 +532,37 @@ export async function listSkills(cfg) {
     });
     return `${skills.length} skills available (grade 0 is kindergarten):\n${lines.join("\n")}`;
 }
+export async function checkAllowance(cfg) {
+    const url = `${cfg.baseUrl}/api/usage`;
+    const res = await request(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${cfg.apiKey}`, Accept: "application/json", "User-Agent": `mathter-mcp/${VERSION}` },
+    }, cfg);
+    if (!res.ok) {
+        const { parsed, text } = await readErrorBody(res);
+        // describeHttpError's 503 is about the PDF renderer's queue; here it means the usage count
+        // itself could not be read, and nothing about a renderer applies.
+        if (res.status === 503) {
+            throw new ToolError("Mathter could not check the allowance right now. Try again in a minute." + serverSaid(text));
+        }
+        throw new ToolError(describeHttpError(res.status, parsed, res.headers.get("retry-after"), { caller: "key", url }) + serverSaid(text));
+    }
+    const u = (await res.json().catch(() => null));
+    if (!u || typeof u.remaining !== "number" || typeof u.quota !== "number") {
+        throw new ToolError(`Mathter answered ${url} without allowance figures. Try again shortly.`);
+    }
+    const reset = u.resetsAt ? new Date(u.resetsAt) : null;
+    const resetText = reset && !Number.isNaN(reset.getTime())
+        ? reset.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "America/Toronto" })
+        : "the start of the next period";
+    const plan = `${u.plan ?? "Mathter"} plan${u.onTrial ? " (free trial)" : ""}`;
+    const perPack = typeof u.maxWorksheets === "number" ? ` Each pack can hold up to ${u.maxWorksheets} worksheets.` : "";
+    if (u.remaining <= 0) {
+        return (`No packs left: all ${u.quota} on the ${plan} are used. The allowance resets on ${resetText}; ` +
+            "to make more before then, upgrade at https://mathter.ca/pricing.");
+    }
+    return `${u.remaining} of ${u.quota} packs left on the ${plan}, resetting on ${resetText}.${perPack}`;
+}
 /**
  * The single outbound filter for tool results. Every text block of every result — success,
  * mapped error, unexpected throw, unknown tool name — passes through here on its way to the
@@ -548,11 +589,14 @@ async function runTool(name, args, cfg) {
         if (name === "list_skills") {
             return { content: [{ type: "text", text: await listSkills(cfg) }] };
         }
+        if (name === "check_allowance") {
+            return { content: [{ type: "text", text: await checkAllowance(cfg) }] };
+        }
         return {
             isError: true,
             content: [{
                     type: "text",
-                    text: `mathter-mcp has no tool called "${name}". It offers generate_worksheet_pack and list_skills.`,
+                    text: `mathter-mcp has no tool called "${name}". It offers generate_worksheet_pack, list_skills and check_allowance.`,
                 }],
         };
     }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "mathter-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "mcpName": "ca.mathter/mathter",
   "description": "MCP server for Mathter \u2014 ask your AI assistant for a printable math worksheet pack and get a PDF on disk.",
   "license": "MIT",
   "author": "Mathter (https://mathter.ca)",