@glie/mcp-polaris 0.1.0 → 0.2.0

package/dist/index.js

@@ -5,6 +5,7 @@
 import { createInterface } from "readline";
 var BASE = process.env.POLARIS_URL ?? "http://127.0.0.1:7843";
 var TOKEN = process.env.POLARIS_TOKEN ?? "";
+var PROJECT = process.env.POLARIS_PROJECT ?? "";
 var log = (msg, ctx) => process.stderr.write(`mcp-polaris: ${msg}${ctx ? ` ${JSON.stringify(ctx)}` : ""}
 `);
 async function apiCall(method, path, body) {
@@ -41,10 +42,38 @@ function objSchema(properties, required = []) {
     additionalProperties: false
   };
 }
+var INSTRUCTIONS = [
+  `Polaris is the studio's operating system. All product work lives as Projects \u2192 Milestones \u2192 Tasks, and agents ("employees") move it forward. Each polaris.* tool wraps one REST call.`,
+  PROJECT ? `You are scoped to project \`${PROJECT}\` \u2014 use it as project_key/product_key unless told otherwise.` : "This connector is not pinned to a project; use polaris.project.list to find yours.",
+  "",
+  "START HERE \u2014 get what is YOURS (resolved from your token, no id lookup needed):",
+  '\u2022 agent  \u2192 polaris.task.list { assignee_agent_id: "self" }',
+  '\u2022 human  \u2192 polaris.task.list { assignee_human_id: "self" }  (and polaris.me for your identity)',
+  "  Narrow with status (e.g. dev) once you know what's assigned to you.",
+  "\u2022 polaris.claude_md.get(project_key) \u2014 read the project's conventions BEFORE you touch its tasks.",
+  "",
+  "STATE MACHINES \u2014 transitions are enforced; only legal moves succeed:",
+  "\u2022 Task:      draft \u2192 backlog \u2192 dev \u2192 test \u2192 approval \u2192 release \u2192 done    (any \u2192 canceled)",
+  "    dev = an agent implements it & opens a PR \xB7 test = QA \xB7 approval = a human reviews \xB7 release = merged to dev/shipped.",
+  "\u2022 Milestone: draft \u2192 discovery \u2192 loop \u2192 release \u2192 done                    (any \u2192 canceled)",
+  "    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).",
+  "",
+  "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 "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 "Break a milestone into tasks"  \u2192 polaris.milestone.qa_list / qa_answer (while in discovery)',
+  "",
+  "Identifiers: projects by `key` (string, e.g. saasA); milestones/tasks/agents/stacks by numeric `id`. Writes need a token; reads work anonymously."
+].join(`
+`);
 var TOOLS = [
   {
     name: "polaris.me",
-    description: "Get the current authenticated human (PAT owner).",
+    description: `Resolve the human your PAT belongs to (identity + org). Humans call this first; agents don't need it \u2014 they pass "self" to other tools.`,
     inputSchema: objSchema({}),
     call: async () => {
       const r = await apiCall("GET", "/api/humans/me");
@@ -121,17 +150,27 @@ var TOOLS = [
   },
   {
     name: "polaris.task.list",
-    description: "List tasks across milestones. Filter by status/product/team/assignee.",
+    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.`,
     inputSchema: objSchema({
-      status: strSchema("comma-separated: backlog,dev,test,..."),
+      status: strSchema("comma-separated subset of: draft,backlog,dev,test,approval,release,done,canceled"),
       milestone_id: intSchema(),
-      product_key: strSchema(),
+      product_key: strSchema("project key, e.g. saasA"),
       team: strSchema("dev|mkt"),
+      assignee_agent_id: strSchema('agent id, or "self" for the calling agent'),
+      assignee_human_id: strSchema('human id, or "self" for the calling human'),
       limit: intSchema()
     }),
     call: async (args) => {
       const qs = new URLSearchParams;
-      for (const k of ["status", "milestone_id", "product_key", "team", "limit"]) {
+      for (const k of [
+        "status",
+        "milestone_id",
+        "product_key",
+        "team",
+        "assignee_agent_id",
+        "assignee_human_id",
+        "limit"
+      ]) {
         const v = args[k];
         if (v !== undefined && v !== null)
           qs.set(k, String(v));
@@ -154,13 +193,13 @@ var TOOLS = [
   },
   {
     name: "polaris.task.transition",
-    description: "Transition task status (state machine enforced).",
+    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).",
     inputSchema: objSchema({ id: intSchema(), status: strSchema() }, ["id", "status"]),
     call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/state`, { status: args.status })).body
   },
   {
     name: "polaris.task.approve",
-    description: "Approve a task in approval state (human-only).",
+    description: "The human review gate: approve a task in `approval` \u2192 it advances toward release. Human-only. To ship several approval tasks of one milestone together, group them into a stack and use polaris.stack.release instead.",
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/approve`)).body
   },
@@ -178,8 +217,8 @@ var TOOLS = [
   },
   {
     name: "polaris.stack.list",
-    description: "List approval stacks (Release Candidates). Filter by status: liquid|frozen|released|canceled.",
-    inputSchema: objSchema({ status: strSchema("liquid|frozen|released|canceled") }),
+    description: "List Release-Candidate stacks (groups of approval tasks shipped together). Filter by status: liquid|blocked|frozen|released|canceled.",
+    inputSchema: objSchema({ status: strSchema("liquid|blocked|frozen|released|canceled") }),
     call: async (args) => {
       const qs = typeof args.status === "string" ? `?status=${encodeURIComponent(args.status)}` : "";
       return (await apiCall("GET", `/api/stacks${qs}`)).body;
@@ -187,22 +226,16 @@ var TOOLS = [
   },
   {
     name: "polaris.stack.get",
-    description: "Get one approval stack by id \u2014 includes its member tasks and the rc integration branch.",
+    description: "Inspect one stack by id \u2014 its member tasks, the rc branch + PR, and (when blocked) which member failed to integrate and why.",
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("GET", `/api/stacks/${args.id}`)).body
   },
   {
     name: "polaris.stack.release",
-    description: "Release a stack \u2014 merge its rc branch to dev and settle members to release (human-only).",
+    description: "Ship a stack \u2014 merge its rc PR into dev, settle members to release, then close & delete the member branches (their commits land via the rc). Human-only; barred while blocked.",
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("POST", `/api/stacks/${args.id}/release`)).body
   },
-  {
-    name: "polaris.stack.reject",
-    description: "Reject a stack \u2014 return its member tasks to their prior state (human-only).",
-    inputSchema: objSchema({ id: intSchema() }, ["id"]),
-    call: async (args) => (await apiCall("POST", `/api/stacks/${args.id}/reject`)).body
-  },
   {
     name: "polaris.agent.list",
     description: "List agents.",
@@ -223,7 +256,7 @@ var TOOLS = [
   },
   {
     name: "polaris.claude_md.get",
-    description: "Read the CLAUDE.md of a project (via polaris-bot).",
+    description: "Read a project's CLAUDE.md \u2014 its conventions, stack and rules (served from main via polaris-bot). Do this BEFORE working that project's tasks.",
     inputSchema: objSchema({ project_key: strSchema() }, ["project_key"]),
     call: async (args) => (await apiCall("GET", `/api/projects/${args.project_key}/claude-md`)).body
   },
@@ -252,7 +285,8 @@ 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.1.0" },
+        instructions: INSTRUCTIONS
       });
     case "initialized":
       return null;

package/package.json

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