@reynandaptr/replyto-mcp 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @reynandaptr/replyto-mcp
+
+MCP server for [Replyto](https://replyto.id) — manage your products and
+Instagram automations from any MCP-capable AI client.
+
+## Setup
+
+1. In the Replyto dashboard, open **Settings → API Keys** (paid plans) and
+   create a key.
+2. Add to your AI client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "replyto": {
+      "command": "npx",
+      "args": ["-y", "@reynandaptr/replyto-mcp"],
+      "env": { "REPLYTO_API_KEY": "rt_..." }
+    }
+  }
+}
+```
+
+`REPLYTO_URL` (optional) overrides the API base URL for staging/local use.
+
+## Tools
+
+Products: list, get, create, update, delete, replace links.
+Automations: list, get, create, update, toggle, delete, preview conflicts, list runs.
+Lookups: stores, Instagram accounts, Instagram media.

package/dist/client.js

@@ -0,0 +1,63 @@
+// Thin fetch wrapper for the Replyto API. Every MCP tool is a one-line
+// call through this — the API stays the validator of record, and coded
+// error bodies are surfaced verbatim so the AI can self-correct.
+export const ok = (text) => ({ content: [{ type: "text", text }] });
+export const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+// One-line remediation hints appended to the coded errors an AI can't fix
+// by changing its input.
+const HINTS = {
+    unauthorized: "Check that REPLYTO_API_KEY is a valid, non-revoked Replyto API key.",
+    plan_upgrade_required: "API access requires a paid Replyto plan — upgrade in the Replyto dashboard.",
+    email_unverified: "Verify your email address in the Replyto dashboard first.",
+};
+export class ReplytoClient {
+    apiKey;
+    baseUrl;
+    constructor(baseUrl, apiKey) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+    }
+    async call(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v !== undefined && v !== null && v !== "")
+                url.searchParams.set(k, String(v));
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    ...(opts.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                },
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            });
+        }
+        catch (e) {
+            return err(`network error calling ${method} ${path}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (res.status === 204)
+            return ok("done");
+        const raw = await res.text();
+        let data = null;
+        try {
+            data = raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            // non-JSON body — fall through with raw text
+        }
+        if (!res.ok) {
+            const body = (data ?? {});
+            const code = body.code ?? `http_${res.status}`;
+            let text = `${code}: ${body.message ?? (raw || res.statusText)}`;
+            if (HINTS[code])
+                text += `\n${HINTS[code]}`;
+            if (body.conflicts !== undefined) {
+                text += `\nconflicts: ${JSON.stringify(body.conflicts, null, 2)}`;
+            }
+            return err(text);
+        }
+        return ok(data === null ? "done" : JSON.stringify(data, null, 2));
+    }
+}

package/dist/config.js

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-config.mjs at build time — do not edit or commit.
+export const DEFAULT_BASE_URL = "https://api.replyto.id";

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// @reynandaptr/replyto-mcp — stdio MCP server exposing Replyto products & automations.
+// Config via env: REPLYTO_API_KEY (required), REPLYTO_URL (optional).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ReplytoClient } from "./client.js";
+import { DEFAULT_BASE_URL } from "./config.js";
+import { productTools } from "./tools/products.js";
+import { automationTools } from "./tools/automations.js";
+import { lookupTools } from "./tools/lookups.js";
+const apiKey = process.env.REPLYTO_API_KEY;
+if (!apiKey) {
+    console.error("REPLYTO_API_KEY is not set.\n" +
+        "Create an API key in the Replyto dashboard (Settings → API Keys) and add it to this MCP server's env config.");
+    process.exit(1);
+}
+const client = new ReplytoClient(process.env.REPLYTO_URL ?? DEFAULT_BASE_URL, apiKey);
+const server = new McpServer({ name: "replyto", version: "0.1.0" });
+for (const def of [...productTools, ...automationTools, ...lookupTools]) {
+    server.registerTool(def.name, { description: def.description, inputSchema: def.inputSchema, annotations: def.annotations }, (args) => def.handler(client, args ?? {}));
+}
+try {
+    await server.connect(new StdioServerTransport());
+}
+catch (e) {
+    console.error(`failed to start replyto MCP server: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+}

package/dist/tools/automations.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+// Mirrors automations.AutomationAccountInput. post_id is only meaningful
+// with post_scope=specific.
+const accountInput = {
+    handle: z.string().describe("Instagram handle of a connected account (see list_instagram_accounts)"),
+    post_id: z.string().optional().describe("IG media id — required per account when post_scope=specific (see list_instagram_media)"),
+};
+const ruleFields = {
+    name: z.string().optional().describe("Optional label; the API derives one when omitted"),
+    trigger: z.enum(["keyword", "all"]).describe("keyword = fire only when the comment/DM contains `keyword`; all = fire on every comment"),
+    keyword: z.string().optional().describe("Required when trigger=keyword. Case-insensitive match."),
+    action: z.enum(["reply", "dm", "dm_store", "dm_product"]).describe("reply = public comment reply; dm = send `message` as a DM; dm_store = DM a store link (needs store_id); dm_product = DM a product link (needs product_id)"),
+    message: z.string().optional().describe("The reply/DM text"),
+    accounts: z.array(z.object(accountInput)).describe("Which connected IG accounts this rule runs on"),
+    post_scope: z.enum(["specific", "next", "all", "dm", "live"]).describe("specific = only the given post_id(s); next = the next post published after creating the rule; all = every post; dm = incoming DMs instead of comments; live = live-video comments"),
+    store_id: z.string().uuid().optional().describe("Required when action=dm_store (see list_stores)"),
+    product_id: z.string().uuid().optional().describe("Required when action=dm_product (see list_products)"),
+    reply_also: z.boolean().optional().describe("For DM actions: also leave a short public reply"),
+    reply_text: z.string().optional().describe("The public reply text when reply_also=true"),
+    on: z.boolean().optional().describe("Start enabled (default true)"),
+};
+export const automationTools = [
+    {
+        name: "list_automations",
+        description: "List the user's Instagram automation rules. Filters: account (IG handle), on (enabled), scope, page, limit.",
+        inputSchema: {
+            account: z.string().optional(),
+            on: z.boolean().optional(),
+            scope: z.enum(["specific", "next", "all", "dm", "live"]).optional(),
+            page: z.number().int().min(1).optional(),
+            limit: z.number().int().min(1).optional(),
+        },
+        annotations: { readOnlyHint: true },
+        handler: (c, a) => c.call("GET", "/automations", { query: a }),
+    },
+    {
+        name: "get_automation",
+        description: "Fetch one automation rule by id.",
+        inputSchema: { id: z.string().uuid() },
+        annotations: { readOnlyHint: true },
+        handler: (c, { id }) => c.call("GET", `/automations/${id}`),
+    },
+    {
+        name: "create_automation",
+        description: "Create an Instagram auto-reply/DM rule. On a 409 the response lists conflicting rules — " +
+            "adjust keyword/scope/accounts or ask the user. Consider preview_automation_conflicts first.",
+        inputSchema: ruleFields,
+        handler: (c, a) => c.call("POST", "/automations", { body: a }),
+    },
+    {
+        name: "update_automation",
+        description: "Update rule fields by id. Only send the fields to change.",
+        inputSchema: {
+            id: z.string().uuid(),
+            ...Object.fromEntries(Object.entries(ruleFields).map(([k, v]) => [k, v.optional()])),
+        },
+        handler: (c, { id, ...body }) => c.call("PATCH", `/automations/${id}`, { body }),
+    },
+    {
+        name: "toggle_automation",
+        description: "Turn a rule on or off without editing it.",
+        inputSchema: { id: z.string().uuid(), on: z.boolean() },
+        handler: (c, { id, on }) => c.call("POST", `/automations/${id}/toggle`, { body: { on } }),
+    },
+    {
+        name: "delete_automation",
+        description: "Permanently delete an automation rule.",
+        inputSchema: { id: z.string().uuid() },
+        annotations: { destructiveHint: true },
+        handler: (c, { id }) => c.call("DELETE", `/automations/${id}`),
+    },
+    {
+        name: "preview_automation_conflicts",
+        description: "Dry-run conflict check for a prospective rule — returns conflicting existing rules without creating anything. " +
+            "Pass exclude_id when checking an edit to an existing rule.",
+        inputSchema: {
+            trigger: ruleFields.trigger,
+            keyword: ruleFields.keyword,
+            action: ruleFields.action,
+            message: ruleFields.message,
+            accounts: ruleFields.accounts,
+            post_scope: ruleFields.post_scope,
+            reply_also: ruleFields.reply_also,
+            exclude_id: z.string().uuid().optional(),
+        },
+        annotations: { readOnlyHint: true },
+        handler: (c, a) => c.call("POST", "/automations/conflicts/preview", { body: a }),
+    },
+    {
+        name: "list_automation_runs",
+        description: "Recent executions of a rule (what fired, when, outcome). Cursor with before=RFC3339 timestamp.",
+        inputSchema: {
+            id: z.string().uuid(),
+            limit: z.number().int().min(1).optional(),
+            before: z.string().optional().describe("RFC3339 timestamp cursor"),
+        },
+        annotations: { readOnlyHint: true },
+        handler: (c, { id, ...rest }) => c.call("GET", `/automations/${id}/runs`, { query: rest }),
+    },
+];

package/dist/tools/lookups.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export const lookupTools = [
+    {
+        name: "list_stores",
+        description: "List the user's storefronts. Use a store's id for product store_id or automation action=dm_store.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+        handler: (c) => c.call("GET", "/stores"),
+    },
+    {
+        name: "list_instagram_accounts",
+        description: "List the user's connected Instagram accounts (handle, ig_user_id, connection health). " +
+            "Automations reference accounts by handle.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+        handler: (c) => c.call("GET", "/instagram/accounts"),
+    },
+    {
+        name: "list_instagram_media",
+        description: "List recent posts of a connected IG account (media id, caption, permalink). " +
+            "Use a media id as accounts[].post_id for post_scope=specific automations.",
+        inputSchema: {
+            ig_user_id: z.string().describe("The account's ig_user_id from list_instagram_accounts"),
+        },
+        annotations: { readOnlyHint: true },
+        handler: (c, { ig_user_id }) => c.call("GET", `/instagram/accounts/${ig_user_id}/media`),
+    },
+];

package/dist/tools/products.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+// Mirrors products.LinkInput (api/internal/products/dto.go). Prices are
+// integer minor units (IDR has no cents — 15000 = Rp 15.000).
+const linkInput = {
+    id: z.string().uuid().optional().describe("Existing link id — only when replacing links and keeping a row"),
+    platform: z.string().describe("Marketplace platform key, e.g. shopee, tokopedia, tiktok_shop, lazada, website"),
+    url: z.string().describe("Full product URL on that platform"),
+    price: z.number().int().optional().describe("Current price in integer rupiah (no decimals)"),
+    original: z.number().int().optional().describe("Pre-discount price in integer rupiah; omit if no discount"),
+    label: z.string().optional().describe("Optional badge label shown on the button, e.g. 'Official Store'"),
+};
+const productFields = {
+    slug: z.string().describe("URL slug for the public product page (/p/<slug>). Lowercase, hyphenated."),
+    name: z.string().max(200).describe("Product display name"),
+    desc: z.string().optional().describe("Short description shown on the product page"),
+    tag: z.string().optional().describe("Free-form tag/category label"),
+    img_preset: z.string().optional().describe("Preset illustration id (alternative to img_url)"),
+    img_url: z.string().optional().describe("Product image URL (use the dashboard to upload; pass an existing URL here)"),
+    featured: z.boolean().optional(),
+    active: z.boolean().optional().describe("Inactive products hide from the public page"),
+    mode: z.enum(["platforms", "redirect"]).describe("platforms = landing page listing marketplace buttons; redirect = short link straight to one URL"),
+    redirect_url: z.string().optional().describe("Required when mode=redirect: the destination URL"),
+    store_id: z.string().uuid().optional().describe("Attach to one of the user's stores (see list_stores)"),
+    links: z.array(z.object(linkInput)).optional().describe("Required when mode=platforms: at least one marketplace link"),
+};
+export const productTools = [
+    {
+        name: "list_products",
+        description: "List the user's products with pagination. Filters: q (name search), active, store_id (uuid, or 'none' for products not in any store).",
+        inputSchema: {
+            q: z.string().optional(),
+            active: z.boolean().optional(),
+            store_id: z.string().optional(),
+            page: z.number().int().min(1).optional(),
+            limit: z.number().int().min(1).optional(),
+        },
+        annotations: { readOnlyHint: true },
+        handler: (c, a) => c.call("GET", "/products", { query: a }),
+    },
+    {
+        name: "get_product",
+        description: "Fetch one product by id, including its links and short-link click URLs.",
+        inputSchema: { id: z.string().uuid() },
+        annotations: { readOnlyHint: true },
+        handler: (c, { id }) => c.call("GET", `/products/${id}`),
+    },
+    {
+        name: "create_product",
+        description: "Create a product. mode=platforms needs links[] (marketplace buttons); mode=redirect needs redirect_url. " +
+            "The API auto-creates short links and returns their click URLs.",
+        inputSchema: productFields,
+        handler: (c, a) => c.call("POST", "/products", { body: a }),
+    },
+    {
+        name: "update_product",
+        description: "Update product fields by id. Only send the fields to change. Links are managed via replace_product_links.",
+        inputSchema: {
+            id: z.string().uuid(),
+            ...Object.fromEntries(Object.entries(productFields).map(([k, v]) => [k, v.optional()])),
+        },
+        handler: (c, { id, ...body }) => c.call("PATCH", `/products/${id}`, { body }),
+    },
+    {
+        name: "delete_product",
+        description: "Permanently delete a product and its short links.",
+        inputSchema: { id: z.string().uuid() },
+        annotations: { destructiveHint: true },
+        handler: (c, { id }) => c.call("DELETE", `/products/${id}`),
+    },
+    {
+        name: "replace_product_links",
+        description: "Replace ALL marketplace links of a mode=platforms product in one shot. " +
+            "Include id on rows to keep (preserves click stats); rows without id are created; omitted rows are deleted.",
+        inputSchema: { id: z.string().uuid(), links: z.array(z.object(linkInput)) },
+        handler: (c, { id, links }) => c.call("PUT", `/products/${id}/links`, { body: { links } }),
+    },
+];

package/dist/tools/types.js

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

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@reynandaptr/replyto-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Replyto — manage your products and Instagram automations from any AI client",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reynandaptr/replyto-mcp.git"
+  },
+  "homepage": "https://github.com/reynandaptr/replyto-mcp#readme",
+  "bugs": { "url": "https://github.com/reynandaptr/replyto-mcp/issues" },
+  "bin": { "replyto-mcp": "dist/index.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "prebuild": "node scripts/gen-config.mjs",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}