paisa-mcp 0.1.0 → 0.2.0

package/dist/index.js

@@ -39147,6 +39147,220 @@ function validateAndWarnToolName(name) {
   issueToolNameWarning(name, result.warnings);
   return result.isValid;
 }
+var MAX_TEMPLATE_LENGTH = 1e6;
+var MAX_VARIABLE_LENGTH = 1e6;
+var MAX_TEMPLATE_EXPRESSIONS = 1e4;
+var MAX_REGEX_LENGTH = 1e6;
+var UriTemplate = class UriTemplate2 {
+  static isTemplate(str) {
+    return /\{[^}\s]+\}/.test(str);
+  }
+  static validateLength(str, max, context) {
+    if (str.length > max)
+      throw new Error(`${context} exceeds maximum length of ${max} characters (got ${str.length})`);
+  }
+  template;
+  parts;
+  get variableNames() {
+    return this.parts.flatMap((part) => typeof part === "string" ? [] : part.names);
+  }
+  constructor(template) {
+    UriTemplate2.validateLength(template, MAX_TEMPLATE_LENGTH, "Template");
+    this.template = template;
+    this.parts = this.parse(template);
+  }
+  toString() {
+    return this.template;
+  }
+  parse(template) {
+    const parts = [];
+    let currentText = "";
+    let i = 0;
+    let expressionCount = 0;
+    while (i < template.length)
+      if (template[i] === "{") {
+        if (currentText) {
+          parts.push(currentText);
+          currentText = "";
+        }
+        const end = template.indexOf("}", i);
+        if (end === -1)
+          throw new Error("Unclosed template expression");
+        expressionCount++;
+        if (expressionCount > MAX_TEMPLATE_EXPRESSIONS)
+          throw new Error(`Template contains too many expressions (max ${MAX_TEMPLATE_EXPRESSIONS})`);
+        const expr = template.slice(i + 1, end);
+        const operator = this.getOperator(expr);
+        const exploded = expr.includes("*");
+        const names = this.getNames(expr);
+        const name = names[0];
+        for (const name$1 of names)
+          UriTemplate2.validateLength(name$1, MAX_VARIABLE_LENGTH, "Variable name");
+        parts.push({
+          name,
+          operator,
+          names,
+          exploded
+        });
+        i = end + 1;
+      } else {
+        currentText += template[i];
+        i++;
+      }
+    if (currentText)
+      parts.push(currentText);
+    return parts;
+  }
+  getOperator(expr) {
+    return [
+      "+",
+      "#",
+      ".",
+      "/",
+      "?",
+      "&"
+    ].find((op) => expr.startsWith(op)) || "";
+  }
+  getNames(expr) {
+    const operator = this.getOperator(expr);
+    return expr.slice(operator.length).split(",").map((name) => name.replace("*", "").trim()).filter((name) => name.length > 0);
+  }
+  encodeValue(value, operator) {
+    UriTemplate2.validateLength(value, MAX_VARIABLE_LENGTH, "Variable value");
+    if (operator === "+" || operator === "#")
+      return encodeURI(value);
+    return encodeURIComponent(value);
+  }
+  expandPart(part, variables) {
+    if (part.operator === "?" || part.operator === "&") {
+      const pairs = part.names.map((name) => {
+        const value$1 = variables[name];
+        if (value$1 === undefined)
+          return "";
+        return `${name}=${Array.isArray(value$1) ? value$1.map((v) => this.encodeValue(v, part.operator)).join(",") : this.encodeValue(value$1.toString(), part.operator)}`;
+      }).filter((pair) => pair.length > 0);
+      if (pairs.length === 0)
+        return "";
+      return (part.operator === "?" ? "?" : "&") + pairs.join("&");
+    }
+    if (part.names.length > 1) {
+      const values = part.names.map((name) => variables[name]).filter((v) => v !== undefined);
+      if (values.length === 0)
+        return "";
+      return values.map((v) => Array.isArray(v) ? v[0] : v).join(",");
+    }
+    const value = variables[part.name];
+    if (value === undefined)
+      return "";
+    const encoded = (Array.isArray(value) ? value : [value]).map((v) => this.encodeValue(v, part.operator));
+    switch (part.operator) {
+      case "":
+        return encoded.join(",");
+      case "+":
+        return encoded.join(",");
+      case "#":
+        return "#" + encoded.join(",");
+      case ".":
+        return "." + encoded.join(".");
+      case "/":
+        return "/" + encoded.join("/");
+      default:
+        return encoded.join(",");
+    }
+  }
+  expand(variables) {
+    let result = "";
+    let hasQueryParam = false;
+    for (const part of this.parts) {
+      if (typeof part === "string") {
+        result += part;
+        continue;
+      }
+      const expanded = this.expandPart(part, variables);
+      if (!expanded)
+        continue;
+      result += (part.operator === "?" || part.operator === "&") && hasQueryParam ? expanded.replace("?", "&") : expanded;
+      if (part.operator === "?" || part.operator === "&")
+        hasQueryParam = true;
+    }
+    return result;
+  }
+  escapeRegExp(str) {
+    return str.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+  }
+  partToRegExp(part) {
+    const patterns = [];
+    for (const name$1 of part.names)
+      UriTemplate2.validateLength(name$1, MAX_VARIABLE_LENGTH, "Variable name");
+    if (part.operator === "?" || part.operator === "&") {
+      for (let i = 0;i < part.names.length; i++) {
+        const name$1 = part.names[i];
+        const prefix = i === 0 ? "\\" + part.operator : "&";
+        patterns.push({
+          pattern: prefix + this.escapeRegExp(name$1) + "=([^&]+)",
+          name: name$1
+        });
+      }
+      return patterns;
+    }
+    let pattern;
+    const name = part.name;
+    switch (part.operator) {
+      case "":
+        pattern = part.exploded ? "([^/,]+(?:,[^/,]+)*)" : "([^/,]+)";
+        break;
+      case "+":
+      case "#":
+        pattern = "(.+)";
+        break;
+      case ".":
+        pattern = String.raw`\.([^/,]+)`;
+        break;
+      case "/":
+        pattern = "/" + (part.exploded ? "([^/,]+(?:,[^/,]+)*)" : "([^/,]+)");
+        break;
+      default:
+        pattern = "([^/]+)";
+    }
+    patterns.push({
+      pattern,
+      name
+    });
+    return patterns;
+  }
+  match(uri) {
+    UriTemplate2.validateLength(uri, MAX_TEMPLATE_LENGTH, "URI");
+    let pattern = "^";
+    const names = [];
+    for (const part of this.parts)
+      if (typeof part === "string")
+        pattern += this.escapeRegExp(part);
+      else {
+        const patterns = this.partToRegExp(part);
+        for (const { pattern: partPattern2, name } of patterns) {
+          pattern += partPattern2;
+          names.push({
+            name,
+            exploded: part.exploded
+          });
+        }
+      }
+    pattern += "$";
+    UriTemplate2.validateLength(pattern, MAX_REGEX_LENGTH, "Generated regex pattern");
+    const regex = new RegExp(pattern);
+    const match = uri.match(regex);
+    if (!match)
+      return null;
+    const result = {};
+    for (const [i, name_] of names.entries()) {
+      const { name, exploded } = name_;
+      const value = match[i + 1];
+      const cleanName = name.replace("*", "");
+      result[cleanName] = exploded && value.includes(",") ? value.split(",") : value;
+    }
+    return result;
+  }
+};
 function isZodV4Schema(v) {
   return typeof v === "object" && v !== null && "_zod" in v;
 }
@@ -48100,6 +48314,22 @@ var McpServer = class {
       this.server.sendPromptListChanged();
   }
 };
+var ResourceTemplate = class {
+  _uriTemplate;
+  constructor(uriTemplate, _callbacks) {
+    this._callbacks = _callbacks;
+    this._uriTemplate = typeof uriTemplate === "string" ? new UriTemplate(uriTemplate) : uriTemplate;
+  }
+  get uriTemplate() {
+    return this._uriTemplate;
+  }
+  get listCallback() {
+    return this._callbacks.list;
+  }
+  completeCallback(variable) {
+    return this._callbacks.complete?.[variable];
+  }
+};
 function createToolExecutor(inputSchema, handler) {
   if (inputSchema) {
     const callback$1 = handler;
@@ -53421,6 +53651,108 @@ function applyAnnotations(tools) {
   });
 }
 
+// src/prompts.ts
+var CONFIRM = "Ask me before any write; show what will change first (counts, not a dump).";
+var month = exports_external.string().regex(/^\d{4}-\d{2}$/).optional().describe("YYYY-MM; defaults to the last full month");
+function monthText(m) {
+  if (!m)
+    return "the last full month";
+  const [y, mm] = m.split("-");
+  return `${m} (month=${Number(mm)}, year=${y})`;
+}
+function rangeText(a) {
+  if (a.startDate && a.endDate)
+    return ` startDate=${a.startDate} endDate=${a.endDate}`;
+  if (a.startDate)
+    return ` startDate=${a.startDate}`;
+  if (a.endDate)
+    return ` endDate=${a.endDate}`;
+  return "";
+}
+var PROMPTS = [
+  {
+    name: "monthly_review",
+    title: "Monthly review",
+    description: "Review one month: income, spending, savings rate, budgets, what's due next.",
+    args: exports_external.object({ month }),
+    text: (a) => [
+      `Review my finances for ${monthText(a.month)}.`,
+      "1. `check_alerts` — note anything urgent.",
+      "2. `get_report` report='monthly' months=3 — income, expenses, savings rate vs the months before.",
+      "3. `get_analytics` report='spending_trends' months=3 — category breakdown and budget vs actual (read that month's row).",
+      "4. `get_transactions` for that month with amountMin to find the biggest items (limit 25).",
+      "5. `get_report` report='upcoming' days=30 — EMIs, SIPs, renewals, card bills.",
+      "Summarize: income, spend, savings rate, top categories, over-budget categories, unusual items, upcoming dues. Do not edit, import or delete anything.",
+      "If I ask to save it, call `generate_monthly_report` with month and year."
+    ].join(`
+`)
+  },
+  {
+    name: "import_statement",
+    title: "Import a statement",
+    description: "Preview, confirm, import and categorize a bank or card statement (PDF or CSV).",
+    args: exports_external.object({
+      filePath: exports_external.string().optional().describe("Local path of the statement file")
+    }),
+    text: (a) => [
+      `Import the statement ${a.filePath ? `at ${a.filePath}` : "I give you (ask for the file path)"}.`,
+      "1. `list_entities` entity='bank_accounts' — pick the account. Missing? Create it with `upsert_entity` entity='bank_account' only after I confirm name, bank, type, last4 and owner.",
+      "2. `preview_import` — from='pdf' with filePath + account, or from='csv' with filePath. It writes nothing. Show me the new / already-in-Paisa / conflict counts and totals (CSV: the detected mapping).",
+      "3. After I confirm, `import_statement` with the same args (CSV: the confirmed mapping). Never pass force unless I say so. CSV import is not available in private mode.",
+      "4. Credit card statement: `get_settlement_candidates` with ccAccountId, then mark the matching bank debits isTransfer=true with `update_transaction` once I confirm.",
+      "5. `sync_recurring`, then categorize what's left with `get_uncategorized_groups` → `categorize_groups` (see the categorize_uncategorized prompt).",
+      CONFIRM
+    ].join(`
+`)
+  },
+  {
+    name: "categorize_uncategorized",
+    title: "Categorize uncategorized",
+    description: "Group uncategorized transactions, propose categories, apply them and save learning rules.",
+    args: exports_external.object({
+      startDate: exports_external.string().optional().describe("YYYY-MM-DD"),
+      endDate: exports_external.string().optional().describe("YYYY-MM-DD")
+    }),
+    text: (a) => [
+      "Categorize my uncategorized transactions.",
+      "1. `list_entities` entity='categories' (or the paisa://categories resource) for valid slugs.",
+      `2. \`get_uncategorized_groups\`${rangeText(a)} — groups by pattern, biggest first.`,
+      "3. Propose a category slug per group as a table (pattern, count, total, slug). Ask about groups you are unsure of instead of guessing.",
+      `4. After I confirm, \`categorize_groups\`${rangeText(a)} with dryRun=true, show the counts, then run it again without dryRun. It also saves learning rules for future imports.`,
+      "5. Transfers to/from individuals: `backfill_persons` with dryRun=true, then for real once I confirm.",
+      "6. Tell me how many uncategorized groups remain.",
+      CONFIRM
+    ].join(`
+`)
+  },
+  {
+    name: "budget_check",
+    title: "Budget check",
+    description: "Compare one month's spending to its budgets and suggest changes.",
+    args: exports_external.object({ month }),
+    text: (a) => [
+      `Check my budgets for ${monthText(a.month)}.`,
+      "1. `list_entities` entity='budgets' with month and year.",
+      "2. `get_analytics` report='spending_trends' months=3 — budget vs actual (read that month's row).",
+      "3. Show a table: category, budget, spent, remaining, % used. Flag categories over 80% and over 100%, and big categories with no budget.",
+      "4. Suggest changes. Call `set_budget` (categoryId from `list_entities` entity='categories') only for the changes I approve."
+    ].join(`
+`)
+  }
+];
+function registerPrompts(server) {
+  for (const p of PROMPTS) {
+    const cb = (args) => ({
+      messages: [{ role: "user", content: { type: "text", text: p.text(args) } }]
+    });
+    if (p.args) {
+      server.registerPrompt(p.name, { title: p.title, description: p.description, argsSchema: p.args }, (args) => cb(args));
+    } else {
+      server.registerPrompt(p.name, { title: p.title, description: p.description }, () => cb({}));
+    }
+  }
+}
+
 // src/tools/alert-rules.ts
 function alertRuleVariants(client) {
   return {
@@ -57279,22 +57611,22 @@ function parseMonthDayYear(raw) {
   const match = raw.trim().match(/^(\w+)\s+(\d{1,2}),?\s+(\d{4})$/);
   if (!match)
     return null;
-  const month = MONTH_MAP[match[1].toLowerCase()];
-  if (!month)
+  const month2 = MONTH_MAP[match[1].toLowerCase()];
+  if (!month2)
     return null;
   const day = parseInt(match[2], 10);
   const year = parseInt(match[3], 10);
-  const iso = `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
-  return { month, day, year, iso };
+  const iso = `${year}-${String(month2).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+  return { month: month2, day, year, iso };
 }
 function parseMonthDay(raw) {
   const match = raw.trim().match(/^(\w+)\s+(\d{1,2})$/);
   if (!match)
     return null;
-  const month = MONTH_MAP[match[1].toLowerCase()];
-  if (!month)
+  const month2 = MONTH_MAP[match[1].toLowerCase()];
+  if (!month2)
     return null;
-  return { month, day: parseInt(match[2], 10) };
+  return { month: month2, day: parseInt(match[2], 10) };
 }
 function parseAmexPdfDate(raw, meta3) {
   const parsed = parseMonthDay(raw);
@@ -57697,10 +58029,10 @@ function parseMonthNameDate(raw) {
   const match = raw.trim().match(/^(\d{1,2})\s+(\w{3})\w*,?\s+(\d{4})$/);
   if (!match)
     return null;
-  const month = MONTH_NAMES[match[2].toLowerCase().slice(0, 3)];
-  if (!month)
+  const month2 = MONTH_NAMES[match[2].toLowerCase().slice(0, 3)];
+  if (!month2)
     return null;
-  return `${match[3]}-${month}-${match[1].padStart(2, "0")}`;
+  return `${match[3]}-${month2}-${match[1].padStart(2, "0")}`;
 }
 function parseDdMmYyyy(raw) {
   const match = raw.trim().match(/^(\d{2})\/(\d{2})\/(\d{4})/);
@@ -57998,13 +58330,13 @@ function parseHdfcDate(raw) {
   if (!match)
     return null;
   const day = match[1];
-  const month = match[2];
+  const month2 = match[2];
   let year = match[3];
   if (year.length === 2) {
     const num = parseInt(year, 10);
     year = num > 50 ? `19${year}` : `20${year}`;
   }
-  return `${year}-${month}-${day}`;
+  return `${year}-${month2}-${day}`;
 }
 function parseAmount3(raw) {
   if (!raw)
@@ -60263,10 +60595,127 @@ var REGISTRATIONS = [
   { title: "Settings", tools: settingsTools },
   { title: "Encryption & privacy", tools: authCryptoTools }
 ];
+
+// src/resources.ts
+var MERCHANT_CAP = 500;
+var JSON_MIME = "application/json";
+var RESOURCES = [
+  {
+    name: "categories",
+    uri: "paisa://categories",
+    title: "Categories",
+    description: "Category tree (id, slug, name, type, children). Same as list_entities categories.",
+    tool: "list_entities",
+    args: { entity: "categories" }
+  },
+  {
+    name: "bank_accounts",
+    uri: "paisa://bank-accounts",
+    title: "Bank accounts",
+    description: "Bank accounts and cards (id, name, bank, type, last4, owner).",
+    tool: "list_entities",
+    args: { entity: "bank_accounts" }
+  },
+  {
+    name: "persons",
+    uri: "paisa://persons",
+    title: "Persons",
+    description: "People you send/receive money from (decrypted in private mode).",
+    tool: "list_entities",
+    args: { entity: "persons" }
+  },
+  {
+    name: "merchants",
+    uri: "paisa://merchants",
+    title: "Merchants",
+    description: `Merchants with their category (first ${MERCHANT_CAP}; look others up with list_entities entity='merchants' rawId).`,
+    tool: "list_entities",
+    args: { entity: "merchants" },
+    shape: capMerchants
+  },
+  {
+    name: "household",
+    uri: "paisa://household",
+    title: "Household",
+    description: "Household name, currency, locale, owner labels and members.",
+    tool: "get_settings",
+    args: { section: "household" }
+  },
+  {
+    name: "profile",
+    uri: "paisa://profile",
+    title: "Profile",
+    description: "Your name, email and owner slug.",
+    tool: "get_settings",
+    args: { section: "profile" }
+  }
+];
+var TRANSACTION_TEMPLATE = "paisa://transactions/{id}";
+function capMerchants(value) {
+  const v2 = value;
+  if (!v2 || !Array.isArray(v2.data) || v2.data.length <= MERCHANT_CAP)
+    return value;
+  return {
+    ...v2,
+    data: v2.data.slice(0, MERCHANT_CAP),
+    truncated: {
+      returned: MERCHANT_CAP,
+      total: v2.data.length,
+      hint: "Use list_entities entity='merchants' rawId=<UPI ID or name> to find one."
+    }
+  };
+}
+function scrubCiphertext(value) {
+  const scrub = (row) => {
+    if (row && typeof row === "object" && typeof row.cipher === "string") {
+      Object.assign(row, { cipher: null, undecrypted: true });
+    }
+  };
+  const data = value?.data;
+  if (Array.isArray(data))
+    data.forEach(scrub);
+  else
+    scrub(data);
+  return value;
+}
+async function runTool(tool, args, mcp) {
+  const input2 = tool.input ? await tool.input.parseAsync(args) : args;
+  const ctx = { tool: tool.name, signal: mcp.mcpReq.signal, mcp };
+  return tool.handler(input2, ctx);
+}
+function jsonContents(uri, value) {
+  return { contents: [{ uri: uri.href, mimeType: JSON_MIME, text: JSON.stringify(value ?? null) }] };
+}
+function registerResources(server, tools) {
+  const byName = new Map(tools.map((t2) => [t2.name, t2]));
+  const need = (name) => {
+    const t2 = byName.get(name);
+    if (!t2)
+      throw new Error(`MCP resources: tool ${name} is not registered`);
+    return t2;
+  };
+  for (const r2 of RESOURCES) {
+    const tool = need(r2.tool);
+    server.registerResource(r2.name, r2.uri, { title: r2.title, description: r2.description, mimeType: JSON_MIME }, async (uri, mcp) => {
+      const value = scrubCiphertext(await runTool(tool, r2.args, mcp));
+      return jsonContents(uri, r2.shape ? r2.shape(value) : value);
+    });
+  }
+  const getTransaction = need("get_transaction");
+  server.registerResource("transaction", new ResourceTemplate(TRANSACTION_TEMPLATE, { list: undefined }), {
+    title: "Transaction",
+    description: "One transaction by UUID (same as get_transaction; decrypted in private mode).",
+    mimeType: JSON_MIME
+  }, async (uri, variables, mcp) => {
+    const id = Array.isArray(variables.id) ? variables.id[0] : variables.id;
+    const value = scrubCiphertext(await runTool(getTransaction, { id }, mcp));
+    return jsonContents(uri, value);
+  });
+}
 // package.json
 var package_default = {
   name: "paisa-mcp",
-  version: "0.1.0",
+  version: "0.2.0",
   repository: {
     type: "git",
     url: "git+https://github.com/nimit9/paisa.git",
@@ -60332,6 +60781,8 @@ function buildServer(client, crypto3) {
     errorResult: paisaErrorResult
   });
   hideFromToolsList(server, new Set(tools.filter(isAlias).map((t2) => t2.name)));
+  registerResources(server, tools);
+  registerPrompts(server);
   return server;
 }
 function hideFromToolsList(server, hidden) {
@@ -60368,5 +60819,5 @@ main().catch((err) => {
   process.exit(1);
 });
 
-//# debugId=FDF0CD88C245260A64756E2164756E21
+//# debugId=1E3042577A7AFC5F64756E2164756E21
 //# sourceMappingURL=index.js.map