lotux-mcp 0.4.0 → 0.5.0

package/README.md

@@ -45,3 +45,30 @@ Restart Claude, then try: *"list my LOTUX brands"*.
 |-----|-------|
 | `LOTUX_MCP_TOKEN` | your personal token from Settings → Connections |
 | `LOTUX_API_URL` | the LOTUX app URL (e.g. `https://app.lotuxagency.com`) |
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `list_brands` | Brands (+ agency) you can access |
+| `list_entities` / `create_entity` / `update_entity` / `delete_entity` | A brand's products / personas / angles / use-cases |
+| `list_concepts` / `get_concept` | Find a concept; read its full state (fields, links, **scripts** = markdown per language + shotlist, copy) |
+| `list_options` / `list_members` | Valid field values; assignable team members |
+| `create_concept` | New concept in Idea (+ optional links). Returns `{ id, script_id }` — write the script with `save_script` |
+| `set_concept_fields` | Update fields / links / team roles |
+| `save_script` | Write a script: markdown body for one language (`- **Hook:** …`, `- **1:** …`, `- **CTA:** …`), the shotlist, a rename. Pass `language` for a translation |
+| `add_script` / `delete_script` / `remove_script_language` / `set_base_language` | More scripts per concept; language housekeeping |
+| `set_beats` / `set_beat_translations` | **Compatibility** for older prompts: a beat list is stored as the script document. Prefer `save_script` |
+| `list_copy` / `create_copy` / `link_copy` / `unlink_copy` / `add_copy_translation` | Ad copy library + concept links |
+| `list_kb_*` / `get_kb_doc` / `create_kb_doc` / `update_kb_doc` | Kennisbank pages |
+
+Beats (`add_beat`, `update_beat`, `delete_beat`, `set_beat_translation`, `add_language`) were
+retired in Sep 2026 — scripts are documents now. Calling one returns a message pointing at the
+replacement.
+
+## Updating
+
+A running connector keeps the tool list it started with. To pick up new tools:
+
+1. Use `"args": ["-y", "lotux-mcp@latest"]` in the config (so `npx` re-resolves the version).
+2. Restart Claude (Desktop: quit + reopen; Code: `/mcp` → reconnect, or restart the session).

package/index.mjs

@@ -52,7 +52,7 @@ const ok = (result) => ({
   content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 });
 
-const server = new McpServer({ name: "lotux", version: "0.4.0" });
+const server = new McpServer({ name: "lotux", version: "0.5.0" });
 
 // ── Reads ─────────────────────────────────────────────────────────────────────
 
@@ -79,7 +79,7 @@ server.tool(
 
 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.",
+  "Read the full state of one concept by id: fields, linked products/personas/angles/use-cases, scripts (markdown per language + shotlist), and linked copy. Use to confirm what was written.",
   { concept_id: z.string() },
   async ({ concept_id }) => ok(await rpc("get_concept", { concept_id }))
 );
@@ -113,19 +113,21 @@ server.tool(
 
 server.tool(
   "create_concept",
-  "Create a new concept in the brand's first (Idea) stage, optionally linking products/personas/angles/use-cases. Returns { id, beat_ids } — the concept id plus the ids of 3 pre-seeded empty Hook beats. Fill those 3 with update_beat; do NOT add_beat for the first three hooks or you get duplicates. A human moves the concept through the copy-check gate later in the app.",
+  "Create a new concept in the brand's first (Idea) stage, optionally linking products/personas/angles/offers/use-cases (a concept needs ≥1 product, persona, angle and offer before it can enter Copy check). Returns { id, script_id } — the concept id plus the id of its pre-seeded script (starter template). Write the script with save_script(script_id, body); do NOT add_script for the first script. A human moves the concept 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)"),
+      .optional()
+      .describe("Main bucket, e.g. video / static / carousel (the brand's bucket key). Defaults to video."),
     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(),
+    offer_ids: z.array(z.string()).optional().describe("Offer ids from list_entities (offers)"),
   },
   async (args) => ok(await rpc("create_concept", args))
 );
@@ -142,14 +144,19 @@ server.tool(
     variant: z.string().optional(),
     country: z.string().optional(),
     promotion: z.string().optional(),
-    visual_direction: z.string().optional(),
-    description: z.string().optional(),
+    brief: z.string().optional().describe("Concept brief (markdown)"),
     base_language: z.string().optional(),
     sub_buckets: z.array(z.string()).optional(),
+    bucket: z.string().optional().describe("Main bucket option key (see list_options.fields)"),
+    fields: z
+      .record(z.union([z.string(), z.array(z.string()), z.null()]))
+      .optional()
+      .describe("Brand-defined concept fields by key → option key(s); see list_options.fields"),
     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(),
+    offer_ids: z.array(z.string()).optional(),
     // Team roles — pass a member id from list_members.
     strategist_id: z.string().optional().describe("Member id from list_members"),
     copy_checker_id: z.string().optional().describe("Member id from list_members"),
@@ -161,139 +168,95 @@ server.tool(
     ok(await rpc("set_concept_fields", { concept_id, patch }))
 );
 
-// ── Script beats ────────────────────────────────────────────────────────────────
+// ── Scripts (document model) ────────────────────────────────────────────────
+
+const SCRIPT_BODY_DOC =
+  "Markdown. Use labelled lines: `- **Hook:** …` (or `- **Hook 1:** …`, `- **Hook 2:** …` for several hooks), `- **1:** …`, `- **2:** …` for body lines, `- **CTA:** …` for the close. Hook ad-names are derived from the Hook lines. Free text (headings, paragraphs) is fine around them.";
 
 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. NOTE: new concepts already come with 3 empty Hook beats (see create_concept) — fill those with update_beat first; only add_beat for extra beats beyond them.",
+  "save_script",
+  "Write a concept script: the markdown body for one language and/or the shotlist and/or a rename. Any omitted part is left unchanged. script_id comes from create_concept (script_id) or get_concept (scripts[].id). language defaults to the concept's base language; pass a translation language (full-written, e.g. Dutch) to write that language's version — a new language is added automatically. Returns the full script.",
   {
-    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"),
-    delivery_kind: z
-      .enum(["voiceover", "talking_head", "text_on_screen"])
-      .optional()
-      .describe("Per-beat delivery type dropdown"),
+    script_id: z.string(),
+    language: z.string().optional().describe("Full-written language name, e.g. English / Dutch. Defaults to the base language."),
+    body: z.string().optional().describe(SCRIPT_BODY_DOC),
+    shotlist: z.array(z.string()).optional().describe("Ordered list of shots / b-roll (one line each). Replaces the whole list."),
+    name: z.string().optional().describe("Rename the script"),
   },
-  async (args) => ok(await rpc("add_beat", args))
+  async (args) => ok(await rpc("save_script", args))
 );
 
 server.tool(
-  "update_beat",
-  "Update an existing script beat's script text, type, delivery kind, or visual note. Use this (not add_beat) to edit a beat — the beat_id comes from create_concept or get_concept.",
-  {
-    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(),
-    delivery_kind: z
-      .enum(["voiceover", "talking_head", "text_on_screen"])
-      .optional()
-      .describe("Per-beat delivery type dropdown"),
-  },
-  async ({ beat_id, ...patch }) => ok(await rpc("update_beat", { beat_id, patch }))
+  "add_script",
+  "Add another script to a concept (every concept already has one — use save_script on it first). Returns the new script (starter template in the base language).",
+  { concept_id: z.string(), name: z.string().optional() },
+  async (args) => ok(await rpc("add_script", args))
 );
 
 server.tool(
-  "delete_beat",
-  "Delete a script beat by id (its translations are removed with it). Use to remove a wrong or leftover beat instead of blanking its text.",
-  { beat_id: z.string() },
-  async ({ beat_id }) => ok(await rpc("delete_beat", { beat_id }))
+  "delete_script",
+  "Delete a script (all its language versions + shotlist). Irreversible.",
+  { script_id: z.string() },
+  async ({ script_id }) => ok(await rpc("delete_script", { script_id }))
 );
 
+server.tool(
+  "remove_script_language",
+  "Remove one translation language from a script. The base language cannot be removed.",
+  { script_id: z.string(), language: z.string() },
+  async (args) => ok(await rpc("remove_script_language", args))
+);
+
+// ── Beat compat (older prompts / scripts) ───────────────────────────────────
+
 server.tool(
   "set_beats",
-  "Set a concept's ENTIRE script in one call (the efficient way to build or restructure beats). AUTHORITATIVE: the beats array becomes the full ordered script — order = array order, beats with an id are updated in place, id-less beats are inserted, and any existing beat you omit is deleted. Preserves translations on kept beats. Returns { beat_ids } in final order — feed those to set_beat_translation for per-language text. Prefer this over repeated add_beat/update_beat/delete_beat. Read the current beats with get_concept first so you resend the ones you want to keep.",
+  "Compatibility — prefer save_script. Sends an ordered beat list (Hook / Body / CTA lines + optional visual notes) and stores it as the concept's script document: lines become `- **Hook:**` / `- **1:**` / `- **CTA:**` markdown, visual notes become the shotlist. Replaces the whole script text for that language (default: the base language). Returns script_id + synthetic beat_ids ('<script_id>#<index>') for set_beat_translations.",
   {
     concept_id: z.string(),
-    beats: z
-      .array(
-        z.object({
-          id: z.string().optional().describe("Existing beat id to update; omit to insert a new beat"),
-          beat_type: z.enum(["hook", "body", "cta"]).optional(),
-          text: z.string().optional().describe("The script line / what's said"),
-          visual_note: z.string().optional(),
-          delivery_kind: z.enum(["voiceover", "talking_head", "text_on_screen"]).optional(),
-        })
-      )
-      .describe("The full ordered beat list. Anything not included is deleted."),
+    beats: z.array(
+      z.object({
+        beat_type: z.enum(["hook", "body", "cta"]).optional(),
+        text: z.string().optional().describe("Spoken line"),
+        visual_note: z.string().optional().describe("What to show — lands in the shotlist"),
+      })
+    ),
+    language: z.string().optional().describe("Full-written language, defaults to the concept's base language"),
   },
   async (args) => ok(await rpc("set_beats", args))
 );
 
 server.tool(
   "set_beat_translations",
-  "Write one language's ENTIRE translated script in a single call (the efficient partner to set_beats). Registers the language (if new) and upserts each beat's translated line. Prefer this over repeated add_language + set_beat_translation. beat_id values come from set_beats or get_concept; language is a full-written name (e.g. Dutch).",
+  "Compatibility — prefer save_script with a language. Writes one language's translated lines onto the concept's script: items are matched to the base script's lines by beat_id ('<script_id>#<index>' from set_beats) or by array order; a missing/empty text keeps the base line. Labels (Hook / 1 / CTA) are preserved.",
   {
     concept_id: z.string(),
-    language: z.string().describe("Full-written name, e.g. Dutch"),
-    items: z
-      .array(
-        z.object({
-          beat_id: z.string(),
-          text: z.string().optional().describe("The translated script line"),
-          visual_note: z.string().optional(),
-        })
-      )
-      .describe("One entry per beat to translate for this language"),
+    language: z.string().describe("Full-written language, e.g. Dutch"),
+    items: z.array(
+      z.object({
+        beat_id: z.string().optional(),
+        text: z.string().optional(),
+        visual_note: z.string().optional().describe("Ignored — shotlists are language-independent"),
+      })
+    ),
   },
   async (args) => ok(await rpc("set_beat_translations", args))
 );
 
 server.tool(
   "delete_concept",
-  "Delete an entire concept by id. Removes its beats, translations, entity links and copy links. Irreversible — confirm the id via list_concepts / get_concept first.",
+  "Delete an entire concept by id. Removes its scripts, entity links and copy links. Irreversible — confirm the id via list_concepts / get_concept first.",
   { concept_id: z.string() },
   async ({ concept_id }) => ok(await rpc("delete_concept", { concept_id }))
 );
 
 server.tool(
   "set_base_language",
-  "Set the concept's base script language (the 'Original' tab), e.g. English.",
+  "Set the concept's base script language, e.g. English. Existing base-language script texts are re-labelled to the new language.",
   { concept_id: z.string(), language: z.string() },
   async (args) => ok(await rpc("set_base_language", args))
 );
 
-server.tool(
-  "add_language",
-  "Add a translation language (tab) to a concept's Script, e.g. Dutch. Use a full-written name from list_options. Then write each beat's translated line with set_beat_translation.",
-  { concept_id: z.string(), language: z.string().describe("Full-written name, e.g. Dutch") },
-  async (args) => ok(await rpc("add_language", args))
-);
-
-server.tool(
-  "set_beat_translation",
-  "Write one beat's translated script line for a language. beat_id comes from get_concept; language must match one added via add_language.",
-  {
-    beat_id: z.string(),
-    language: z.string().describe("Full-written name, e.g. Dutch"),
-    delivery_text: z.string().optional().describe("The translated script line / what's said"),
-    visual_note: z.string().optional(),
-  },
-  async ({ beat_id, language, ...patch }) =>
-    ok(await rpc("set_beat_translation", { beat_id, language, ...patch }))
-);
-
-// ── 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.",
@@ -324,10 +287,10 @@ server.tool(
 
 server.tool(
   "create_entity",
-  "Create a brand-DB entity (persona / product / use_case / angle). name is required; description optional. `extras` carries the typed fields (e.g. persona awareness_stage/hypothesis, angle core idea via description + belief_shift, product average_price/margin_pct) — omit if unknown. Personas/use_cases/angles get an auto id_code (p1/u1/a1), returned in the result. Link it to a concept afterwards with set_concept_fields.",
+  "Create a NEW brand-DB entity — a product, persona, use_case or angle that doesn't exist yet (to attach an EXISTING one to a concept, pass its id to set_concept_fields instead). name is required; description optional. `extras` carries the typed fields: products take average_price / margin_pct / cm_target (target contribution-margin %) / ltv_multiplier / be_ncroas / product_link / type / status; personas take awareness_stage / hypothesis; angles take belief_shift (core idea goes in description). Omit unknown fields. Personas/use_cases/angles get an auto id_code (p1/u1/a1), returned in the result. Link the new entity to a concept afterwards with set_concept_fields.",
   {
     account_id: z.string().describe("Brand id from list_brands"),
-    kind: z.enum(["products", "personas", "angles", "use_cases"]),
+    kind: z.enum(["products", "personas", "angles", "use_cases", "offers"]),
     name: z.string(),
     description: z.string().optional(),
     extras: z.record(z.any()).optional().describe("Typed fields keyed by column name (see list_entities output shape)"),
@@ -340,7 +303,7 @@ server.tool(
   "Update a brand-DB entity by id. Omitted fields are left unchanged; a blank name is ignored (name is required). Use extras to patch typed fields.",
   {
     entity_id: z.string(),
-    kind: z.enum(["products", "personas", "angles", "use_cases"]),
+    kind: z.enum(["products", "personas", "angles", "use_cases", "offers"]),
     name: z.string().optional(),
     description: z.string().optional(),
     extras: z.record(z.any()).optional(),
@@ -350,10 +313,10 @@ server.tool(
 
 server.tool(
   "delete_entity",
-  "Delete a brand-DB entity by id. Its links to concepts are removed with it. Irreversible — confirm via list_entities first.",
+  "Delete a brand-DB entity (product / persona / use_case / angle / offer) by id. Its links to concepts are removed with it. Irreversible — confirm the id via list_entities first.",
   {
     entity_id: z.string(),
-    kind: z.enum(["products", "personas", "angles", "use_cases"]),
+    kind: z.enum(["products", "personas", "angles", "use_cases", "offers"]),
   },
   async (args) => ok(await rpc("delete_entity", args))
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lotux-mcp",
-  "version": "0.4.0",
+  "version": "0.5.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": {