@echomate/mcp-server 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valerian Huber
+
+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

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @echomate/mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for [echomate](https://echomate.shop) — the AI-powered Shopify app for QR codes, dynamic links, analytics, store health, and link-in-bio.
+
+**20 tools** for full zero-click store management via Claude, ChatGPT, or any MCP client.
+
+## Quick Start
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "echomate": {
+      "command": "npx",
+      "args": ["-y", "@echomate/mcp-server"],
+      "env": {
+        "ECHOMATE_API_KEY": "em_live_your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Claude.ai (Remote MCP)
+
+URL: `https://api.echomate.shop/mcp`
+Auth: API Key header `X-API-Key: em_live_...`
+
+## Getting Your API Key
+
+1. Open echomate in your Shopify admin
+2. Go to **Settings** > **API Key**
+3. Click **Generate API Key**
+4. Copy the key (shown only once!)
+
+Which plan includes API access is shown in the plan comparison inside echomate — prices are not repeated here, they change.
+
+## Tools
+
+Your MCP client lists every tool with what it does and its parameters. An AI gets
+the same list, together with the usage rules, by calling `get_setup_guide`.
+
+## Example Prompts
+
+> "Show me my top performing QR codes this month"
+
+> "Create 5 QR codes for my products with UTM tracking"
+
+> "How fast is my store? What apps are slowing it down?"
+
+> "Set up my Link-in-Bio page with my top 5 links"
+
+## License
+
+MIT, see [LICENSE](./LICENSE). Using the echomate API requires an echomate plan that includes API access.
+
+Contributions are accepted under the same MIT license (inbound = outbound), with a DCO sign-off (`git commit -s`).
+
+To report a vulnerability, see [SECURITY.md](./SECURITY.md).

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues **privately** to **security@alpin-code.de**. Do not open a public GitHub issue.
+
+Include, if you can: the affected package and version, a description of the issue, steps to reproduce, and whether you know
+of active exploitation.
+
+We acknowledge reports within 2 business days. If a vulnerability in this package is actively exploited, we notify the
+competent authorities under Article 14 of the EU Cyber Resilience Act (Regulation (EU) 2024/2847) and inform affected users,
+including the steps they should take.
+
+## Supported versions
+
+Only the latest published version receives security fixes. Releases are published to npm by the maintainer from our own CI.
+
+## Your API key
+
+This package only sends your API key to `https://api.echomate.shop`, or to the URL you set yourself in `ECHOMATE_API_URL`. If you suspect your key was exposed, rotate it in the app
+settings immediately.

package/dist/client.d.ts

@@ -0,0 +1,83 @@
+import type { QRCode, ShortLink, PaginatedResponse, AnalyticsResponse, HealthScore, LinkDetail, TopPerformers, ShopSettings, BioConfig, ShopIdentity, ScanResult } from "./types.js";
+export declare function sanitizeForAI(text: string): string;
+export declare const ZUGANG_KOPF = "x-echomate-zugang";
+export declare const ZUGANG_MCP = "mcp";
+export declare class EchomateClient {
+    private apiKey;
+    private baseUrl;
+    private art;
+    constructor(apiKey: string, baseUrl: string, art?: "schluessel" | "bearer");
+    private request;
+    listQRCodes(page?: number, pageSize?: number): Promise<PaginatedResponse<QRCode>>;
+    createQRCode(name: string, targetUrl: string): Promise<{
+        data: QRCode;
+    }>;
+    getQRImageUrl(id: string, format?: "png" | "svg"): string;
+    getQRImageSvg(id: string): Promise<string>;
+    listLinks(page?: number, pageSize?: number): Promise<PaginatedResponse<ShortLink>>;
+    createLink(params: {
+        targetUrl: string;
+        customSlug?: string;
+        utmSource?: string;
+        utmMedium?: string;
+        utmCampaign?: string;
+    }): Promise<{
+        data: ShortLink;
+    }>;
+    getAnalytics(days?: number): Promise<AnalyticsResponse>;
+    getMe(): Promise<ShopIdentity>;
+    getQRCode(id: string): Promise<{
+        data: QRCode;
+    }>;
+    updateQRCode(id: string, input: {
+        name?: string;
+        targetUrl?: string;
+        isActive?: boolean;
+    }): Promise<{
+        data: QRCode;
+    }>;
+    deleteQRCode(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    getLinkDetails(id: string): Promise<{
+        data: LinkDetail;
+    }>;
+    updateLink(id: string, input: {
+        targetUrl?: string;
+        utmSource?: string;
+        utmMedium?: string;
+        utmCampaign?: string;
+        isActive?: boolean;
+    }): Promise<{
+        data: ShortLink;
+    }>;
+    deleteLink(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    getSettings(): Promise<{
+        data: ShopSettings;
+    }>;
+    updateSettings(input: Partial<ShopSettings>): Promise<{
+        data: ShopSettings;
+    }>;
+    getHealthScores(): Promise<{
+        data: HealthScore;
+    }>;
+    triggerHealthScan(): Promise<{
+        data: ScanResult;
+    }>;
+    getTopPerformers(days?: number): Promise<{
+        data: TopPerformers;
+    }>;
+    getBio(): Promise<{
+        data: BioConfig;
+    }>;
+    updateBio(input: Partial<BioConfig>): Promise<{
+        updated: boolean;
+    }>;
+    healthCheck(): Promise<{
+        status: "healthy" | "degraded" | "unhealthy";
+        db?: string;
+    }>;
+    getBaseUrl(): string;
+}

package/dist/client.js

@@ -0,0 +1,142 @@
+export function sanitizeForAI(text) {
+    if (!text)
+        return "";
+    return text
+        .replace(/<[^>]*>/g, "")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .slice(0, 500);
+}
+export const ZUGANG_KOPF = "x-echomate-zugang";
+export const ZUGANG_MCP = "mcp";
+export class EchomateClient {
+    apiKey;
+    baseUrl;
+    art;
+    constructor(apiKey, baseUrl, art = "schluessel") {
+        this.apiKey = apiKey;
+        this.art = art;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const internalSecret = process.env.MCP_INTERNAL_SECRET;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                "Content-Type": "application/json",
+                ...(this.art === "bearer" ? { Authorization: `Bearer ${this.apiKey}` } : { "X-API-Key": this.apiKey }),
+                ...(internalSecret ? { "X-Echomate-Internal": internalSecret } : {}),
+                ...options.headers,
+                [ZUGANG_KOPF]: ZUGANG_MCP,
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`echomate API error ${response.status}: ${body}`);
+        }
+        return response.json();
+    }
+    async listQRCodes(page = 1, pageSize = 25) {
+        return this.request(`/api/v1/qr?page=${page}&pageSize=${pageSize}`);
+    }
+    async createQRCode(name, targetUrl) {
+        return this.request("/api/v1/qr", {
+            method: "POST",
+            body: JSON.stringify({ name, targetUrl }),
+        });
+    }
+    getQRImageUrl(id, format = "svg") {
+        return `${this.baseUrl}/api/v1/qr/${id}/image?format=${format}`;
+    }
+    async getQRImageSvg(id) {
+        const internalSecret = process.env.MCP_INTERNAL_SECRET;
+        const response = await fetch(`${this.baseUrl}/api/v1/qr/${encodeURIComponent(id)}/image?format=svg&size=320`, {
+            headers: {
+                ...(this.art === "bearer" ? { Authorization: `Bearer ${this.apiKey}` } : { "X-API-Key": this.apiKey }),
+                ...(internalSecret ? { "X-Echomate-Internal": internalSecret } : {}),
+                [ZUGANG_KOPF]: ZUGANG_MCP,
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`echomate API error ${response.status}: ${body}`);
+        }
+        return response.text();
+    }
+    async listLinks(page = 1, pageSize = 25) {
+        return this.request(`/api/v1/links?page=${page}&pageSize=${pageSize}`);
+    }
+    async createLink(params) {
+        return this.request("/api/v1/links", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    async getAnalytics(days = 7) {
+        return this.request(`/api/v1/analytics?days=${days}`);
+    }
+    async getMe() {
+        return this.request("/api/v1/me");
+    }
+    async getQRCode(id) {
+        return this.request(`/api/v1/qr/${id}`);
+    }
+    async updateQRCode(id, input) {
+        return this.request(`/api/v1/qr/${id}`, {
+            method: "PATCH",
+            body: JSON.stringify(input),
+        });
+    }
+    async deleteQRCode(id) {
+        return this.request(`/api/v1/qr/${id}`, { method: "DELETE" });
+    }
+    async getLinkDetails(id) {
+        return this.request(`/api/v1/links/${id}`);
+    }
+    async updateLink(id, input) {
+        return this.request(`/api/v1/links/${id}`, {
+            method: "PATCH",
+            body: JSON.stringify(input),
+        });
+    }
+    async deleteLink(id) {
+        return this.request(`/api/v1/links/${id}`, { method: "DELETE" });
+    }
+    async getSettings() {
+        return this.request("/api/v1/settings");
+    }
+    async updateSettings(input) {
+        return this.request("/api/v1/settings", {
+            method: "PATCH",
+            body: JSON.stringify(input),
+        });
+    }
+    async getHealthScores() {
+        return this.request("/api/v1/health-scores");
+    }
+    async triggerHealthScan() {
+        return this.request("/api/v1/health-scan", { method: "POST" });
+    }
+    async getTopPerformers(days = 30) {
+        return this.request(`/api/v1/top-performers?days=${days}`);
+    }
+    async getBio() {
+        return this.request("/api/v1/spotlight");
+    }
+    async updateBio(input) {
+        return this.request("/api/v1/spotlight", {
+            method: "PATCH",
+            body: JSON.stringify(input),
+        });
+    }
+    async healthCheck() {
+        const url = `${this.baseUrl}/health`;
+        const res = await fetch(url);
+        return res.json();
+    }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/guide.d.ts

@@ -0,0 +1 @@
+export declare const ECHOMATE_GUIDE = "# echomate MCP Server \u2014 Setup Guide\n\n## What is echomate?\nechomate is a Shopify app for QR codes, dynamic links, analytics, store health monitoring, and link-in-bio pages.\n\n## Tools\nYour MCP client lists every available tool with its description \u2014 this guide\ndoes not repeat them. Some installations are read-only, and deleting is switched\noff unless ECHOMATE_MCP_ALLOW_DELETE=true is set, so the list can be shorter.\n\n## Example Workflows\n\n### \"How are my QR codes performing?\"\n1. get_analytics (days=30)\n2. get_top_performers (days=30)\n3. AI summarizes: top performers, trends, recommendations\n\n### \"Create a campaign with tracking\"\n1. create_link with UTM params (source, medium, campaign)\n2. create_qr_code pointing to the short link\n3. get_qr_image to download the QR code\n\n### \"Is my store fast enough?\"\n1. get_store_health \u2014 check current scores\n2. If score < 80: check appImpacts for slow apps\n3. trigger_health_scan \u2014 get fresh data after changes\n\n## Setup\n1. In echomate app: Settings \u2192 API Key \u2192 Generate\n2. Copy the key (shown once!)\n3. Add to your MCP client config with env var ECHOMATE_API_KEY\n";

package/dist/guide.js

@@ -0,0 +1,33 @@
+export const ECHOMATE_GUIDE = `# echomate MCP Server — Setup Guide
+
+## What is echomate?
+echomate is a Shopify app for QR codes, dynamic links, analytics, store health monitoring, and link-in-bio pages.
+
+## Tools
+Your MCP client lists every available tool with its description — this guide
+does not repeat them. Some installations are read-only, and deleting is switched
+off unless ECHOMATE_MCP_ALLOW_DELETE=true is set, so the list can be shorter.
+
+## Example Workflows
+
+### "How are my QR codes performing?"
+1. get_analytics (days=30)
+2. get_top_performers (days=30)
+3. AI summarizes: top performers, trends, recommendations
+
+### "Create a campaign with tracking"
+1. create_link with UTM params (source, medium, campaign)
+2. create_qr_code pointing to the short link
+3. get_qr_image to download the QR code
+
+### "Is my store fast enough?"
+1. get_store_health — check current scores
+2. If score < 80: check appImpacts for slow apps
+3. trigger_health_scan — get fresh data after changes
+
+## Setup
+1. In echomate app: Settings → API Key → Generate
+2. Copy the key (shown once!)
+3. Add to your MCP client config with env var ECHOMATE_API_KEY
+`;
+//# sourceMappingURL=guide.js.map

package/dist/guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.js","sourceRoot":"","sources":["../src/guide.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B7B,CAAC"}

package/dist/http-server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http-server.js

@@ -0,0 +1,115 @@
+import http from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { EchomateClient } from "./client.js";
+import { registerTools } from "./tools.js";
+import { SERVER_ANLEITUNG } from "./instructions.js";
+import { SERVER_INFO } from "./server-info.js";
+import { leseZugang, oauthAn, wwwAuthenticate } from "./zugang.js";
+const MCP_PORT = parseInt(process.env.MCP_PORT || "3847", 10);
+const ECHOMATE_API_URL = process.env.ECHOMATE_API_URL || "https://api.echomate.shop";
+const CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, X-API-Key, Authorization, Mcp-Protocol-Version, Mcp-Session-Id",
+    "Access-Control-Expose-Headers": "WWW-Authenticate, Mcp-Session-Id",
+    "Access-Control-Max-Age": "86400",
+};
+function antworte(res, status, koerper, zusatz = {}) {
+    res.writeHead(status, { ...CORS_HEADERS, "Content-Type": "application/json", ...zusatz });
+    res.end(JSON.stringify(koerper));
+}
+function anmeldungNoetig(res, koerper, fehler) {
+    const zusatz = oauthAn(process.env.MCP_OAUTH_LAEDEN)
+        ? { "WWW-Authenticate": wwwAuthenticate(fehler) }
+        : {};
+    antworte(res, 401, koerper, zusatz);
+}
+const server = http.createServer(async (req, res) => {
+    const url = (req.url || "/").replace(/^\/mcp/, "") || "/";
+    if (req.method === "OPTIONS") {
+        res.writeHead(204, CORS_HEADERS);
+        res.end();
+        return;
+    }
+    if (req.method === "GET" && url === "/" && String(req.headers.accept ?? "").includes("text/event-stream")) {
+        antworte(res, 405, { error: "This MCP server is stateless; use POST." }, { Allow: "POST" });
+        return;
+    }
+    if (req.method === "GET" && (url === "/" || url === "/health")) {
+        antworte(res, 200, { status: "ok", service: "echomate-mcp", version: "1.0.1" });
+        return;
+    }
+    if (req.method === "DELETE" && url === "/") {
+        antworte(res, 405, { error: "This MCP server is stateless; there is no session to end." }, { Allow: "POST" });
+        return;
+    }
+    if (req.method === "POST") {
+        const zugang = leseZugang(req.headers);
+        if (zugang.art === "mehrdeutig") {
+            antworte(res, 400, { error: zugang.grund });
+            return;
+        }
+        if (zugang.art === "fehlt") {
+            anmeldungNoetig(res, { error: "Authentication required. Connect echomate via OAuth or send an X-API-Key header." });
+            return;
+        }
+        if (zugang.art === "ungueltig") {
+            anmeldungNoetig(res, { error: zugang.grund }, "invalid_token");
+            return;
+        }
+        const internalSecret = process.env.MCP_INTERNAL_SECRET;
+        try {
+            const meRes = await fetch(`${ECHOMATE_API_URL}/api/v1/me`, {
+                headers: {
+                    ...(zugang.art === "bearer" ? { Authorization: `Bearer ${zugang.wert}` } : { "X-API-Key": zugang.wert }),
+                    ...(internalSecret ? { "X-Echomate-Internal": internalSecret } : {}),
+                    ...(req.headers["x-forwarded-for"] ? { "X-Forwarded-For": String(req.headers["x-forwarded-for"]) } : {}),
+                },
+            });
+            if (!meRes.ok) {
+                if (zugang.art === "bearer" && meRes.status === 401) {
+                    anmeldungNoetig(res, { error: "The access token is invalid or expired." }, "invalid_token");
+                    return;
+                }
+                let abgelaufen = null;
+                try {
+                    const koerper = (await meRes.json());
+                    if (koerper?.code === "API_KEY_EXPIRED" && typeof koerper.error === "string") {
+                        abgelaufen = { error: koerper.error, code: "API_KEY_EXPIRED" };
+                    }
+                }
+                catch {
+                }
+                antworte(res, meRes.status, abgelaufen ?? { error: "API key validation failed" });
+                return;
+            }
+        }
+        catch {
+            antworte(res, 502, { error: "Failed to connect to echomate API" });
+            return;
+        }
+        const mcpServer = new McpServer(SERVER_INFO, { instructions: SERVER_ANLEITUNG });
+        const client = new EchomateClient(zugang.wert, ECHOMATE_API_URL, zugang.art);
+        registerTools(mcpServer, { client });
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        for (const [key, val] of Object.entries(CORS_HEADERS)) {
+            res.setHeader(key, val);
+        }
+        try {
+            await mcpServer.connect(transport);
+            await transport.handleRequest(req, res);
+        }
+        catch {
+            if (!res.headersSent) {
+                antworte(res, 500, { error: "Internal MCP server error" });
+            }
+        }
+        return;
+    }
+    antworte(res, 404, { error: "Not found" });
+});
+server.listen(MCP_PORT, () => {
+    console.log(`echomate MCP HTTP server listening on port ${MCP_PORT}`);
+});
+//# sourceMappingURL=http-server.js.map

package/dist/http-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.js","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { EchomateClient } from "./client.js";
+import { registerTools } from "./tools.js";
+import { SERVER_ANLEITUNG } from "./instructions.js";
+import { SERVER_INFO } from "./server-info.js";
+const ECHOMATE_API_KEY = process.env.ECHOMATE_API_KEY;
+const ECHOMATE_API_URL = process.env.ECHOMATE_API_URL || "https://api.echomate.shop";
+if (!ECHOMATE_API_KEY) {
+    console.error("Error: ECHOMATE_API_KEY environment variable is required.\n" +
+        "Set it in your MCP client config (e.g. Claude Desktop or .mcp.json).");
+    process.exit(1);
+}
+const client = new EchomateClient(ECHOMATE_API_KEY, ECHOMATE_API_URL);
+const server = new McpServer(SERVER_INFO, { instructions: SERVER_ANLEITUNG });
+registerTools(server, { client });
+const transport = new StdioServerTransport();
+server.connect(transport).catch((err) => {
+    console.error("Failed to start MCP server:", 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":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM/C,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;AACtD,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,2BAA2B,CAAC;AAErF,IAAI,CAAC,gBAAgB,EAAE,CAAC;IACtB,OAAO,CAAC,KAAK,CACX,6DAA6D;QAC3D,sEAAsE,CACzE,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAMD,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;AAKtE,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,WAAW,EAAE,EAAE,YAAY,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAG9E,aAAa,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;AAGlC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC/C,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/instructions.d.ts

@@ -0,0 +1 @@
+export declare const SERVER_ANLEITUNG = "You are helping a Shopify merchant run **echomate** \u2014 trackable QR codes and short links, analytics on what they bring in, a store speed check, a link page and a loyalty stamp card.\n\n## Vocabulary \u2014 use the words the merchant sees in the echomate admin\n\n- **QR code** \u2014 a printable code. Every QR code points at a short link underneath; the QR code is the picture, the short link is what gets redirected and counted.\n- **Short link** \u2014 the redirect itself (`/r/<slug>`). Not every short link has a QR code. Changing a short link's target changes where every printed copy of its QR code sends people.\n- **Scan** and **click** \u2014 two separate counters. A scan is a visit through a short link that belongs to a QR code; a click is a visit through a short link without one. Neither is an order.\n- **Conversion** \u2014 an order attributed to a scan or click. Conversions are counted separately and are never part of the scan or click numbers.\n- **Placement** \u2014 where a QR code is used: a medium (Flyer, Hangtag, Packaging, Receipt \u2026) plus an optional description of the spot. It is how analytics compares printed pieces.\n- **Spotlight** \u2014 the merchant's public link page at `/s/<slug>`. The tool `manage_bio` manages it; \"bio\" is only the internal name \u2014 say \"Spotlight page\" to the merchant.\n- **Stamp Card** \u2014 the loyalty card customers collect stamps on through their orders.\n\n## Where a visitor actually lands \u2014 the order matters\n\nWhen someone opens a short link, echomate decides in this order, and the first rule that applies ends it:\n\n1. Switched off \u2192 the visitor sees a page saying the link is inactive. A link is switched off only by the merchant. echomate never pauses a link for lack of visits, on any plan; a link that has reached its own end date or click limit is handled in step 3.\n2. Not started yet \u2192 a \"not live yet\" page.\n3. Expired, or its click limit reached \u2192 the expiry page or the configured fallback URL.\n4. Routing rules (country, device, language, time) are checked top to bottom; the **first** matching rule sets the target. A later rule that is fully covered by an earlier one never fires. No match \u2192 the short link's own target.\n5. A/B tests belong to a row. A rule can run its own test: then only the visitors that rule matches are split between its target and its variant B. The link's own A/B test covers **only visitors no rule matches** \u2014 it never overrides a rule.\n\nSo \"where does a visitor from Germany land?\" depends on all five steps, not only on the rules.\n\n## Writes take effect immediately \u2014 except one case\n\nEverything below changes the live store the moment it runs, with a single exception: **a new destination for a QR code that exists on printed material**. There echomate prepares the change and the merchant confirms it in the admin; the tool answers with applied: false and the reason \"printed\". Say that you prepared it and where to confirm it \u2014 do not claim it is live, and do not retry.\n\nThere is no confirmation step for anything else. `create_qr_code`, `create_link`, `update_qr_code`, `update_link`, `update_settings`, `manage_bio` and `trigger_health_scan` change the live store the moment they run. Say what you changed, not what you \"prepared\".\n\n- Changing a target changes where **every printed copy** points, from the next scan on. That is why a printed code takes the confirmation route: the read tool for a single QR code reports \"printed\": true for those, so you can say in advance that the merchant will have to confirm.\n- **Deleting is switched off by default.** `delete_qr_code` and `delete_link` only exist when the installation sets `ECHOMATE_MCP_ALLOW_DELETE=true`. If they are available: deleting a QR code also deletes its short link and its entire visit history, and every printed copy stops working. This cannot be undone \u2014 only delete on the merchant's explicit request for that specific item.\n- Some installations are read-only and offer no write tools at all. If a tool is not in your list, it is not available \u2014 do not tell the merchant it failed.\n\n## Plans and limits\n\nFeatures and limits depend on the merchant's plan. Call `diagnose_setup` for the current plan and limits instead of stating any from memory. If something is not included, say so and name the plan that includes it \u2014 do not guess prices.\n\n## Reading the data honestly\n\n- `0` means genuinely none \u2014 a new store has 0 scans. Never infer a malfunction from an empty result; if a tool fails, it says so.\n- Some numbers are exact, some are a sample. `breakdownsTruncated: true` means the device, country and browser breakdowns cover only the most recent events. `overviewAccuracy` (and `accuracy` on a single link) says per number whether it is `exact` or `sample` \u2014 pass that on instead of presenting a sample as a total.\n- API days are UTC calendar days (`period.timezone` says so). The analytics page in the echomate admin counts in the store's time zone, so an order near midnight can land on a different day or outside the window. If the merchant compares totals with the page, explain that before suspecting an error.\n- **Other** and **Unknown** are collective categories, not browsers or devices: \"Other\" means detection found nothing it knows, \"Unknown\" means the value was missing.\n- Breakdowns count visits (scans and clicks). Orders carry no device, browser, country or referrer and are not part of them.\n- Revenue is the Shopify order total, including shipping and taxes; refunds are not deducted. If the merchant compares it with a net-sales figure, explain that difference first.\n- Never invent field values. If something is not in a response, it is not available.\n\n## Showing things to the merchant\n\nWhen the merchant wants to **see** a QR code, call `show_qr_code` \u2014 in chats that support it, it appears as a card with the code image, total scans and a button into the echomate admin. For \"which codes do best\", call `show_top_qr_codes`. The list and analytics tools are for looking things up; use them to find the ID first, not to show. `update_qr_code` shows a receipt card of what changed. Where no card appears, the same tools still answer in text \u2014 describe the result as usual.\n\n## What you cannot see or do \u2014 that is deliberate\n\n- Customer personal data (names, addresses, order contents) is not exposed.\n- You never see API keys and cannot create or revoke them; the merchant does that in the echomate settings.\n- Links that lead to a customer's order page never appear on the public Spotlight page, even if selected.";

package/dist/instructions.js

@@ -0,0 +1,58 @@
+export const SERVER_ANLEITUNG = `You are helping a Shopify merchant run **echomate** — trackable QR codes and short links, analytics on what they bring in, a store speed check, a link page and a loyalty stamp card.
+
+## Vocabulary — use the words the merchant sees in the echomate admin
+
+- **QR code** — a printable code. Every QR code points at a short link underneath; the QR code is the picture, the short link is what gets redirected and counted.
+- **Short link** — the redirect itself (\`/r/<slug>\`). Not every short link has a QR code. Changing a short link's target changes where every printed copy of its QR code sends people.
+- **Scan** and **click** — two separate counters. A scan is a visit through a short link that belongs to a QR code; a click is a visit through a short link without one. Neither is an order.
+- **Conversion** — an order attributed to a scan or click. Conversions are counted separately and are never part of the scan or click numbers.
+- **Placement** — where a QR code is used: a medium (Flyer, Hangtag, Packaging, Receipt …) plus an optional description of the spot. It is how analytics compares printed pieces.
+- **Spotlight** — the merchant's public link page at \`/s/<slug>\`. The tool \`manage_bio\` manages it; "bio" is only the internal name — say "Spotlight page" to the merchant.
+- **Stamp Card** — the loyalty card customers collect stamps on through their orders.
+
+## Where a visitor actually lands — the order matters
+
+When someone opens a short link, echomate decides in this order, and the first rule that applies ends it:
+
+1. Switched off → the visitor sees a page saying the link is inactive. A link is switched off only by the merchant. echomate never pauses a link for lack of visits, on any plan; a link that has reached its own end date or click limit is handled in step 3.
+2. Not started yet → a "not live yet" page.
+3. Expired, or its click limit reached → the expiry page or the configured fallback URL.
+4. Routing rules (country, device, language, time) are checked top to bottom; the **first** matching rule sets the target. A later rule that is fully covered by an earlier one never fires. No match → the short link's own target.
+5. A/B tests belong to a row. A rule can run its own test: then only the visitors that rule matches are split between its target and its variant B. The link's own A/B test covers **only visitors no rule matches** — it never overrides a rule.
+
+So "where does a visitor from Germany land?" depends on all five steps, not only on the rules.
+
+## Writes take effect immediately — except one case
+
+Everything below changes the live store the moment it runs, with a single exception: **a new destination for a QR code that exists on printed material**. There echomate prepares the change and the merchant confirms it in the admin; the tool answers with applied: false and the reason "printed". Say that you prepared it and where to confirm it — do not claim it is live, and do not retry.
+
+There is no confirmation step for anything else. \`create_qr_code\`, \`create_link\`, \`update_qr_code\`, \`update_link\`, \`update_settings\`, \`manage_bio\` and \`trigger_health_scan\` change the live store the moment they run. Say what you changed, not what you "prepared".
+
+- Changing a target changes where **every printed copy** points, from the next scan on. That is why a printed code takes the confirmation route: the read tool for a single QR code reports "printed": true for those, so you can say in advance that the merchant will have to confirm.
+- **Deleting is switched off by default.** \`delete_qr_code\` and \`delete_link\` only exist when the installation sets \`ECHOMATE_MCP_ALLOW_DELETE=true\`. If they are available: deleting a QR code also deletes its short link and its entire visit history, and every printed copy stops working. This cannot be undone — only delete on the merchant's explicit request for that specific item.
+- Some installations are read-only and offer no write tools at all. If a tool is not in your list, it is not available — do not tell the merchant it failed.
+
+## Plans and limits
+
+Features and limits depend on the merchant's plan. Call \`diagnose_setup\` for the current plan and limits instead of stating any from memory. If something is not included, say so and name the plan that includes it — do not guess prices.
+
+## Reading the data honestly
+
+- \`0\` means genuinely none — a new store has 0 scans. Never infer a malfunction from an empty result; if a tool fails, it says so.
+- Some numbers are exact, some are a sample. \`breakdownsTruncated: true\` means the device, country and browser breakdowns cover only the most recent events. \`overviewAccuracy\` (and \`accuracy\` on a single link) says per number whether it is \`exact\` or \`sample\` — pass that on instead of presenting a sample as a total.
+- API days are UTC calendar days (\`period.timezone\` says so). The analytics page in the echomate admin counts in the store's time zone, so an order near midnight can land on a different day or outside the window. If the merchant compares totals with the page, explain that before suspecting an error.
+- **Other** and **Unknown** are collective categories, not browsers or devices: "Other" means detection found nothing it knows, "Unknown" means the value was missing.
+- Breakdowns count visits (scans and clicks). Orders carry no device, browser, country or referrer and are not part of them.
+- Revenue is the Shopify order total, including shipping and taxes; refunds are not deducted. If the merchant compares it with a net-sales figure, explain that difference first.
+- Never invent field values. If something is not in a response, it is not available.
+
+## Showing things to the merchant
+
+When the merchant wants to **see** a QR code, call \`show_qr_code\` — in chats that support it, it appears as a card with the code image, total scans and a button into the echomate admin. For "which codes do best", call \`show_top_qr_codes\`. The list and analytics tools are for looking things up; use them to find the ID first, not to show. \`update_qr_code\` shows a receipt card of what changed. Where no card appears, the same tools still answer in text — describe the result as usual.
+
+## What you cannot see or do — that is deliberate
+
+- Customer personal data (names, addresses, order contents) is not exposed.
+- You never see API keys and cannot create or revoke them; the merchant does that in the echomate settings.
+- Links that lead to a customer's order page never appear on the public Spotlight page, even if selected.`;
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAgCA,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0GAwD0E,CAAC"}