jpdcl 1.0.0

package/openapi.yaml

@@ -0,0 +1,284 @@
+openapi: 3.1.0
+info:
+  title: JPDCL API-only Toolkit
+  version: 1.0.0
+  description: Local, normalized REST facade over JPDCL billing, Genus smart-meter, and daily import/export ledger APIs.
+servers:
+  - url: http://127.0.0.1:8787
+components:
+  securitySchemes:
+    LocalApiKey:
+      type: http
+      scheme: bearer
+      description: Optional local key configured with JPDCL_API_KEY.
+  schemas:
+    PortalResponse:
+      type: object
+      additionalProperties: true
+    RawRequest:
+      type: object
+      properties:
+        params: { type: object, additionalProperties: true }
+        body: { type: object, additionalProperties: true }
+        confirm: { type: boolean, default: false, description: Required for a cataloged account-changing endpoint in addition to JPDCL_ENABLE_MUTATIONS=true }
+    TariffEstimate:
+      type: object
+      additionalProperties: true
+      description: Deterministic domestic charge estimate with rate, slab, provenance, and exclusion details.
+    EnergyLedger:
+      type: object
+      additionalProperties: true
+      description: Normalized cumulative daily registers, deterministic deltas, freshness, and provisional net-meter billing quantity.
+    MeterHealth:
+      type: object
+      additionalProperties: true
+      description: Unified supply, meter-reading, voltage, outage, ledger-freshness, and alarm evidence.
+paths:
+  /health:
+    get:
+      summary: Service health
+      responses:
+        "200": { description: Healthy }
+  /v1/catalog:
+    get:
+      summary: Complete discovered endpoint catalog
+      parameters:
+        - { name: portal, in: query, schema: { type: string, enum: [main, smart, ledger] } }
+      responses:
+        "200": { description: Endpoint definitions }
+  /v1/tariff:
+    get:
+      summary: Encoded official FY 2025-26 domestic tariff and source pages
+      security: [{ LocalApiKey: [] }]
+      responses:
+        "200": { description: Tariff schedule and general charge terms }
+  /v1/auth/login:
+    post:
+      summary: Create and securely save a main-portal API session
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [loginId, password]
+              properties:
+                loginId: { type: string }
+                password: { type: string, format: password }
+      responses:
+        "200": { description: Authenticated }
+  /v1/me:
+    get:
+      summary: Saved session status
+      security: [{ LocalApiKey: [] }]
+      responses:
+        "200": { description: Session metadata }
+  /v1/snapshot:
+    get:
+      summary: Preferred normalized factual snapshot across all three data sources
+      description: Automatically uses or refreshes API sessions, adds deterministic ledger and tariff calculations, and excludes forecasts, recommendations, and smart tips.
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: query, schema: { type: string } }
+      responses:
+        "200": { description: Provenance-labelled observed-only snapshot }
+  /v1/accounts/{accountId}:
+    get:
+      summary: Consumer, bill, tariff, load, and meter summary
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: accountId, in: path, required: true, schema: { type: string } }]
+      responses:
+        "200": { description: Account data }
+  /v1/accounts/{accountId}/digest:
+    get:
+      summary: Combined account, bills, payments, consumption, and linked-account digest
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: accountId, in: path, required: true, schema: { type: string } }]
+      responses:
+        "200": { description: Complete digest }
+  /v1/accounts/{accountId}/bills:
+    get:
+      summary: Billing history
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: from, in: query, schema: { type: string, format: date } }
+        - { name: to, in: query, schema: { type: string, format: date } }
+      responses:
+        "200": { description: Bills }
+  /v1/accounts/{accountId}/payments:
+    get:
+      summary: Payment history
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: from, in: query, schema: { type: string, format: date } }
+        - { name: to, in: query, schema: { type: string, format: date } }
+      responses:
+        "200": { description: Payments }
+  /v1/accounts/{accountId}/consumption:
+    get:
+      summary: Main-portal billed consumption
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: from, in: query, schema: { type: string, format: date } }
+        - { name: to, in: query, schema: { type: string, format: date } }
+      responses:
+        "200": { description: Consumption }
+  /v1/accounts/{accountId}/tariff-estimate:
+    get:
+      summary: Automatic domestic electricity charge estimate
+      description: Prefers current-month net-import register differences for net meters, with Genus usage as fallback; detects category, plan and sanctioned load. The result is deterministic but is not a utility bill.
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: units, in: query, schema: { type: number, minimum: 0 }, description: Optional kWh override }
+        - { name: load, in: query, schema: { type: number, minimum: 0 }, description: Optional sanctioned-load override }
+        - { name: prepaid, in: query, schema: { type: boolean }, description: Optional plan override }
+        - { name: solarWaterHeaterEligible, in: query, schema: { type: boolean }, description: Apply only when verified by JPDCL }
+        - { name: electricityDuty, in: query, schema: { type: number, minimum: 0 }, description: Explicit duty amount; never inferred }
+        - { name: otherCharges, in: query, schema: { type: number, minimum: 0 } }
+        - { name: unpaidPrincipal, in: query, schema: { type: number, minimum: 0 } }
+        - { name: lateMonths, in: query, schema: { type: number, minimum: 0 } }
+      responses:
+        "200":
+          description: Provenance-labelled tariff estimate
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/TariffEstimate" }
+  /v1/accounts/{accountId}/energy-ledger:
+    get:
+      summary: Daily import, export, net-import, and apparent-energy ledger
+      description: Resolves the consumer ID from the authenticated account, then returns normalized registers, daily/period deltas, source freshness, and provisional billable kWh.
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: from, in: query, schema: { type: string, format: date } }
+        - { name: to, in: query, schema: { type: string, format: date } }
+        - { name: limit, in: query, schema: { type: integer, minimum: 0, maximum: 500, default: 35 }, description: Daily rows; zero returns only the period summary }
+      responses:
+        "200":
+          description: Provenance-labelled energy ledger
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/EnergyLedger" }
+  /v1/accounts/{accountId}/meter-health:
+    get:
+      summary: Unified meter, electrical supply, and data-freshness status
+      description: Combines the latest utility status, on-demand readings, voltage profile, power events, daily register freshness, and meter alarms. It does not invent a network-connectivity status the portals do not expose.
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: accountId, in: path, required: true, schema: { type: string } }]
+      responses:
+        "200":
+          description: Multi-source meter-health evidence
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MeterHealth" }
+  /v1/smart/session:
+    get:
+      summary: Smart-meter session and account metadata
+      security: [{ LocalApiKey: [] }]
+      responses:
+        "200": { description: Smart account metadata }
+  /v1/smart/accounts/{accountId}/dashboard:
+    get:
+      summary: Measured readings and account records; derived content excluded by default
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: includeDerived, in: query, schema: { type: boolean, default: false }, description: Opt in to clearly labelled predictions, estimates, insights, and tips }
+      responses:
+        "200": { description: Live usage, reading, bill, alerts, and session }
+  /v1/smart/accounts/{accountId}/meter:
+    get:
+      summary: Meter technical profile and current reading
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: accountId, in: path, required: true, schema: { type: string } }]
+      responses:
+        "200": { description: Meter and connection details }
+  /v1/smart/accounts/{accountId}/alerts:
+    get:
+      summary: Live daily and monthly usage alerts
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: accountId, in: path, required: true, schema: { type: string } }]
+      responses:
+        "200": { description: Alert state and thresholds }
+  /v1/smart/accounts/{accountId}/preferences:
+    get:
+      summary: Notification categories and delivery-channel preferences
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: accountId, in: path, required: true, schema: { type: string } }]
+      responses:
+        "200": { description: Preferences }
+  /v1/smart/accounts/{accountId}/notifications:
+    get:
+      summary: Notifications and unread count
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: accountId, in: path, required: true, schema: { type: string } }]
+      responses:
+        "200": { description: Notifications }
+  /v1/smart/accounts/{accountId}/support:
+    get:
+      summary: FAQs, contact details, categories, and complaints
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: page, in: query, schema: { type: integer, default: 1 } }
+        - { name: pageSize, in: query, schema: { type: integer, default: 20 } }
+        - { name: statusCodes, in: query, schema: { type: string } }
+      responses:
+        "200": { description: Support data }
+  /v1/smart/accounts/{accountId}/consumption:
+    get:
+      summary: Smart-meter consumption comparison
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: type, in: query, schema: { type: string, enum: [daily, weekly, monthly], default: monthly } }
+        - { name: value, in: query, schema: { type: integer, default: 12 } }
+      responses:
+        "200": { description: Consumption comparison }
+  /v1/smart/accounts/{accountId}/intervals:
+    get:
+      summary: Half-hour smart-meter readings
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: from, in: query, required: true, schema: { type: string, format: date } }
+        - { name: to, in: query, required: true, schema: { type: string, format: date } }
+        - { name: sort, in: query, schema: { type: string, default: date } }
+      responses:
+        "200": { description: Interval readings }
+  /v1/smart/accounts/{accountId}/reports/{reportType}:
+    get:
+      summary: Smart-meter analytical report
+      security: [{ LocalApiKey: [] }]
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string } }
+        - { name: reportType, in: path, required: true, schema: { type: string } }
+        - { name: from, in: query, schema: { type: string, format: date } }
+        - { name: to, in: query, schema: { type: string, format: date } }
+        - { name: start, in: query, schema: { type: integer, default: 1 } }
+        - { name: end, in: query, schema: { type: integer } }
+        - { name: filter, in: query, schema: { type: string } }
+        - { name: format, in: query, schema: { type: string, enum: [xlsx, pdf] } }
+      responses:
+        "200": { description: Report data or base64-encoded download }
+  /v1/raw/{endpoint}:
+    get:
+      summary: Call any cataloged read endpoint with query parameters
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: endpoint, in: path, required: true, schema: { type: string } }]
+      responses:
+        "200": { description: Portal response }
+    post:
+      summary: Call any cataloged endpoint with explicit path parameters and body
+      security: [{ LocalApiKey: [] }]
+      parameters: [{ name: endpoint, in: path, required: true, schema: { type: string } }]
+      requestBody:
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RawRequest" }
+      responses:
+        "200": { description: Portal response }

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "jpdcl",
+  "version": "1.0.0",
+  "description": "Unofficial Jammu Power Distribution Corporation Limited (JPDCL) smart-meter MCP, CLI, REST API, and TypeScript client",
+  "license": "MIT",
+  "keywords": [
+    "jpdcl",
+    "jammu-power-distribution",
+    "jammu-kashmir",
+    "jk-electricity",
+    "electricity",
+    "smart-meter",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "api"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/ashfaqmehmood/jpdcl#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashfaqmehmood/jpdcl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ashfaqmehmood/jpdcl/issues"
+  },
+  "overrides": {
+    "@hono/node-server": "$@hono/node-server"
+  },
+  "type": "module",
+  "bin": {
+    "jpdcl": "dist/launcher.js",
+    "jpdcl-mcp": "dist/mcp-stdio.js",
+    "jpdcl-api": "dist/server.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "scripts",
+    "tsconfig.json",
+    "tsconfig.build.json",
+    "README.md",
+    "openapi.yaml",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "publish:smithery": "node scripts/publish-smithery.mjs",
+    "dev:cli": "node --import tsx src/cli.ts",
+    "dev:api": "node --import tsx src/server.ts",
+    "dev:mcp": "node --import tsx src/mcp.ts",
+    "dev": "node --import tsx src/launcher.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test src/toolkit.test.ts",
+    "audit:smart": "node --import tsx scripts/audit-smart-portal.mjs",
+    "audit:ledger": "node --import tsx scripts/audit-ledger-portal.ts",
+    "audit:launcher": "npm run build --silent && node scripts/audit-launcher.mjs",
+    "audit:http": "node --import tsx scripts/audit-http.ts",
+    "audit:mcp": "npm run build --silent && node scripts/audit-mcp.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.0.11",
+    "@inquirer/prompts": "^7.8.0",
+    "@modelcontextprotocol/sdk": "^1.17.2",
+    "cheerio": "^1.2.0",
+    "commander": "^14.0.0",
+    "crypto-js": "^4.2.0",
+    "dotenv": "^17.4.2",
+    "fetch-cookie": "^3.1.0",
+    "hono": "^4.8.10",
+    "tough-cookie": "^5.1.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4.2.2",
+    "@types/node": "^24.1.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3",
+    "wrangler": "^4.114.0"
+  }
+}

package/scripts/audit-http.ts

@@ -0,0 +1,36 @@
+import { serve } from "@hono/node-server";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { handleMcpRequest } from "../src/http-handler.js";
+
+const listener = await new Promise<ReturnType<typeof serve>>((resolve) => {
+  const server = serve({ fetch: handleMcpRequest, port: 0 }, () => resolve(server));
+});
+const address = listener.address();
+if (!address || typeof address === "string") throw new Error("Could not start HTTP audit server");
+
+const transport = new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${address.port}/api/mcp`), {
+  requestInit: {
+    headers: {
+      "x-jpdcl-login-id": "audit-user",
+      "x-jpdcl-password": "audit-password",
+    },
+  },
+});
+const client = new Client({ name: "jpdcl-http-audit", version: "1.0.0" });
+
+try {
+  await client.connect(transport);
+  const tools = await client.listTools();
+  const status = await client.callTool({ name: "jpdcl_session_status", arguments: {} });
+  if (client.getServerVersion()?.name !== "JPDCL Smart Meter" || tools.tools.length !== 29) {
+    throw new Error("HTTP endpoint returned unexpected MCP metadata");
+  }
+  if (status.isError || status.structuredContent?.credentialSource !== "smithery-connection") {
+    throw new Error("HTTP credentials were not isolated as connection configuration");
+  }
+  process.stdout.write(`${JSON.stringify({ status: "ok", transport: "streamable-http", toolCount: tools.tools.length })}\n`);
+} finally {
+  await client.close();
+  listener.close();
+}

package/scripts/audit-launcher.mjs

@@ -0,0 +1,28 @@
+import { spawnSync } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const launcher = new URL("../dist/launcher.js", import.meta.url).pathname;
+const cli = spawnSync(process.execPath, [launcher, "--help"], { encoding: "utf8" });
+if (cli.status !== 0 || !cli.stdout.includes("Usage: jpdcl")) {
+  throw new Error(`jpdcl CLI dispatch failed: ${cli.stderr || cli.stdout}`);
+}
+
+const transport = new StdioClientTransport({
+  command: process.execPath,
+  args: [launcher],
+  cwd: new URL("..", import.meta.url).pathname,
+  stderr: "pipe",
+});
+const client = new Client({ name: "jpdcl-launcher-audit", version: "1.0.0" });
+
+try {
+  await client.connect(transport);
+  const tools = await client.listTools();
+  if (client.getServerVersion()?.name !== "JPDCL Smart Meter" || tools.tools.length !== 29) {
+    throw new Error("jpdcl MCP dispatch returned unexpected server metadata");
+  }
+  process.stdout.write(`${JSON.stringify({ status: "ok", command: "jpdcl", cli: true, mcp: true, toolCount: tools.tools.length })}\n`);
+} finally {
+  await client.close();
+}

package/scripts/audit-ledger-portal.ts

@@ -0,0 +1,23 @@
+import { JpdclRuntime } from "../src/runtime.js";
+
+const runtime = await JpdclRuntime.create();
+const ledger = await runtime.energyLedger(undefined, { limit: 1 });
+const consumer = ledger.consumer as { smartMeterNumber?: string | null; netMeter?: boolean | null };
+const availability = ledger.availability as { sourceRecordCount?: number; latestObservation?: string | null };
+const readings = ledger.readings as Array<{ cumulative?: Record<string, unknown> }>;
+const requiredRegisters = ["importKwh", "exportKwh", "netImportKwh", "importKvah", "exportKvah", "netImportKvah"];
+const missing = requiredRegisters.filter((key) => !(key in (readings[0]?.cumulative ?? {})));
+if (!availability.sourceRecordCount || !readings.length || missing.length) {
+  throw new Error(`Daily ledger audit failed; missing registers: ${missing.join(", ") || "reading rows"}`);
+}
+if (!consumer.smartMeterNumber) throw new Error("Daily ledger audit failed; meter number is missing");
+const alarms = await runtime.ledger.alarms(consumer.smartMeterNumber);
+
+process.stdout.write(`${JSON.stringify({
+  status: "ok",
+  sourceRecordCount: availability.sourceRecordCount,
+  latestObservation: availability.latestObservation,
+  netMeter: consumer.netMeter,
+  registers: requiredRegisters,
+  alarmResponseParsed: typeof alarms.hasAlarms === "boolean",
+}, null, 2)}\n`);

package/scripts/audit-mcp.mjs

@@ -0,0 +1,140 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const isoDaysAgo = (days) => {
+  const date = new Date();
+  date.setUTCDate(date.getUTCDate() - days);
+  return date.toISOString().slice(0, 10);
+};
+
+const today = isoDaysAgo(0);
+const recent = isoDaysAgo(7);
+const historyStart = isoDaysAgo(150);
+const cases = {
+  jpdcl_catalog: {},
+  jpdcl_guide: {},
+  jpdcl_session_status: {},
+  jpdcl_snapshot: {},
+  jpdcl_tariff_estimate: {},
+  jpdcl_tariff_schedule: {},
+  jpdcl_energy_ledger: { limit: 2 },
+  jpdcl_meter_health: {},
+  jpdcl_account_info: {},
+  jpdcl_account_digest: {},
+  jpdcl_bills: { from: historyStart, to: today },
+  jpdcl_payments: { from: historyStart, to: today },
+  jpdcl_consumption: { from: historyStart, to: today },
+  jpdcl_smart_session: {},
+  jpdcl_smart_dashboard: {},
+  jpdcl_smart_consumption: { type: "monthly", value: 2 },
+  jpdcl_smart_intervals: { from: recent, to: today },
+  jpdcl_smart_meter_profile: {},
+  jpdcl_smart_forecasts: {},
+  jpdcl_smart_billing: {},
+  jpdcl_smart_alerts: {},
+  jpdcl_smart_preferences: {},
+  jpdcl_smart_support: { pageSize: 5 },
+  jpdcl_smart_notifications: {},
+  jpdcl_smart_nearby_offices: { latitude: 32.7266, longitude: 74.8570 },
+  jpdcl_smart_report: { report: "voltage", from: recent, to: today, end: 5 },
+  jpdcl_read: { endpoint: "main_complaint_types" },
+};
+
+const auditCommand = process.env.JPDCL_MCP_AUDIT_COMMAND || process.execPath;
+const auditArgs = process.env.JPDCL_MCP_AUDIT_ARGS
+  ? JSON.parse(process.env.JPDCL_MCP_AUDIT_ARGS)
+  : [new URL("../dist/mcp-stdio.js", import.meta.url).pathname];
+
+const transport = new StdioClientTransport({
+  command: auditCommand,
+  args: auditArgs,
+  cwd: new URL("..", import.meta.url).pathname,
+  env: { ...process.env },
+  stderr: "pipe",
+});
+const client = new Client({ name: "jpdcl-mcp-audit", version: "1.0.0" });
+
+try {
+  await client.connect(transport);
+  if (client.getServerVersion()?.name !== "JPDCL Smart Meter") {
+    throw new Error(`Unexpected MCP server name: ${client.getServerVersion()?.name ?? "missing"}`);
+  }
+  const listed = await client.listTools();
+  const names = listed.tools.map((tool) => tool.name);
+  const duplicates = names.filter((name, index) => names.indexOf(name) !== index);
+  const missingMetadata = listed.tools
+    .filter((tool) => !tool.title || !tool.description || !tool.annotations)
+    .map((tool) => tool.name);
+  const untested = names.filter((name) => name !== "jpdcl_auth_login" && !(name in cases) && name !== "jpdcl_mutate");
+  const unknownCases = Object.keys(cases).filter((name) => !names.includes(name));
+  if (duplicates.length || missingMetadata.length || untested.length || unknownCases.length) {
+    throw new Error(JSON.stringify({ duplicates, missingMetadata, untested, unknownCases }));
+  }
+
+  const authTool = listed.tools.find((tool) => tool.name === "jpdcl_auth_login");
+  const authRequired = authTool?.inputSchema?.required ?? [];
+  if (!authRequired.includes("loginId") || !authRequired.includes("password")) {
+    throw new Error("jpdcl_auth_login must require loginId and password");
+  }
+  let authenticationCheck = "schema-only (no configured credentials)";
+  const { resolveCredentials } = await import("../dist/credentials.js");
+  const credentials = await resolveCredentials();
+  if (credentials) {
+    const authentication = await client.callTool({
+      name: "jpdcl_auth_login",
+      arguments: { loginId: credentials.loginId, password: credentials.password, saveToEnv: false },
+    });
+    if (authentication.isError || !authentication.structuredContent?.authenticated) {
+      throw new Error("jpdcl_auth_login failed with the configured credentials");
+    }
+    authenticationCheck = "live login passed without rewriting credentials";
+  }
+
+  const results = [];
+  const upstreamUnavailable = [];
+  for (const [name, args] of Object.entries(cases)) {
+    const started = Date.now();
+    const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 45_000 });
+    results.push({ name, ok: !response.isError, milliseconds: Date.now() - started });
+    if (response.isError) throw new Error(`${name} failed its live read-only audit`);
+    if (!response.structuredContent) throw new Error(`${name} returned no structuredContent`);
+    if (response.structuredContent?._meta?.available === false) upstreamUnavailable.push(name);
+  }
+
+  const mutationGuard = await client.callTool({
+    name: "jpdcl_mutate",
+    arguments: { endpoint: "main_update_contact", confirm: false },
+  });
+  if (!mutationGuard.isError || !mutationGuard.content?.some((block) => block.type === "text" && block.text.includes("confirm=true"))) {
+    throw new Error("jpdcl_mutate explicit-confirmation guard failed");
+  }
+
+  const derivedGuard = await client.callTool({
+    name: "jpdcl_read",
+    arguments: { endpoint: "smart_forecast_today" },
+  });
+  if (!derivedGuard.isError || !derivedGuard.content?.some((block) => block.type === "text" && block.text.includes("allowDerived=true"))) {
+    throw new Error("jpdcl_read derived-data guard failed");
+  }
+
+  const resources = await client.listResources();
+  for (const uri of ["jpdcl://catalog", "jpdcl://guide"]) {
+    if (!resources.resources.some((resource) => resource.uri === uri)) throw new Error(`Missing MCP resource ${uri}`);
+    const resource = await client.readResource({ uri });
+    if (!resource.contents.length) throw new Error(`Empty MCP resource ${uri}`);
+  }
+  if (!client.getInstructions()?.includes("jpdcl_snapshot")) throw new Error("MCP initialization instructions are missing");
+
+  process.stdout.write(`${JSON.stringify({
+    status: "ok",
+    toolCount: names.length,
+    liveReadToolsPassed: results.length,
+    authenticationCheck,
+    guardedToolsPassed: ["jpdcl_mutate confirmation", "jpdcl_read derived-data opt-in"],
+    resourcesPassed: ["jpdcl://catalog", "jpdcl://guide"],
+    upstreamUnavailable,
+    slowest: [...results].sort((a, b) => b.milliseconds - a.milliseconds).slice(0, 5),
+  }, null, 2)}\n`);
+} finally {
+  await client.close();
+}

package/scripts/audit-smart-portal.mjs

@@ -0,0 +1,63 @@
+import { listEndpoints } from "../src/catalog.ts";
+
+const origin = process.env.JPDCL_SMART_ORIGIN ?? "https://cp.rdssjpdcl.com";
+const htmlResponse = await fetch(`${origin}/`);
+if (!htmlResponse.ok) throw new Error(`Smart portal returned HTTP ${htmlResponse.status}`);
+const html = await htmlResponse.text();
+const assetPath = html.match(/(?:src=["'])(\/assets\/index-[^"']+\.js)/)?.[1];
+if (!assetPath) throw new Error("Unable to locate the current smart-portal application bundle");
+
+const bundleResponse = await fetch(new URL(assetPath, origin));
+if (!bundleResponse.ok) throw new Error(`Smart-portal bundle returned HTTP ${bundleResponse.status}`);
+const bundle = await bundleResponse.text();
+
+const routes = [
+  "/", "/login", "/home", "/usage", "/usage/reports", "/usage/reports/:reportId",
+  "/usage/calculator", "/pay", "/pay/recharge", "/pay/payment", "/pay/autopay",
+  "/pay/bill", "/pay/success", "/payment/return", "/support", "/accounts",
+  "/know-your-meter", "/energy-saving-tips", "/dashboard", "/prepaid/*", "/postpaid/*",
+  "/admin", "/admin/dashboard", "/admin/token", "/admin/login-counts", "/admin/feature",
+];
+
+const panels = [
+  "Meter Details", "Connection", "Locate Office", "My Connections", "Payment Methods",
+  "Notification Preferences", "My Alerts", "Frequently Asked Questions", "About Department",
+  "Terms and Conditions", "Privacy Policy",
+];
+
+const missingRoutes = routes.filter((route) => !bundle.includes(`path:\"${route}\"`));
+const missingPanels = panels.filter((panel) => !bundle.includes(panel));
+
+function staticFragments(path) {
+  return path
+    .split(/\{[^}]+\}/)
+    .flatMap((part) => part.split(/[?&=]/))
+    .map((part) => part.replace(/\/$/, ""))
+    .filter((part) => part.length >= 4 && part !== "true" && part !== "false");
+}
+
+function fragmentExists(fragment) {
+  if (bundle.includes(fragment)) return true;
+  const pieces = fragment.split("/").filter((piece) => piece.length >= 4);
+  return pieces.length > 0 && pieces.every((piece) => bundle.includes(piece));
+}
+
+const smartEndpoints = listEndpoints("smart");
+const missingEndpoints = smartEndpoints
+  .filter((endpoint) => !staticFragments(endpoint.path).every(fragmentExists))
+  .map((endpoint) => ({ name: endpoint.name, path: endpoint.path }));
+
+const result = {
+  origin,
+  assetPath,
+  routesChecked: routes.length,
+  panelsChecked: panels.length,
+  smartEndpointsChecked: smartEndpoints.length,
+  missingRoutes,
+  missingPanels,
+  missingEndpoints,
+  passed: missingRoutes.length === 0 && missingPanels.length === 0 && missingEndpoints.length === 0,
+};
+
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+if (!result.passed) process.exitCode = 1;