@ekoindia/eps-transact-mcp 0.1.0

package/dist/chunk-AAUR66A3.js

@@ -0,0 +1,181 @@
+// src/load-bundle.ts
+import { promises as fs } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var here = path.dirname(fileURLToPath(import.meta.url));
+var BAKED_PATH = path.resolve(here, "../data/eps.json");
+var loadBundle = async () => {
+  const url = process.env.EPS_BUNDLE_URL;
+  if (url) {
+    try {
+      const res = await fetch(url);
+      if (res.ok)
+        return { bundle: await res.json(), source: "remote" };
+    } catch {
+    }
+  }
+  const raw = await fs.readFile(BAKED_PATH, "utf8");
+  return { bundle: JSON.parse(raw), source: "baked" };
+};
+
+// src/tools.ts
+var EXECUTOR_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "developer_key",
+  "secret-key",
+  "secret-key-timestamp",
+  "content-type"
+]);
+var IDENTITY_PARAMS = /* @__PURE__ */ new Set(["initiator_id", "user_code"]);
+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) => {
+  const schema = {};
+  if (JSON_SCHEMA_TYPES.has(p.type)) schema.type = p.type;
+  const description = [
+    p.description ?? p.label ?? p.name,
+    p.example !== void 0 ? `Example: ${JSON.stringify(p.example)}` : ""
+  ].filter(Boolean).join(" ");
+  if (description) schema.description = description;
+  return schema;
+};
+var buildToolDefs = (bundle) => verificationApis(bundle).map((api) => {
+  const unrepresentable = api.headers.filter(
+    (h) => h.required && !EXECUTOR_HEADER_NAMES.has(h.name)
+  );
+  if (unrepresentable.length)
+    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 properties = {};
+  for (const p of api.requestParams)
+    properties[p.name] = paramToJsonSchema(p);
+  const required = api.requestParams.filter((p) => p.required).map((p) => p.name);
+  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 }
+  };
+});
+
+// src/ctx.ts
+var parseEnvironment = (raw) => {
+  const value = (raw ?? "uat").trim().toLowerCase();
+  if (value === "uat") return "sandbox";
+  if (value === "production") return "production";
+  return void 0;
+};
+var parseAllowed = (raw) => {
+  const value = raw?.trim();
+  if (!value) return void 0;
+  if (value === "*") return "all";
+  const names = value.split(",").map((s) => s.trim()).filter(Boolean);
+  return names.length ? new Set(names) : void 0;
+};
+var isAllowed = (ctx, toolName) => ctx.allowed === "all" || ctx.allowed.has(toolName);
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { EpsClient } from "@ekoindia/eps-sdk";
+var SAFE_MESSAGE_PATTERNS = [
+  /^Missing required params for /,
+  /^Invalid param types for /,
+  /^Unknown endpoint slug /,
+  /^Unknown environment /
+];
+var sanitizeError = (err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  if (SAFE_MESSAGE_PATTERNS.some((re) => re.test(message)))
+    return { code: "VALIDATION", message };
+  if (err instanceof Error && err.name === "TimeoutError")
+    return { code: "UPSTREAM_TIMEOUT", message: "Eko EPS request timed out." };
+  return {
+    code: "UPSTREAM_ERROR",
+    message: "Eko EPS call failed (network or non-JSON upstream response)."
+  };
+};
+var errorResult = (payload) => ({
+  isError: true,
+  content: [{ type: "text", text: JSON.stringify(payload) }]
+});
+var createTransactServer = (tools, ctx, version) => {
+  const server = new Server(
+    { name: "eps-transact-mcp", version },
+    { capabilities: { tools: {} } }
+  );
+  const visibleTools = tools.filter((t) => isAllowed(ctx, t.name));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: visibleTools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      // 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.
+      inputSchema: {
+        ...t.inputSchema,
+        required: t.inputSchema.required.filter(
+          (name) => !(IDENTITY_PARAMS.has(name) && (name === "initiator_id" && ctx.initiatorId !== void 0 || name === "user_code" && ctx.userCode !== void 0))
+        )
+      }
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = tools.find((t) => t.name === req.params.name);
+    if (!tool)
+      return errorResult({
+        code: "UNKNOWN_TOOL",
+        message: `Unknown tool "${req.params.name}".`
+      });
+    if (!isAllowed(ctx, tool.name))
+      return errorResult({
+        code: "TOOL_NOT_ALLOWED",
+        message: `Tool "${tool.name}" is not in this connection's X-Eko-Allowed-Apis allowlist.`
+      });
+    const client = new EpsClient({
+      developerKey: ctx.developerKey,
+      accessKey: ctx.accessKey,
+      environment: ctx.environment,
+      ...ctx.initiatorId !== void 0 && { initiatorId: ctx.initiatorId },
+      ...ctx.userCode !== void 0 && { userCode: ctx.userCode },
+      ...ctx.fetch && { fetch: ctx.fetch },
+      ...ctx.now && { now: ctx.now }
+    });
+    try {
+      const result = await client.call(
+        tool.slug,
+        req.params.arguments ?? {}
+      );
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(result, null, 2) }
+        ]
+      };
+    } catch (err) {
+      return errorResult(sanitizeError(err));
+    }
+  });
+  return server;
+};
+
+// src/fetchTimeout.ts
+var DEFAULT_FETCH_TIMEOUT_MS = 1e4;
+function withTimeout(fetchImpl, ms = DEFAULT_FETCH_TIMEOUT_MS) {
+  return (input, init) => fetchImpl(input, {
+    ...init,
+    signal: init?.signal ?? AbortSignal.timeout(ms)
+  });
+}
+
+export {
+  loadBundle,
+  buildToolDefs,
+  parseEnvironment,
+  parseAllowed,
+  createTransactServer,
+  withTimeout
+};

package/dist/index.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import {
+  buildToolDefs,
+  createTransactServer,
+  loadBundle,
+  parseAllowed,
+  parseEnvironment,
+  withTimeout
+} from "./chunk-AAUR66A3.js";
+
+// src/index.ts
+import { serve } from "@hono/node-server";
+
+// src/http.ts
+import { createHash } from "crypto";
+import { Hono } from "hono";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+
+// src/requestId.ts
+import { randomUUID } from "crypto";
+var FALLBACK_RID = "rid-unavailable";
+function sanitizeRequestId(raw) {
+  if (!raw) return "";
+  return raw.replace(/[^A-Za-z0-9._-]/g, "").slice(0, 128);
+}
+function requestId(opts = {}) {
+  const genId = opts.genId ?? (() => randomUUID());
+  return async (c, next) => {
+    let rid = sanitizeRequestId(c.req.header("x-request-id"));
+    if (!rid) {
+      try {
+        rid = genId();
+      } catch {
+        rid = FALLBACK_RID;
+      }
+    }
+    c.set("rid", rid);
+    c.header("x-request-id", rid);
+    await next();
+  };
+}
+
+// src/accessLog.ts
+function createAccessLogger(opts = {}) {
+  const sink = opts.sink ?? ((line) => console.log(line));
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  return {
+    log(input) {
+      try {
+        const record = {
+          type: "access",
+          ts: now().toISOString(),
+          ...input
+        };
+        void Promise.resolve(sink(JSON.stringify(record))).catch(() => {
+        });
+      } catch {
+      }
+    }
+  };
+}
+var noopAccessLogger = {
+  log() {
+  }
+};
+
+// src/http.ts
+var RL_LIMIT = 60;
+var RL_WINDOW_SEC = 600;
+var rpcError = (code, message) => ({
+  jsonrpc: "2.0",
+  error: { code, message },
+  id: null
+});
+var extractToolName = async (raw) => {
+  try {
+    const body = await raw.json();
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+      return void 0;
+    const rpc = body;
+    if (rpc.method !== "tools/call") return void 0;
+    return typeof rpc.params?.name === "string" ? rpc.params.name : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var createApp = (deps) => {
+  const tools = buildToolDefs(deps.bundle);
+  const accessLog = deps.accessLog ?? noopAccessLogger;
+  const upstreamFetch = withTimeout(deps.fetch ?? fetch);
+  const rl = deps.rateLimit ?? { limit: RL_LIMIT, windowSec: RL_WINDOW_SEC };
+  const windows = /* @__PURE__ */ new Map();
+  const nowMs = deps.now ?? Date.now;
+  const overLimit = (key) => {
+    if (rl === false) return false;
+    const t = nowMs();
+    const w = windows.get(key);
+    if (!w || t >= w.resetAt) {
+      windows.set(key, { count: 1, resetAt: t + rl.windowSec * 1e3 });
+      return false;
+    }
+    w.count += 1;
+    return w.count > rl.limit;
+  };
+  const app = new Hono();
+  app.use(requestId());
+  app.use(async (c, next) => {
+    const start = nowMs();
+    try {
+      await next();
+    } finally {
+      if (c.req.path !== "/healthz")
+        accessLog.log({
+          rid: c.get("rid") ?? "rid-unavailable",
+          method: c.req.method,
+          path: c.req.path,
+          status: c.res?.status ?? 500,
+          durMs: nowMs() - start,
+          ip: c.req.header("x-real-ip") ?? "",
+          ...c.get("toolName") && { tool: c.get("toolName") }
+        });
+    }
+  });
+  app.get(
+    "/healthz",
+    (c) => c.json({
+      ok: true,
+      bundleVersion: deps.bundle.meta.bundleVersion,
+      tools: tools.length
+    })
+  );
+  app.post("/mcp", async (c) => {
+    const developerKey = c.req.header("x-eko-developer-key");
+    const accessKey = c.req.header("x-eko-access-key");
+    if (!developerKey || !accessKey)
+      return c.json(
+        rpcError(
+          -32001,
+          "Missing X-Eko-Developer-Key and/or X-Eko-Access-Key header."
+        ),
+        401
+      );
+    const allowed = parseAllowed(c.req.header("x-eko-allowed-apis"));
+    if (!allowed)
+      return c.json(
+        rpcError(
+          -32602,
+          'Missing or empty X-Eko-Allowed-Apis header. Send a comma-separated list of tool names, or "*" to allow all verification tools. This is deliberate: EPS calls are billed.'
+        ),
+        400
+      );
+    const environment = parseEnvironment(c.req.header("x-eko-env"));
+    if (!environment)
+      return c.json(
+        rpcError(
+          -32602,
+          'Invalid X-Eko-Env header. Use "uat" (default) or "production".'
+        ),
+        400
+      );
+    const rlKey = `${environment}:${createHash("sha256").update(developerKey).digest("hex")}`;
+    if (overLimit(rlKey))
+      return c.json(
+        rpcError(-32e3, "Rate limit exceeded for this developer key."),
+        429
+      );
+    c.set("toolName", await extractToolName(c.req.raw.clone()));
+    const ctx = {
+      developerKey,
+      accessKey,
+      environment,
+      allowed,
+      initiatorId: c.req.header("x-eko-initiator-id"),
+      userCode: c.req.header("x-eko-user-code"),
+      fetch: upstreamFetch,
+      ...deps.now && { now: deps.now }
+    };
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      // stateless: no session to manage
+      enableJsonResponse: true
+    });
+    const server = createTransactServer(
+      tools,
+      ctx,
+      deps.bundle.meta.bundleVersion
+    );
+    await server.connect(transport);
+    return transport.handleRequest(c.req.raw);
+  });
+  app.on(["GET", "DELETE"], "/mcp", (c) => {
+    c.header("Allow", "POST");
+    return c.json(rpcError(-32e3, "Method not allowed. POST only."), 405);
+  });
+  return app;
+};
+
+// src/index.ts
+var main = async () => {
+  const { bundle, source } = await loadBundle();
+  const app = createApp({ bundle, accessLog: createAccessLogger() });
+  const port = Number(process.env.PORT ?? 8788);
+  const server = serve({ fetch: app.fetch, port, hostname: "0.0.0.0" }, () => {
+    console.error(
+      `[eps-transact-mcp] listening on :${port} (bundle ${bundle.meta.bundleVersion}, ${source})`
+    );
+  });
+  const shutdown = () => {
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 5e3).unref();
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+};
+main().catch((err) => {
+  console.error(
+    `[eps-transact-mcp] fatal: ${err instanceof Error ? err.message : String(err)}`
+  );
+  process.exit(1);
+});

package/dist/stdio.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import {
+  buildToolDefs,
+  createTransactServer,
+  loadBundle,
+  parseAllowed,
+  parseEnvironment,
+  withTimeout
+} from "./chunk-AAUR66A3.js";
+
+// src/stdio.ts
+import { createRequire } from "module";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/update-check.ts
+var REGISTRY_URL = "https://registry.npmjs.org/@ekoindia/eps-transact-mcp/latest";
+var parseStrict = (v) => {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+};
+var isNewer = (current, latest) => {
+  const a = parseStrict(current);
+  const b = parseStrict(latest);
+  if (!a || !b) return void 0;
+  for (let i = 0; i < 3; i++) {
+    if (b[i] > a[i]) return true;
+    if (b[i] < a[i]) return false;
+  }
+  return false;
+};
+var checkForUpdate = async (current, deps = {}) => {
+  const fetchFn = deps.fetch ?? fetch;
+  try {
+    const res = await fetchFn(REGISTRY_URL, {
+      signal: AbortSignal.timeout(deps.timeoutMs ?? 3e3)
+    });
+    if (!res.ok) return { current };
+    const body = await res.json();
+    const latest = typeof body.version === "string" ? body.version : void 0;
+    if (!latest) return { current };
+    const newer = isNewer(current, latest);
+    return {
+      current,
+      latest,
+      ...newer !== void 0 && { updateAvailable: newer }
+    };
+  } catch {
+    return { current };
+  }
+};
+var updateNotice = (state) => `eps-transact-mcp ${state.latest} available (running ${state.current}). Use "npx -y @ekoindia/eps-transact-mcp@latest" in your MCP config to always run the newest version.`;
+var notifyIfOutdated = async (current, deps = {}) => {
+  const env = deps.env ?? process.env;
+  if (env.EPS_NO_UPDATE_CHECK === "1") return;
+  const state = await checkForUpdate(current, { fetch: deps.fetch });
+  if (state.updateAvailable) (deps.warn ?? console.error)(updateNotice(state));
+};
+
+// src/stdio.ts
+var { version: OWN_VERSION } = createRequire(import.meta.url)(
+  "../package.json"
+);
+var main = async () => {
+  const developerKey = process.env.EKO_DEVELOPER_KEY;
+  const accessKey = process.env.EKO_ACCESS_KEY;
+  if (!developerKey || !accessKey) {
+    console.error(
+      "[eps-transact-mcp] EKO_DEVELOPER_KEY and EKO_ACCESS_KEY env vars are required."
+    );
+    process.exit(1);
+  }
+  const environment = parseEnvironment(process.env.EKO_ENV);
+  if (!environment) {
+    console.error(
+      '[eps-transact-mcp] Invalid EKO_ENV. Use "uat" (default) or "production".'
+    );
+    process.exit(1);
+  }
+  const allowed = parseAllowed(process.env.EKO_ALLOWED_APIS) ?? "all";
+  const { bundle } = await loadBundle();
+  const ctx = {
+    developerKey,
+    accessKey,
+    environment,
+    allowed,
+    initiatorId: process.env.EKO_INITIATOR_ID,
+    userCode: process.env.EKO_USER_CODE,
+    fetch: withTimeout(fetch)
+  };
+  const server = createTransactServer(
+    buildToolDefs(bundle),
+    ctx,
+    bundle.meta.bundleVersion
+  );
+  await server.connect(new StdioServerTransport());
+  console.error(
+    `[eps-transact-mcp] stdio ready (${environment}, bundle ${bundle.meta.bundleVersion})`
+  );
+  void notifyIfOutdated(OWN_VERSION);
+};
+main().catch((err) => {
+  console.error(
+    `[eps-transact-mcp] fatal: ${err instanceof Error ? err.message : String(err)}`
+  );
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@ekoindia/eps-transact-mcp",
+	"version": "0.1.0",
+	"description": "Transactional MCP server for Eko Platform Services (EPS) verification APIs — remote (streamable HTTP) and local (stdio).",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/ekoindia/eps-platform.git",
+		"directory": "packages/eps-transact-mcp"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"bin": {
+		"eps-transact-mcp": "dist/stdio.js"
+	},
+	"files": [
+		"dist",
+		"data"
+	],
+	"scripts": {
+		"bake": "node scripts/bake-bundle.mjs",
+		"build": "tsup",
+		"dev": "tsx watch src/index.ts",
+		"start": "node dist/index.js",
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "npm run bake && npm run build"
+	},
+	"dependencies": {
+		"@ekoindia/eps-sdk": "*",
+		"@hono/node-server": "^1.0.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"hono": "^4.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.20.0",
+		"tsup": "^8.0.0",
+		"tsx": "^4.22.4",
+		"typescript": "^5.8.3",
+		"vitest": "^3.2.4"
+	},
+	"engines": {
+		"node": ">=20"
+	}
+}