@glie/mcp-polaris 0.2.0 → 0.3.0

package/README.md

@@ -47,10 +47,12 @@ it. The same token authenticates this server and the `polaris` CLI as you.
 
 ## Tools
 
-`polaris.me`, `polaris.project.*`, `polaris.milestone.*`, `polaris.task.*`
-(incl. `approve`), `polaris.stack.*` (`list` / `get` / `release` / `reject` for
-the approval Release Candidate flow), `polaris.agent.*`, `polaris.claude_md.get`,
-`polaris.framework.list`.
+`polaris.me`, `polaris.project.*`, `polaris.milestone.*` (incl. `update` to
+refine a spec), `polaris.task.*` (incl. `update`, `transition`, `approve`),
+`polaris.stack.*` (`list` / `get` / `release` for the approval Release Candidate
+flow), `polaris.agent.*`, `polaris.claude_md.get`, `polaris.framework.list`, plus
+read-only context from the feed: `polaris.activity.list` (what happened) and
+`polaris.chat.get` / `polaris.chat.messages` (comments agents left on a scope).
 
 Run `tools/list` against the server for the full, current set.
 

package/dist/index.js

@@ -59,13 +59,29 @@ var INSTRUCTIONS = [
   "    discovery = answer the framework Q&A to split it into tasks \xB7 loop = build/test/approve \xB7 release = ship.",
   "\u2022 Stack (Release Candidate): 2+ approval tasks of ONE milestone on an rc branch, tested & shipped together \u2014",
   "    liquid (assembling) \u2192 blocked (a member conflicts) | frozen (human-resolved) \u2192 released   (any \u2192 canceled).",
+  "    The rc has its own PR (rc/stack-N \u2192 dev); while blocked it's a DRAFT (un-mergeable) and auto-flips to ready the moment the blocking member integrates.",
+  "\u2022 Issue (reactive/helpdesk): open \u2192 triaging \u2192 fixing \u2192 resolved   (any \u2192 canceled). resolved is manual.",
+  "",
+  "TWO MODES \u2014 roadmap is proactive (milestone \u2192 tasks); HELPDESK is reactive (tickets \u2192 issues \u2192 tasks):",
+  "\u2022 A `ticket` is the customer conversation/report; an `issue` is the PROBLEM (the helpdesk twin of a milestone); `task`s are the work.",
+  "\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.",
   "",
   "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 "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 "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',
+  '\u2022 "Same bug reported again"         \u2192 polaris.ticket.link_issue (dedup onto the open issue)',
   "",
   "Identifiers: projects by `key` (string, e.g. saasA); milestones/tasks/agents/stacks by numeric `id`. Writes need a token; reads work anonymously."
 ].join(`
@@ -124,6 +140,23 @@ var TOOLS = [
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("GET", `/api/milestones/${args.id}`)).body
   },
+  {
+    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. Use it to sharpen the brief for better scoping. Needs a token.",
+    inputSchema: objSchema({
+      id: intSchema(),
+      name: strSchema(),
+      description_md: strSchema("full markdown brief; replaces the current description")
+    }, ["id"]),
+    call: async (args) => {
+      const body = {};
+      if (typeof args.name === "string")
+        body.name = args.name;
+      if (typeof args.description_md === "string")
+        body.description_md = args.description_md;
+      return (await apiCall("PATCH", `/api/milestones/${args.id}`, body)).body;
+    }
+  },
   {
     name: "polaris.milestone.transition",
     description: "Transition milestone status (state machine enforced: draft\u2192discovery\u2192loop\u2192release\u2192done, *\u2192canceled).",
@@ -191,6 +224,23 @@ var TOOLS = [
     inputSchema: objSchema({ milestone_id: intSchema(), name: strSchema(), description_md: strSchema() }, ["milestone_id", "name"]),
     call: async (args) => (await apiCall("POST", "/api/tasks", args)).body
   },
+  {
+    name: "polaris.task.update",
+    description: "Correct or refine a task's spec \u2014 PATCH its description_md (and optionally name). Use this to sharpen an underspecified brief so the implementing agent gets better results; it is NOT a log of what was done (leave that as a comment). Needs a token.",
+    inputSchema: objSchema({
+      id: intSchema(),
+      name: strSchema(),
+      description_md: strSchema("full markdown brief; replaces the current description")
+    }, ["id"]),
+    call: async (args) => {
+      const body = {};
+      if (typeof args.name === "string")
+        body.name = args.name;
+      if (typeof args.description_md === "string")
+        body.description_md = args.description_md;
+      return (await apiCall("PATCH", `/api/tasks/${args.id}`, body)).body;
+    }
+  },
   {
     name: "polaris.task.transition",
     description: "Move a task to its next status when you finish a stage (e.g. dev\u2192test once your PR is up). Enforced flow: draft\u2192backlog\u2192dev\u2192test\u2192approval\u2192release\u2192done (any\u2192canceled). Illegal jumps are rejected. The approval\u2192release gate is polaris.task.approve (human-only).",
@@ -215,6 +265,155 @@ var TOOLS = [
     inputSchema: objSchema({ id: intSchema(), dep_task_id: intSchema() }, ["id", "dep_task_id"]),
     call: async (args) => (await apiCall("DELETE", `/api/tasks/${args.id}/deps/${args.dep_task_id}`)).body
   },
+  {
+    name: "polaris.ticket.list",
+    description: "List the support queue (reactive mode), ordered by the P1\u2192P4 priority (a customer waiting on our move is P1). Filter by project_key, status (new|triaging|open|resolved|closed), include_closed.",
+    inputSchema: objSchema({
+      project_key: strSchema(),
+      status: strSchema("new|triaging|open|resolved|closed"),
+      include_closed: strSchema('"1" to include closed tickets')
+    }),
+    call: async (args) => {
+      const qs = new URLSearchParams;
+      if (typeof args.project_key === "string")
+        qs.set("project_key", args.project_key);
+      if (typeof args.status === "string")
+        qs.set("status", args.status);
+      if (args.include_closed === "1" || args.include_closed === true)
+        qs.set("include_closed", "1");
+      const s = qs.toString();
+      return (await apiCall("GET", `/api/tickets${s ? `?${s}` : ""}`)).body;
+    }
+  },
+  {
+    name: "polaris.ticket.get",
+    description: "Get one ticket by id \u2014 its conversation (messages), the issues it reports, and its attachments.",
+    inputSchema: objSchema({ id: intSchema() }, ["id"]),
+    call: async (args) => (await apiCall("GET", `/api/tickets/${args.id}`)).body
+  },
+  {
+    name: "polaris.ticket.create",
+    description: "Open a support ticket (a customer report) + its first message. Scope it with project_key (e.g. saasA).",
+    inputSchema: objSchema({
+      project_key: strSchema(),
+      type: strSchema("bug|question|suggestion|feedback"),
+      subject: strSchema(),
+      requester: strSchema("email/handle of who reported it"),
+      body_md: strSchema(),
+      channel: strSchema("email|discord|slack|portal|in_product")
+    }, ["project_key", "subject", "requester", "body_md"]),
+    call: async (args) => (await apiCall("POST", "/api/tickets", args)).body
+  },
+  {
+    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"]),
+    call: async (args) => (await apiCall("POST", `/api/tickets/${args.id}/messages`, {
+      body_md: args.body_md,
+      side: args.side
+    })).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.",
+    inputSchema: objSchema({ id: intSchema(), to: strSchema("customer|team") }, ["id", "to"]),
+    call: async (args) => (await apiCall("POST", `/api/tickets/${args.id}/pass`, { to: args.to })).body
+  },
+  {
+    name: "polaris.ticket.transition",
+    description: "Move a ticket through its lifecycle: new \u2192 triaging \u2192 open \u2192 resolved \u2192 closed. A customer reply auto-reopens a resolved/closed ticket.",
+    inputSchema: objSchema({ id: intSchema(), status: strSchema("new|triaging|open|resolved|closed") }, ["id", "status"]),
+    call: async (args) => (await apiCall("POST", `/api/tickets/${args.id}/status`, { status: args.status })).body
+  },
+  {
+    name: "polaris.ticket.frame_issue",
+    description: "Frame a NEW issue (the problem) from this ticket's conversation \u2014 the helpdesk twin of a milestone. A note is added to the thread. Then decompose it via polaris.issue.add_task.",
+    inputSchema: objSchema({ id: intSchema(), title: strSchema() }, ["id", "title"]),
+    call: async (args) => (await apiCall("POST", `/api/tickets/${args.id}/issues`, { title: args.title })).body
+  },
+  {
+    name: "polaris.ticket.link_issue",
+    description: "Link this ticket to an EXISTING issue (dedup \u2014 it's a duplicate report of a problem already being worked).",
+    inputSchema: objSchema({ id: intSchema(), issue_id: intSchema() }, ["id", "issue_id"]),
+    call: async (args) => (await apiCall("POST", `/api/tickets/${args.id}/issues/link`, { issue_id: args.issue_id })).body
+  },
+  {
+    name: "polaris.ticket.update",
+    description: "Update a ticket's type, its human assignee, and/or its guidance (the communicator's orientation on what to do/say next).",
+    inputSchema: objSchema({
+      id: intSchema(),
+      type: strSchema("bug|question|suggestion|feedback"),
+      assignee_human_id: intSchema(),
+      guidance: strSchema("The communicator's guidance on what to do/say next \u2014 orientation (e.g. create an issue, inform, reassure), researched from the customer's history + related issues. Shown to the human as advice; NOT inserted into the reply box.")
+    }, ["id"]),
+    call: async (args) => (await apiCall("PATCH", `/api/tickets/${args.id}`, {
+      type: args.type,
+      assignee_human_id: args.assignee_human_id,
+      guidance: args.guidance
+    })).body
+  },
+  {
+    name: "polaris.issue.list",
+    description: "List issues (the problems) for a project. Filter by status: open|triaging|fixing|resolved|canceled.",
+    inputSchema: objSchema({
+      project_key: strSchema(),
+      status: strSchema("open|triaging|fixing|resolved|canceled")
+    }),
+    call: async (args) => {
+      const qs = new URLSearchParams;
+      if (typeof args.project_key === "string")
+        qs.set("project_key", args.project_key);
+      if (typeof args.status === "string")
+        qs.set("status", args.status);
+      const s = qs.toString();
+      return (await apiCall("GET", `/api/issues${s ? `?${s}` : ""}`)).body;
+    }
+  },
+  {
+    name: "polaris.issue.get",
+    description: "Get one issue \u2014 its linked tickets (the reports) and its tasks (the work).",
+    inputSchema: objSchema({ id: intSchema() }, ["id"]),
+    call: async (args) => (await apiCall("GET", `/api/issues/${args.id}`)).body
+  },
+  {
+    name: "polaris.issue.open",
+    description: "Open a STANDALONE issue (no ticket needed) \u2014 e.g. an internal dev files a bug. Scope with project_key.",
+    inputSchema: objSchema({ project_key: strSchema(), title: strSchema() }, [
+      "project_key",
+      "title"
+    ]),
+    call: async (args) => (await apiCall("POST", "/api/issues", args)).body
+  },
+  {
+    name: "polaris.issue.update",
+    description: "Update an issue \u2014 set its title and/or assign it to an agent (assignee_agent_id, e.g. hand it to a planner).",
+    inputSchema: objSchema({ id: intSchema(), title: strSchema(), assignee_agent_id: intSchema() }, ["id"]),
+    call: async (args) => (await apiCall("PATCH", `/api/issues/${args.id}`, {
+      title: args.title,
+      assignee_agent_id: args.assignee_agent_id
+    })).body
+  },
+  {
+    name: "polaris.issue.transition",
+    description: "Move an issue through its state: open \u2192 triaging \u2192 fixing \u2192 resolved (any \u2192 canceled). resolved is manual.",
+    inputSchema: objSchema({ id: intSchema(), status: strSchema("open|triaging|fixing|resolved|canceled") }, ["id", "status"]),
+    call: async (args) => (await apiCall("POST", `/api/issues/${args.id}/status`, { status: args.status })).body
+  },
+  {
+    name: "polaris.issue.add_task",
+    description: "The planner's move: decompose an issue into a task (no milestone \u2014 it belongs to the issue, enters draft). A helpdesk planner also does this autonomously once the issue is in 'triaging'. When the issue is in 'fixing', a helpdesk-domain developer/tester claims and runs the tasks; you can also drive them with polaris.task.transition. hotfix=true is claimed first, branches off main, and auto-merges to main at release once CI passes (the prod gate is CI).",
+    inputSchema: objSchema({
+      id: intSchema(),
+      name: strSchema(),
+      description_md: strSchema(),
+      hotfix: { type: "boolean" }
+    }, ["id", "name"]),
+    call: async (args) => (await apiCall("POST", `/api/issues/${args.id}/tasks`, {
+      name: args.name,
+      description_md: args.description_md,
+      hotfix: args.hotfix
+    })).body
+  },
   {
     name: "polaris.stack.list",
     description: "List Release-Candidate stacks (groups of approval tasks shipped together). Filter by status: liquid|blocked|frozen|released|canceled.",
@@ -226,7 +425,7 @@ var TOOLS = [
   },
   {
     name: "polaris.stack.get",
-    description: "Inspect one stack by id \u2014 its member tasks, the rc branch + PR, and (when blocked) which member failed to integrate and why.",
+    description: "Inspect one stack by id \u2014 its member tasks, the rc branch + PR, and (when blocked) which member failed to integrate and why. While blocked the rc PR is a draft (can't be merged); resolve the blocking member's branch (rebase onto dev + push) or commit the fix on the rc and it flips to ready automatically.",
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("GET", `/api/stacks/${args.id}`)).body
   },
@@ -265,6 +464,52 @@ var TOOLS = [
     description: "List the curated frameworks (knowledge bases).",
     inputSchema: objSchema({}),
     call: async () => (await apiCall("GET", "/api/frameworks")).body
+  },
+  {
+    name: "polaris.activity.list",
+    description: 'Read the activity feed \u2014 the system event log of what HAPPENED (state changes, approvals, etc.). Filter by scope_type+scope_id (e.g. task 42) and/or event_type. Answers "what changed here?"; for what agents WROTE, use polaris.chat.messages.',
+    inputSchema: objSchema({
+      scope_type: strSchema("task|milestone|project|agent"),
+      scope_id: intSchema(),
+      event_type: strSchema(),
+      limit: intSchema()
+    }),
+    call: async (args) => {
+      const qs = new URLSearchParams;
+      for (const k of ["scope_type", "scope_id", "event_type", "limit"]) {
+        const v = args[k];
+        if (v !== undefined && v !== null)
+          qs.set(k, String(v));
+      }
+      const r = await apiCall("GET", `/api/activities${qs.toString() ? `?${qs}` : ""}`);
+      return r.body;
+    }
+  },
+  {
+    name: "polaris.chat.get",
+    description: "Resolve the chat thread for a scope (e.g. task 42) and return its id. Idempotent (get-or-create). You rarely need this directly \u2014 polaris.chat.messages takes the scope and resolves the id for you.",
+    inputSchema: objSchema({
+      scope_type: strSchema("task|milestone|project|agent_dm|human_dm|general"),
+      scope_id: intSchema()
+    }, ["scope_type", "scope_id"]),
+    call: async (args) => (await apiCall("GET", `/api/chats/${args.scope_type}/${args.scope_id}`)).body
+  },
+  {
+    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).",
+    inputSchema: objSchema({
+      scope_type: strSchema("task|milestone|project|agent_dm|human_dm|general"),
+      scope_id: intSchema(),
+      limit: intSchema()
+    }, ["scope_type", "scope_id"]),
+    call: async (args) => {
+      const chat = (await apiCall("GET", `/api/chats/${args.scope_type}/${args.scope_id}`)).body;
+      const chatId = chat?.data?.id;
+      if (!chatId)
+        throw new Error(`no chat for ${args.scope_type}/${args.scope_id}`);
+      const qs = typeof args.limit === "number" ? `?limit=${args.limit}` : "";
+      return (await apiCall("GET", `/api/chats/${chatId}/messages${qs}`)).body;
+    }
   }
 ];
 var TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
@@ -285,7 +530,7 @@ async function handle(req) {
       return ok(id, {
         protocolVersion: "2024-11-05",
         capabilities: { tools: {} },
-        serverInfo: { name: "mcp-polaris", version: "0.1.0" },
+        serverInfo: { name: "mcp-polaris", version: "0.3.0" },
         instructions: INSTRUCTIONS
       });
     case "initialized":
@@ -321,27 +566,29 @@ async function handle(req) {
       return fail(id, -32601, `method not found: ${req.method}`);
   }
 }
-log(`starting against ${BASE} (token=${TOKEN ? "set" : "none"})`);
-var rl = createInterface({ input: process.stdin, crlfDelay: Number.POSITIVE_INFINITY });
-rl.on("line", async (line) => {
-  if (!line.trim())
-    return;
-  let req;
-  try {
-    req = JSON.parse(line);
-  } catch (_err) {
-    send(fail(null, -32700, "parse error", { line }));
-    return;
-  }
-  try {
-    const res = await handle(req);
-    if (res)
-      send(res);
-  } catch (err) {
-    send(fail(req.id ?? null, -32603, err.message));
-  }
-});
-rl.on("close", () => log("stdin closed, exiting"));
+if (__require.main == __require.module) {
+  log(`starting against ${BASE} (token=${TOKEN ? "set" : "none"})`);
+  const rl = createInterface({ input: process.stdin, crlfDelay: Number.POSITIVE_INFINITY });
+  rl.on("line", async (line) => {
+    if (!line.trim())
+      return;
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch (_err) {
+      send(fail(null, -32700, "parse error", { line }));
+      return;
+    }
+    try {
+      const res = await handle(req);
+      if (res)
+        send(res);
+    } catch (err) {
+      send(fail(req.id ?? null, -32603, err.message));
+    }
+  });
+  rl.on("close", () => log("stdin closed, exiting"));
+}
 export {
   TOOLS
 };

package/package.json

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