lotux-mcp 0.16.0 → 0.18.0

package/README.md

@@ -66,6 +66,9 @@ Restart Claude, then try: *"list my LOTUX brands"*.
 | `content_options` / `create_flywheel` / `update_flywheel` / `list_flywheels` / `get_flywheel` | Content flywheels (Marketing → Content, agency-only): one long-form video. Start with `content_options`; give flywheels a `key` so re-runs reuse them |
 | `push_assets` / `add_asset` / `get_asset` / `list_assets` / `update_asset` / `set_asset_status` / `add_comment` / `delete_asset` | Content assets, upserted on their `key`. Statuses: scripting → production → ready_for_post → post_production → to_review → revisions → approved → live → testing → scaling → turned_off. Content you write lands in `to_review`; Claude can't set revisions, approve, or set live / testing / scaling / turned_off; deleting signed-off work needs `force`. Each asset carries `raw_footage_url` (raw files folder) and `final_asset_url` (the export — a change sends it to review), plus its content ID (`code`) and `name` = `"<code> - <title>"`; pass `code` instead of `asset_id` anywhere |
 | `get_setup_checks` / `set_setup_check` | A flywheel's setup checklist (Instagram auto-replies, setter replies, reel covers, YouTube, Klaviyo flow) — tick a step by `check_key` after doing it |
+| `list_team` / `get_team_member` / `update_team_member` | HR (agency-only, needs HR access): the team — role, lead, status, dates, KPIs, archive/restore. No pay, no delete, no invites (app only) |
+| `list_job_roles` / `get_job_role` / `update_job_role` / `create_job_role` | HR → Responsibilities: role templates (responsibilities, KPIs, capacity, owned columns). Lists are replaced whole |
+| `list_sops` / `get_sop` / `suggest_sop_change` / `create_sop_draft` | SOPs (Brain → SOPs). Claude only **suggests** changes: the SOP owner or an editor approves them in LOTUX, and the changelog shows the person "(via Claude)". One open suggestion per person per SOP (a new one replaces it). New SOPs start as a draft (needs Brain edit). No approve, edit, publish or delete over MCP |
 
 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

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.16.0" });
+const server = new McpServer({ name: "lotux", version: "0.18.0" });
 
 // ── Reads ─────────────────────────────────────────────────────────────────────
 
@@ -589,8 +589,8 @@ server.tool(
 
 const PLATFORMS = ["youtube", "youtube_shorts", "instagram", "tiktok", "linkedin", "x", "email", "meta_ads", "opt_in_page", "google_doc", "internal"];
 // Statuses follow production. You may set the first five; revisions,
-// approved, live, testing, scaling and turned_off are a human's call.
-const STATUSES = ["scripting", "production", "ready_for_post", "post_production", "to_review", "revisions", "approved", "live", "testing", "scaling", "turned_off"];
+// approved, to_launch, live, testing, scaling, turned_off and archived are a human's call.
+const STATUSES = ["scripting", "production", "ready_for_post", "post_production", "to_review", "revisions", "approved", "to_launch", "live", "testing", "scaling", "turned_off", "archived"];
 const CLAUDE_STATUSES = ["scripting", "production", "ready_for_post", "post_production", "to_review"];
 // video = "To long form".
 const CTAS = ["none", "video", "lead_magnet", "dm_keyword", "booking", "follow"];
@@ -613,6 +613,7 @@ const assetRef = {
 const assetFields = {
   asset_type: z.enum(ASSET_TYPES).optional(),
   title: z.string().optional().describe("Card title. long_form: the YouTube title"),
+  ad_format: z.enum(["video", "static"]).optional().describe('VSL + Follower ads: its Dropbox folder (Video/ or Static/). Left out = "static" when the title says static, else video'),
   platform: z.enum(PLATFORMS).optional().describe("Defaults from the type"),
   cross_post: z.array(z.enum(PLATFORMS)).optional().describe("Also posted on (defaults from the type)"),
   account: z.enum(["personal", "company"]).optional().describe("personal = Niels, company = the agency"),
@@ -773,7 +774,7 @@ server.tool(
 
 server.tool(
   "set_asset_status",
-  "Move an asset through scripting, production, ready_for_post, post_production or to_review (to_review hands it to a human). Revisions, approved, live, testing, scaling and turned_off are a human's call in LOTUX.",
+  "Move an asset through scripting, production, ready_for_post, post_production or to_review (to_review hands it to a human). Revisions, approved, to_launch, live, testing, scaling, turned_off and archived are a human's call in LOTUX.",
   {
     ...assetRef,
     status: z.enum(CLAUDE_STATUSES),
@@ -817,6 +818,170 @@ server.tool(
   async (args) => ok(await rpc("set_setup_check", args))
 );
 
+// ---------------------------------------------------------------------------
+// HR (agency only): the team and the role templates (Responsibilities).
+// Needs HR access in LOTUX. Pay, contracts, documents, deleting people and
+// invites stay in the app on purpose.
+// ---------------------------------------------------------------------------
+
+const kpiShape = z.object({
+  label: z.string(),
+  target: z.string().nullable().optional(),
+  source: z.string().nullable().optional(),
+});
+
+server.tool(
+  "list_team",
+  "Everyone at the agency in HR: name, job role, lead, is_lead, status (onboarding / active / left), employment, start/end date, LOTUX login yes/no. Archived and left people only with include_archived. No pay.",
+  { include_archived: z.boolean().optional(), account_id: z.string().optional().describe("Agency id; omit for your own agency") },
+  async (args) => ok(await rpc("list_team", args))
+);
+
+server.tool(
+  "get_team_member",
+  "One person in HR: role, lead, who they lead, contact fields, their own KPIs (else the role's apply), access checklist and their last 20 notes. No pay.",
+  { member: z.string().describe("Person id or (part of) their name"), account_id: z.string().optional() },
+  async (args) => ok(await rpc("get_team_member", args))
+);
+
+server.tool(
+  "update_team_member",
+  "Change a person in HR. Only the fields you send change. role and lead take a name or id (null clears). archived true hides them from HR lists, the lead picker and payroll (data kept); false restores. kpis replaces their own KPI list ([] = use the role's KPIs). Can't change pay, delete people or send invites — do that in the app.",
+  {
+    member: z.string().describe("Person id or name"),
+    name: z.string().optional(),
+    role: z.string().nullable().optional().describe("Job role name or id (list_job_roles)"),
+    lead: z.string().nullable().optional().describe("Lead's name or id"),
+    is_lead: z.boolean().optional(),
+    status: z.enum(["onboarding", "active", "left"]).optional(),
+    employment: z.enum(["employee", "freelance"]).nullable().optional(),
+    start_date: z.string().nullable().optional().describe("YYYY-MM-DD"),
+    end_date: z.string().nullable().optional().describe("YYYY-MM-DD"),
+    lotux_email: z.string().nullable().optional(),
+    personal_email: z.string().nullable().optional(),
+    phone: z.string().nullable().optional(),
+    archived: z.boolean().optional(),
+    kpis: z.array(kpiShape).optional(),
+    account_id: z.string().optional(),
+  },
+  async (args) => ok(await rpc("update_team_member", args))
+);
+
+server.tool(
+  "list_job_roles",
+  "The role templates in HR → Responsibilities: id, name, one-line summary and how many people have the role.",
+  { account_id: z.string().optional() },
+  async (args) => ok(await rpc("list_job_roles", args))
+);
+
+server.tool(
+  "get_job_role",
+  "One role template in full: title, one-liner, what they obsess over, who they work with, what failure looks like, what they're not responsible for, responsibilities, KPIs, capacity, the LOTUX columns they own, and who has the role.",
+  { role: z.string().describe("Role id or exact name"), account_id: z.string().optional() },
+  async (args) => ok(await rpc("get_job_role", args))
+);
+
+const roleFields = {
+  role_label: z.string().nullable().optional(),
+  title: z.string().nullable().optional(),
+  one_line: z.string().nullable().optional(),
+  obsess_over: z.string().nullable().optional(),
+  works_with: z.string().nullable().optional(),
+  failure_looks_like: z.string().nullable().optional(),
+  not_responsible_for: z.string().nullable().optional(),
+  kpi_headline: z.string().nullable().optional(),
+  kpi_detail: z.string().nullable().optional(),
+  capacity_count: z.number().int().nonnegative().nullable().optional(),
+  capacity_unit: z.enum(["clients", "accounts", "brands"]).nullable().optional(),
+  software_columns: z.array(z.string()).optional().describe("LOTUX columns this role owns"),
+  responsibilities: z.array(z.string()).optional().describe("Replaces the whole list, in order"),
+  kpis: z.array(kpiShape).optional().describe("Replaces the whole list, in order"),
+};
+
+server.tool(
+  "update_job_role",
+  "Change a role template (HR → Responsibilities). Only the fields you send change; responsibilities and kpis replace the whole list, so send the full list. new_name renames the role.",
+  {
+    role: z.string().describe("Role id or exact name"),
+    new_name: z.string().optional(),
+    ...roleFields,
+    account_id: z.string().optional(),
+  },
+  async (args) => ok(await rpc("update_job_role", args))
+);
+
+server.tool(
+  "create_job_role",
+  "Create a role template (starts with the standard Start here flow) and fill it in one go. An existing role with the same name is returned (and updated with the fields you send) instead of a duplicate.",
+  { name: z.string(), ...roleFields, account_id: z.string().optional() },
+  async (args) => ok(await rpc("create_job_role", args))
+);
+
+// ── SOPs (Brain → SOPs) ────────────────────────────────────────────────────
+// Claude reads SOPs and SUGGESTS changes; a person approves them in LOTUX.
+// There is deliberately no tool to approve, edit or publish an SOP.
+
+const sopStep = z.object({
+  title: z.string(),
+  detail: z.string().optional(),
+  sub: z.array(z.string()).optional().describe("Sub-points"),
+  when: z.string().optional().describe('Timing chip, e.g. "Day 0, 60 min"'),
+});
+const sopContent = {
+  summary: z.string().optional().describe("One line, shown on the card"),
+  purpose: z.string().optional(),
+  scope: z.string().optional().describe('"At a glance": lines like "When: …" / "Trigger: …"'),
+  materials: z.array(z.string()).optional().describe("Before you start"),
+  steps: z.array(sopStep).optional().describe("The FULL ordered list of steps. Who does a step is kept from the step at the same position."),
+  done_when: z.string().optional(),
+  troubleshooting: z.array(z.object({ risk: z.string(), fix: z.string() })).optional().describe("Watch out"),
+  tools: z.array(z.string()).optional(),
+  video_url: z.string().nullable().optional().describe("Walkthrough link (http/https)"),
+};
+
+server.tool(
+  "list_sops",
+  "The SOPs in LOTUX (Brain → SOPs): code, title, phase, status, owner, number of steps and open suggestions. Archived ones are left out unless you ask for status archived.",
+  {
+    phase: z.string().optional().describe("Phase key, e.g. lead, sell, contract, shoot, launch, run"),
+    status: z.enum(["draft", "review", "published", "archived"]).optional(),
+    search: z.string().optional(),
+    account_id: z.string().optional().describe("Omit for the agency"),
+  },
+  async (args) => ok(await rpc("list_sops", args))
+);
+
+server.tool(
+  "get_sop",
+  "One SOP in full: purpose, at a glance, before you start, steps (with who does them), done when, watch out, tools, open suggestions and the changelog.",
+  { sop: z.string().describe("SOP id, code (e.g. OC1) or title"), account_id: z.string().optional() },
+  async (args) => ok(await rpc("get_sop", args))
+);
+
+server.tool(
+  "suggest_sop_change",
+  "Suggest a change to an SOP. Nothing changes until the SOP owner or an editor approves it in LOTUX; the changelog then shows you (via Claude) as the author. Send only the fields you change; lists (steps, materials, troubleshooting, tools) replace the whole list. One open suggestion per person per SOP: a new one replaces your earlier one.",
+  {
+    sop: z.string().describe("SOP id, code or title"),
+    changes: z.object(sopContent).extend({ title: z.string().optional() }),
+    reason: z.string().describe("Why this change is needed (the approver reads it)"),
+    account_id: z.string().optional(),
+  },
+  async (args) => ok(await rpc("suggest_sop_change", args))
+);
+
+server.tool(
+  "create_sop_draft",
+  "Create a new SOP as a DRAFT (needs Brain edit rights). It is not live: a person sets owner and category and publishes it in LOTUX. The changelog logs it as created by you (via Claude). An existing title is refused: suggest a change to that SOP instead.",
+  {
+    title: z.string(),
+    phase: z.string().optional().describe("Board column: lead, sell, contract, team_onboard, client_onboard, preprod, shoot, production, launch, run, retain, offboard, always, team"),
+    ...sopContent,
+    account_id: z.string().optional(),
+  },
+  async (args) => ok(await rpc("create_sop_draft", args))
+);
+
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

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