lotux-mcp 0.15.0 → 0.17.0

package/README.md

@@ -66,6 +66,8 @@ 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 |
 
 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.15.0" });
+const server = new McpServer({ name: "lotux", version: "0.17.0" });
 
 // ── Reads ─────────────────────────────────────────────────────────────────────
 
@@ -91,7 +91,7 @@ server.tool(
 
 server.tool(
   "run_client_setup",
-  "Run client setup for a brand: slug, second brain from the template, the agentic workspace folder + CLIENT.md settings block, and (once the brand has connected Dropbox) the linked Dropbox client folder. It already runs by itself when a brand is created and when it connects Dropbox; run it again to fill gaps. Only creates what's missing; running it twice changes nothing. Skipped for clients that aren't active. dry_run: true returns the plan without changing anything. Returns a report per step (created / linked / updated / already there / failed + reason).",
+  "Run client setup for a brand: slug, second brain (an \"Agentic workspace\" page plus Client Feedback and Basic Rules folders in its \"Exposed to MCP\" section), the agentic workspace folder + CLIENT.md settings block, and (once the brand has connected Dropbox) the linked Dropbox client folder. It already runs by itself when a brand is created and when it connects Dropbox; run it again to fill gaps. Only creates what's missing; running it twice changes nothing. Skipped for clients that aren't active. dry_run: true returns the plan without changing anything. Returns a report per step (created / linked / updated / already there / failed + reason).",
   {
     account_id: z.string().describe("Brand id from list_brands"),
     dry_run: z.boolean().optional(),
@@ -101,14 +101,14 @@ server.tool(
 
 server.tool(
   "list_kb_folders",
-  "The folders of a Kennisbank workspace (id, name, parent_id). Use a folder id as folder_id in create_kb_doc.",
+  "The folders in a Kennisbank workspace's \"Exposed to MCP\" section, the only part of a second brain the MCP can see (id, name, parent_id, path; parent_id null = directly in the section). Use a folder id as folder_id in create_kb_doc.",
   { workspace_id: z.string().describe("Workspace id from list_kb_workspaces or get_brand") },
   async (args) => ok(await rpc("list_kb_folders", args))
 );
 
 server.tool(
   "create_kb_folder",
-  "Create a folder in a Kennisbank workspace (at the root, or inside parent_id). Returns the folder id.",
+  "Create a folder in a Kennisbank workspace's \"Exposed to MCP\" section (at its top level, or inside parent_id). Returns the folder id.",
   {
     workspace_id: z.string(),
     name: z.string(),
@@ -536,28 +536,28 @@ server.tool(
 
 server.tool(
   "list_kb_workspaces",
-  "List the Kennisbank (knowledge base) workspaces you can access — markdown docs the team and AI share. Returns id, name, visibility. Use a workspace id with list_kb_docs / create_kb_doc.",
+  "List the Kennisbank (knowledge base) workspaces you can access — markdown docs the team and AI share. Returns id, name, visibility. Use a workspace id with list_kb_docs / create_kb_doc. Only each workspace's \"Exposed to MCP\" section is visible to the MCP; the rest is the team's own notes.",
   {},
   async () => ok(await rpc("list_kb_workspaces"))
 );
 
 server.tool(
   "list_kb_docs",
-  "List the pages in a Kennisbank workspace (id, title, folder path). Use a doc id with get_kb_doc.",
+  "List the pages in a Kennisbank workspace's \"Exposed to MCP\" section (id, title, folder path inside the section; \"\" = its top level). Pages outside the section are not listed. Use a doc id with get_kb_doc.",
   { workspace_id: z.string().describe("Workspace id from list_kb_workspaces") },
   async ({ workspace_id }) => ok(await rpc("list_kb_docs", { workspace_id }))
 );
 
 server.tool(
   "get_kb_doc",
-  "Read one Kennisbank page's full markdown content by id.",
+  "Read one Kennisbank page's full markdown content by id. Only pages in the \"Exposed to MCP\" section can be read.",
   { doc_id: z.string() },
   async ({ doc_id }) => ok(await rpc("get_kb_doc", { doc_id }))
 );
 
 server.tool(
   "create_kb_doc",
-  "Create a new markdown page in a Kennisbank workspace. Returns the new doc id. content is markdown; folder_id is optional (root if omitted).",
+  "Create a new markdown page in a Kennisbank workspace's \"Exposed to MCP\" section. Returns the new doc id. content is markdown; folder_id is optional (top of the section if omitted) and must be a folder from list_kb_folders.",
   {
     workspace_id: z.string().describe("Workspace id from list_kb_workspaces"),
     title: z.string(),
@@ -569,7 +569,7 @@ server.tool(
 
 server.tool(
   "update_kb_doc",
-  "Update a Kennisbank page's title and/or markdown content. Omitted fields are left unchanged.",
+  "Update a Kennisbank page's title and/or markdown content (pages in the \"Exposed to MCP\" section only). Omitted fields are left unchanged.",
   {
     doc_id: z.string(),
     title: z.string().optional(),
@@ -817,6 +817,105 @@ 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))
+);
+
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

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