easypaydirect-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the easypaydirect-mcp 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,103 @@
+# easypaydirect-mcp
+
+> **Unofficial, read-only [Model Context Protocol](https://modelcontextprotocol.io) server for the [Easy Pay Direct](https://easypaydirect.com) (EPD) / NMI-family payment gateway.**
+
+Give an AI assistant (Claude Desktop, Claude Code, or any MCP client) safe, **read-only** access to your gateway's transactions, subscriptions, recurring plans, and Customer Vault records — so you can ask questions like *"find the failed transactions for this customer last week"* or *"is this subscription still active?"* in plain language.
+
+Easy Pay Direct is built on the **NMI / Network Merchants** gateway platform, so this server works with **any NMI white-label gateway** — just point it at your gateway's host. EPD is the headline example, not the limit.
+
+> ⚠️ **Not affiliated with, endorsed by, or sponsored by Easy Pay Direct or NMI.** "Easy Pay Direct", "EPD", and "NMI" are trademarks of their respective owners. This is an independent open-source client for their public [Query API](https://docs.nmi.com/reference/query).
+
+---
+
+## Why read-only?
+
+This server talks **only** to the gateway's [Query API](https://docs.nmi.com/reference/query) (`/api/query.php`) — the reporting endpoint. It has **no code path** to the transaction endpoint (`transact.php`), so it **cannot** charge a card, issue a refund, void a transaction, or modify the vault. An LLM connected to this server can look, but it cannot touch money. See [`docs/security.md`](docs/security.md).
+
+Write operations may arrive in a future major version — always **opt-in, off by default, and loudly gated**.
+
+---
+
+## Install & run
+
+Requires **Node.js 18+**.
+
+```bash
+# no install needed — run straight from npm
+npx easypaydirect-mcp
+```
+
+The server speaks MCP over **stdio** and expects two environment variables:
+
+| Variable | Required | Description |
+|---|---|---|
+| `NMI_SECURITY_KEY` | ✅ | Your gateway API **security key** (a **read-only** key is recommended). Merchant portal → Settings → Security Keys. |
+| `NMI_API_URL` | — | Gateway API base URL. Defaults to `https://secure.nmi.com`. For EPD/white-labels, set this to your gateway's host. |
+
+See [`docs/configuration.md`](docs/configuration.md) for how to find your key and host.
+
+## Connect it to Claude
+
+**Claude Desktop** — add to `claude_desktop_config.json` (see [`examples/claude-desktop-config.json`](examples/claude-desktop-config.json)):
+
+```json
+{
+  "mcpServers": {
+    "easypaydirect": {
+      "command": "npx",
+      "args": ["-y", "easypaydirect-mcp"],
+      "env": {
+        "NMI_SECURITY_KEY": "your_read_only_security_key",
+        "NMI_API_URL": "https://secure.nmi.com"
+      }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add easypaydirect \
+  -e NMI_SECURITY_KEY=your_read_only_security_key \
+  -e NMI_API_URL=https://secure.nmi.com \
+  -- npx -y easypaydirect-mcp
+```
+
+Full walkthrough: [`docs/getting-started.md`](docs/getting-started.md).
+
+## Tools
+
+All tools are **read-only**. Full reference in [`docs/tools.md`](docs/tools.md).
+
+| Tool | What it does |
+|---|---|
+| `get_transaction` | Fetch one transaction by gateway transaction ID. |
+| `search_transactions` | Search transactions by date range + filters (condition, action type, payment type, source, email, order id). |
+| `get_subscription` | Fetch one recurring subscription by ID. |
+| `list_subscriptions` | List recurring subscriptions, optionally by created/updated date range. |
+| `list_recurring_plans` | List recurring billing plans (or one by `plan_id`). |
+| `get_customer_vault_record` | Fetch one stored Customer Vault record by ID. |
+| `list_customer_vault` | List stored Customer Vault records, optionally by date range. |
+
+## Develop
+
+```bash
+git clone https://github.com/praveendias1180/easypaydirect-mcp.git
+cd easypaydirect-mcp
+npm install
+npm run build      # compile TypeScript to dist/
+npm run typecheck  # type-check only
+```
+
+Local run against the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+Architecture and how tools map to the Query API: [`docs/nmi-api-mapping.md`](docs/nmi-api-mapping.md).
+
+## License
+
+[MIT](LICENSE) © the easypaydirect-mcp contributors.

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import type { Config } from "./config.js";
+export type QueryParams = Record<string, string | number | undefined>;
+export declare class NmiQueryError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: string | undefined;
+    constructor(message: string, status?: number | undefined, body?: string | undefined);
+}
+/**
+ * Thin client over the EPD / NMI **Query API** (`POST /api/query.php`).
+ *
+ * The Query API is strictly READ-ONLY: it returns transaction, subscription,
+ * recurring-plan and customer-vault data. This client intentionally exposes no
+ * way to reach the transaction (`transact.php`) endpoint, so no charge, refund,
+ * void or vault-write can be issued through it.
+ */
+export declare class NmiClient {
+    private readonly config;
+    constructor(config: Config);
+    query(params: QueryParams): Promise<unknown>;
+}

package/dist/client.js

@@ -0,0 +1,66 @@
+import { XMLParser } from "fast-xml-parser";
+/**
+ * Values are kept as strings (parseTagValue: false) so that monetary amounts
+ * and long numeric IDs are never coerced to floats and lose precision.
+ */
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    parseTagValue: false,
+    trimValues: true,
+});
+export class NmiQueryError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "NmiQueryError";
+    }
+}
+/**
+ * Thin client over the EPD / NMI **Query API** (`POST /api/query.php`).
+ *
+ * The Query API is strictly READ-ONLY: it returns transaction, subscription,
+ * recurring-plan and customer-vault data. This client intentionally exposes no
+ * way to reach the transaction (`transact.php`) endpoint, so no charge, refund,
+ * void or vault-write can be issued through it.
+ */
+export class NmiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async query(params) {
+        const body = new URLSearchParams();
+        body.set("security_key", this.config.securityKey);
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null && value !== "") {
+                body.set(key, String(value));
+            }
+        }
+        const url = `${this.config.apiUrl}/api/query.php`;
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: body.toString(),
+            });
+        }
+        catch (err) {
+            throw new NmiQueryError(`Network error calling ${url}: ${err.message}`);
+        }
+        const text = await res.text();
+        if (!res.ok) {
+            throw new NmiQueryError(`Query API returned HTTP ${res.status}`, res.status, text.slice(0, 500));
+        }
+        // A well-formed response is XML. A plaintext body almost always means an
+        // authentication failure (bad/missing security key) or a wrong base URL.
+        if (!text.trim().startsWith("<")) {
+            throw new NmiQueryError(`Unexpected non-XML response (check NMI_SECURITY_KEY and NMI_API_URL): ${text.slice(0, 300)}`, res.status, text.slice(0, 500));
+        }
+        return parser.parse(text);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C;;;GAGG;AACH,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,gBAAgB,EAAE,KAAK;IACvB,aAAa,EAAE,KAAK;IACpB,UAAU,EAAE,IAAI;CACjB,CAAC,CAAC;AAIH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAG3B;IACA;IAHX,YACE,OAAe,EACN,MAAe,EACf,IAAa;QAEtB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAS;QACf,SAAI,GAAJ,IAAI,CAAS;QAGtB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,SAAS;IACS;IAA7B,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C,KAAK,CAAC,KAAK,CAAC,MAAmB;QAC7B,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;QACnC,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAClD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBAC1D,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,gBAAgB,CAAC;QAElD,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBACrB,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE;gBAChE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE;aACtB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CAAC,yBAAyB,GAAG,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACrF,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAE9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,aAAa,CAAC,2BAA2B,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACnG,CAAC;QAED,yEAAyE;QACzE,yEAAyE;QACzE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,aAAa,CACrB,yEAAyE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAC7F,GAAG,CAAC,MAAM,EACV,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CACnB,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime configuration, loaded from environment variables.
+ *
+ * The gateway security key is read from the environment ONLY — it is never
+ * accepted as a tool argument, so a model driving this server can never see it
+ * or pass it around.
+ */
+export interface Config {
+    /** Gateway API "security key" (read-only key recommended). */
+    securityKey: string;
+    /** Gateway API base URL, no trailing slash. */
+    apiUrl: string;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,11 @@
+const DEFAULT_API_URL = "https://secure.nmi.com";
+export function loadConfig(env = process.env) {
+    const securityKey = env.NMI_SECURITY_KEY?.trim();
+    if (!securityKey) {
+        throw new Error("NMI_SECURITY_KEY is required. Set it to your gateway API security key " +
+            "(EPD / NMI merchant portal -> Settings -> Security Keys). A read-only key is recommended.");
+    }
+    const apiUrl = (env.NMI_API_URL?.trim() || DEFAULT_API_URL).replace(/\/+$/, "");
+    return { securityKey, apiUrl };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAcA,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,WAAW,GAAG,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACjD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,wEAAwE;YACtE,2FAA2F,CAC9F,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,eAAe,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEhF,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACjC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { NmiClient } from "./client.js";
+import { registerTransactionTools } from "./tools/transactions.js";
+import { registerSubscriptionTools } from "./tools/subscriptions.js";
+import { registerPlanTools } from "./tools/plans.js";
+import { registerVaultTools } from "./tools/vault.js";
+async function main() {
+    const config = loadConfig();
+    const client = new NmiClient(config);
+    const server = new McpServer({
+        name: "easypaydirect-mcp",
+        version: "0.1.0",
+    });
+    registerTransactionTools(server, client);
+    registerSubscriptionTools(server, client);
+    registerPlanTools(server, client);
+    registerVaultTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is reserved for the MCP protocol; log to stderr only.
+    console.error(`easypaydirect-mcp running on stdio (endpoint: ${config.apiUrl})`);
+}
+main().catch((err) => {
+    console.error("Fatal:", err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IAErC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEnC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,+DAA+D;IAC/D,OAAO,CAAC,KAAK,CAAC,iDAAiD,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;AACnF,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/helpers.d.ts

@@ -0,0 +1,15 @@
+/** Wrap parsed Query API data as an MCP text result (pretty-printed JSON). */
+export declare function jsonResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** Convert a thrown error into an MCP error result without leaking internals. */
+export declare function toErrorResult(err: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/helpers.js

@@ -0,0 +1,25 @@
+import { NmiQueryError } from "../client.js";
+/** Wrap parsed Query API data as an MCP text result (pretty-printed JSON). */
+export function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+/** Convert a thrown error into an MCP error result without leaking internals. */
+export function toErrorResult(err) {
+    let message;
+    if (err instanceof NmiQueryError) {
+        message = err.status ? `${err.message} (HTTP ${err.status})` : err.message;
+    }
+    else if (err instanceof Error) {
+        message = err.message;
+    }
+    else {
+        message = String(err);
+    }
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/tools/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/tools/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,8EAA8E;AAC9E,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,OAAe,CAAC;IACpB,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;QACjC,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,UAAU,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;IAC7E,CAAC;SAAM,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QAChC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IACxB,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IACD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;QAC/D,OAAO,EAAE,IAAa;KACvB,CAAC;AACJ,CAAC"}

package/dist/tools/plans.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { NmiClient } from "../client.js";
+export declare function registerPlanTools(server: McpServer, client: NmiClient): void;

package/dist/tools/plans.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { jsonResult, toErrorResult } from "./helpers.js";
+export function registerPlanTools(server, client) {
+    server.tool("list_recurring_plans", "List recurring billing plans, optionally filtered to a single plan (report_type=recurring_plans). Read-only.", {
+        plan_id: z.string().optional().describe("Optional plan ID to return a single plan instead of all plans."),
+    }, async ({ plan_id }) => {
+        try {
+            return jsonResult(await client.query({ report_type: "recurring_plans", plan_id }));
+        }
+        catch (err) {
+            return toErrorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=plans.js.map

package/dist/tools/plans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.js","sourceRoot":"","sources":["../../src/tools/plans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,UAAU,iBAAiB,CAAC,MAAiB,EAAE,MAAiB;IACpE,MAAM,CAAC,IAAI,CACT,sBAAsB,EACtB,8GAA8G,EAC9G;QACE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gEAAgE,CAAC;KAC1G,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACpB,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QACrF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/subscriptions.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { NmiClient } from "../client.js";
+export declare function registerSubscriptionTools(server: McpServer, client: NmiClient): void;

package/dist/tools/subscriptions.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { jsonResult, toErrorResult } from "./helpers.js";
+export function registerSubscriptionTools(server, client) {
+    server.tool("get_subscription", "Fetch a single recurring subscription by its subscription ID (report_type=recurring). Read-only.", {
+        subscription_id: z.string().min(1).describe("The recurring subscription ID to look up."),
+    }, async ({ subscription_id }) => {
+        try {
+            return jsonResult(await client.query({ report_type: "recurring", subscription_id }));
+        }
+        catch (err) {
+            return toErrorResult(err);
+        }
+    });
+    server.tool("list_subscriptions", "List recurring subscriptions, optionally filtered by created/updated date range (report_type=recurring). Read-only.", {
+        date_search: z
+            .string()
+            .optional()
+            .describe("Which date(s) to filter on, e.g. 'created' or 'updated' or 'created,updated'."),
+        start_date: z.string().optional().describe("Start of range, NMI format YYYYMMDDhhmmss."),
+        end_date: z.string().optional().describe("End of range, NMI format YYYYMMDDhhmmss."),
+    }, async (args) => {
+        try {
+            return jsonResult(await client.query({ report_type: "recurring", ...args }));
+        }
+        catch (err) {
+            return toErrorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/tools/subscriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../../src/tools/subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,UAAU,yBAAyB,CAAC,MAAiB,EAAE,MAAiB;IAC5E,MAAM,CAAC,IAAI,CACT,kBAAkB,EAClB,kGAAkG,EAClG;QACE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC;KACzF,EACD,KAAK,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE;QAC5B,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC;QACvF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,oBAAoB,EACpB,qHAAqH,EACrH;QACE,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,+EAA+E,CAAC;QAC5F,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QACxF,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;KACrF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;QAC/E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/transactions.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { NmiClient } from "../client.js";
+export declare function registerTransactionTools(server: McpServer, client: NmiClient): void;

package/dist/tools/transactions.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { jsonResult, toErrorResult } from "./helpers.js";
+const NMI_DATE_HINT = "NMI datetime format YYYYMMDDhhmmss (e.g. 20260101000000 for 2026-01-01 00:00:00).";
+export function registerTransactionTools(server, client) {
+    server.tool("get_transaction", "Fetch a single transaction by its gateway transaction ID. Read-only.", {
+        transaction_id: z.string().min(1).describe("The gateway transaction ID to look up."),
+    }, async ({ transaction_id }) => {
+        try {
+            return jsonResult(await client.query({ transaction_id }));
+        }
+        catch (err) {
+            return toErrorResult(err);
+        }
+    });
+    server.tool("search_transactions", "Search transactions by date range and optional filters (condition, action type, payment type, source, email, order id). Read-only.", {
+        start_date: z.string().optional().describe(`Start of range. ${NMI_DATE_HINT}`),
+        end_date: z.string().optional().describe(`End of range. ${NMI_DATE_HINT}`),
+        condition: z
+            .string()
+            .optional()
+            .describe("Comma-separated transaction conditions: pending, pendingsettlement, in_progress, abandoned, failed, canceled, complete, unknown."),
+        action_type: z
+            .string()
+            .optional()
+            .describe("Comma-separated action types: sale, refund, credit, auth, capture, void, return."),
+        transaction_type: z.string().optional().describe("Payment type filter: 'cc' (card) or 'ck' (ACH/check)."),
+        source: z.string().optional().describe("Filter by transaction source."),
+        email: z.string().optional().describe("Filter by customer email address."),
+        order_id: z.string().optional().describe("Filter by merchant-supplied order id."),
+    }, async (args) => {
+        try {
+            return jsonResult(await client.query(args));
+        }
+        catch (err) {
+            return toErrorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=transactions.js.map

package/dist/tools/transactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactions.js","sourceRoot":"","sources":["../../src/tools/transactions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,aAAa,GAAG,mFAAmF,CAAC;AAE1G,MAAM,UAAU,wBAAwB,CAAC,MAAiB,EAAE,MAAiB;IAC3E,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,sEAAsE,EACtE;QACE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,wCAAwC,CAAC;KACrF,EACD,KAAK,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE;QAC3B,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,oIAAoI,EACpI;QACE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,aAAa,EAAE,CAAC;QAC9E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iBAAiB,aAAa,EAAE,CAAC;QAC1E,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,kIAAkI,CAAC;QAC/I,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,kFAAkF,CAAC;QAC/F,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;QACzG,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;QACvE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAC1E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;KAClF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/vault.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { NmiClient } from "../client.js";
+export declare function registerVaultTools(server: McpServer, client: NmiClient): void;

package/dist/tools/vault.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { jsonResult, toErrorResult } from "./helpers.js";
+export function registerVaultTools(server, client) {
+    server.tool("get_customer_vault_record", "Fetch a single stored Customer Vault record by its customer_vault_id (report_type=customer_vault). Returns stored profile data only — never full card numbers. Read-only.", {
+        customer_vault_id: z.string().min(1).describe("The Customer Vault ID to look up."),
+    }, async ({ customer_vault_id }) => {
+        try {
+            return jsonResult(await client.query({ report_type: "customer_vault", customer_vault_id }));
+        }
+        catch (err) {
+            return toErrorResult(err);
+        }
+    });
+    server.tool("list_customer_vault", "List stored Customer Vault records, optionally filtered by created/updated date range (report_type=customer_vault). Read-only.", {
+        date_search: z
+            .string()
+            .optional()
+            .describe("Which date(s) to filter on, e.g. 'created', 'updated', or 'created,updated'."),
+        start_date: z.string().optional().describe("Start of range, NMI format YYYYMMDDhhmmss."),
+        end_date: z.string().optional().describe("End of range, NMI format YYYYMMDDhhmmss."),
+    }, async (args) => {
+        try {
+            return jsonResult(await client.query({ report_type: "customer_vault", ...args }));
+        }
+        catch (err) {
+            return toErrorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=vault.js.map

package/dist/tools/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../src/tools/vault.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,MAAiB;IACrE,MAAM,CAAC,IAAI,CACT,2BAA2B,EAC3B,2KAA2K,EAC3K;QACE,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,mCAAmC,CAAC;KACnF,EACD,KAAK,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE;QAC9B,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;QAC9F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,gIAAgI,EAChI;QACE,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,8EAA8E,CAAC;QAC3F,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QACxF,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;KACrF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;QACpF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "easypaydirect-mcp",
+  "version": "0.1.0",
+  "description": "Unofficial read-only Model Context Protocol (MCP) server for the Easy Pay Direct (EPD) / NMI-family payment gateway Query API.",
+  "type": "module",
+  "bin": {
+    "easypaydirect-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "nmi",
+    "easypaydirect",
+    "epd",
+    "payments",
+    "payment-gateway",
+    "claude",
+    "ai"
+  ],
+  "author": "Praveen Dias (https://github.com/praveendias1180)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/praveendias1180/easypaydirect-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/praveendias1180/easypaydirect-mcp/issues"
+  },
+  "homepage": "https://github.com/praveendias1180/easypaydirect-mcp#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "fast-xml-parser": "^5.9.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}