@ekoindia/eps-transact-mcp 0.1.0 → 0.1.2

package/README.md

@@ -55,13 +55,15 @@ Optional env: `EKO_ENV` (`uat` default | `production`), `EKO_ALLOWED_APIS` (defa
 
 ## Staying up to date
 
-- **Remote server** — nothing to do. It's hosted; the operator redeploys and every client is instantly current. `GET /healthz` reports the live `bundleVersion`.
+- **Remote server** — nothing to do. It's hosted and auto-redeploys on every published update (its poller pulls the new `:prod`), so every client is instantly current. `GET /healthz` reports the live `bundleVersion`.
 - **Local stdio** — the `@latest` in the install command re-resolves the newest published version on every launch, so `npx` always fetches current. `@latest` does a registry lookup at start; the server runs fully offline after that. Offline/air-gapped? Pin a version: `npx --offline -y @ekoindia/eps-transact-mcp@<version>`.
 - **Update check** — on startup the stdio bin does one best-effort `GET registry.npmjs.org/@ekoindia/eps-transact-mcp/latest` (3s timeout, silent on any failure) and, if your config pinned an older version, prints a one-line stderr nudge. It never blocks startup, sends no data, and touches nothing but stderr. Disable with `EPS_NO_UPDATE_CHECK=1` (corporate/no-egress). The remote server does **not** run this check.
 
 ## Tools
 
-One tool per verification endpoint, named `eps_<slug with underscores>` — e.g. `eps_pan_lite`, `eps_bank_account_verification`, `eps_verify_gstin`, `eps_driving_license`. Every tool description carries the billing reminder; input schemas (required params, types, examples) are generated from the API specs. Multi-step flows (mobile OTP, DigiLocker) are exposed as their individual steps — the server is stateless; your agent carries intermediate ids between calls.
+One tool per verification endpoint, named `eps_<slug with underscores>` — e.g. `eps_pan_lite`, `eps_bank_account_verification`, `eps_verify_gstin`, `eps_driving_license`. Every tool description carries the billing reminder; input schemas (required params, types, examples — including item shapes for array params like bulk `entries`) are generated from the API specs. Multi-step flows (mobile OTP, DigiLocker, bulk verify) are exposed as their individual steps — the server is stateless; your agent carries intermediate ids between calls, and each step's description says which tool comes next and which field carries over.
+
+Every tool declares MCP annotations: `openWorldHint: true` on all (they call a paid external API), and `readOnlyHint: false` + `idempotentHint: false` on the side-effecting ones — `eps_bank_account_verification` (live, non-refundable ₹1 penny-drop), the two bulk-submit tools (enqueue async batches), `eps_mobile_otp_send`/`eps_mobile_otp_verify` (send/consume an OTP), and `eps_digilocker_create_url` (creates a consent session). Their descriptions state the side effect instead of "Read-only verification". Hosts should gate side-effecting tools accordingly; billing applies to **all** successful calls either way.
 
 Errors come back sanitized as `{ code, message }`: `VALIDATION` (names the missing/invalid params — never their values), `TOOL_NOT_ALLOWED`, `UNKNOWN_TOOL`, `UPSTREAM_TIMEOUT`, `UPSTREAM_ERROR`. Successful upstream envelopes (including business failures like "PAN not found") are returned verbatim — they are your data.
 
@@ -84,7 +86,9 @@ npm run transact:dev         # HTTP server on :8788 with tsx watch
 npm run transact:typecheck
 ```
 
-Tests never call Eko; upstream fetch is injected. The one exception is the env-gated live UAT smoke:
+Four utils (`fetchTimeout`, `requestId`, `accessLog`, `update-check`) are hand-copied/adapted from eps-backend / eps-context-mcp; `parity.copied-utils.test.ts` pins a content hash of both sides of each pair, so editing either file fails the suite until you diff the pair, port what applies, and paste the replacement hash printed in the failure.
+
+Tests never call Eko; upstream fetch is injected. The one exception is the opt-in live UAT smoke (`uat-smoke.test.ts`), which self-skips unless real UAT credentials are set. Copy `.env.example` to `.env` in this package (gitignored; vitest loads `EPS_UAT_*` from it) or pass the vars inline — inline wins:
 
 ```sh
 EPS_UAT_DEVELOPER_KEY=… EPS_UAT_ACCESS_KEY=… EPS_UAT_INITIATOR_ID=… \

package/data/eps.json

@@ -2,7 +2,7 @@
   "meta": {
     "org": "ekoindia",
     "apiVersion": "v3",
-    "bundleVersion": "5f1b3ac4",
+    "bundleVersion": "2f801127",
     "environments": [
       {
         "id": "sandbox",
@@ -188,6 +188,44 @@
           "note": "Credentials issued after organizational KYC."
         }
       ]
+    },
+    "getting-started": {
+      "id": "getting-started",
+      "summary": "Start testing Eko verification APIs in ~10 minutes: sign up, verify identity, load your wallet, and test live before integrating.",
+      "steps": [
+        {
+          "title": "Sign up",
+          "detail": "Sign up with your mobile number (OTP verified).",
+          "url": "https://ekostore.app/eps"
+        },
+        {
+          "title": "Verify identity",
+          "detail": "Submit PAN + bank account to verify your account."
+        },
+        {
+          "title": "Test live",
+          "detail": "Load wallet funds; call the verification APIs live to evaluate before integrating."
+        },
+        {
+          "title": "Integrate",
+          "detail": "Free AI plugins/tools + MCP & SDKs to integrate faster.",
+          "url": "https://eps.eko.in/ai"
+        },
+        {
+          "title": "Go live",
+          "detail": "Welcome email lists the KYC docs for production; reply with docs to get production keys."
+        }
+      ],
+      "links": [
+        {
+          "label": "Sign up",
+          "url": "https://ekostore.app/eps"
+        },
+        {
+          "label": "AI integration hub",
+          "url": "https://eps.eko.in/ai"
+        }
+      ]
     }
   },
   "apis": [
@@ -1856,8 +1894,8 @@
           "in": "header",
           "type": "string",
           "required": true,
-          "description": "application/json",
-          "example": "application/json"
+          "description": "multipart/form-data — let your HTTP client set this header itself (it generates the required boundary); do not hardcode the value.",
+          "example": "multipart/form-data"
         }
       ],
       "requestParams": [
@@ -1921,7 +1959,7 @@
         },
         {
           "name": "pan_card",
-          "type": "string",
+          "type": "file",
           "required": true,
           "description": "PAN card document upload (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB. PNG not accepted.",
           "example": "<binary file>",
@@ -1929,7 +1967,7 @@
         },
         {
           "name": "aadhar_front",
-          "type": "string",
+          "type": "file",
           "required": true,
           "description": "Front side of the Aadhaar card (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB.",
           "example": "<binary file>",
@@ -1937,7 +1975,7 @@
         },
         {
           "name": "aadhar_back",
-          "type": "string",
+          "type": "file",
           "required": true,
           "description": "Back side of the Aadhaar card (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB.",
           "example": "<binary file>",

package/dist/{chunk-AAUR66A3.js → chunk-XLZLL6DZ.js}

@@ -26,12 +26,62 @@ var EXECUTOR_HEADER_NAMES = /* @__PURE__ */ new Set([
   "content-type"
 ]);
 var IDENTITY_PARAMS = /* @__PURE__ */ new Set(["initiator_id", "user_code"]);
+var SIDE_EFFECTS = {
+  "bank-account-verification": "Performs a live, non-refundable \u20B91 penny-drop to the target account",
+  "bulk-bank-account-verification": "Enqueues an async penny-drop verification batch",
+  "pan-bulk-verify": "Enqueues an async PAN verification batch",
+  "mobile-otp-send": "Sends an OTP SMS to the target mobile number",
+  "mobile-otp-verify": "Consumes the OTP and advances the verification session",
+  "digilocker-create-url": "Creates a DigiLocker consent session"
+};
+var FLOW_GUIDANCE = {
+  "pan-bulk-verify": "Then poll eps_pan_bulk_status with the returned reference_id.",
+  "pan-bulk-status": "Poll step: pass the reference_id returned by eps_pan_bulk_verify.",
+  "bulk-bank-account-verification": "Then poll eps_bulk_bank_account_verification_status with the returned bulk_reference_id.",
+  "bulk-bank-account-verification-status": "Poll step: pass the bulk_reference_id returned by eps_bulk_bank_account_verification.",
+  "digilocker-create-url": "Flow step 1/3: after user consent, call eps_digilocker_get_document with the returned verification_id and reference_id.",
+  "digilocker-get-document": "Flow step 2/3: pass the verification_id and reference_id from eps_digilocker_create_url.",
+  "digilocker-verification-status": "Flow step 3/3: pass the reference_id from eps_digilocker_create_url.",
+  "mobile-otp-send": "Flow step 1/3: then call eps_mobile_otp_verify with the OTP the user received.",
+  "mobile-otp-verify": "Flow step 2/3: use the same mobile as eps_mobile_otp_send; returns an otp_verification_token.",
+  "mobile-otp-validate-token": "Flow step 3/3: pass the otp_verification_token returned by eps_mobile_otp_verify."
+};
 var toToolName = (slug) => `eps_${slug.replace(/-/g, "_")}`;
 var verificationApis = (bundle) => bundle.apis.filter((a) => a.category === "verification" && !a.financial);
 var JSON_SCHEMA_TYPES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean"]);
-var paramToJsonSchema = (p) => {
+var scalarTypeOf = (value) => {
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  return void 0;
+};
+var arrayItems = (p, children) => {
+  if (children.length) {
+    const properties = {};
+    for (const c of children)
+      properties[c.name.slice(p.name.length + 3)] = paramToJsonSchema(c);
+    const required = children.filter((c) => c.required).map((c) => c.name.slice(p.name.length + 3));
+    return { type: "object", properties, required };
+  }
+  const first = Array.isArray(p.example) ? p.example[0] : void 0;
+  if (first !== null && typeof first === "object") {
+    const properties = {};
+    for (const [key, value] of Object.entries(first)) {
+      const type2 = scalarTypeOf(value);
+      properties[key] = type2 ? { type: type2 } : {};
+    }
+    return { type: "object", properties };
+  }
+  const type = scalarTypeOf(first);
+  return type ? { type } : {};
+};
+var paramToJsonSchema = (p, arrayChildren = []) => {
   const schema = {};
   if (JSON_SCHEMA_TYPES.has(p.type)) schema.type = p.type;
+  else if (p.type === "array") {
+    schema.type = "array";
+    schema.items = arrayItems(p, arrayChildren);
+  }
   const description = [
     p.description ?? p.label ?? p.name,
     p.example !== void 0 ? `Example: ${JSON.stringify(p.example)}` : ""
@@ -47,15 +97,33 @@ var buildToolDefs = (bundle) => verificationApis(bundle).map((api) => {
     throw new Error(
       `Spec "${api.slug}" requires header(s) ${unrepresentable.map((h) => h.name).join(", ")} which the transactional executor cannot send. Add header support to the executor before exposing this tool.`
     );
+  const topLevel = api.requestParams.filter((p) => !p.name.includes("[]."));
+  const childrenOf = (parent) => api.requestParams.filter((p) => p.name.startsWith(`${parent.name}[].`));
   const properties = {};
-  for (const p of api.requestParams)
-    properties[p.name] = paramToJsonSchema(p);
-  const required = api.requestParams.filter((p) => p.required).map((p) => p.name);
+  for (const p of topLevel)
+    properties[p.name] = paramToJsonSchema(p, childrenOf(p));
+  const required = topLevel.filter((p) => p.required).map((p) => p.name);
+  const sideEffect = SIDE_EFFECTS[api.slug];
+  const description = [
+    api.summary,
+    sideEffect ? `${sideEffect} via Eko EPS (${api.method} ${api.path}).` : `Read-only verification via Eko EPS (${api.method} ${api.path}).`,
+    "Each successful call is billed per EPS pricing.",
+    FLOW_GUIDANCE[api.slug]
+  ].filter(Boolean).join(" ");
   return {
     name: toToolName(api.slug),
     slug: api.slug,
-    description: `${api.summary} Read-only verification via Eko EPS (${api.method} ${api.path}). Each successful call is billed per EPS pricing.`,
-    inputSchema: { type: "object", properties, required }
+    title: api.name,
+    description,
+    inputSchema: { type: "object", properties, required },
+    annotations: {
+      readOnlyHint: !sideEffect,
+      // Meaningful only when readOnlyHint is false (MCP spec); every
+      // side-effecting call here does something new (new penny-drop,
+      // new SMS, new batch, new session).
+      ...sideEffect && { idempotentHint: false },
+      openWorldHint: true
+    }
   };
 });
 
@@ -112,7 +180,9 @@ var createTransactServer = (tools, ctx, version) => {
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: visibleTools.map((t) => ({
       name: t.name,
+      title: t.title,
       description: t.description,
+      annotations: t.annotations,
       // Identity params covered by a server-side default are demoted from
       // `required` so schema-validating hosts don't force the model to
       // invent them; EpsClient still enforces presence after merging.
@@ -151,9 +221,7 @@ var createTransactServer = (tools, ctx, version) => {
         req.params.arguments ?? {}
       );
       return {
-        content: [
-          { type: "text", text: JSON.stringify(result, null, 2) }
-        ]
+        content: [{ type: "text", text: JSON.stringify(result) }]
       };
     } catch (err) {
       return errorResult(sanitizeError(err));

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   parseAllowed,
   parseEnvironment,
   withTimeout
-} from "./chunk-AAUR66A3.js";
+} from "./chunk-XLZLL6DZ.js";
 
 // src/index.ts
 import { serve } from "@hono/node-server";

package/dist/stdio.js

@@ -6,7 +6,7 @@ import {
   parseAllowed,
   parseEnvironment,
   withTimeout
-} from "./chunk-AAUR66A3.js";
+} from "./chunk-XLZLL6DZ.js";
 
 // src/stdio.ts
 import { createRequire } from "module";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ekoindia/eps-transact-mcp",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "Transactional MCP server for Eko Platform Services (EPS) verification APIs — remote (streamable HTTP) and local (stdio).",
 	"license": "MIT",
 	"type": "module",
@@ -29,7 +29,7 @@
 		"prepublishOnly": "npm run bake && npm run build"
 	},
 	"dependencies": {
-		"@ekoindia/eps-sdk": "*",
+		"@ekoindia/eps-sdk": "^0.1.1",
 		"@hono/node-server": "^1.0.0",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"hono": "^4.0.0"