feat: add get_subscription tool

Author: verepdev

README.md

@@ -2,7 +2,7 @@
 
 > MCP server for Iyzico (Turkish payment processor) — read-mostly access for Claude / Cursor / cline.
 
-**v0.0.2** — 4 read tools: `get_payment`, `list_payments`, `get_bin_info`, `get_installment_info`. Not yet published to npm; install from source.
+**v0.0.3** — 5 read tools: `get_payment`, `list_payments`, `get_bin_info`, `get_installment_info`, `get_subscription`. Not yet published to npm; install from source.
 
 ## Tools
 
@@ -53,6 +53,17 @@ List installment options Iyzico will allow for a given card BIN at a given price
 | `price` | string | yes | Total price as a decimal string (e.g. `"1000"`, `"1000.50"`). |
 | `locale` | `"tr"` \| `"en"` | no | Response language. Default `"en"`. |
 
+### `get_subscription`
+
+Retrieve an Iyzico subscription by its reference code. Returns subscription state (active/canceled/expired), pricing plan, customer reference, and billing schedule.
+
+**Input:**
+
+| field | type | required | notes |
+|---|---|---|---|
+| `subscriptionReferenceCode` | string | yes | Iyzico subscription reference code (returned at subscription creation, permanent ID). |
+| `locale` | `"tr"` \| `"en"` | no | Response language. Default `"en"`. |
+
 ## Setup
 
 ### Install from source

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verepdev/iyzico-mcp",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "MCP server scaffold for Iyzico (Turkish payment processor) — read-mostly access for Claude / Cursor / cline.",
   "type": "module",
   "main": "dist/index.js",

src/index.ts

@@ -5,11 +5,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { getBinInfo, getBinInfoInputShape } from "./tools/get_bin_info.js";
 import { getInstallmentInfo, getInstallmentInfoInputShape } from "./tools/get_installment_info.js";
 import { getPayment, getPaymentInputShape } from "./tools/get_payment.js";
+import { getSubscription, getSubscriptionInputShape } from "./tools/get_subscription.js";
 import { listPayments, listPaymentsInputShape } from "./tools/list_payments.js";
 
 const server = new McpServer({
   name: "iyzico-mcp",
-  version: "0.0.2",
+  version: "0.0.3",
 });
 
 server.tool(
@@ -80,5 +81,22 @@ server.tool(
   },
 );
 
+server.tool(
+  "get_subscription",
+  "Retrieve an Iyzico subscription by its reference code. Returns subscription state (active/canceled/expired), pricing plan, customer reference, and billing schedule.",
+  getSubscriptionInputShape,
+  async (input) => {
+    const result = await getSubscription(input);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  },
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

src/iyzico/types.d.ts

@@ -60,11 +60,22 @@ declare module "iyzipay" {
     retrieve(request: InstallmentInfoRetrieveRequest, cb: Callback): void;
   }
 
+  export interface SubscriptionRetrieveRequest {
+    locale?: "tr" | "en";
+    conversationId?: string;
+    subscriptionReferenceCode: string;
+  }
+
+  export interface SubscriptionResource {
+    retrieve(request: SubscriptionRetrieveRequest, cb: Callback): void;
+  }
+
   export default class Iyzipay {
     constructor(config: IyzipayConfig);
     payment: PaymentResource;
     reportingTransactions: ReportingTransactionsResource;
     binNumber: BinNumberResource;
     installmentInfo: InstallmentInfoResource;
+    subscription: SubscriptionResource;
   }
 }

src/tools/get_subscription.ts

@@ -0,0 +1,44 @@
+import type { IyzicoResponse } from "iyzipay";
+import { z } from "zod";
+import { createClient, getConfig } from "../iyzico/client.js";
+import { mapIyzicoFailure } from "../iyzico/error.js";
+
+export const getSubscriptionInputShape = {
+  subscriptionReferenceCode: z
+    .string()
+    .min(1)
+    .describe(
+      "Iyzico subscription reference code (returned at subscription creation, used as the subscription's permanent ID).",
+    ),
+  locale: z.enum(["tr", "en"]).default("en").describe("Response language. Default 'en'."),
+};
+
+export const getSubscriptionInputSchema = z.object(getSubscriptionInputShape);
+export type GetSubscriptionInput = z.infer<typeof getSubscriptionInputSchema>;
+
+export async function getSubscription(input: GetSubscriptionInput): Promise<IyzicoResponse> {
+  const config = getConfig();
+  const client = createClient(config);
+
+  return new Promise<IyzicoResponse>((resolve, reject) => {
+    client.subscription.retrieve(
+      {
+        locale: input.locale,
+        conversationId: `mcp-get-subscription-${input.subscriptionReferenceCode}`,
+        subscriptionReferenceCode: input.subscriptionReferenceCode,
+      },
+      (err, result) => {
+        if (err) {
+          reject(err instanceof Error ? err : new Error(String(err)));
+          return;
+        }
+        const failure = mapIyzicoFailure(result);
+        if (failure) {
+          reject(failure);
+          return;
+        }
+        resolve(result);
+      },
+    );
+  });
+}

tests/tools/get_subscription.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { getSubscriptionInputSchema } from "../../src/tools/get_subscription";
+
+describe("get_subscription input schema", () => {
+  test("accepts valid reference code and applies locale default", () => {
+    const result = getSubscriptionInputSchema.parse({
+      subscriptionReferenceCode: "SUB-REF-12345",
+    });
+    expect(result.subscriptionReferenceCode).toBe("SUB-REF-12345");
+    expect(result.locale).toBe("en");
+  });
+
+  test("accepts explicit locale", () => {
+    const result = getSubscriptionInputSchema.parse({
+      subscriptionReferenceCode: "SUB-REF-12345",
+      locale: "tr",
+    });
+    expect(result.locale).toBe("tr");
+  });
+
+  test("rejects missing subscriptionReferenceCode", () => {
+    expect(() => getSubscriptionInputSchema.parse({})).toThrow();
+  });
+
+  test("rejects empty subscriptionReferenceCode", () => {
+    expect(() => getSubscriptionInputSchema.parse({ subscriptionReferenceCode: "" })).toThrow();
+  });
+
+  test("rejects invalid locale", () => {
+    expect(() =>
+      getSubscriptionInputSchema.parse({
+        subscriptionReferenceCode: "SUB-REF-12345",
+        locale: "de",
+      }),
+    ).toThrow();
+  });
+});