@glie/mcp-polaris 0.13.0 → 0.18.2

package/README.md

@@ -48,8 +48,10 @@ it. The same token authenticates this server and the `polaris` CLI as you.
 ## Tools
 
 **Roadmap.** `polaris.me`, `polaris.project.*`, `polaris.milestone.*` (incl.
-`update` to refine a spec, `attachment_*` to list/attach/remove the visual
-references anchored in its body), `polaris.task.*` (incl. `update`,
+`update` to refine a spec or move its dates, `demote` to send one with no tasks back to the
+idea list, `attachment_*` to list/attach/remove the visual
+references anchored in its body), `polaris.idea.*` (incl. `promote` into a milestone and
+`promote_task` into a standalone task with no milestone), `polaris.task.*` (incl. `update`,
 `transition`, `approve`, `schedule`, `attachment_*` — same as the milestone's,
 plus how a milestone reference gets forwarded here via
 `source_attachment_id`), `polaris.stack.*` (`list` / `get` / `release` for the
@@ -57,12 +59,22 @@ approval Release Candidate flow), `polaris.agent.*`, `polaris.team.*`,
 `polaris.claude_md.get`, `polaris.framework.list`.
 
 **Helpdesk.** `polaris.ticket.*` (the customer conversation: `reply`, `pass`,
-`frame_issue`, `link_issue`) and `polaris.issue.*` (the problem: `open`,
-`transition`, `add_task`). N tickets can dedup onto one issue, and one issue
-fans out into N tasks.
-
-**Context, read-only.** `polaris.activity.list` (what happened) and
-`polaris.chat.get` / `polaris.chat.messages` (comments agents left on a scope).
+`frame_issue`, `link_issue`, `attachment_list`) and `polaris.issue.*` (the problem:
+`open`, `transition`, `add_task`). N tickets can dedup onto one issue, and one issue
+fans out into N tasks. A reply carries files through `attachment_ids`: upload each
+one to `POST /api/tickets/:id/attachments` first (this server does not carry bytes),
+then paste its `marker` into `body_md` to draw it inside the message.
+
+**Context, read-only.** `polaris.activity.list` (what happened),
+`polaris.chat.get` / `polaris.chat.messages` (comments agents left on a scope),
+and `polaris.task.run_lines` (the thread of an agent's run on a task: what it was
+asked, said, ran and got back; human tokens only).
+
+**What a creative delivered.** `polaris.task.creatives` lists every version of a
+creative task with its files and the words that go out beside them (caption,
+title, copy). `polaris.task.creative_download` saves one version to this machine
+as a zip of its slides, so a video can be opened, its frames pulled and its
+sound measured.
 
 Run `tools/list` against the server for the full, current set.
 

package/dist/index.js

@@ -2,6 +2,9 @@
 // @bun
 
 // ../../src/mcp/index.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
 import { createInterface } from "readline";
 
 // ../../src/lib/media-types.ts
@@ -13,11 +16,22 @@ var MEDIA_TYPES = [
   { mime: "video/quicktime", kind: "video", ext: ".mov", aliases: [] },
   { mime: "video/webm", kind: "video", ext: ".webm", aliases: [] }
 ];
+function mimesOfKind(kind) {
+  return MEDIA_TYPES.filter((t) => t.kind === kind).map((t) => t.mime);
+}
 function allMimes() {
   return MEDIA_TYPES.map((t) => t.mime);
 }
+var RECEIVED_IMAGE_MIMES = ["image/gif"];
+var INLINE_MIMES = new Set([
+  ...mimesOfKind("image"),
+  ...mimesOfKind("video"),
+  ...RECEIVED_IMAGE_MIMES
+]);
 
 // ../../src/mcp/index.ts
+var VERSION = "0.18.2";
+var FRAMEWORK_KEY_DOC = "optional \u2014 a key from polaris.framework.list. Leave it out when none applies: a framework is for founding a large domain, and most milestones take none. An unknown key is refused (400) with the keys that exist.";
 var BASE = process.env.POLARIS_URL ?? "http://127.0.0.1:7843";
 var TOKEN = process.env.POLARIS_TOKEN ?? "";
 var PROJECT = process.env.POLARIS_PROJECT ?? "";
@@ -84,17 +98,24 @@ var INSTRUCTIONS = [
   "\u2022 N tickets \u2192 1 issue (duplicates dedup onto one problem) \xB7 1 ticket \u2192 N issues \xB7 1 issue \u2192 N tasks (iterative fix).",
   "\u2022 Flow: ticket.create \u2192 ticket.reply / ticket.pass (communicate) \u2192 ticket.frame_issue (or issue.open standalone; ticket.link_issue to dedup)",
   "    \u2192 issue.add_task \xD7N (a planner decomposes) \u2192 task.transition the tasks through dev\u2192test\u2192approval\u2192release.",
-  "\u2022 The ball: ticket.pass sets whose move it is (customer|team); a message never flips it. A customer reply auto-reopens a resolved/closed ticket.",
+  "\u2022 The ball: ticket.pass sets whose move it is (customer|team). A team message never moves it; a customer reply brings it back to the team and auto-reopens a resolved/closed ticket.",
   "",
   "WHICH TOOL WHEN:",
   `\u2022 "What's mine / what next?"      \u2192 polaris.task.list (assignee \u2026="self", status=\u2026)`,
   '\u2022 "Read X in full"                \u2192 polaris.task.get \xB7 milestone.get \xB7 project.get \xB7 stack.get',
   '\u2022 "Fix an unclear brief"          \u2192 polaris.task.update / milestone.update (PATCH description_md)',
   '\u2022 "Catch up \u2014 what happened/said?"\u2192 polaris.activity.list (events) \xB7 polaris.chat.messages (comments left by agents)',
+  `\u2022 "What is the agent doing / why?" \u2192 polaris.task.run_lines (the run's thread: prompt, reasoning, commands, results; human-only)`,
+  '\u2022 "What did this creative deliver?" \u2192 polaris.task.creatives (versions, files, caption) \xB7 polaris.task.creative_download (the file, saved locally)',
   '\u2022 "Move my task forward"          \u2192 polaris.task.transition(id, status)',
   `\u2022 "It's reviewed, ship it"        \u2192 polaris.task.approve (human-only); ship several together via polaris.stack.* \u2192 stack.release`,
   `\u2022 "My task is stuck in a blocked stack" \u2192 fix the conflict on YOUR branch (rebase agent/task-N onto dev, push) \u2014 the rc PR flips to ready automatically. A stacked task can't advance individually; never merge the rc PR by hand.`,
   '\u2022 "Break a milestone into tasks"  \u2192 polaris.milestone.qa_list / qa_answer (while in discovery)',
+  '\u2022 "Jot something down for later" \u2192 polaris.idea.create (a title is enough). NO dates: an idea is not a milestone.',
+  '\u2022 "What have we already thought of?" \u2192 polaris.idea.list \u2014 read it before proposing work; it also holds what was turned down',
+  '\u2022 "This idea is now real"        \u2192 polaris.idea.promote (needs end_date + team) \u2014 the one door from the idea list to the timeline',
+  '\u2022 "This idea is one small piece of dev work" \u2192 polaris.idea.promote_task \u2014 a standalone task, no milestone, straight into the dev backlog (human-only)',
+  '\u2022 "This milestone was only a hunch" \u2192 polaris.milestone.demote \u2014 back to the idea list, only while it has no tasks (human-only)',
   `\u2022 "Triage support / what's waiting?" \u2192 polaris.ticket.list (status, project_key) \u2014 P1 first`,
   '\u2022 "Reply to a customer / hand off"  \u2192 polaris.ticket.reply then polaris.ticket.pass(to)',
   '\u2022 "Turn a report into work"         \u2192 polaris.ticket.frame_issue \u2192 polaris.issue.add_task \xD7N (framing is HUMAN-only; the helpdesker proposes it)',
@@ -162,16 +183,111 @@ var TOOLS = [
   },
   {
     name: "polaris.project.arm",
-    description: "Arm a project for auto-approval (human-only): while armed, dev work that reaches `approval` CLEAN is approved on your behalf \u2014 no per-task click \u2014 and follows the normal path to release. Escalated tasks, mkt creatives, and support work still wait for a person; a merge that fails leaves the task in `approval`. Idempotent.",
+    description: "Arm a project for auto-approval (human-only): while armed, a task an agent writes in `draft` (discovery's batch, a campaign's pieces) is approved into `backlog` on your behalf, with no per-task click. Tasks a person creates by hand and support work still wait in `draft`. `approval \u2192 release` is never automatic. Not retroactive: drafts already there stay. Idempotent.",
     inputSchema: objSchema({ key: strSchema("project key (e.g. saasA)") }, ["key"]),
     call: async (args) => (await apiCall("POST", `/api/projects/${args.key}/arm`)).body
   },
   {
     name: "polaris.project.disarm",
-    description: "Disarm a project (human-only). Immediate effect: the next task to reach `approval` waits for a person again. Work already parked in `approval` is untouched. Idempotent.",
+    description: "Disarm a project (human-only). Immediate effect: the next task an agent writes in `draft` waits for a person again. Tasks already moved to `backlog` stay there. Idempotent.",
     inputSchema: objSchema({ key: strSchema("project key (e.g. saasA)") }, ["key"]),
     call: async (args) => (await apiCall("POST", `/api/projects/${args.key}/disarm`)).body
   },
+  {
+    name: "polaris.idea.list",
+    description: "List a project's IDEAS \u2014 what might matter later, before it has a date. An idea is not a milestone: no dates, no tasks, never on the timeline. Read this before proposing new work: it is where the things already thought of (and the things already turned down) live. Optional status filter: open|promoted|dropped.",
+    inputSchema: objSchema({
+      project_key: strSchema("project key (e.g. saasA)"),
+      status: strSchema("open|promoted|dropped")
+    }, ["project_key"]),
+    call: async (args) => {
+      const qs = typeof args.status === "string" ? `?status=${args.status}` : "";
+      return (await apiCall("GET", `/api/projects/${args.project_key}/ideas${qs}`)).body;
+    }
+  },
+  {
+    name: "polaris.idea.create",
+    description: "Capture an idea in a project. The title is the only required field \u2014 capturing has to cost less than losing the idea. No dates: if it has a deadline it is a milestone, so use polaris.milestone.create instead. Needs a token.",
+    inputSchema: objSchema({
+      project_key: strSchema("project key (e.g. saasA)"),
+      title: strSchema("one line \u2014 what the idea is"),
+      note_md: strSchema("optional: what it is and why now; becomes the milestone's description on promotion"),
+      team: strSchema("optional: dev|mkt \u2014 leave empty if you don't know yet")
+    }, ["project_key", "title"]),
+    call: async (args) => {
+      const { project_key, ...body } = args;
+      return (await apiCall("POST", `/api/projects/${project_key}/ideas`, body)).body;
+    }
+  },
+  {
+    name: "polaris.idea.update",
+    description: "Refine an open idea \u2014 its title, note or team. A promoted idea is refused: it became a milestone, and the milestone is the truth from then on (use polaris.milestone.update). Needs a token.",
+    inputSchema: objSchema({
+      project_key: strSchema(),
+      id: intSchema("idea id"),
+      title: strSchema(),
+      note_md: strSchema(),
+      team: strSchema("dev|mkt")
+    }, ["project_key", "id"]),
+    call: async (args) => {
+      const { project_key, id, ...body } = args;
+      return (await apiCall("PATCH", `/api/projects/${project_key}/ideas/${id}`, body)).body;
+    }
+  },
+  {
+    name: "polaris.idea.promote",
+    description: "Promote an idea into a milestone \u2014 the one door between the idea list and the timeline. Demands what a milestone demands: end_date, and a team (unless the idea already carries one). The milestone is created and the idea stamped in ONE transaction; promoting twice returns the first milestone and writes nothing. Needs a token.",
+    inputSchema: objSchema({
+      project_key: strSchema(),
+      id: intSchema("idea id"),
+      end_date: strSchema("YYYY-MM-DD \u2014 the deadline the milestone commits to"),
+      team: strSchema("dev|mkt \u2014 required unless the idea already has one"),
+      start_date: strSchema("YYYY-MM-DD, optional"),
+      name: strSchema("optional: overrides the idea's title"),
+      description_md: strSchema("optional: overrides the idea's note"),
+      framework_key: strSchema(FRAMEWORK_KEY_DOC)
+    }, ["project_key", "id", "end_date"]),
+    call: async (args) => {
+      const { project_key, id, ...body } = args;
+      return (await apiCall("POST", `/api/projects/${project_key}/ideas/${id}/promote`, body)).body;
+    }
+  },
+  {
+    name: "polaris.idea.promote_task",
+    description: "Promote a dev idea into a STANDALONE task \u2014 one piece of work with no milestone and no deadline, born in the idea's project and straight into the dev backlog, where the project's developer agents pick it up. For work that is a goal with several tasks, use polaris.idea.promote (a milestone). A mkt idea is refused: a creative needs a campaign. Promoting twice returns the first task and writes nothing. Human-only.",
+    inputSchema: objSchema({
+      project_key: strSchema(),
+      id: intSchema("idea id"),
+      name: strSchema("optional: overrides the idea's title"),
+      description_md: strSchema("optional: overrides the idea's note (the developer's brief)")
+    }, ["project_key", "id"]),
+    call: async (args) => {
+      const { project_key, id, ...body } = args;
+      return (await apiCall("POST", `/api/projects/${project_key}/ideas/${id}/promote-task`, body)).body;
+    }
+  },
+  {
+    name: "polaris.idea.drop",
+    description: "Drop an idea, with the reason it was dropped. Reversible (polaris.idea.reopen) \u2014 dropping is not a one-way door, because almost every good idea looks bad at first. Idempotent: dropping twice keeps the first reason. Needs a token.",
+    inputSchema: objSchema({
+      project_key: strSchema(),
+      id: intSchema("idea id"),
+      reason: strSchema("why it was dropped")
+    }, ["project_key", "id"]),
+    call: async (args) => {
+      const { project_key, id, ...body } = args;
+      return (await apiCall("POST", `/api/projects/${project_key}/ideas/${id}/drop`, body)).body;
+    }
+  },
+  {
+    name: "polaris.idea.reopen",
+    description: "Put a dropped idea back on the open list, clearing its reason. Required before promoting a dropped idea \u2014 resurrecting is a decision, not a side effect. Needs a token.",
+    inputSchema: objSchema({ project_key: strSchema(), id: intSchema("idea id") }, [
+      "project_key",
+      "id"
+    ]),
+    call: async (args) => (await apiCall("POST", `/api/projects/${args.project_key}/ideas/${args.id}/reopen`, {})).body
+  },
   {
     name: "polaris.project.pause_publishing",
     description: "Pause publishing through Polaris for a product (human-only). While paused, no creative of this product goes out at its scheduled hour. It does NOT hold the clock: a piece whose hour passes meanwhile comes back to the person in `release`, like any other late piece \u2014 that is what pausing is for. Idempotent: a second call keeps the original pause, and the original reason. `reason` is optional and is what whoever finds it paused reads.",
@@ -191,9 +307,21 @@ var TOOLS = [
   },
   {
     name: "polaris.milestone.list",
-    description: "List milestones in a project.",
-    inputSchema: objSchema({ project_key: strSchema() }, ["project_key"]),
-    call: async (args) => (await apiCall("GET", `/api/projects/${args.project_key}/milestones?limit=200`)).body
+    description: "List milestones in a project. Each one comes with its whole description, so a project with a long history answers with a lot: narrow it with `status` (e.g. loop for the campaigns running now) and `team` (dev|mkt).",
+    inputSchema: objSchema({
+      project_key: strSchema(),
+      status: strSchema("draft|discovery|loop|release|done|canceled"),
+      team: strSchema("dev|mkt")
+    }, ["project_key"]),
+    call: async (args) => {
+      const qs = new URLSearchParams({ limit: "200" });
+      for (const k of ["status", "team"]) {
+        const v = args[k];
+        if (v !== undefined && v !== null)
+          qs.set(k, String(v));
+      }
+      return (await apiCall("GET", `/api/projects/${args.project_key}/milestones?${qs}`)).body;
+    }
   },
   {
     name: "polaris.milestone.get",
@@ -203,11 +331,13 @@ var TOOLS = [
   },
   {
     name: "polaris.milestone.update",
-    description: "Correct or refine a milestone's spec \u2014 PATCH its description_md (and optionally name), same idea as polaris.task.update. On a mkt campaign the market can also be corrected, while it is still in draft or discovery: after that the creatives are already bound to accounts. The campaign's rhythm, budget and channels live in the description \u2014 write them there and the briefer reads them. Needs a token.",
+    description: "Correct or refine a milestone \u2014 PATCH its description_md, name, or dates (start_date / end_date move it on the timeline; send only the one that changes, start can never fall after end), same idea as polaris.task.update. On a mkt campaign the market can also be corrected, while it is still in draft or discovery: after that the creatives are already bound to accounts. The campaign's rhythm, budget and channels live in the description \u2014 write them there and the briefer reads them. Needs a token.",
     inputSchema: objSchema({
       id: intSchema(),
       name: strSchema(),
       description_md: strSchema("full markdown brief; replaces the current description"),
+      start_date: strSchema("ISO date, e.g. 2026-06-01"),
+      end_date: strSchema("ISO date, the deadline, e.g. 2026-06-30"),
       market: {
         type: "array",
         items: { type: "string", enum: ["BR", "US", "EU"] },
@@ -220,6 +350,10 @@ var TOOLS = [
         body.name = args.name;
       if (typeof args.description_md === "string")
         body.description_md = args.description_md;
+      if (typeof args.start_date === "string")
+        body.start_date = args.start_date;
+      if (typeof args.end_date === "string")
+        body.end_date = args.end_date;
       if ("market" in args)
         body.market = args.market;
       return (await apiCall("PATCH", `/api/milestones/${args.id}`, body)).body;
@@ -231,6 +365,12 @@ var TOOLS = [
     inputSchema: objSchema({ id: intSchema(), status: strSchema() }, ["id", "status"]),
     call: async (args) => (await apiCall("POST", `/api/milestones/${args.id}/state`, { status: args.status })).body
   },
+  {
+    name: "polaris.milestone.demote",
+    description: "Send a milestone back to the idea list. Only a milestone with NO tasks (not even canceled ones), still in draft, discovery or loop, and not while a planner is breaking it into tasks. The idea it was promoted from reopens (or a new idea is captured from it) carrying the milestone's name and context; the milestone is canceled and cannot be reopened \u2014 promote the idea again instead. Demoting twice returns the first idea. Human-only.",
+    inputSchema: objSchema({ id: intSchema("milestone id") }, ["id"]),
+    call: async (args) => (await apiCall("POST", `/api/milestones/${args.id}/demote`, {})).body
+  },
   {
     name: "polaris.milestone.qa_list",
     description: "List framework Q&A rows for a milestone.",
@@ -305,10 +445,10 @@ var TOOLS = [
   },
   {
     name: "polaris.task.list",
-    description: `Find tasks \u2014 the agent's entry point. Pass assignee_agent_id="self" (or assignee_human_id="self" for a human) to get what is YOURS; add status=dev (etc.) to see only active work. Other filters: milestone_id, product_key, team.`,
+    description: `Find tasks \u2014 the agent's entry point. Pass assignee_agent_id="self" (or assignee_human_id="self" for a human) to get what is YOURS; add status=dev (etc.) to see only active work. Other filters: milestone_id (or "none" for the standalone tasks, which have no milestone), product_key, team.`,
     inputSchema: objSchema({
       status: strSchema("comma-separated subset of: draft,backlog,dev,test,approval,release,done,canceled"),
-      milestone_id: intSchema(),
+      milestone_id: strSchema('a milestone id, or "none" for the standalone tasks (no milestone)'),
       product_key: strSchema("project key, e.g. saasA"),
       team: strSchema("dev|mkt"),
       assignee_agent_id: strSchema('agent id, or "self" for the calling agent'),
@@ -342,9 +482,10 @@ var TOOLS = [
   },
   {
     name: "polaris.task.create",
-    description: "Create a task within a milestone. A marketing CREATIVE (a task in an mkt campaign) carries WHERE IT GOES: `presence_id`, one of the destinations from polaris.destination.list. The channel and the market are read from that destination, and sending them here is refused. It also takes format + scheduled_date (the publish day / calendar slot) + platform (if this creative is individually paid). A CAROUSEL (format=carrossel) also requires `slides` (2..10) \u2014 without it the call is refused, because a carousel with no declared size ships one image.",
+    description: "Create a task within a milestone \u2014 or, for one small piece of DEV work with no milestone, a STANDALONE task in a project: send project_key instead of milestone_id (human-only, team dev, no creative fields). A marketing CREATIVE (a task in an mkt campaign) carries WHERE IT GOES: `presence_id`, one of the destinations from polaris.destination.list. The channel and the market are read from that destination, and sending them here is refused. It also takes format + scheduled_date (the publish day / calendar slot) + platform (if this creative is individually paid). A CAROUSEL (format=carrossel) also requires `slides` (2..10) \u2014 without it the call is refused, because a carousel with no declared size ships one image.",
     inputSchema: objSchema({
-      milestone_id: intSchema(),
+      milestone_id: intSchema("the milestone it belongs to \u2014 or omit it and send project_key"),
+      project_key: strSchema("instead of milestone_id: a standalone dev task in this project, with no milestone (human-only)"),
       name: strSchema(),
       description_md: strSchema(),
       status: strSchema("draft \u2014 the only status a task can be created in; it reaches the rest by being moved, one legal step at a time (polaris.task.transition)"),
@@ -359,7 +500,7 @@ var TOOLS = [
       scheduled_date: strSchema("mkt: publish day (ISO date) \u2014 the calendar slot"),
       platform: strSchema("mkt: ad platform if this creative is individually paid"),
       asset_url: strSchema("mkt: URL of the produced creative asset (image/video) for the reviewer")
-    }, ["milestone_id", "name"]),
+    }, ["name"]),
     call: async (args) => (await apiCall("POST", "/api/tasks", args)).body
   },
   {
@@ -535,13 +676,29 @@ var TOOLS = [
   },
   {
     name: "polaris.ticket.reply",
-    description: "Add a message to a ticket's conversation. Default side=team (you replying); an adapter relaying a customer message passes side=customer. Sending a message does NOT pass the ball.",
-    inputSchema: objSchema({ id: intSchema(), body_md: strSchema(), side: strSchema("customer|team") }, ["id", "body_md"]),
+    description: "Add a message to a ticket's conversation. Default side=team (you replying); an adapter relaying a customer message passes side=customer. Sending a message does NOT pass the ball. To send FILES with the reply (a screenshot, a screencast of the thing you are describing): upload each one first \u2014 `curl -sS -H \"Authorization: Bearer $POLARIS_TOKEN\" -F file=@clip.mp4 $POLARIS_URL/api/tickets/<id>/attachments` \u2014 then pass the ids it returns as attachment_ids. Paste each one's `marker` into body_md where it belongs and the image or video is drawn THERE, between your paragraphs; an attachment whose marker you never placed falls to a strip at the foot of the message, which for a screencast is the wrong place. Up to 15MB per file.",
+    inputSchema: objSchema({
+      id: intSchema(),
+      body_md: strSchema(),
+      side: strSchema("customer|team"),
+      attachment_ids: {
+        type: "array",
+        items: { type: "integer" },
+        description: "Ids from the attachment upload above (or from ticket.attachment_list, where sent=false). They ride on THIS message and become visible with it."
+      }
+    }, ["id", "body_md"]),
     call: async (args) => (await apiCall("POST", `/api/tickets/${args.id}/messages`, {
       body_md: args.body_md,
-      side: args.side
+      side: args.side,
+      attachment_ids: args.attachment_ids
     })).body
   },
+  {
+    name: "polaris.ticket.attachment_list",
+    description: 'Every file on this ticket \u2014 what the customer sent and what we have attached. Each row carries a `marker` (`![name](ref:N)` for an image, `[name](ref:N)` for a video) to paste into a reply\'s body_md so the file is drawn inside the message instead of in a list under it, and `sent` (false while it has been uploaded and no message names it yet \u2014 nobody sees it until a reply does). A file (PDF, log) has no marker: there is nothing to draw, and it rides as a download chip. Upload with `curl -sS -H "Authorization: Bearer $POLARIS_TOKEN" -F file=@shot.png $POLARIS_URL/api/tickets/<id>/attachments` \u2014 this call does not carry bytes.',
+    inputSchema: objSchema({ id: intSchema() }, ["id"]),
+    call: async (args) => (await apiCall("GET", `/api/tickets/${args.id}/attachments`)).body
+  },
   {
     name: "polaris.ticket.pass",
     description: "Pass the ball \u2014 whose move it is. to=customer after you reply; to=team to pull it back. Manual + idempotent.",
@@ -752,7 +909,7 @@ var TOOLS = [
   },
   {
     name: "polaris.chat.messages",
-    description: "Read the comments/context agents and humans left on a scope (e.g. task 42) \u2014 free-text notes, decisions, @mentions. Pass the scope; the chat id is resolved for you. Read-only (posting isn't exposed yet).",
+    description: "Read the comments/context agents and humans left on a scope (e.g. task 42) \u2014 free-text notes, decisions, @mentions, and the handover notes that travel with a task's moves (what the maker delivered, why a reviewer sent it back). Pass the scope; the chat id is resolved for you. To write one, polaris.chat.post.",
     inputSchema: objSchema({
       scope_type: strSchema("task|milestone|project|agent_dm|human_dm|general"),
       scope_id: intSchema(),
@@ -767,6 +924,58 @@ var TOOLS = [
       return (await apiCall("GET", `/api/chats/${chatId}/messages${qs}`)).body;
     }
   },
+  {
+    name: "polaris.task.run_lines",
+    description: "Watch an agent work: the THREAD of one run on a task \u2014 what it was asked (`prompt`), what it said (`said`), what it ran (`ran`, tool + full input), what came back (`back`), and the rest (`other`). This is the backstage of a run; for the comments left on the task use polaris.chat.messages. HUMAN ONLY: an agent token gets 403 (one agent reading another's reasoning changes what it can judge). A task has one run per agent session (the brief, whoever made the piece, the reviewer); the response's `runs` lists them, newest first, and without `session` you get the newest. Bodies are whole, never truncated, and the first line is the entire prompt \u2014 page with `limit`, then pass the response's `next_after` as `after` to read on or to follow a live run.",
+    inputSchema: objSchema({
+      id: intSchema("task id"),
+      session: strSchema("a session_id from `runs` \u2014 which run to read; omit for the newest"),
+      after: intSchema("return only lines with seq greater than this (the previous `next_after`)"),
+      limit: intSchema("how many lines (default 500, max 2000)")
+    }, ["id"]),
+    call: async (args) => {
+      const qs = new URLSearchParams;
+      for (const k of ["session", "after", "limit"]) {
+        const v = args[k];
+        if (v !== undefined && v !== null)
+          qs.set(k, String(v));
+      }
+      const r = await apiCall("GET", `/api/tasks/${args.id}/run-lines${qs.toString() ? `?${qs}` : ""}`);
+      return r.body;
+    }
+  },
+  {
+    name: "polaris.task.creatives",
+    description: "What a creative task has actually delivered: every version, newest first, each slot with its file (`mime`, `url`, `status`) and the words that go out beside it (`caption`, `title`, `copy`, `description`). Read this to judge a piece; the maker's handover note is in polaris.chat.messages on the task. The files sit behind the same login as the API, so to look at one, polaris.task.creative_download.",
+    inputSchema: objSchema({ id: intSchema("task id") }, ["id"]),
+    call: async (args) => (await apiCall("GET", `/api/tasks/${args.id}/creatives`)).body
+  },
+  {
+    name: "polaris.task.creative_download",
+    description: "Save one version of a creative to THIS machine, as a zip of its slides in slot order (slide-01.mp4, slide-02.png, ...), so its frames can be pulled and its sound measured. Newest version unless `version` is given; only a version whose slides are all ready exists to download (404 otherwise). Writes into `dir` (default: the system temp folder) and returns the file's absolute path and size; unzip it to look inside.",
+    inputSchema: objSchema({
+      id: intSchema("task id"),
+      version: intSchema("which version (polaris.task.creatives lists them); omit for the newest"),
+      dir: strSchema("folder to save into; created if missing. Default: the system temp folder")
+    }, ["id"]),
+    call: async (args) => {
+      const qs = typeof args.version === "number" ? `?version=${args.version}` : "";
+      const headers = {};
+      if (TOKEN)
+        headers.Authorization = `Bearer ${TOKEN}`;
+      const res = await fetch(`${BASE}/api/tasks/${args.id}/creative.zip${qs}`, { headers });
+      if (!res.ok) {
+        return { status: res.status, body: await res.text() };
+      }
+      const bytes = new Uint8Array(await res.arrayBuffer());
+      const dir = resolve(typeof args.dir === "string" && args.dir ? args.dir : tmpdir());
+      mkdirSync(dir, { recursive: true });
+      const name = `task-${args.id}-${typeof args.version === "number" ? `v${args.version}` : "latest"}.zip`;
+      const path = join(dir, name);
+      writeFileSync(path, bytes);
+      return { data: { path, bytes: bytes.length } };
+    }
+  },
   {
     name: "polaris.project.update",
     description: "Update a project (human-only): repo_url, name, status (active|paused|archived), owner_human_id. Brand/context live in the CLAUDE.md \u2014 use polaris.project.claude_md_set.",
@@ -987,7 +1196,7 @@ var TOOLS = [
       team: strSchema("dev|mkt"),
       end_date: strSchema("ISO date, e.g. 2026-06-30"),
       start_date: strSchema("ISO date (optional)"),
-      framework_key: strSchema(),
+      framework_key: strSchema(FRAMEWORK_KEY_DOC),
       description_md: strSchema(),
       market: {
         type: "array",
@@ -1094,7 +1303,7 @@ var TOOLS = [
         items: { type: "string" },
         description: "developer|tester|planner|helpdesker"
       },
-      framework_key: strSchema()
+      framework_key: strSchema("optional \u2014 the team's default framework: a key from polaris.framework.list")
     }, ["key", "name"]),
     call: async (args) => (await apiCall("POST", "/api/teams", args)).body
   },
@@ -1106,7 +1315,7 @@ var TOOLS = [
       name: strSchema(),
       requires: { type: "array", items: { type: "string" } },
       functions: { type: "array", items: { type: "string" } },
-      framework_key: strSchema()
+      framework_key: strSchema("the team's default framework: a key from polaris.framework.list")
     }, ["key"]),
     call: async (args) => {
       const { key, ...patch } = args;
@@ -1132,7 +1341,7 @@ async function handle(req) {
       return ok(id, {
         protocolVersion: "2024-11-05",
         capabilities: { tools: {} },
-        serverInfo: { name: "mcp-polaris", version: "0.3.0" },
+        serverInfo: { name: "mcp-polaris", version: VERSION },
         instructions: INSTRUCTIONS
       });
     case "initialized":
@@ -1192,5 +1401,6 @@ if (true) {
   rl.on("close", () => log("stdin closed, exiting"));
 }
 export {
+  VERSION,
   TOOLS
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glie/mcp-polaris",
-  "version": "0.13.0",
+  "version": "0.18.2",
   "description": "Model Context Protocol (stdio) server exposing Polaris, glie's ops platform, as native tools in Claude Code and any MCP client.",
   "license": "Apache-2.0",
   "author": "glie <carlos@glie.ai>",