linktest-mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,804 @@
+#!/usr/bin/env node
+/**
+ * LinkTest MCP Server
+ *
+ * Enables AI assistants to automate Google Play closed testing.
+ * Users can place orders, check status, view screenshots, and manage billing
+ * directly through Claude or any MCP-compatible AI.
+ *
+ * Environment variables:
+ *   LINKTEST_API_TOKEN  — Required. Your LinkTest API token (from linktest.dev/settings)
+ *   LINKTEST_API_URL    — Optional. API base URL (default: http://localhost:3001)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import axios, { AxiosError } from "axios";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const CHARACTER_LIMIT = 25000;
+// ─── API Client ──────────────────────────────────────────────────────────────
+function getApiClient() {
+    const token = process.env.LINKTEST_API_TOKEN;
+    const baseURL = process.env.LINKTEST_API_URL || "https://api-p2mrc3yq4a-du.a.run.app";
+    if (!token) {
+        throw new Error("LINKTEST_API_TOKEN environment variable is not set. " +
+            "Get your token from https://linktest.dev/settings");
+    }
+    return axios.create({
+        baseURL,
+        timeout: 30000,
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${token}`,
+        },
+    });
+}
+async function apiRequest(method, path, data, params) {
+    const client = getApiClient();
+    const response = await client.request({ method, url: path, data, params });
+    return response.data;
+}
+// ─── Error Handling ───────────────────────────────────────────────────────────
+function handleError(error) {
+    if (error instanceof AxiosError) {
+        if (error.response) {
+            const status = error.response.status;
+            const msg = error.response.data?.error;
+            switch (status) {
+                case 400:
+                    return `Error: Bad request — ${msg || "check your input parameters"}`;
+                case 401:
+                    return "Error: Invalid API token. Get a new one at https://linktest.dev/settings";
+                case 403:
+                    return "Error: Access denied. This resource belongs to another account.";
+                case 404:
+                    return `Error: Not found — ${msg || "the requested resource does not exist"}`;
+                case 409:
+                    return `Error: Conflict — ${msg || "an order for this app may already exist"}`;
+                case 429:
+                    return "Error: Rate limit exceeded. Please wait a moment and try again.";
+                default:
+                    return `Error: API error (${status}) — ${msg || "unexpected error"}`;
+            }
+        }
+        else if (error.code === "ECONNABORTED") {
+            return "Error: Request timed out. Check your internet connection and try again.";
+        }
+        else if (error.code === "ECONNREFUSED") {
+            return "Error: Cannot connect to LinkTest API. The service may be temporarily unavailable.";
+        }
+    }
+    if (error instanceof Error && error.message.startsWith("LINKTEST_API_TOKEN")) {
+        return `Error: ${error.message}`;
+    }
+    return `Error: Unexpected error — ${error instanceof Error ? error.message : String(error)}`;
+}
+// ─── Formatters ───────────────────────────────────────────────────────────────
+const STATUS_LABELS = {
+    pending: "Pending Payment",
+    active: "Testing in Progress",
+    completed: "Completed",
+    expired: "Expired",
+    payment_failed: "Payment Failed",
+    failed: "Failed — Tester Not Registered",
+};
+function formatDate(iso) {
+    return new Date(iso).toLocaleDateString("en-US", {
+        year: "numeric", month: "short", day: "numeric",
+    });
+}
+function formatOrder(order) {
+    const status = STATUS_LABELS[order.status] ?? String(order.status);
+    const lines = [
+        `**Package**: ${order.packageName}`,
+        `**Status**: ${status}`,
+        `**Order ID**: ${order.id}`,
+    ];
+    if (order.failReason) {
+        lines.push(`**Fail Reason**: ${order.failReason === "tester_not_registered"
+            ? "Tester emails not registered — add LinkTest emails to your closed testing track"
+            : String(order.failReason)}`);
+    }
+    if (order.installedCount !== undefined) {
+        lines.push(`**Devices**: ${order.installedCount} installed`);
+    }
+    if (order.daysLeft !== undefined && order.status === "active") {
+        lines.push(`**Days Left**: ${order.daysLeft} days remaining`);
+    }
+    if (order.startDate)
+        lines.push(`**Started**: ${formatDate(String(order.startDate))}`);
+    if (order.expireDate)
+        lines.push(`**Expires**: ${formatDate(String(order.expireDate))}`);
+    if (order.optInLink)
+        lines.push(`**Opt-in Link**: ${order.optInLink}`);
+    return lines.join("\n");
+}
+// ─── MCP Server ───────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "linktest-mcp-server",
+    version: "1.0.0",
+});
+// ─── Tool: linktest_validate ──────────────────────────────────────────────────
+server.registerTool("linktest_validate", {
+    title: "Validate Opt-in Link",
+    description: `Validate a Google Play closed testing opt-in link before placing an order.
+
+Checks that the link is correctly formatted and accessible on the Play Store.
+Always validate the link first before calling linktest_order to catch issues early.
+
+Args:
+  - opt_in_link (string): The closed testing opt-in URL from Google Play Console.
+    Format: https://play.google.com/apps/testing/{packageName}
+  - package_name (string): The app's package name (e.g., com.example.myapp)
+
+Returns:
+  A message indicating whether the link is valid or the reason it failed.
+
+Examples:
+  - Use when: User provides a Play Store testing link and wants to check it's correct
+  - Use when: Before calling linktest_order to ensure the order will succeed
+
+Error Handling:
+  - "invalid_format": Link URL doesn't match expected Play Store pattern
+  - "package_mismatch": Package name in URL doesn't match provided package_name
+  - "not_accessible": Play Store returned an error for this link`,
+    inputSchema: z.object({
+        opt_in_link: z.string()
+            .url("Must be a valid URL")
+            .describe("Google Play closed testing opt-in URL (e.g. https://play.google.com/apps/testing/com.example.app)"),
+        package_name: z.string()
+            .min(3)
+            .regex(/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/, "Must be a valid Android package name")
+            .describe("App package name (e.g. com.example.myapp)"),
+    }).strict(),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (params) => {
+    try {
+        const data = await apiRequest("POST", "/api/validate/optin-link", { optInLink: params.opt_in_link, packageName: params.package_name });
+        if (data.valid) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `✅ Valid! ${data.reason || "Opt-in link is accessible and correctly formatted."}\n\nYou can now place an order with linktest_order.`,
+                    }],
+            };
+        }
+        else {
+            return {
+                content: [{
+                        type: "text",
+                        text: `❌ Invalid opt-in link: ${data.reason}\n\nFix the link in Google Play Console → Testing → Closed Testing → Copy link`,
+                    }],
+            };
+        }
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: handleError(error) }] };
+    }
+});
+// ─── Tool: linktest_verify ───────────────────────────────────────────────────
+server.registerTool("linktest_verify", {
+    title: "Verify Tester Access",
+    description: `Verify that LinkTest devices can actually access and install the user's app.
+
+This triggers a real device to attempt accessing the app on Google Play Store.
+It checks whether the tester emails are properly registered in the user's closed testing track.
+
+IMPORTANT: After calling this tool, wait 30 seconds, then call it again with the verify_id
+to check the result. Do NOT proceed with linktest_order until verification passes.
+
+Workflow:
+  1. Call with package_name + opt_in_link → returns verify_id (status: pending)
+  2. Wait 30 seconds
+  3. Call with verify_id → returns result (passed or failed)
+  4. If passed → proceed with linktest_order
+  5. If failed → tell user to check tester registration in Play Console
+
+Args (to start verification):
+  - package_name (string): Android package name
+  - opt_in_link (string): Google Play closed testing opt-in URL
+
+Args (to check result):
+  - verify_id (string): The verification ID returned from step 1`,
+    inputSchema: z.object({
+        package_name: z.string()
+            .optional()
+            .describe("Android package name (for starting verification)"),
+        opt_in_link: z.string()
+            .optional()
+            .describe("Google Play closed testing opt-in URL (for starting verification)"),
+        verify_id: z.string()
+            .optional()
+            .describe("Verification ID to check result (from previous call)"),
+    }).strict(),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async (params) => {
+    try {
+        // 결과 확인 모드
+        if (params.verify_id) {
+            const data = await apiRequest("GET", `/api/verify/${params.verify_id}`);
+            if (data.status === "pending") {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `⏳ Verification still in progress (ID: ${data.verifyId}).\n\nPlease wait another 15-30 seconds and check again.`,
+                        }],
+                };
+            }
+            if (data.status === "passed") {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ **Verification passed!** Tester access confirmed for \`${data.packageName}\`.\n\n` +
+                                `Devices can install this app. You can now proceed with linktest_order.`,
+                        }],
+                };
+            }
+            // failed
+            const reasonMsg = data.failReason === "tester_not_registered"
+                ? "Tester emails are NOT registered in your closed testing track."
+                : `Reason: ${data.failReason}`;
+            return {
+                content: [{
+                        type: "text",
+                        text: `❌ **Verification failed** for \`${data.packageName}\`.\n\n${reasonMsg}\n\n` +
+                            `**How to fix:**\n` +
+                            `1. Open Google Play Console → your app\n` +
+                            `2. Testing → Closed Testing → Manage track\n` +
+                            `3. "Testers" tab → Add the "LinkTest" email list\n` +
+                            `4. Click "Save changes" → "Send changes for review"\n\n` +
+                            `After fixing, run linktest_verify again to re-check.`,
+                    }],
+            };
+        }
+        // 새 검증 요청 모드
+        if (!params.package_name || !params.opt_in_link) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Error: package_name and opt_in_link are required to start verification.",
+                    }],
+            };
+        }
+        const data = await apiRequest("POST", "/api/verify/tester-access", { packageName: params.package_name, optInLink: params.opt_in_link });
+        return {
+            content: [{
+                    type: "text",
+                    text: `🔍 **Verification started** (ID: ${data.verifyId})\n\n` +
+                        `A real device is now checking if it can access \`${params.package_name}\` on Google Play.\n\n` +
+                        `⏳ **Wait 30 seconds**, then call:\n` +
+                        `linktest_verify(verify_id="${data.verifyId}")`,
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: handleError(error) }] };
+    }
+});
+// ─── Tool: linktest_order ─────────────────────────────────────────────────────
+server.registerTool("linktest_order", {
+    title: "Place a Closed Testing Order",
+    description: `Place a new closed testing order for a Google Play app.
+
+This creates an order and returns a payment checkout URL. The user must complete
+the $5 payment before testing begins. After payment, LinkTest installs the app
+on 12+ real Android devices and runs it daily for 14+ days.
+
+IMPORTANT — Before placing an order, you MUST follow this workflow:
+
+Step 1. Call linktest_testers to get the email list.
+  - Confirm the user has registered those emails in Play Console.
+  - Confirm the user has a closed testing release deployed.
+  - Confirm the user has clicked "변경사항 전송" (Send changes) in Play Console.
+  - Only AFTER all three are done does the opt-in link become available.
+  - If any step is missing → guide them to complete it before asking for the link.
+
+Step 2. Call linktest_validate to check the opt-in link format.
+
+Step 3. Call linktest_verify to confirm devices can actually install the app.
+  - Wait 30 seconds, then check the result.
+  - If failed → tell user to fix tester registration. Do NOT proceed.
+
+Step 4. Only after verification passes, call this tool to create the order.
+
+Step 5. Share the checkout_url with the user so they can complete payment.
+
+Step 6. After payment, call linktest_status to monitor progress.
+
+Args:
+  - package_name (string): Android package name (e.g., com.example.myapp)
+  - opt_in_link (string): Google Play closed testing opt-in URL
+
+Returns (JSON):
+  {
+    "order_id": string,       // Unique order ID for tracking
+    "status": "pending",      // Initial status (awaiting payment)
+    "checkout_url": string,   // Paddle payment URL — share with user
+    "message": string         // Human-readable next step
+  }
+
+Examples:
+  - Use when: User says "start closed testing for my app"
+  - Use when: User provides a package name and wants to begin testing
+  - Don't use when: An active order already exists for the same package (check with linktest_status)
+
+Error Handling:
+  - 409 Conflict: An order for this package may already exist — check with linktest_status`,
+    inputSchema: z.object({
+        package_name: z.string()
+            .min(3)
+            .regex(/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/, "Must be a valid Android package name")
+            .describe("Android package name (e.g., com.example.myapp)"),
+        opt_in_link: z.string()
+            .url("Must be a valid URL")
+            .describe("Google Play closed testing opt-in URL (from Google Play Console → Testing → Closed Testing)"),
+    }).strict(),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async (params) => {
+    try {
+        // Step 1: Create order
+        const order = await apiRequest("POST", "/api/orders", { packageName: params.package_name, optInLink: params.opt_in_link });
+        // Step 2: Create checkout session
+        const checkout = await apiRequest("POST", "/api/payment/checkout", { orderId: order.orderId });
+        const result = {
+            order_id: order.orderId,
+            status: "pending",
+            checkout_url: checkout.checkoutUrl,
+            message: "Order created! Complete the $5 payment to start testing.",
+        };
+        return {
+            content: [{
+                    type: "text",
+                    text: `## Order Created ✅\n\n` +
+                        `**Order ID**: ${result.order_id}\n` +
+                        `**Package**: ${params.package_name}\n` +
+                        `**Status**: Pending Payment\n\n` +
+                        `💳 **Payment required**: ${checkout.checkoutUrl}\n\n` +
+                        `After payment, testing begins automatically on 12+ real Android devices.\n` +
+                        `Check progress with: linktest_status(order_id="${result.order_id}")`,
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: handleError(error) }] };
+    }
+});
+// ─── Tool: linktest_status ────────────────────────────────────────────────────
+server.registerTool("linktest_status", {
+    title: "Check Order Status",
+    description: `Check the status of one or all LinkTest orders.
+
+If order_id is provided, returns detailed info about that specific order.
+If omitted, returns a summary list of all orders.
+
+Args:
+  - order_id (string, optional): Specific order ID to look up. If omitted, lists all orders.
+
+Returns (with order_id):
+  Detailed order info including:
+  - Package name, status, days remaining
+  - Number of devices installed (out of 20)
+  - Start date, expiry date
+  - Opt-in link
+
+Returns (without order_id):
+  List of all orders with:
+  - Order ID, package name, status, days left, device count
+
+Status values:
+  - pending: Awaiting payment
+  - active: Testing in progress on devices
+  - completed: Test period finished
+  - expired: Expired without completing
+  - payment_failed: Payment was not completed
+  - failed: Tester emails not registered — devices could not install the app
+
+Examples:
+  - Use when: "How's my testing going?"
+  - Use when: "Check status for com.example.app"
+  - Use when: "Show all my orders"`,
+    inputSchema: z.object({
+        order_id: z.string()
+            .optional()
+            .describe("Specific order ID to look up. Omit to list all orders."),
+    }).strict(),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (params) => {
+    try {
+        if (params.order_id) {
+            // Single order
+            const data = await apiRequest("GET", `/api/orders/${params.order_id}`);
+            const order = data.order;
+            const status = String(order.status);
+            let text = `## Order Status\n\n${formatOrder(order)}`;
+            if (status === "active") {
+                const installed = Number(order.installedCount ?? 0);
+                const pct = Math.round((installed / 20) * 100);
+                const bar = "█".repeat(Math.floor(pct / 5)) + "░".repeat(20 - Math.floor(pct / 5));
+                text += `\n\n**Install Progress**: [${bar}] ${pct}%`;
+            }
+            if (status === "pending") {
+                text += `\n\n⚠️ Payment is required to start testing. Use the checkout URL from your order.`;
+            }
+            if (status === "failed") {
+                text += `\n\n❌ **Testing failed**: Our devices could not access your app.\n` +
+                    `Please check that all LinkTest tester emails are registered in your Google Play Console:\n` +
+                    `Play Console → Testing → Closed Testing → Testers → Add LinkTest email list\n\n` +
+                    `After fixing, create a new order with linktest_order.`;
+            }
+            if (status === "active" && Number(order.daysLeft) <= 2) {
+                text += `\n\n⚠️ Testing ends soon! Only ${order.daysLeft} days remaining.`;
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        else {
+            // All orders
+            const data = await apiRequest("GET", "/api/orders");
+            const orders = data.orders ?? [];
+            if (orders.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "No orders yet.\n\nStart your first test with linktest_order.",
+                        }],
+                };
+            }
+            const lines = [`## My LinkTest Orders (${orders.length} total)\n`];
+            for (const order of orders) {
+                const status = STATUS_LABELS[String(order.status)] ?? String(order.status);
+                lines.push(`### ${order.packageName}`);
+                lines.push(`- **Status**: ${status}`);
+                lines.push(`- **ID**: ${order.id}`);
+                if (order.status === "active") {
+                    lines.push(`- **Devices**: ${order.installedCount} · ${order.daysLeft} days left`);
+                }
+                lines.push("");
+            }
+            const result = lines.join("\n");
+            return {
+                content: [{
+                        type: "text",
+                        text: result.length > CHARACTER_LIMIT
+                            ? result.slice(0, CHARACTER_LIMIT) + "\n\n[Response truncated. Use order_id to get details for a specific order.]"
+                            : result,
+                    }],
+            };
+        }
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: handleError(error) }] };
+    }
+});
+// ─── Tool: linktest_screenshots ───────────────────────────────────────────────
+server.registerTool("linktest_screenshots", {
+    title: "Get Order Screenshots",
+    description: `Retrieve screenshot URLs taken by LinkTest devices for an order.
+
+Screenshots are captured daily from each Android device running the app.
+Returns a list of URLs that can be opened in a browser to verify the app is running correctly.
+
+Args:
+  - order_id (string): The order ID to get screenshots for
+
+Returns:
+  List of screenshots with:
+  - device_id: Which device took the screenshot
+  - url: Direct URL to the screenshot image
+  - taken_at: When the screenshot was captured
+
+Note: Screenshots are only available for active or completed orders.
+Pending or expired orders will have no screenshots.
+
+Examples:
+  - Use when: "Show me screenshots from my test"
+  - Use when: "Is my app running correctly on the devices?"`,
+    inputSchema: z.object({
+        order_id: z.string()
+            .min(1, "Order ID is required")
+            .describe("The order ID to fetch screenshots for"),
+    }).strict(),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (params) => {
+    try {
+        const data = await apiRequest("GET", `/api/orders/${params.order_id}/screenshots`);
+        const screenshots = data.screenshots ?? [];
+        if (screenshots.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "No screenshots yet for this order.\n\nScreenshots appear after the first daily run (within 24 hours of payment).",
+                    }],
+            };
+        }
+        const lines = [
+            `## Screenshots for Order ${params.order_id}`,
+            `${screenshots.length} screenshot(s) found\n`,
+        ];
+        for (const ss of screenshots) {
+            const date = new Date(ss.takenAt).toLocaleString("en-US", {
+                month: "short", day: "numeric", hour: "2-digit", minute: "2-digit",
+            });
+            lines.push(`**Device ${ss.deviceId}** — ${date}`);
+            lines.push(ss.url);
+            lines.push("");
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: handleError(error) }] };
+    }
+});
+// ─── Tool: linktest_cancel ────────────────────────────────────────────────────
+server.registerTool("linktest_cancel", {
+    title: "Cancel or Complete an Order",
+    description: `Cancel a pending order or mark a completed order as done.
+
+Only orders in 'pending' or 'payment_failed' status can be cancelled.
+Active testing orders cannot be cancelled (testing continues until the period ends).
+
+Args:
+  - order_id (string): The order ID to cancel
+
+Returns:
+  Confirmation message or error if the order cannot be cancelled.
+
+When to use:
+  - User placed an order by mistake and hasn't paid yet
+  - User wants to clean up a failed payment order
+  - User wants to manually mark an order as completed
+
+When NOT to use:
+  - Order is 'active' — testing is already running, cannot stop it
+  - Order is already 'completed' or 'expired'`,
+    inputSchema: z.object({
+        order_id: z.string()
+            .min(1, "Order ID is required")
+            .describe("The order ID to cancel"),
+    }).strict(),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async (params) => {
+    try {
+        await apiRequest("DELETE", `/api/orders/${params.order_id}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: `✅ Order ${params.order_id} has been cancelled successfully.`,
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: handleError(error) }] };
+    }
+});
+// ─── Tool: linktest_billing ───────────────────────────────────────────────────
+server.registerTool("linktest_billing", {
+    title: "Get Billing History",
+    description: `View payment history and get receipt details.
+
+Returns a list of all payments made, including amounts, dates, and order associations.
+Optionally provide a payment_id to get a specific receipt.
+
+Args:
+  - payment_id (string, optional): Specific payment ID for receipt details. Omit for full history.
+
+Returns (without payment_id):
+  {
+    "total_spent": string,       // Total amount spent (formatted, e.g. "$15.00")
+    "total_orders": number,      // Number of completed payments
+    "payments": [
+      {
+        "id": string,            // Payment ID
+        "order_id": string,      // Associated order
+        "amount": string,        // Formatted amount (e.g. "$5.00")
+        "date": string,          // Payment date
+        "status": string         // "completed" or "failed"
+      }
+    ]
+  }
+
+Returns (with payment_id):
+  Detailed receipt info including transaction ID for tax/accounting purposes.
+
+Examples:
+  - Use when: "How much have I spent on LinkTest?"
+  - Use when: "Show me my payment history"
+  - Use when: "Get a receipt for my last payment"`,
+    inputSchema: z.object({
+        payment_id: z.string()
+            .optional()
+            .describe("Specific payment ID for receipt lookup. Omit to get full billing history."),
+    }).strict(),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async (params) => {
+    try {
+        if (params.payment_id) {
+            const data = await apiRequest("GET", `/api/billing/${params.payment_id}`);
+            const receipt = data.receipt ?? data;
+            const r = receipt;
+            const lines = [
+                `## Receipt`,
+                `**Payment ID**: ${r.paymentId ?? params.payment_id}`,
+                `**Amount**: $${Number(r.amount ?? 0).toFixed(2)} ${r.currency ?? "USD"}`,
+                `**Date**: ${formatDate(String(r.createdAt ?? ""))}`,
+                `**Status**: ${r.status}`,
+            ];
+            if (r.orderId)
+                lines.push(`**Order ID**: ${r.orderId}`);
+            if (r.paddleTransactionId)
+                lines.push(`**Transaction ID**: ${r.paddleTransactionId}`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        else {
+            const data = await apiRequest("GET", "/api/billing");
+            const payments = data.payments ?? [];
+            const completed = payments.filter(p => p.status === "completed");
+            const totalSpent = completed.reduce((sum, p) => sum + p.amount, 0);
+            if (payments.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "No payment history yet.\n\nPlace an order with linktest_order to get started.",
+                        }],
+                };
+            }
+            const lines = [
+                `## Billing History`,
+                `**Total Spent**: $${totalSpent.toFixed(2)} · **Orders**: ${completed.length}\n`,
+            ];
+            for (const p of payments) {
+                const date = formatDate(p.createdAt);
+                const status = p.status === "completed" ? "✅" : "❌";
+                lines.push(`${status} **$${p.amount.toFixed(2)}** — ${date} (Order: ${p.orderId.slice(-8)})`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: handleError(error) }] };
+    }
+});
+// ─── Tool: linktest_testers ───────────────────────────────────────────────────
+server.registerTool("linktest_testers", {
+    title: "Get Tester Email List",
+    description: `Get the LinkTest tester email list for Google Play closed testing registration.
+
+**ALWAYS call this tool FIRST before anything else** — registering these emails
+in Google Play Console is a required prerequisite before an opt-in link even exists.
+
+The workflow is:
+  1. Call THIS TOOL → get the tester email list
+  2. User registers the emails in Play Console (see instructions below)
+  3. User deploys a closed testing release in Play Console
+  4. User sends changes ("변경사항 전송") in Play Console
+  5. ONLY THEN does the opt-in link become available
+  6. User copies opt-in link → call linktest_order
+
+If a user asks "what should I do first?" or "how do I start?" or "링크테스트 시작",
+ALWAYS call this tool first to show them the tester emails and registration steps.
+Do NOT ask for an opt-in link before confirming tester registration is complete.
+
+Returns:
+  {
+    "groupName": string,   // Name of the tester group
+    "emails": string[],    // List of tester email addresses
+    "count": number        // Total number of testers
+  }
+
+Examples:
+  - Use when: User says "링크테스트 시작해줘" or "how do I start?"
+  - Use when: "What emails do I need to add to closed testing?"
+  - Use when: User asks what the first step is
+  - Use when: Before calling linktest_order or linktest_validate`,
+    inputSchema: z.object({}).strict(),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async () => {
+    try {
+        const data = await apiRequest("GET", "/api/testers");
+        // CSV 파일 로컬에 다운로드
+        const csvResponse = await apiRequest("GET", "/api/testers/csv");
+        const csvPath = path.join(os.homedir(), "Downloads", "linktest-testers.csv");
+        fs.writeFileSync(csvPath, typeof csvResponse === "string" ? csvResponse : data.emails.join("\n"));
+        const lines = [
+            `## LinkTest 테스터 그룹: ${data.groupName}`,
+            `총 ${data.count}개 계정\n`,
+            `---`,
+            `### 방법 1: AI가 자동 등록 (권장)`,
+            `Google Play Developer API를 사용해 AI가 직접 테스터를 등록합니다.`,
+            ``,
+            `**사전 설정 (한 번만):**`,
+            `1. [Google Cloud Console](https://console.cloud.google.com) → 프로젝트 생성`,
+            `2. "API 및 서비스" → "Google Play Android Developer API" 활성화`,
+            `3. "IAM → 서비스 계정" → 서비스 계정 생성 → JSON 키 다운로드`,
+            `4. [Play Console](https://play.google.com/console) → "Users and permissions" → "Invite new users"`,
+            `5. 서비스 계정 이메일(JSON의 client_email) 입력 → "Release apps to testing tracks" 권한 부여`,
+            `6. JSON 키 내용을 AI에게 전달하면 자동 등록 완료`,
+            ``,
+            `---`,
+            `### 방법 2: CSV 파일로 직접 등록`,
+            `아래 CSV 파일을 다운로드 후 Play Console에 업로드하세요.`,
+            ``,
+            `**📥 CSV 다운로드 완료:** ${csvPath}`,
+            ``,
+            `**처음 등록 시:**`,
+            `1. Play Console → 앱 선택`,
+            `2. 테스트 → 비공개 테스트 → 트랙 관리`,
+            `3. "테스터" 탭 → "이메일 목록 만들기"`,
+            `4. "CSV 파일 업로드" → 다운로드한 파일 선택 → 목록 이름: "LinkTest"`,
+            `5. 게시 개요 탭에서 "변경사항 전송"`,
+            ``,
+            `**이후 다른 앱 등록 시 (CSV 재업로드 불필요):**`,
+            `1. Play Console → 새 앱 선택`,
+            `2. 테스트 → 비공개 테스트 → 트랙 관리 → "테스터" 탭`,
+            `3. 기존 "LinkTest" 목록 체크 → 변경사항 전송`,
+            ``,
+            `---`,
+            `### 테스터 이메일 목록`,
+        ];
+        data.emails.forEach((email, i) => {
+            lines.push(`${i + 1}. ${email}`);
+        });
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: handleError(error) }] };
+    }
+});
+// ─── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+    if (!process.env.LINKTEST_API_TOKEN) {
+        console.error("ERROR: LINKTEST_API_TOKEN environment variable is required.");
+        console.error("Get your token at https://linktest.dev/settings");
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("LinkTest MCP server running via stdio");
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map