@glie/mcp-polaris 0.12.0 → 0.14.0

package/dist/index.js

@@ -95,6 +95,9 @@ var INSTRUCTIONS = [
   `\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 "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 +165,114 @@ 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("optional: e.g. feature, marketing")
+    }, ["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.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.",
+    inputSchema: objSchema({
+      key: strSchema("project key (e.g. saasA)"),
+      reason: strSchema("why publishing was stopped \u2014 read by whoever finds it paused")
+    }, ["key"]),
+    call: async (args) => (await apiCall("POST", `/api/projects/${args.key}/pause-publishing`, {
+      reason: args.reason
+    })).body
+  },
+  {
+    name: "polaris.project.resume_publishing",
+    description: "Resume publishing through Polaris (human-only). Immediate: the next pass publishes whatever is still inside its 15-minute window; anything past it has already gone back to the person. Idempotent.",
+    inputSchema: objSchema({ key: strSchema("project key (e.g. saasA)") }, ["key"]),
+    call: async (args) => (await apiCall("POST", `/api/projects/${args.key}/resume-publishing`)).body
+  },
   {
     name: "polaris.milestone.list",
     description: "List milestones in a project.",
@@ -325,18 +426,19 @@ var TOOLS = [
   },
   {
     name: "polaris.task.create",
-    description: "Create a task within a milestone. For a marketing CREATIVE (a task in an mkt campaign): channel + 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. 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(),
       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)"),
-      channel: strSchema("mkt: Instagram, TikTok, LinkedIn, \u2026"),
+      presence_id: intSchema("mkt: WHERE THE PIECE GOES \u2014 the id of one of the product's destinations " + "(polaris.destination.list). Required for a creative; the channel and the market come " + "from it. A place the product is not on is refused, with the reason."),
       format: strSchema("mkt: post, carrossel, reel, story, artigo, \u2026"),
       slides: intSchema("mkt: REQUIRED when format is a carousel \u2014 how many images the piece has (2..10). " + "It is a contract: the generator delivers exactly this many. Omit for every other format."),
       medium: strSchema("mkt: what the piece IS \u2014 image | video | text. The engine follows it (Codex, Remotion, " + "the writer). A carousel is `image` with slides > 1: only an image has more than one."),
       surface: strSchema("mkt: where it publishes \u2014 feed | stories | reels | shorts | article | newsletter. It is " + "what separates a reel from a story: same medium, same 9:16, different place (and a " + "story is gone in 24h)."),
       aspect: strSchema("mkt: the piece's SHAPE \u2014 1:1 | 4:5 | 9:16 | 16:9 | 2:3. The format says what the piece " + "IS (post, carrossel, reel), this says how it is framed, and they are independent: a " + "carousel can be vertical, a reel can be square. Omit to take the channel's usual one."),
+      link_url: strSchema("mkt: WHERE THE PIECE SENDS THE READER \u2014 the full URL, tracking parameters already in " + "it. Required on a PAID piece: the network does not create an ad without a " + "destination, and the click leaves through the ad itself. On an organic piece it is " + "optional, because there the link travels in the body text."),
       output_type: strSchema("pr|post|video|email|generic \u2014 the delivery medium. Omit it: the format decides (reel/v\xEDdeo/short \u2192 video). Only pass it to override."),
       scheduled_date: strSchema("mkt: publish day (ISO date) \u2014 the calendar slot"),
       platform: strSchema("mkt: ad platform if this creative is individually paid"),
@@ -406,7 +508,8 @@ var TOOLS = [
       name: strSchema(),
       description_md: strSchema("full markdown brief; replaces the current description"),
       asset_url: strSchema("mkt: URL of the produced creative asset (image/video) for the reviewer"),
-      output_type: strSchema("pr|post|video|email|generic \u2014 fix the delivery medium of a task filed with the wrong one (it routes the worker to the video or the image pipeline).")
+      output_type: strSchema("pr|post|video|email|generic \u2014 fix the delivery medium of a task filed with the wrong one (it routes the worker to the video or the image pipeline)."),
+      link_url: strSchema("mkt: where the piece sends the reader \u2014 the full URL with its tracking parameters. A " + "PAID piece cannot go to review without one: the network does not create an ad with " + 'no destination. Send "" to clear it.')
     }, ["id"]),
     call: async (args) => {
       const body = {};
@@ -418,6 +521,8 @@ var TOOLS = [
         body.asset_url = args.asset_url;
       if (typeof args.output_type === "string")
         body.output_type = args.output_type;
+      if (typeof args.link_url === "string")
+        body.link_url = args.link_url;
       return (await apiCall("PATCH", `/api/tasks/${args.id}`, body)).body;
     }
   },
@@ -442,7 +547,7 @@ var TOOLS = [
   },
   {
     name: "polaris.task.schedule",
-    description: "Schedule a mkt creative for publication: release \u2192 agendado, and the publisher takes it to `done` when its time arrives. The creative must be bound to an active social account (resolved from its market + channel) and have a publish_at in the future. Its copy is frozen while scheduled \u2014 editing it requires unscheduling first.",
+    description: 'Schedule a mkt creative for publication: release \u2192 agendado, and the publisher takes it to `done` when its time arrives. The creative must be bound to an active social account (resolved from its market + channel) and have a publish_at in the future. Its copy is frozen while scheduled \u2014 editing it requires unscheduling first. The hour is not a promise the clock keeps at any cost (docs/spec/publishing.md, "Rules \u2014 the brakes on publishing through Polaris"): more than 15 minutes past it the piece is NOT published, it comes back to `release` carrying the reason, because a post at the wrong hour is not the post that was planned. Publishing is also skipped entirely while the product is paused (polaris.project.pause_publishing), and a piece whose hour passes meanwhile comes back the same way.',
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/schedule`)).body
   },
@@ -781,7 +886,7 @@ var TOOLS = [
   },
   {
     name: "polaris.social_account.list",
-    description: "The social accounts connected to publish through: a product's (`key`), or the organization's own when `key` is left out \u2014 the company's identity, which publishes as the company and not as a product. Each account says its channel, handle, market and timezone, whether it is `schedulable` (market and timezone set), and whether its credential needs a person (`token_expired`). No credential ever comes back. Connecting is a person's job, through the provider's consent screen; read this to know where a creative can go.",
+    description: "The social accounts connected to publish through: a product's (`key`), or the organization's own when `key` is left out \u2014 the company's identity, which publishes as the company and not as a product. Each account says its channel, handle, market and timezone, whether it is `schedulable` (market and timezone set), and whether its credential needs a person (`token_expired`). It also says `settings_problem`: what the NETWORK still requires of this account before anything can go out through it, in a sentence naming the field and where to set it, or null when nothing is missing. A YouTube channel needs a video category (YouTube refuses the upload without one) and an answer to whether its content is made for children (a legal declaration its API never asks for). No credential ever comes back. Connecting is a person's job, through the provider's consent screen; read this to know where a creative can go.",
     inputSchema: objSchema({
       key: strSchema("project key; leave it out for the organization's own accounts")
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glie/mcp-polaris",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "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>",