jpdcl 1.0.0

package/.env.example

@@ -0,0 +1,15 @@
+# Copy to .env (which is git-ignored and should remain mode 0600).
+# The CLI, REST API, MCP, OpenCode, and other AI clients load it automatically.
+JPDCL_LOGIN_ID=
+JPDCL_PASSWORD=
+
+# Optional: defaults to ~/.jpdcl/session.json
+JPDCL_SESSION_FILE=
+
+# REST API settings
+JPDCL_API_HOST=127.0.0.1
+JPDCL_API_PORT=8787
+JPDCL_API_KEY=
+
+# Mutating actions are disabled unless explicitly enabled.
+JPDCL_ENABLE_MUTATIONS=false

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JPDCL Toolkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# Jammu Power Distribution Corporation Limited (JPDCL) Smart Meter MCP
+
+Unofficial, community-built, and MIT-licensed. This project is not affiliated with or endorsed by JPDCL, JERC, Genus, or the Government of Jammu and Kashmir.
+
+An API-only MCP integration for Jammu Power Distribution Corporation Limited (JPDCL): the consumer portal, Genus smart-meter portal, and JPDCL daily import/export meter ledger. It maps 122 portal operations and exposes 29 AI-focused MCP tools with structured output, provenance, automatic authentication, deterministic tariff calculations, and guarded account actions. It never automates a browser at runtime.
+
+## MCP quick start
+
+### Hosted MCP (no installation)
+
+The public Streamable HTTP endpoint is:
+
+```text
+https://jpdcl.ashfaq.workers.dev/mcp
+```
+
+It is also published as [JPDCL Smart Meter on Smithery](https://smithery.ai/servers/ashfaqmehmood-01/jpdcl). Smithery can install it into supported AI clients and asks for the JPDCL login ID and password as protected per-user connection settings:
+
+```sh
+npx -y @smithery/cli@latest mcp add ashfaqmehmood-01/jpdcl --client opencode
+```
+
+For a direct HTTP MCP connection, send `x-jpdcl-login-id` and `x-jpdcl-password` headers to the public endpoint. The Cloudflare Worker keeps no credential or session file; credentials are isolated to that request. Account-changing tools remain disabled unless the connection also sets `allowMutations=true` and the individual call includes explicit confirmation.
+
+### Local MCP with npx
+
+The npm package is [`jpdcl`](https://www.npmjs.com/package/jpdcl). Running it without arguments starts the stdio MCP server:
+
+```sh
+npx -y jpdcl
+```
+
+Add it to any MCP-compatible client:
+
+```json
+{
+  "mcpServers": {
+    "JPDCL Smart Meter": {
+      "command": "npx",
+      "args": ["-y", "jpdcl"],
+      "env": {
+        "JPDCL_SESSION_FILE": "/Users/you/.jpdcl/session.json",
+        "JPDCL_ENV_FILE": "/Users/you/.config/jpdcl/.env"
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add this inside `~/.config/opencode/opencode.jsonc`:
+
+```jsonc
+"mcp": {
+  "JPDCL Smart Meter": {
+    "type": "local",
+    "command": ["npx", "-y", "jpdcl"],
+    "environment": {
+      "JPDCL_SESSION_FILE": "/Users/you/.jpdcl/session.json",
+      "JPDCL_ENV_FILE": "/Users/you/.config/jpdcl/.env"
+    },
+    "enabled": true,
+    "timeout": 30000
+  }
+}
+```
+
+Confirm it with `opencode mcp list`. For a local checkout before npm publication, use `command: ["npx", "--yes", "--package", "/absolute/path/to/jpdcl", "jpdcl"]`.
+
+## Authentication
+
+On first use, ask the AI client to call `jpdcl_auth_login` and provide your portal login only when the client requests it. The tool:
+
+- authenticates against JPDCL without browser automation;
+- stores the session in `JPDCL_SESSION_FILE` with permissions `0600`;
+- saves credentials to `JPDCL_ENV_FILE` when requested, without returning the password;
+- automatically renews expired main-portal sessions;
+- obtains a fresh Genus SSO token whenever the smart-meter token expires.
+
+For unattended setup, create the private environment file yourself:
+
+```sh
+mkdir -p ~/.config/jpdcl
+cp .env.example ~/.config/jpdcl/.env
+chmod 600 ~/.config/jpdcl/.env
+```
+
+Then fill `JPDCL_LOGIN_ID` and `JPDCL_PASSWORD`. The private environment and session files live outside the npm cache, so upgrades do not remove authentication.
+
+## Best MCP tools for AI
+
+- `jpdcl_snapshot`: preferred all-in-one factual account, billing, smart-meter, and ledger response.
+- `jpdcl_meter_health`: supply, reading, voltage, alarm, outage, and freshness evidence without inventing an online status.
+- `jpdcl_tariff_estimate`: automatic consumption, category, sanctioned-load, plan, slab, rebate, and charge calculation.
+- `jpdcl_energy_ledger`: normalized import, export, net-import registers and deterministic period differences.
+- `jpdcl_account_digest`: normalized consumer, billing, payment, and consumption information.
+- `jpdcl_smart_dashboard`: current Genus account and meter records.
+- `jpdcl_smart_intervals`: dated interval readings.
+- `jpdcl_smart_report`: voltage, current, power, energy, and other supported smart-meter reports.
+- `jpdcl_smart_meter_profile`: meter and connection attributes.
+- `jpdcl_smart_billing`: postpaid or prepaid billing information.
+- `jpdcl_smart_alerts`: portal alarms and alert records.
+- `jpdcl_catalog`: searchable inventory of every mapped operation.
+- `jpdcl_read`: low-level structured access to any safe catalog endpoint.
+- `jpdcl_mutate`: guarded account actions that require explicit confirmation and mutation enablement.
+- `jpdcl_guide`: embedded source-selection, safety, freshness, provenance, and tariff instructions.
+
+The remaining tools cover bills, payments, consumption, smart sessions, forecasts, preferences, support, notifications, nearby offices, tariff schedules, and authentication. MCP resources `jpdcl://catalog` and `jpdcl://guide` expose the complete machine-readable catalog and decision guide.
+
+## AI data policy
+
+`jpdcl_snapshot` is the recommended default because it separates:
+
+- observed portal data;
+- deterministic calculations;
+- derived forecasts;
+- advisory tips and recommendations;
+- unavailable or stale upstream evidence.
+
+Forecasts, recommendations, energy-saving advice, and `smartTips` are excluded from factual responses by default. Generic reads reject derived or advisory endpoints unless the caller explicitly supplies `allowDerived=true`.
+
+The toolkit does not claim instant live voltage or connectivity when the portal only provides delayed records. `jpdcl_meter_health` returns the newest available timestamps and evidence, allowing an AI to explain freshness instead of presenting stale data as live.
+
+Daily and period consumption is calculated from cumulative meter registers. For net meters, tariff estimates prefer the ledger's net-import difference and fall back to Genus consumption only when necessary. Estimates remain provisional because utility cutoffs, export settlement, credits, adjustments, and duties can differ from a final bill.
+
+## MCP safety
+
+Payments, complaints, profile changes, account linking, on-demand reads, preference changes, and notification deletion are disabled by default. A mutation requires both:
+
+1. `JPDCL_ENABLE_MUTATIONS=true` in the private environment.
+2. An explicit confirmation in the `jpdcl_mutate` call.
+
+Never commit `.env`, session files, consumer IDs, meter numbers, bills, or readings. If a device is shared or lost, use `jpdcl auth logout` and change the portal password.
+
+## CLI
+
+The same package is also the CLI. Supplying any argument selects CLI mode, while no arguments start MCP mode:
+
+```sh
+# Login and automatic re-login setup
+npx -y jpdcl auth login --login-id YOUR_MOBILE_OR_EMAIL --save-env
+jpdcl auth status
+
+# Best normalized responses
+jpdcl snapshot
+jpdcl account digest
+jpdcl smart dashboard
+jpdcl smart health
+jpdcl tariff estimate
+jpdcl ledger summary
+
+# Readings and reports
+jpdcl smart consumption --type monthly --value 12
+jpdcl smart intervals --from 2026-07-01 --to 2026-07-24
+jpdcl smart report --type voltage --from 2026-07-24 --to 2026-07-24
+jpdcl ledger readings --from 2026-07-01 --to 2026-07-24 --limit 10
+
+# Complete endpoint catalog and raw access
+jpdcl catalog --portal smart
+jpdcl request smart_preferences --params '{"isPrepaid":false}'
+```
+
+All CLI output is JSON. Use `jpdcl --help` for the complete command tree.
+
+## REST API and TypeScript client
+
+The secondary local REST API provides normalized routes plus full catalog access:
+
+```sh
+JPDCL_API_KEY='choose-a-local-key' jpdcl-api
+
+curl -H 'Authorization: Bearer choose-a-local-key' \
+  'http://127.0.0.1:8787/v1/snapshot?accountId=YOUR_ACCOUNT_ID'
+```
+
+The server binds to `127.0.0.1` by default. Set a strong `JPDCL_API_KEY` before exposing it to another process or machine. The full contract is in [openapi.yaml](./openapi.yaml), and the package root exports the typed clients for direct TypeScript use.
+
+## Install from source
+
+Node.js 20 or newer is required:
+
+```sh
+npm ci
+npm run build
+npm link
+```
+
+After linking, `jpdcl` with no arguments starts MCP; `jpdcl --help` or any subcommand starts the CLI. `jpdcl-mcp` remains available as an explicit MCP-only executable, and `jpdcl-api` starts the local REST API.
+
+## Free public deployment
+
+The hosted MCP runs on the Cloudflare Workers free tier. Fork the repository, authenticate Wrangler, and deploy your own copy with:
+
+```sh
+npm ci
+npx wrangler deploy
+```
+
+`wrangler.jsonc` explicitly enables the public `workers.dev` route. No JPDCL credentials belong in Cloudflare environment variables or repository secrets because each MCP connection supplies its own protected headers.
+
+## Development checks
+
+```sh
+npm run typecheck
+npm test
+npm run build
+npm run audit:launcher
+npm run audit:smart
+npm run audit:ledger
+npm run audit:mcp
+npm pack --dry-run
+```
+
+The MCP audit launches the real server, verifies its name, checks all 29 tool declarations and embedded resources, calls every safe tool against live APIs, and confirms mutation and derived-data guards without changing the account. Live audits require your own private JPDCL account and must never run with credentials in CI.
+
+## License
+
+Released under the [MIT License](./LICENSE). Portal names, services, and data remain the property of their respective owners.

package/dist/catalog.d.ts

@@ -0,0 +1,141 @@
+import type { EndpointDefinition } from "./types.js";
+export declare const endpointCatalog: {
+    main_login: EndpointDefinition;
+    main_department_login: EndpointDefinition;
+    main_validate_password: EndpointDefinition;
+    main_reset_password: EndpointDefinition;
+    main_forgot_password: EndpointDefinition;
+    main_register: EndpointDefinition;
+    main_visitor_count: EndpointDefinition;
+    main_customer_info: EndpointDefinition;
+    main_accounts_for_identity: EndpointDefinition;
+    main_add_primary_account: EndpointDefinition;
+    main_linked_accounts: EndpointDefinition;
+    main_link_account: EndpointDefinition;
+    main_swap_linked_account: EndpointDefinition;
+    main_delink_account: EndpointDefinition;
+    main_update_contact: EndpointDefinition;
+    main_alert_settings: EndpointDefinition;
+    main_bill_history: EndpointDefinition;
+    main_bill_pdf: EndpointDefinition;
+    main_consumption: EndpointDefinition;
+    main_consumption_legacy: EndpointDefinition;
+    main_meter_changes: EndpointDefinition;
+    main_meter_status: EndpointDefinition;
+    main_prepaid_transactions: EndpointDefinition;
+    main_prepaid_bill_history: EndpointDefinition;
+    main_prepaid_bill_distribution: EndpointDefinition;
+    main_prepaid_statement_date: EndpointDefinition;
+    main_prepaid_statement_month: EndpointDefinition;
+    main_same_day_transaction: EndpointDefinition;
+    main_initiate_payment: EndpointDefinition;
+    main_cancel_payment_remark: EndpointDefinition;
+    main_amnesty_info: EndpointDefinition;
+    main_complaint_types: EndpointDefinition;
+    main_complaints: EndpointDefinition;
+    main_register_complaint: EndpointDefinition;
+    main_contact: EndpointDefinition;
+    main_group_info: EndpointDefinition;
+    main_group_hierarchy: EndpointDefinition;
+    main_group_payment: EndpointDefinition;
+    main_group_payment_report: EndpointDefinition;
+    main_smart_sso: EndpointDefinition;
+    main_generate_log: EndpointDefinition;
+    smart_otp_send: EndpointDefinition;
+    smart_otp_verify: EndpointDefinition;
+    smart_guest_otp_send: EndpointDefinition;
+    smart_guest_otp_verify: EndpointDefinition;
+    smart_switch_account: EndpointDefinition;
+    smart_logout: EndpointDefinition;
+    smart_admin_login: EndpointDefinition;
+    smart_admin_login_counts: EndpointDefinition;
+    smart_admin_bypass_link: EndpointDefinition;
+    smart_today_monthly: EndpointDefinition;
+    smart_current_month: EndpointDefinition;
+    smart_last_month_bill: EndpointDefinition;
+    smart_meter_reading: EndpointDefinition;
+    smart_current_meter_reading: EndpointDefinition;
+    smart_prepaid_recharge_balance: EndpointDefinition;
+    smart_prepaid_balance: EndpointDefinition;
+    smart_bill_summary: EndpointDefinition;
+    smart_insights: EndpointDefinition;
+    smart_forecast_today: EndpointDefinition;
+    smart_forecast_weekly: EndpointDefinition;
+    smart_forecast_monthly: EndpointDefinition;
+    smart_consumption_comparison: EndpointDefinition;
+    smart_consumption_30min: EndpointDefinition;
+    smart_consumption_30min_csv: EndpointDefinition;
+    smart_consumption_30min_pdf: EndpointDefinition;
+    smart_on_demand_request: EndpointDefinition;
+    smart_on_demand_logs: EndpointDefinition;
+    smart_my_alerts: EndpointDefinition;
+    smart_postpaid_payment_history: EndpointDefinition;
+    smart_postpaid_bill_history: EndpointDefinition;
+    smart_postpaid_last_bill: EndpointDefinition;
+    smart_prepaid_recharge_history: EndpointDefinition;
+    smart_prepaid_bill_history: EndpointDefinition;
+    smart_prepaid_recharge_pdf: EndpointDefinition;
+    smart_faqs: EndpointDefinition;
+    smart_contact_support: EndpointDefinition;
+    smart_complaint_categories: EndpointDefinition;
+    smart_complaint_priorities: EndpointDefinition;
+    smart_complaints: EndpointDefinition;
+    smart_create_complaint: EndpointDefinition;
+    smart_cancel_complaint: EndpointDefinition;
+    smart_track_complaint: EndpointDefinition;
+    smart_chatbot_questions: EndpointDefinition;
+    smart_chatbot_submit: EndpointDefinition;
+    smart_msedcl_chatbot_questions: EndpointDefinition;
+    smart_msedcl_chatbot_options: EndpointDefinition;
+    smart_msedcl_chatbot_precheck: EndpointDefinition;
+    smart_msedcl_chatbot_submit: EndpointDefinition;
+    smart_msedcl_chatbot_tickets: EndpointDefinition;
+    smart_msedcl_chatbot_ticket: EndpointDefinition;
+    smart_meter_details: EndpointDefinition;
+    smart_tariff_details: EndpointDefinition;
+    smart_slab_rates: EndpointDefinition;
+    smart_page_content: EndpointDefinition;
+    smart_update_account_label: EndpointDefinition;
+    smart_update_language: EndpointDefinition;
+    smart_preferences: EndpointDefinition;
+    smart_update_preferences: EndpointDefinition;
+    smart_enable_all_preferences: EndpointDefinition;
+    smart_disable_all_preferences: EndpointDefinition;
+    smart_update_alerts: EndpointDefinition;
+    smart_notifications: EndpointDefinition;
+    smart_notification_unread_count: EndpointDefinition;
+    smart_notification_mark_read: EndpointDefinition;
+    smart_notification_mark_all_read: EndpointDefinition;
+    smart_notification_delete: EndpointDefinition;
+    smart_notification_filter: EndpointDefinition;
+    smart_nearby_offices: EndpointDefinition;
+    smart_appliances: EndpointDefinition;
+    smart_report: EndpointDefinition;
+    smart_report_power_events: EndpointDefinition;
+    smart_report_daily_tod: EndpointDefinition;
+    smart_report_monthly_tod: EndpointDefinition;
+    smart_report_peak_slots: EndpointDefinition;
+    smart_report_peak_slots_monthly: EndpointDefinition;
+    smart_report_voltage: EndpointDefinition;
+    smart_report_demand: EndpointDefinition;
+    smart_payment_initiate: EndpointDefinition;
+    smart_payment_verify: EndpointDefinition;
+    ledger_consumer_readings: EndpointDefinition;
+    ledger_meter_alarms: EndpointDefinition;
+};
+export type EndpointName = keyof typeof endpointCatalog;
+export declare function isEndpointName(name: string): name is EndpointName;
+export declare function listEndpoints(portal?: EndpointDefinition["portal"]): {
+    portal: "main" | "smart" | "ledger";
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    encrypted?: boolean;
+    auth: "public" | "public-basic" | "main-session" | "smart-bearer" | "smart-admin" | "external-basic";
+    mutation?: boolean;
+    binary?: boolean;
+    dataClass?: "observed" | "derived" | "advisory" | "configuration" | "transactional";
+    description: string;
+    parameters?: string[];
+    bodyExample?: Record<string, unknown>;
+    name: string;
+}[];