@getly/mcp 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# @getly/mcp
+
+MCP server that lets Claude, Cursor, Windsurf and any other [Model Context Protocol](https://modelcontextprotocol.io) client run your [Getly](https://www.getly.store) digital-products store: create and publish products, upload files, write blog posts, mint coupons and instant checkout links, inspect licenses and sales — all from chat.
+
+```bash
+npx @getly/mcp init   # guided setup for Claude Code / Cursor / Claude Desktop / Windsurf
+```
+
+## Prerequisites
+
+1. A Getly account with a store (free): https://www.getly.store/sell
+2. An API key: https://www.getly.store/dashboard/developer/keys — grant **only the scopes you need** (see [Security](#security)).
+
+The key is read from the `GETLY_API_KEY` environment variable — the server never accepts keys as tool arguments and never prints them.
+
+## Install & configure
+
+### Claude Code
+
+```bash
+claude mcp add getly --env GETLY_API_KEY=YOUR_GETLY_API_KEY -- npx -y @getly/mcp
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "getly": {
+      "command": "npx",
+      "args": ["-y", "@getly/mcp"],
+      "env": { "GETLY_API_KEY": "YOUR_GETLY_API_KEY" }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Same JSON as Cursor, in:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+
+Same JSON as Cursor.
+
+### Smithery
+
+The repo ships a root `smithery.yaml`; the hosted config asks for `getlyApiKey` and maps it to `GETLY_API_KEY`.
+
+> `npx @getly/mcp init` detects installed clients and offers to write these files for you (merging safely with existing config). `init --print` only prints the snippets.
+
+## Tools (18)
+
+| Tool | What it does | Hints / gates |
+|---|---|---|
+| `list_products` | List store products (cursor-paginated, filters) | read-only |
+| `get_product` | Full product detail (files, images, reviews, URLs) | read-only |
+| `create_product` | Create a **draft** product (money = integer cents) | 20/day cap |
+| `update_product` | Edit name/price/description/images/tags | idempotent; cannot publish/archive |
+| `publish_product` | Make a draft publicly purchasable | **requires `confirm: true`** |
+| `archive_product` | Remove a product from sale (soft delete) | **destructive, requires `confirm: true`** |
+| `upload_product_file` | Upload a local file as the buyer download (≤2GB) | slow for large files |
+| `upload_image` | Upload a local image, returns a URL for products/posts | ≤10MB |
+| `create_blog_post` | Markdown blog post; `[product:slug]` embeds a buy card | 5/day cap |
+| `list_blog_posts` | List posts | read-only |
+| `create_coupon` | Percentage or fixed-cents discount | **50%+ requires `confirm: true`**; 30/day cap |
+| `list_coupons` | List coupons | read-only |
+| `create_checkout_link` | Instant pay link, coupon auto-applied | idempotent per (product, coupon, reference) |
+| `get_checkout_link_status` | Poll a link: open / completed / expired | read-only |
+| `list_licenses` | Issued license keys + activations | read-only |
+| `get_sales_stats` | Revenue (cents), sales, per-month breakdown, recent orders | read-only |
+| `search_categories` | Fuzzy search of the public 700+ category tree | read-only, no key needed, cached 1h |
+| `get_store` | Store profile + public URL | read-only |
+
+There is intentionally **no bulk-delete tool**, and the model is instructed to get explicit human approval before any confirm-gated call.
+
+## Security
+
+- **Least-privilege scopes.** Create separate keys per workflow:
+  - Catalog management: `read:products`, `write:products`
+  - Blogging: `read:posts`, `write:posts` (+ `write:products` for image uploads)
+  - Sales bot: `checkout:create`, `read:coupons` (+ `write:coupons` if it mints discounts)
+  - Reporting: `read:analytics`, `read:orders`, `read:store`, `read:licenses`
+- **Plaintext config warning.** MCP client config files store `GETLY_API_KEY` in plaintext on your machine. Anyone with access to those files can act on your store. Prefer per-machine keys.
+- **Rotate / revoke** any key you suspect leaked at https://www.getly.store/dashboard/developer/keys (rotation keeps the old token valid for 24h so configs don't break mid-swap).
+- The key never leaves the `Authorization` header of requests to `www.getly.store`; the server never logs or echoes it (setup output masks all but the last 4 characters).
+
+## Programmatic use
+
+```ts
+import { createGetlyMcpServer } from '@getly/mcp';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = createGetlyMcpServer();
+await server.connect(new StdioServerTransport());
+```
+
+## Development
+
+```bash
+npm -w packages/mcp run typecheck
+npm -w packages/mcp run build
+npm -w packages/mcp test        # includes a real stdio boot test
+```
+
+MIT © Getly

package/dist/api.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Minimal Getly v1 API client used by the MCP tools.
+ *
+ * Conventions (mirror of the platform contract):
+ * - Base URL https://www.getly.store (override with GETLY_BASE_URL for tests).
+ * - Auth: `Authorization: Bearer <key>` — the key comes ONLY from the
+ *   GETLY_API_KEY environment variable, never from tool arguments, and is
+ *   never logged or echoed back.
+ * - Responses: `{ success: true, data }` / `{ success: false, error, errorDetail }`
+ *   where errorDetail = { code, message, hint, docsUrl, param? }.
+ * - Money: integer cents only (priceCents / discountedPriceCents / valueCents).
+ * - Cursor pagination: { items, nextCursor }.
+ * - POST creates send an auto-generated Idempotency-Key.
+ */
+import { Getly } from '@getly/sdk';
+export declare const DEFAULT_BASE_URL = "https://www.getly.store";
+export declare function getBaseUrl(): string;
+/** Read the API key from the environment. Returns null when not configured. */
+export declare function getApiKey(): string | null;
+/**
+ * Build a @getly/sdk client for the multi-step flows the SDK already solves
+ * (presign → PUT → attach uploads). Constructed per call so env changes and
+ * test fetch stubs are always picked up.
+ */
+export declare function getClient(): Getly;
+export interface ErrorDetail {
+    code: string;
+    message: string;
+    hint?: string;
+    docsUrl?: string;
+    param?: string;
+}
+export interface PublishReason {
+    code: string;
+    detail: string;
+}
+/** Error thrown for any non-success Getly API response. Never contains the key. */
+export declare class GetlyApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly hint?: string;
+    readonly docsUrl?: string;
+    readonly param?: string;
+    readonly retryAfterSeconds?: number;
+    /** Machine-readable publish blockers (422 not_publishable). */
+    readonly reasons?: PublishReason[];
+    constructor(status: number, detail: ErrorDetail, opts?: {
+        retryAfterSeconds?: number;
+        reasons?: PublishReason[];
+    });
+}
+export interface ApiEnvelope<T = unknown> {
+    success: true;
+    data: T;
+    /** Extra top-level keys some endpoints add (warnings, total, page, ...). */
+    [key: string]: unknown;
+}
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    /** Auto-attach a random Idempotency-Key (use on POST creates). */
+    idempotent?: boolean;
+    /** Override: allow unauthenticated calls (public endpoints). */
+    apiKey?: string | null;
+    timeoutMs?: number;
+}
+/**
+ * Perform a JSON request against the Getly API and return the full success
+ * envelope. Throws GetlyApiError on { success: false } or non-2xx.
+ */
+export declare function apiRequest<T = unknown>(path: string, opts?: RequestOptions): Promise<ApiEnvelope<T>>;

package/dist/api.js

@@ -0,0 +1,109 @@
+/**
+ * Minimal Getly v1 API client used by the MCP tools.
+ *
+ * Conventions (mirror of the platform contract):
+ * - Base URL https://www.getly.store (override with GETLY_BASE_URL for tests).
+ * - Auth: `Authorization: Bearer <key>` — the key comes ONLY from the
+ *   GETLY_API_KEY environment variable, never from tool arguments, and is
+ *   never logged or echoed back.
+ * - Responses: `{ success: true, data }` / `{ success: false, error, errorDetail }`
+ *   where errorDetail = { code, message, hint, docsUrl, param? }.
+ * - Money: integer cents only (priceCents / discountedPriceCents / valueCents).
+ * - Cursor pagination: { items, nextCursor }.
+ * - POST creates send an auto-generated Idempotency-Key.
+ */
+import { Getly } from '@getly/sdk';
+export const DEFAULT_BASE_URL = 'https://www.getly.store';
+export function getBaseUrl() {
+    const raw = process.env.GETLY_BASE_URL;
+    return raw && raw.trim() ? raw.trim().replace(/\/+$/, '') : DEFAULT_BASE_URL;
+}
+/** Read the API key from the environment. Returns null when not configured. */
+export function getApiKey() {
+    const key = process.env.GETLY_API_KEY;
+    return key && key.trim() ? key.trim() : null;
+}
+/**
+ * Build a @getly/sdk client for the multi-step flows the SDK already solves
+ * (presign → PUT → attach uploads). Constructed per call so env changes and
+ * test fetch stubs are always picked up.
+ */
+export function getClient() {
+    return new Getly({ baseUrl: getBaseUrl() });
+}
+/** Error thrown for any non-success Getly API response. Never contains the key. */
+export class GetlyApiError extends Error {
+    status;
+    code;
+    hint;
+    docsUrl;
+    param;
+    retryAfterSeconds;
+    /** Machine-readable publish blockers (422 not_publishable). */
+    reasons;
+    constructor(status, detail, opts = {}) {
+        super(detail.message);
+        this.name = 'GetlyApiError';
+        this.status = status;
+        this.code = detail.code;
+        this.hint = detail.hint;
+        this.docsUrl = detail.docsUrl;
+        this.param = detail.param;
+        this.retryAfterSeconds = opts.retryAfterSeconds;
+        this.reasons = opts.reasons;
+    }
+}
+/**
+ * Perform a JSON request against the Getly API and return the full success
+ * envelope. Throws GetlyApiError on { success: false } or non-2xx.
+ */
+export async function apiRequest(path, opts = {}) {
+    const url = new URL(path, getBaseUrl() + '/');
+    if (opts.query) {
+        for (const [k, v] of Object.entries(opts.query)) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+    }
+    const headers = { Accept: 'application/json' };
+    const key = opts.apiKey === undefined ? getApiKey() : opts.apiKey;
+    if (key)
+        headers['Authorization'] = `Bearer ${key}`;
+    if (opts.body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    if (opts.idempotent)
+        headers['Idempotency-Key'] = crypto.randomUUID();
+    let res;
+    try {
+        res = await fetch(url, {
+            method: opts.method ?? 'GET',
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 60_000),
+        });
+    }
+    catch (err) {
+        throw new GetlyApiError(0, {
+            code: 'network_error',
+            message: `Could not reach ${url.host}: ${err instanceof Error ? err.message : String(err)}`,
+            hint: 'Check the network connection, then retry the same call.',
+        });
+    }
+    const json = (await res.json().catch(() => null));
+    if (!res.ok || !json || json.success !== true) {
+        const detail = (json?.errorDetail ?? {});
+        const retryAfterRaw = res.headers.get('retry-after');
+        throw new GetlyApiError(res.status, {
+            code: detail.code ?? (res.status === 429 ? 'rate_limited' : 'api_error'),
+            message: detail.message ??
+                (typeof json?.error === 'string' ? json.error : `Request failed with HTTP ${res.status}`),
+            hint: detail.hint,
+            docsUrl: detail.docsUrl,
+            param: detail.param,
+        }, {
+            retryAfterSeconds: retryAfterRaw ? Number(retryAfterRaw) || undefined : undefined,
+            reasons: Array.isArray(json?.reasons) ? json.reasons : undefined,
+        });
+    }
+    return json;
+}

package/dist/categories.d.ts

@@ -0,0 +1,19 @@
+export interface FlatCategory {
+    id: string;
+    name: string;
+    slug: string;
+    /** Human-readable ancestry, e.g. "Graphics & Design > Icons". */
+    path: string;
+}
+/** Test hook: clear the in-process cache. */
+export declare function _resetCategoryCache(): void;
+/**
+ * Fuzzy score for a category against a query. 0 = no match.
+ * Ordering: exact name > name prefix > name substring > all query tokens
+ * somewhere in the path > character subsequence of the name.
+ */
+export declare function fuzzyScore(query: string, cat: FlatCategory): number;
+/** Search the category tree. Returns the best `limit` matches, scored. */
+export declare function searchCategories(query: string, limit?: number): Promise<Array<FlatCategory & {
+    score: number;
+}>>;

package/dist/categories.js

@@ -0,0 +1,86 @@
+/**
+ * Category search: fetches the PUBLIC category tree from
+ * GET /api/categories (no auth), flattens it (3 levels), fuzzy-filters
+ * locally, and caches the tree in-process for 1 hour.
+ *
+ * Endpoint shape (ground truth: src/app/api/categories/route.ts):
+ *   { success: true, data: [{ id, name, slug, parentId, icon?, children: [
+ *       { id, name, slug, parentId, children: [...] } ] }] }
+ */
+import { getBaseUrl, GetlyApiError } from './api.js';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+let cache = null;
+/** Test hook: clear the in-process cache. */
+export function _resetCategoryCache() {
+    cache = null;
+}
+function flatten(nodes, prefix, out) {
+    for (const node of nodes) {
+        const path = prefix ? `${prefix} > ${node.name}` : node.name;
+        out.push({ id: node.id, name: node.name, slug: node.slug, path });
+        if (Array.isArray(node.children) && node.children.length > 0) {
+            flatten(node.children, path, out);
+        }
+    }
+}
+async function loadCategories() {
+    if (cache && Date.now() - cache.fetchedAt < CACHE_TTL_MS)
+        return cache.flat;
+    const res = await fetch(`${getBaseUrl()}/api/categories`, {
+        headers: { Accept: 'application/json' },
+        signal: AbortSignal.timeout(30_000),
+    });
+    const json = (await res.json().catch(() => null));
+    if (!res.ok || !json?.success || !Array.isArray(json.data)) {
+        throw new GetlyApiError(res.status, {
+            code: 'api_error',
+            message: 'Failed to load the Getly category tree',
+            hint: 'Retry in a few seconds; the endpoint is public and cached.',
+        });
+    }
+    const flat = [];
+    flatten(json.data, '', flat);
+    cache = { fetchedAt: Date.now(), flat };
+    return flat;
+}
+/**
+ * Fuzzy score for a category against a query. 0 = no match.
+ * Ordering: exact name > name prefix > name substring > all query tokens
+ * somewhere in the path > character subsequence of the name.
+ */
+export function fuzzyScore(query, cat) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return 0;
+    const name = cat.name.toLowerCase();
+    const path = cat.path.toLowerCase();
+    const slug = cat.slug.toLowerCase();
+    if (name === q || slug === q)
+        return 100;
+    if (name.startsWith(q))
+        return 80;
+    if (name.includes(q) || slug.includes(q))
+        return 60;
+    const tokens = q.split(/[\s/,&>-]+/).filter(Boolean);
+    if (tokens.length > 0 && tokens.every((t) => path.includes(t)))
+        return 40;
+    // Character subsequence over the name (e.g. "grph dsgn" ~ "graphics design").
+    let i = 0;
+    const compact = q.replace(/\s+/g, '');
+    for (const ch of name) {
+        if (ch === compact[i])
+            i++;
+        if (i === compact.length)
+            return 20;
+    }
+    return 0;
+}
+/** Search the category tree. Returns the best `limit` matches, scored. */
+export async function searchCategories(query, limit = 10) {
+    const flat = await loadCategories();
+    return flat
+        .map((cat) => ({ ...cat, score: fuzzyScore(query, cat) }))
+        .filter((c) => c.score > 0)
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+        .slice(0, Math.min(Math.max(limit, 1), 50));
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * getly-mcp CLI:
+ *   getly-mcp             → start the stdio MCP server
+ *   getly-mcp init        → interactive client setup (Cursor/Claude/Windsurf)
+ *   getly-mcp init --print → print all config snippets, write nothing
+ */
+import { runInit } from './init.js';
+import { startStdioServer } from './server.js';
+const command = process.argv[2];
+if (command === 'init') {
+    await runInit(process.argv.slice(3));
+}
+else if (command === '--help' || command === '-h' || command === 'help') {
+    process.stderr.write([
+        'Usage: getly-mcp [command]',
+        '',
+        '  (no command)   start the MCP server on stdio',
+        '  init           set up Claude Code / Cursor / Claude Desktop / Windsurf',
+        '  init --print   print config snippets without writing any files',
+        '',
+        'The Getly API key is read from the GETLY_API_KEY environment variable.',
+        'Create one: https://www.getly.store/dashboard/developer/keys',
+        '',
+    ].join('\n'));
+}
+else {
+    await startStdioServer();
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createGetlyMcpServer, startStdioServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+export { TOOLS, TOOL_NAMES, MISSING_KEY_MESSAGE } from './tools.js';
+export type { GetlyTool, ToolResult, ToolAnnotations } from './tools.js';
+export { GetlyApiError, getBaseUrl, DEFAULT_BASE_URL } from './api.js';
+export { searchCategories } from './categories.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createGetlyMcpServer, startStdioServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+export { TOOLS, TOOL_NAMES, MISSING_KEY_MESSAGE } from './tools.js';
+export { GetlyApiError, getBaseUrl, DEFAULT_BASE_URL } from './api.js';
+export { searchCategories } from './categories.js';

package/dist/init.d.ts

@@ -0,0 +1,9 @@
+/** Mask a secret: everything but the last 4 chars. Never returns the input. */
+export declare function maskKey(key: string): string;
+/**
+ * Merge the getly server into an existing MCP JSON config string.
+ * Returns the new JSON, or null when the existing file is not valid JSON
+ * (we refuse to clobber a file we cannot parse).
+ */
+export declare function mergeMcpConfig(existing: string | null, apiKey: string | null): string | null;
+export declare function runInit(argv: string[]): Promise<void>;

package/dist/init.js

@@ -0,0 +1,133 @@
+/**
+ * `npx @getly/mcp init` — interactive-lite setup for MCP clients.
+ *
+ * Detects Claude Code, Cursor, Claude Desktop and Windsurf; prints the
+ * copy-paste snippet for each and (for JSON-config clients) offers to write
+ * the config, merging existing JSON safely. `--print` only prints, never
+ * writes. The API key is NEVER echoed in full — masked to the last 4 chars.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+const KEY_URL = 'https://www.getly.store/dashboard/developer/keys';
+const PLACEHOLDER = 'YOUR_GETLY_API_KEY';
+/** Mask a secret: everything but the last 4 chars. Never returns the input. */
+export function maskKey(key) {
+    if (key.length <= 4)
+        return '****';
+    return `${'*'.repeat(Math.min(key.length - 4, 20))}${key.slice(-4)}`;
+}
+function jsonClients() {
+    const home = homedir();
+    const claudeDesktopDir = platform() === 'darwin'
+        ? join(home, 'Library', 'Application Support', 'Claude')
+        : platform() === 'win32'
+            ? join(process.env.APPDATA || join(home, 'AppData', 'Roaming'), 'Claude')
+            : join(home, '.config', 'Claude');
+    return [
+        {
+            name: 'Cursor',
+            configPath: join(home, '.cursor', 'mcp.json'),
+            detectPath: join(home, '.cursor'),
+            serversKey: 'mcpServers',
+        },
+        {
+            name: 'Claude Desktop',
+            configPath: join(claudeDesktopDir, 'claude_desktop_config.json'),
+            detectPath: claudeDesktopDir,
+            serversKey: 'mcpServers',
+        },
+        {
+            name: 'Windsurf',
+            configPath: join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+            detectPath: join(home, '.codeium', 'windsurf'),
+            serversKey: 'mcpServers',
+        },
+    ];
+}
+function serverEntry(key) {
+    return {
+        command: 'npx',
+        args: ['-y', '@getly/mcp'],
+        env: { GETLY_API_KEY: key ?? PLACEHOLDER },
+    };
+}
+/**
+ * Merge the getly server into an existing MCP JSON config string.
+ * Returns the new JSON, or null when the existing file is not valid JSON
+ * (we refuse to clobber a file we cannot parse).
+ */
+export function mergeMcpConfig(existing, apiKey) {
+    let config = {};
+    if (existing !== null && existing.trim() !== '') {
+        try {
+            const parsed = JSON.parse(existing);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return null;
+            config = parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    const servers = config.mcpServers && typeof config.mcpServers === 'object' && !Array.isArray(config.mcpServers)
+        ? config.mcpServers
+        : {};
+    servers.getly = serverEntry(apiKey);
+    config.mcpServers = servers;
+    return JSON.stringify(config, null, 2) + '\n';
+}
+function snippetJson(apiKey) {
+    return JSON.stringify({ mcpServers: { getly: serverEntry(apiKey ? maskKey(apiKey) : null) } }, null, 2);
+}
+const log = (s = '') => process.stderr.write(s + '\n');
+export async function runInit(argv) {
+    const printOnly = argv.includes('--print');
+    const apiKey = process.env.GETLY_API_KEY?.trim() || null;
+    log('Getly MCP setup');
+    log('===============');
+    if (apiKey) {
+        log(`Found GETLY_API_KEY in the environment (${maskKey(apiKey)}) — configs will use it.`);
+    }
+    else {
+        log(`No GETLY_API_KEY set. Create a key at ${KEY_URL} (grant only the scopes you need),`);
+        log(`then re-run with the env var set, or replace ${PLACEHOLDER} in the snippets below.`);
+    }
+    log();
+    // Claude Code: one command, no file writing needed.
+    log('Claude Code — run this in your terminal:');
+    log(`  claude mcp add getly --env GETLY_API_KEY=${apiKey ? '<your key>' : PLACEHOLDER} -- npx -y @getly/mcp`);
+    if (apiKey)
+        log('  (substitute <your key> yourself — this tool never prints the full key)');
+    log();
+    const clients = jsonClients();
+    const rl = printOnly ? null : createInterface({ input: process.stdin, output: process.stderr });
+    for (const client of clients) {
+        const detected = existsSync(client.detectPath);
+        log(`${client.name}${detected ? ' (detected)' : ''} — ${client.configPath}:`);
+        log(snippetJson(apiKey));
+        log();
+        if (printOnly || !detected || !rl)
+            continue;
+        const answer = (await rl.question(`Write this to ${client.configPath}? [y/N] `)).trim().toLowerCase();
+        if (answer !== 'y' && answer !== 'yes')
+            continue;
+        const existing = existsSync(client.configPath)
+            ? await readFile(client.configPath, 'utf8')
+            : null;
+        const merged = mergeMcpConfig(existing, apiKey);
+        if (merged === null) {
+            log(`  SKIPPED: ${client.configPath} exists but is not valid JSON — fix it manually, nothing was overwritten.`);
+            continue;
+        }
+        await mkdir(dirname(client.configPath), { recursive: true });
+        await writeFile(client.configPath, merged, 'utf8');
+        log(`  Wrote ${client.configPath}${apiKey ? ` (key ${maskKey(apiKey)})` : ` — replace ${PLACEHOLDER} with your key`}. Restart ${client.name} to load it.`);
+    }
+    rl?.close();
+    log('Security notes:');
+    log('- These config files store the key in PLAINTEXT on this machine. Anyone with file access can read it.');
+    log(`- Grant least-privilege scopes per workflow, and rotate/revoke keys at ${KEY_URL}.`);
+}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Getly MCP server — stdio transport, programmatic export.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const SERVER_NAME = "getly";
+export declare const SERVER_VERSION = "0.1.0";
+/** Build a configured McpServer with all Getly tools registered. */
+export declare function createGetlyMcpServer(): McpServer;
+/** Start the server on stdio (used by the CLI). Never writes to stdout. */
+export declare function startStdioServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,33 @@
+/**
+ * Getly MCP server — stdio transport, programmatic export.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { TOOLS } from './tools.js';
+export const SERVER_NAME = 'getly';
+export const SERVER_VERSION = '0.1.0';
+const INSTRUCTIONS = [
+    'Run the user\'s Getly digital-products store: products, blog posts, coupons, checkout links, license keys, sales stats.',
+    'Money is ALWAYS integer cents (priceCents, valueCents).',
+    'Destructive or revenue-affecting tools (publish_product, archive_product, create_coupon at 50%+ discount) require confirm: true — always ask the human user before setting it.',
+    'The API key is read from the GETLY_API_KEY environment variable only. Never ask the user to paste a key into chat; point them to `npx @getly/mcp init`.',
+].join('\n');
+/** Build a configured McpServer with all Getly tools registered. */
+export function createGetlyMcpServer() {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions: INSTRUCTIONS });
+    for (const tool of TOOLS) {
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: { title: tool.annotations.title, ...tool.annotations },
+        }, (async (args) => tool.handler(args ?? {})));
+    }
+    return server;
+}
+/** Start the server on stdio (used by the CLI). Never writes to stdout. */
+export async function startStdioServer() {
+    const server = createGetlyMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[getly-mcp] server ready (${TOOLS.length} tools). Key configured: ${process.env.GETLY_API_KEY ? 'yes' : 'NO — tools will return setup instructions'}`);
+}

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+import { type ZodRawShape } from 'zod';
+export interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export interface GetlyTool {
+    name: string;
+    description: string;
+    annotations: ToolAnnotations;
+    inputSchema: ZodRawShape;
+    /** Whether the tool needs GETLY_API_KEY (search_categories is public). */
+    requiresAuth: boolean;
+    handler: (args: Record<string, unknown>) => Promise<ToolResult>;
+}
+export declare const MISSING_KEY_MESSAGE: string;
+export declare const TOOLS: GetlyTool[];
+export declare const TOOL_NAMES: string[];