lotux-mcp 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# lotux-mcp
+
+Local MCP server that lets Claude (Desktop or Code) create and edit **LOTUX**
+concepts: fetch a brand's products / personas / angles / use-cases, create
+concepts, fill scripts, draft + link ad copy, and assign team members.
+
+It is a thin connector — all logic and data live in the LOTUX app. This package
+just forwards your tool calls there, authenticated with your personal token.
+RLS in LOTUX scopes everything to the brands your account can access.
+
+## Prerequisites
+
+- **Node.js 18+** installed (this is what runs the connector).
+- A **LOTUX MCP token** — generate one in LOTUX → Settings → Connections →
+  **MCP server** (shown once; revocable any time).
+
+## Setup
+
+Add this to your Claude config (Claude Desktop → Settings → Developer → Edit
+Config, or Claude Code → `~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "lotux": {
+      "command": "npx",
+      "args": ["-y", "lotux-mcp"],
+      "env": {
+        "LOTUX_MCP_TOKEN": "lxmcp_…your token…",
+        "LOTUX_API_URL": "https://app.lotuxagency.com"
+      }
+    }
+  }
+}
+```
+
+**Windows:** use `"command": "cmd"` and
+`"args": ["/c", "npx", "-y", "lotux-mcp"]`.
+
+Restart Claude, then try: *"list my LOTUX brands"*.
+
+## Env
+
+| Var | Value |
+|-----|-------|
+| `LOTUX_MCP_TOKEN` | your personal token from Settings → Connections |
+| `LOTUX_API_URL` | the LOTUX app URL (e.g. `https://app.lotuxagency.com`) |

package/index.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// LOTUX local MCP server. Runs on the user's machine (stdio) and turns Claude
+// tool calls into authenticated RPC calls against the LOTUX app. Every call
+// carries the user's personal token; the app resolves it to a user-scoped
+// Supabase session, so writes are RLS-scoped to the brands that user can access.
+//
+// Env:
+//   LOTUX_MCP_TOKEN  — personal token from LOTUX → Settings → Connections
+//   LOTUX_API_URL    — app base URL, e.g. https://app.lotuxagency.com
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API = (process.env.LOTUX_API_URL || "").replace(/\/$/, "");
+const TOKEN = process.env.LOTUX_MCP_TOKEN || "";
+
+if (!API || !TOKEN) {
+  console.error(
+    "LOTUX MCP: set LOTUX_API_URL and LOTUX_MCP_TOKEN in the MCP server env."
+  );
+  process.exit(1);
+}
+
+// Call the app's RPC endpoint. Drops undefined params so optional fields don't
+// overwrite existing values with null on the server.
+async function rpc(method, params = {}) {
+  const clean = Object.fromEntries(
+    Object.entries(params).filter(([, v]) => v !== undefined)
+  );
+  const res = await fetch(`${API}/api/mcp/rpc`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${TOKEN}`,
+    },
+    body: JSON.stringify({ method, params: clean }),
+  });
+  let data;
+  try {
+    data = await res.json();
+  } catch {
+    throw new Error(`RPC ${method}: non-JSON response (HTTP ${res.status})`);
+  }
+  if (!res.ok || !data.ok) {
+    throw new Error(data?.error || `RPC ${method} failed (HTTP ${res.status})`);
+  }
+  return data.result;
+}
+
+const ok = (result) => ({
+  content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+});
+
+const server = new McpServer({ name: "lotux", version: "0.1.0" });
+
+// ── Reads ─────────────────────────────────────────────────────────────────────
+
+server.tool(
+  "list_brands",
+  "List the LOTUX brands (and the agency) you can access. Use the returned id as account_id for other tools.",
+  {},
+  async () => ok(await rpc("list_brands"))
+);
+
+server.tool(
+  "list_entities",
+  "List a brand's products, personas, angles, and use-cases (the building blocks for a concept). Pass account_id from list_brands.",
+  { account_id: z.string().describe("Brand (or agency) id from list_brands") },
+  async ({ account_id }) => ok(await rpc("list_entities", { account_id }))
+);
+
+server.tool(
+  "list_concepts",
+  "List a brand's existing concepts (id, code like '109', title, stage). Use this to find the id of a concept the user names before editing it.",
+  { account_id: z.string().describe("Brand id from list_brands") },
+  async ({ account_id }) => ok(await rpc("list_concepts", { account_id }))
+);
+
+server.tool(
+  "get_concept",
+  "Read the full state of one concept by id: fields, linked products/personas/angles/use-cases, script beats (with their text), and linked copy. Use to confirm what was written.",
+  { concept_id: z.string() },
+  async ({ concept_id }) => ok(await rpc("get_concept", { concept_id }))
+);
+
+server.tool(
+  "list_options",
+  "Valid values for a concept's fields: buckets, sub_buckets, funnel_stages, messaging_frameworks, variants, formats (per-brand), countries, languages. Call before set_concept_fields so you use real keys (e.g. funnel 'tof', not 'top of funnel').",
+  { account_id: z.string().describe("Brand id from list_brands") },
+  async ({ account_id }) => ok(await rpc("list_options", { account_id }))
+);
+
+server.tool(
+  "list_copy",
+  "List a brand's existing copy items (returns ids for link_copy). Optionally filter by type (adcopy/headline/description) or a text query.",
+  {
+    account_id: z.string().describe("Brand id from list_brands"),
+    type: z.enum(["adcopy", "headline", "description"]).optional(),
+    query: z.string().optional(),
+  },
+  async (args) => ok(await rpc("list_copy", args))
+);
+
+server.tool(
+  "list_members",
+  "List the agency team members (id + name) assignable to a concept's roles. Use the ids with set_concept_fields (strategist_id, copy_checker_id, editor_id, media_buyer_id, final_check_id).",
+  { account_id: z.string().describe("Brand id from list_brands") },
+  async ({ account_id }) => ok(await rpc("list_members", { account_id }))
+);
+
+// ── Concept ────────────────────────────────────────────────────────────────────
+
+server.tool(
+  "create_concept",
+  "Create a new concept in the brand's first (Idea) stage, optionally linking products/personas/angles/use-cases. Returns the new concept id. A human moves it through the copy-check gate later in the app.",
+  {
+    account_id: z.string().describe("Brand id from list_brands"),
+    title: z.string(),
+    bucket: z
+      .string()
+      .describe("Main bucket, e.g. video / static / carousel (the brand's bucket key)"),
+    funnel_stage: z.string().optional(),
+    format: z.string().optional(),
+    product_ids: z.array(z.string()).optional(),
+    persona_ids: z.array(z.string()).optional(),
+    angle_ids: z.array(z.string()).optional(),
+    use_case_ids: z.array(z.string()).optional(),
+  },
+  async (args) => ok(await rpc("create_concept", args))
+);
+
+server.tool(
+  "set_concept_fields",
+  "Update fields on an existing concept. Any omitted field is left unchanged; the id arrays, when given, replace the full set of links.",
+  {
+    concept_id: z.string(),
+    funnel_stage: z.string().optional(),
+    format: z.string().optional(),
+    messaging_framework: z.string().optional(),
+    variant: z.string().optional(),
+    country: z.string().optional(),
+    promotion: z.string().optional(),
+    visual_direction: z.string().optional(),
+    description: z.string().optional(),
+    base_language: z.string().optional(),
+    sub_buckets: z.array(z.string()).optional(),
+    product_ids: z.array(z.string()).optional(),
+    persona_ids: z.array(z.string()).optional(),
+    angle_ids: z.array(z.string()).optional(),
+    use_case_ids: z.array(z.string()).optional(),
+  },
+  async ({ concept_id, ...patch }) =>
+    ok(await rpc("set_concept_fields", { concept_id, patch }))
+);
+
+// ── Script beats ────────────────────────────────────────────────────────────────
+
+server.tool(
+  "add_beat",
+  "Add a script beat (Hook / Body / CTA) to a concept. `text` is the spoken/script line shown in the Script tab's VO/TH/TEXT field. Returns the new beat id.",
+  {
+    concept_id: z.string(),
+    beat_type: z.enum(["hook", "body", "cta"]).optional(),
+    text: z.string().optional().describe("The script line / what's said (the visible beat text)"),
+    visual_note: z.string().optional().describe("Optional on-screen visual note"),
+  },
+  async (args) => ok(await rpc("add_beat", args))
+);
+
+server.tool(
+  "update_beat",
+  "Update an existing script beat's script text, type, or visual note.",
+  {
+    beat_id: z.string(),
+    beat_type: z.enum(["hook", "body", "cta"]).optional(),
+    delivery_text: z.string().optional().describe("The script line / what's said"),
+    visual_note: z.string().optional(),
+  },
+  async ({ beat_id, ...patch }) => ok(await rpc("update_beat", { beat_id, patch }))
+);
+
+server.tool(
+  "set_base_language",
+  "Set the concept's base script language (the 'Original' tab), e.g. English.",
+  { concept_id: z.string(), language: z.string() },
+  async (args) => ok(await rpc("set_base_language", args))
+);
+
+// ── Copy ──────────────────────────────────────────────────────────────────────
+
+server.tool(
+  "create_copy",
+  "Create a brand-scoped ad copy item (adcopy / headline / description) and link it to a concept. Returns the new copy id.",
+  {
+    account_id: z.string().describe("Brand id from list_brands"),
+    concept_id: z.string(),
+    type: z.enum(["adcopy", "headline", "description"]),
+    text: z.string(),
+    product_ids: z.array(z.string()).optional(),
+    promotion: z.string().optional(),
+    country: z.string().optional(),
+    language: z.string().optional(),
+    funnel_stage: z.string().optional(),
+  },
+  async (args) => ok(await rpc("create_copy", args))
+);
+
+server.tool(
+  "link_copy",
+  "Link an existing copy item to a concept.",
+  { concept_id: z.string(), copy_item_id: z.string() },
+  async (args) => ok(await rpc("link_copy", args))
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("LOTUX MCP server running on stdio");
+}
+
+main().catch((e) => {
+  console.error("Fatal:", e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "lotux-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Local MCP server that lets Claude create LOTUX concepts (fetch brand-DB entities, create concepts, fill scripts + copy). Talks to the LOTUX app with a personal token; no business logic or secrets live here.",
+  "bin": {
+    "lotux-mcp": "index.mjs"
+  },
+  "main": "index.mjs",
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "lotux",
+    "claude",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  }
+}