pipebrain-mcp 0.16.0 → 0.17.0

package/README.md

@@ -9,16 +9,24 @@ This package is the **server only**. The command line tool is a separate package
 
 ## Install
 
-Register it with Claude Code (no install step — `npx` fetches it):
+Register it with Claude Code (no install step — `npx` fetches it), at **user scope** so
+every repo on the machine gets the tools:
 
 ```
-claude mcp add pipebrain -- npx -y pipebrain-mcp
+claude mcp add pipebrain -s user -e PIPEBRAIN_API_URL=https://api.pipebrain.dev -e 'PIPEBRAIN_TOKEN=${PIPEBRAIN_TOKEN}' -- npx -y pipebrain-mcp@latest
 ```
 
-The server reads its configuration from the environment of the process that launches it,
-and refuses to start if either value is missing or malformed — including an unexpanded
-`${PIPEBRAIN_TOKEN}` placeholder, which is the failure that otherwise looks like a
-revoked token.
+Both `-e` flags are required, not decoration. The server reads its configuration from the
+environment of the process that launches it, and refuses to start if either value is
+missing or malformed — including an unexpanded `${PIPEBRAIN_TOKEN}` placeholder, which is
+the failure that otherwise looks like a revoked token. There is no default API URL (see
+the table below), so a registration that passes neither flag produces a server that never
+starts.
+
+The single quotes around the token are load-bearing: they keep `${PIPEBRAIN_TOKEN}` a
+literal *reference* in Claude's config instead of expanding it as you type, so the token
+value itself never lands in a config file — the server resolves it from your environment
+at each launch.
 
 ## Environment
 
@@ -27,9 +35,6 @@ revoked token.
 | `PIPEBRAIN_TOKEN` | Your `pbt_…` API token (Settings → Organization → API tokens). A pre-rename `plt_…` token still works. |
 | `PIPEBRAIN_API_URL` | API base URL, e.g. `https://api.pipebrain.dev`. Required — there is no default, so a session can always tell which environment it is bound to. |
 
-The pre-rename names `PIPELINE_TOKEN` and `PIPELINE_API_URL` are still honored as
-fallbacks, indefinitely. When both are set, `PIPEBRAIN_*` wins.
-
 Secret VALUES never cross this server: the secrets tools return metadata only, and there
 is deliberately no value-returning tool. Use `ppb secrets` (from `pipebrain-cli`) for the
 reveal plane.

package/dist/main.js

@@ -14988,6 +14988,7 @@ var orgRoleSchema = external_exports.enum(["OWNER", "ADMIN", "CONTRIBUTOR"]);
 var orgKindSchema = external_exports.enum(["personal", "shared"]);
 var inviteRoleSchema = external_exports.enum(["ADMIN", "CONTRIBUTOR"]);
 var requirementLifecycleSchema = external_exports.enum(["draft", "approved", "amended"]);
+var decisionStatusSchema = external_exports.enum(["proposed", "accepted", "superseded"]);
 var platformSchema = external_exports.enum(["bsky", "x", "reddit", "hn", "blog"]);
 var assetStatusSchema = external_exports.enum(["pending", "active", "rejected"]);
 var assetLinkTargetSchema = external_exports.enum([
@@ -15040,7 +15041,8 @@ var widgetOriginSchema = external_exports.string().trim().transform((raw) => raw
 });
 var emailSchema = external_exports.email({ message: "enter a valid email address" });
 var passwordSchema = external_exports.string().min(8, { message: "password must be at least 8 characters" }).max(128, { message: "password must be at most 128 characters" });
-var tokenPrefixSchema = external_exports.string().regex(/^(plt|pbt)_[0-9A-Za-z]{4}$/, {
+var ACCEPTED_TOKEN_PREFIXES = ["pbt_", "plt_"];
+var tokenPrefixSchema = external_exports.string().regex(new RegExp(`^(?:${ACCEPTED_TOKEN_PREFIXES.join("|")})[0-9A-Za-z]{4}$`), {
   message: "token prefix must be `pbt_` (or the legacy `plt_`) followed by 4 base62 characters"
 });
 var SECRET_NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
@@ -15060,6 +15062,9 @@ var issueRefSchema = external_exports.string().min(1, { message: "issue referenc
 var requirementRefSchema = external_exports.string().min(1, {
   message: "requirement reference must not be empty \u2014 use a display id (`DWB-R4`) or uuid"
 });
+var decisionRefSchema = external_exports.string().min(1, {
+  message: "decision reference must not be empty \u2014 use a display id (`DWB-D7`) or uuid"
+});
 var contentRefSchema = external_exports.string().min(1, {
   message: "content reference must not be empty \u2014 use a display id (`DWB-C3`) or uuid"
 });
@@ -15603,6 +15608,10 @@ var deliverableLinkChangesSchema = external_exports.strictObject({
   add: external_exports.array(deliverableRefSchema).optional(),
   remove: external_exports.array(deliverableRefSchema).optional()
 });
+var decisionLinkChangesSchema = external_exports.strictObject({
+  add: external_exports.array(decisionRefSchema).optional(),
+  remove: external_exports.array(decisionRefSchema).optional()
+});
 var updateIssueInputSchema = external_exports.strictObject({
   issue: issueRefSchema,
   title: external_exports.string().min(1, { message: "issue title must not be empty" }).optional(),
@@ -15613,7 +15622,8 @@ var updateIssueInputSchema = external_exports.strictObject({
   environment: external_exports.string().min(1, { message: "environment must not be empty" }).optional(),
   parent: issueRefSchema.nullable().optional(),
   requirementLinks: requirementLinkChangesSchema.optional(),
-  deliverableLinks: deliverableLinkChangesSchema.optional()
+  deliverableLinks: deliverableLinkChangesSchema.optional(),
+  decisionLinks: decisionLinkChangesSchema.optional()
 });
 var setStatusInputSchema = external_exports.strictObject({
   issue: issueRefSchema,
@@ -15690,14 +15700,41 @@ var updateRequirementInputSchema = external_exports.strictObject({
   body: markdownSchema.optional(),
   area: external_exports.string().optional(),
   note: external_exports.string().min(1, { message: "note must not be empty \u2014 omit it if there is nothing to record" }).optional(),
-  crossCutting: external_exports.boolean().optional()
-}).refine((v) => v.title !== void 0 || v.body !== void 0 || v.summary !== void 0 || v.area !== void 0 || v.crossCutting !== void 0, {
-  message: "empty edit: supply at least one of `title`, `body`, `summary`, `area`, or `crossCutting`"
+  crossCutting: external_exports.boolean().optional(),
+  decisionLinks: decisionLinkChangesSchema.optional()
+}).refine((v) => v.title !== void 0 || v.body !== void 0 || v.summary !== void 0 || v.area !== void 0 || v.crossCutting !== void 0 || v.decisionLinks !== void 0, {
+  message: "empty edit: supply at least one of `title`, `body`, `summary`, `area`, `crossCutting`, or `decisionLinks`"
 });
 var approveRequirementInputSchema = external_exports.strictObject({
   requirement: requirementRefSchema,
   revision: positiveIntSchema.optional()
 });
+var createDecisionInputSchema = external_exports.strictObject({
+  project: projectRefSchema,
+  title: external_exports.string().min(1, { message: "decision title must not be empty" }),
+  body: markdownSchema.min(1, { message: "decision body must not be empty" })
+});
+var getDecisionInputSchema = external_exports.strictObject({
+  decision: decisionRefSchema
+});
+var updateDecisionInputSchema = external_exports.strictObject({
+  decision: decisionRefSchema,
+  title: external_exports.string().min(1, { message: "decision title must not be empty" }).optional(),
+  body: markdownSchema.min(1, { message: "decision body must not be empty" }).optional(),
+  status: decisionStatusSchema.optional()
+}).refine((v) => v.title !== void 0 || v.body !== void 0 || v.status !== void 0, {
+  message: "empty edit: supply at least one of `title`, `body`, or `status`"
+});
+var supersedeDecisionInputSchema = external_exports.strictObject({
+  decision: decisionRefSchema,
+  replacedBy: decisionRefSchema
+});
+var listDecisionsFilterSchema = external_exports.strictObject({
+  project: projectRefSchema.optional(),
+  text: external_exports.string().optional(),
+  limit: external_exports.number().int().min(1, { message: "limit must be at least 1" }).max(500, { message: "limit must be at most 500" }).optional(),
+  offset: external_exports.number().int().nonnegative().optional()
+});
 var claimedByFilterSchema = external_exports.union([
   external_exports.literal("me"),
   external_exports.literal("unclaimed"),
@@ -15965,6 +16002,15 @@ function scopesForTool(tool) {
   });
 }
 
+// ../../libs/agent-shared/dist/token-shape.js
+function isAcceptedTokenShape(value) {
+  return ACCEPTED_TOKEN_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+var UNEXPANDED_PLACEHOLDER = /^\$(\{[^}]*\}|[A-Za-z_][A-Za-z0-9_]*)$/;
+function isUnexpandedPlaceholder(value) {
+  return UNEXPANDED_PLACEHOLDER.test(value);
+}
+
 // ../../libs/api-client/dist/errors.js
 var ApiError = class extends Error {
   status;
@@ -16248,6 +16294,42 @@ var ApiClient = class _ApiClient {
       body: revision === void 0 ? {} : { revision }
     });
   }
+  // --- decision records (PIPE-84) --------------------------------------------
+  //
+  // Five routes, no DELETE: PIPE-73 made four record kinds deletable and this epic
+  // puts itself out of that scope explicitly, so a decision record is superseded
+  // rather than removed — which leaves the original readable and says what replaced
+  // it. There is deliberately no `deleteDecision` method here, and there is no route
+  // for one to call.
+  createDecision(input) {
+    return this.request("POST", "/api/v1/decisions", { body: input });
+  }
+  listDecisions(filter = {}) {
+    return this.requestList("GET", "/api/v1/decisions", { query: filter });
+  }
+  getDecision(ref) {
+    return this.request("GET", `/api/v1/decisions/${enc(ref)}`);
+  }
+  /**
+   * The proposed-stage title/body edit AND the move to `accepted`, on the one route
+   * (contract §5). Both refusals are the server's: an edit once the record is
+   * `accepted`/`superseded`, and any transition that is not the next step in
+   * `proposed → accepted → superseded`, each surface as a typed 422.
+   */
+  updateDecision(ref, fields) {
+    return this.request("PATCH", `/api/v1/decisions/${enc(ref)}`, { body: fields });
+  }
+  /**
+   * Supersedes `ref` with the record at `replacedBy`, in one call, because a
+   * superseded record with nowhere to point is a dead end for whoever opens it. This
+   * is the ONLY way into `superseded` — {@link updateDecision} refuses that target
+   * rather than write a record that names no replacement.
+   */
+  supersedeDecision(ref, replacedBy) {
+    return this.request("POST", `/api/v1/decisions/${enc(ref)}/supersede`, {
+      body: { replacedBy }
+    });
+  }
   // --- content ---------------------------------------------------------------
   createContent(input) {
     return this.request("POST", "/api/v1/content", { body: input });
@@ -16454,6 +16536,22 @@ var ApiClient = class _ApiClient {
       query: { q }
     });
   }
+  // --- the waiting queue -----------------------------------------------------
+  /**
+   * Every gate awaiting a person across ALL projects of the caller's organisation
+   * (PIPE-87): revisions awaiting approval, questions awaiting an answer, and epics
+   * in `verify` with a criterion not yet passed, longest wait first.
+   *
+   * Takes NO project and NO org: a queue you point at a project is the per-project
+   * surface this replaces, and org scope is the client's own (`X-Org-Id` for a
+   * session, the token's org for a bearer caller). `mine` narrows to the gates whose
+   * work the viewer claimed — plus the requirement gates, which have no claimant at
+   * all and would otherwise be waited on by nobody; omitting it is the wide view.
+   */
+  listWaiting(filter) {
+    const query = filter?.mine === true ? { mine: "1" } : void 0;
+    return this.requestList("GET", "/api/v1/waiting", { query });
+  }
   // --- secrets ---------------------------------------------------------------
   // Metadata only: no method here returns a secret VALUE (the reveal plane is a
   // separate surface). Every response type is a `*View` with no `value` field.
@@ -16753,7 +16851,7 @@ ${general}`;
 }
 
 // ../../libs/mcp-server/dist/server.js
-var SUCCESSOR_NOTICE = "NOTICE \u2014 this server is the FINAL release of the `@fvcsolutions/pipeline-mcp` package. The server moved to `pipebrain-mcp` on npmjs.org (public, no registry auth), and the CLI moved to `pipebrain-cli`, which provides the `ppb` command in place of `pipeline`. Re-register through the team bootstrap, or: `claude mcp add pipebrain -- npx -y pipebrain-mcp`. Tell the operator; this build still works and will not be updated again.\n\n";
+var SUCCESSOR_NOTICE = "NOTICE \u2014 this server is the FINAL release of the `@fvcsolutions/pipeline-mcp` package. The server moved to `pipebrain-mcp` on npmjs.org (public, no registry auth), and the CLI moved to `pipebrain-cli`, which provides the `ppb` command in place of `pipeline`. Re-register through the team bootstrap, or: `claude mcp add pipebrain -s user -e PIPEBRAIN_API_URL=https://api.pipebrain.dev -e 'PIPEBRAIN_TOKEN=${PIPEBRAIN_TOKEN}' -- npx -y pipebrain-mcp@latest`. Tell the operator; this build still works and will not be updated again.\n\n";
 function successorNotice() {
   const armed = process.env.PIPELINE_MCP_SUCCESSOR_NOTICE;
   return armed === void 0 || armed === "" ? "" : SUCCESSOR_NOTICE;
@@ -16809,6 +16907,7 @@ async function resolveDeliverableTargetId(client2, projectKey, ref) {
   return match.id;
 }
 function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */ new Map(), opts = {}) {
+  const surface = opts.surface ?? "local";
   const server2 = new McpServer({ name: "pipebrain", version: opts.version ?? DEFAULT_VERSION }, {
     instructions: withGeneralInstructions(successorNotice() + `Pipebrain MCP server, bound to the ${apiBindingLabel(apiBaseUrl)} API at ${apiBaseUrl}. Every tool reads and writes THAT environment \u2014 confirm it is the one you intend (a local dev API vs production) before mutating. Tools are namespaced by this server's registration name in .mcp.json (e.g. pipebrain-local:* vs pipebrain:*).`, orgInstructions2)
   });
@@ -16833,6 +16932,19 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
       key: projectKeySchema
     }
   }, (args) => run(() => client2.createProject(args)));
+  registerTool("list_waiting", {
+    description: "Every gate awaiting a PERSON across ALL projects in the token\u2019s org, longest wait first: a requirement revision awaiting approval, a question awaiting an answer, and an epic in `verify` holding at least one criterion not yet passed. Each entry names its project, the ref the action is taken on (`KEY-R{n}` for a revision, the ISSUE\u2019s `KEY-{n}` for a question or an epic), and `waitingSince` \u2014 the instant the wait began, not a duration. Nothing else is a gate: work in `triage` never appears, and neither does an epic in verify whose criteria have ALL passed. READ-ONLY, and there is no tool on this surface that clears any of the three \u2014 approving a revision, answering a question and marking a manual criterion are all decisions a person takes in the web app. Use it to see what your work is blocked on before asking, rather than to act on it."
+    // NO arguments — not even an org. Org scope arrives from the token, exactly as
+    // it does for `list_projects`, and an org parameter would open a cross-org read
+    // path that has no precedent anywhere on this surface. The viewer narrowing the
+    // web queue offers is filter state on that view, not something an agent picks.
+  }, () => (
+    // `{ items }`, mirroring the HTTP envelope rather than unwrapping to a bare
+    // array like the sibling list tools: AC-7 asks that an agent read the SAME set
+    // the queue shows, and the two surfaces answering in the same shape is what
+    // makes that comparable at a glance.
+    run(async () => ({ items: await client2.listWaiting() }))
+  ));
   registerTool("create_milestone", {
     description: "Create a milestone on a project. `token` is the short ref issues point at via their `milestone` field (e.g. `M1`) and is unique per project (a duplicate is rejected); `label` is its display name (e.g. `Feature Verification`). Optional `position` orders it (0-based, defaults to last); optional `active` marks it the current milestone \u2014 AT MOST ONE milestone per project is active, so `active: true` transactionally DEMOTES the previously active one rather than failing. Returns the created milestone (\xA77).",
     inputSchema: {
@@ -16934,7 +17046,7 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     }
   }, ({ issue: issue2, ...fields }) => run(() => client2.promoteFeedback(issue2, fields)));
   registerTool("update_issue", {
-    description: 'Update any subset of an issue\u2019s title, body, type, priority, milestone, environment, parent (self/cycle rejected), requirement_links (add/remove; adding a link to an unapproved requirement is rejected), or deliverable_links (add/remove content-deliverable links, add pins at the current revision). Changing type away from epic is rejected while the epic has criteria (\xA77). Link another record by key plus title on first mention; never paste its text into a body \u2014 the source changes, the copy does not, and a stale copy gets built. A decision you need from the operator is filed as a question via `ask_questions`, never written as an "Open questions" heading inside a body \u2014 a heading prompts nobody and records no answer, so a later session cannot tell whether the decision was made. Cross-cutting requirements bind every epic automatically and arrive with `get_issue` \u2014 never restate them in a body and never add them to `requirement_links`; an explicit link pins the linked document\u2019s approved revision.',
+    description: 'Update any subset of an issue\u2019s title, body, type, priority, milestone, environment, parent (self/cycle rejected), requirement_links (add/remove; adding a link to an unapproved requirement is rejected), deliverable_links (add/remove content-deliverable links, add pins at the current revision), or decision_links (add/remove decision records this work sits under \u2014 `KEY-D{n}`, from `list_decisions`). Changing type away from epic is rejected while the epic has criteria (\xA77). Cite the decision record a piece of work implements rather than restating what was decided in its body: the record is where the reasoning stays correct, and a body repeating it goes stale the moment the decision is superseded. Link another record by key plus title on first mention; never paste its text into a body \u2014 the source changes, the copy does not, and a stale copy gets built. A decision you need from the operator is filed as a question via `ask_questions`, never written as an "Open questions" heading inside a body \u2014 a heading prompts nobody and records no answer, so a later session cannot tell whether the decision was made. Cross-cutting requirements bind every epic automatically and arrive with `get_issue` \u2014 never restate them in a body and never add them to `requirement_links`; an explicit link pins the linked document\u2019s approved revision.',
     inputSchema: updateIssueInputSchema.shape
   }, ({ issue: issue2, ...fields }) => run(() => client2.updateIssue(issue2, fields)));
   registerTool("set_status", {
@@ -17020,10 +17132,10 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     inputSchema: createRequirementInputSchema.shape
   }, (args) => run(() => client2.createRequirement(args)));
   registerTool("update_requirement", {
-    description: "Update a requirement: title, body, and/or summary APPENDS a new revision (nothing is edited in place; summary versions like title/body); optional note records why. Optional area (product-area label) and cross_cutting are metadata changes (no revision) \u2014 toggling cross_cutting ON is rejected while explicit links exist; unlink first. Supplying none of title/body/summary/area/cross_cutting is an empty edit (400) (\xA77). Link another record by key plus title on first mention; never paste its text into a body \u2014 the source changes, the copy does not, and a stale copy gets built.",
+    description: "Update a requirement: title, body, and/or summary APPENDS a new revision (nothing is edited in place; summary versions like title/body); optional note records why. Optional area (product-area label), cross_cutting, and decision_links (add/remove decision records this rule sits under \u2014 `KEY-D{n}`, from `list_decisions`) are metadata changes (no revision) \u2014 toggling cross_cutting ON is rejected while explicit links exist; unlink first. Supplying none of title/body/summary/area/cross_cutting/decision_links is an empty edit (400) (\xA77). Cite the decision record a rule rests on rather than restating what was decided in its body: the record is where the reasoning stays correct, and a body repeating it goes stale the moment the decision is superseded. Link another record by key plus title on first mention; never paste its text into a body \u2014 the source changes, the copy does not, and a stale copy gets built.",
     // Inline shape (updateRequirementInputSchema is a refine, no .shape) — add
-    // summary/area here explicitly (§210); the empty-edit refine is enforced by
-    // the API, not this shape.
+    // summary/area here explicitly (§210) and decisionLinks (PIPE-84 §6); the
+    // empty-edit refine is enforced by the API, not this shape.
     inputSchema: {
       requirement: requirementRefSchema,
       title: external_exports.string().min(1).optional(),
@@ -17031,13 +17143,30 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
       body: markdownSchema.optional(),
       area: external_exports.string().optional(),
       note: external_exports.string().min(1).optional(),
-      crossCutting: external_exports.boolean().optional()
+      crossCutting: external_exports.boolean().optional(),
+      decisionLinks: decisionLinkChangesSchema.optional()
     }
   }, ({ requirement, ...fields }) => run(() => client2.updateRequirement(requirement, fields)));
   registerTool("approve_requirement", {
     description: "Approve (pin) a requirement\u2019s latest revision, or a specified `revision`, recording it in approvals history and advancing the approved revision that downstream links and reads build against (\xA75, \xA77).",
     inputSchema: approveRequirementInputSchema.shape
   }, (args) => run(() => client2.approveRequirement(args.requirement, args.revision)));
+  registerTool("create_decision", {
+    description: "Record ONE decision as a project-scoped decision record (`KEY-D{n}`): `title` names the decision and `body` says what was decided and why. A new record starts `proposed`; moving it to `accepted` IS the acceptance \u2014 there is no separate approval step. Returns the created record. A decision record is written ONCE. Title and body can be corrected only while it is `proposed`; from `accepted` onward the record is frozen, and the way to change a decision is to write a NEW record and `supersede_decision` the old one \u2014 which leaves the original readable and says where the current decision went. Nothing on any surface deletes one. Search before you create: `list_decisions` takes a `text` filter matching TITLE AND BODY \u2014 run it on the distinctive nouns first. Sessions do not see each other, so re-arguing a settled question leaves two answers on the ledger with nothing saying which one holds. Link another record by key plus title on first mention; never paste its text into a body \u2014 the source changes, the copy does not, and a stale copy gets built.",
+    inputSchema: createDecisionInputSchema.shape
+  }, (args) => run(() => client2.createDecision(args)));
+  registerTool("get_decision", {
+    description: "Get a decision record by display id (`KEY-D{n}`) or uuid: title, body, lifecycle state (`proposed`/`accepted`/`superseded`), who accepted it and when, the record that replaced it, where the CURRENT decision lives when this one has been superseded, and everything that references it \u2014 every requirement and every work item, gathered from both directions.",
+    inputSchema: getDecisionInputSchema.shape
+  }, (args) => run(() => client2.getDecision(args.decision)));
+  registerTool("list_decisions", {
+    description: "List decision records filtered by `project` and `text`: display id, title, lifecycle state, the replacement when superseded, and how many requirements and work items cite each one. `text` matches over TITLE AND BODY, so search on what a decision was about rather than on what someone chose to call it. Read the decisions before re-opening a settled question: an `accepted` record is the project\u2019s answer, and arguing it again inside an issue or requirement body produces a second answer with nothing saying which one holds. If the answer genuinely has changed, record a NEW decision and `supersede_decision` the old one rather than editing anything.",
+    inputSchema: listDecisionsFilterSchema.shape
+  }, (args) => run(() => client2.listDecisions(args)));
+  registerTool("supersede_decision", {
+    description: "Replace an ACCEPTED decision record with another one: `decision` moves to `superseded` and names `replacedBy` as where the current decision now lives, so whoever opens the old record is sent to the standing one. This is the only way a decision changes \u2014 the original is never edited and never removed, and the whole chain stays readable. Refused when the record is still `proposed` (nothing has been decided yet, so correct it instead), when a record is named as its own replacement, when the replacement belongs to another project, or when the replacement\u2019s own chain already leads back to this record. Returns the superseded record.",
+    inputSchema: supersedeDecisionInputSchema.shape
+  }, (args) => run(() => client2.supersedeDecision(args.decision, args.replacedBy)));
   registerTool("list_content", {
     description: "List content drafts filtered by project, text, area, and author: display id (KEY-C{n}), title, summary (latest revision), area, author, latest revision number, deliverable count, and linked-issue count. Content is a project-scoped sibling of requirements \u2014 raw material that gets promoted into work, not an issue type.",
     inputSchema: listContentFilterSchema.shape
@@ -17077,21 +17206,23 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     }
   }, ({ deliverable, ...fields }) => run(() => client2.promoteDeliverable(deliverable, fields)));
   registerTool("list_assets", {
-    description: "List project assets (S3-backed files of any type) filtered by project, status (pending/active/rejected), category (image/video/document), and filename text, sorted by date or size (asc/desc): id, filename, contentType, size, sha256, status, hasThumbnail, and linkCount (live references). Metadata only \u2014 the bytes move by path (upload_asset/download_asset), never through this result.",
+    description: "List project assets (S3-backed files of any type) filtered by project, status (pending/active/rejected), category (image/video/document), and filename text, sorted by date or size (asc/desc): id, filename, contentType, size, sha256, status, hasThumbnail, and linkCount (live references). Metadata only \u2014 the bytes move by path, never through this result.",
     inputSchema: listAssetsFilterSchema.shape
   }, (args) => run(() => client2.listAssets(args)));
   registerTool("get_asset", {
-    description: "Get an asset\u2019s metadata by uuid: filename, contentType, size, sha256 (client-computed, server-verified by read-back), status, hasThumbnail, linkCount (live references), and timestamps. Metadata only \u2014 no value/URL is returned over MCP; use download_asset to write the bytes to a local file.",
+    description: "Get an asset\u2019s metadata by uuid: filename, contentType, size, sha256 (client-computed, server-verified by read-back), status, hasThumbnail, linkCount (live references), and timestamps. Metadata only \u2014 no value/URL is returned over MCP. To get the bytes, use download_asset (a LOCAL server only \u2014 it writes to a path on the machine running the server) or `ppb assets download`.",
     inputSchema: { asset: uuidSchema }
   }, (args) => run(() => client2.getAsset(args.asset)));
-  registerTool("upload_asset", {
-    description: "Upload a LOCAL FILE (by path) as a project asset and activate it: reads and SHA-256-hashes the file locally, registers the asset, PUTs the bytes directly to storage, and completes (server verifies the digest by read-back). Returns the asset metadata (status active on success). Only the file PATH crosses the wire \u2014 the bytes never do; do NOT pass base64 or file contents. contentType is guessed from the extension when omitted. Then use link_asset to attach the returned asset to a deliverable revision or a content draft.",
-    inputSchema: uploadAssetInputSchema.shape
-  }, (args) => run(() => uploadAssetFromPath(client2, apiBaseUrl, args)));
-  registerTool("download_asset", {
-    description: "Download an ACTIVE asset\u2019s bytes to a LOCAL FILE at `path` (created/overwritten), so you can read or view an uploaded image, mockup, or document. The bytes are written to disk and re-verified against the recorded sha256; the RESULT is metadata + the written path \u2014 never the bytes or a URL. Addressed by asset uuid (from list_assets, get_asset, or get_content).",
-    inputSchema: downloadAssetInputSchema.shape
-  }, (args) => run(() => downloadAssetToPath(client2, args)));
+  if (surface === "local") {
+    registerTool("upload_asset", {
+      description: "Upload a LOCAL FILE (by path) as a project asset and activate it: reads and SHA-256-hashes the file locally, registers the asset, PUTs the bytes directly to storage, and completes (server verifies the digest by read-back). Returns the asset metadata (status active on success). Only the file PATH crosses the wire \u2014 the bytes never do; do NOT pass base64 or file contents. contentType is guessed from the extension when omitted. Then use link_asset to attach the returned asset to a deliverable revision or a content draft.",
+      inputSchema: uploadAssetInputSchema.shape
+    }, (args) => run(() => uploadAssetFromPath(client2, apiBaseUrl, args)));
+    registerTool("download_asset", {
+      description: "Download an ACTIVE asset\u2019s bytes to a LOCAL FILE at `path` (created/overwritten), so you can read or view an uploaded image, mockup, or document. The bytes are written to disk and re-verified against the recorded sha256; the RESULT is metadata + the written path \u2014 never the bytes or a URL. Addressed by asset uuid (from list_assets, get_asset, or get_content).",
+      inputSchema: downloadAssetInputSchema.shape
+    }, (args) => run(() => downloadAssetToPath(client2, args)));
+  }
   registerTool("link_asset", {
     description: "Reference an active asset FROM a target. Two targets are wired: `deliverable_revision` (targetId is a content_deliverable_revision uuid, e.g. from get_content) and `content_draft` (targetId is a content_draft uuid \u2014 the asset attaches to the topic doc and is snapshot-copied onto deliverables when they are created). Rejects a non-active asset or a cross-project link.",
     inputSchema: linkAssetInputSchema.shape
@@ -17185,17 +17316,15 @@ ${issues.map((issue2) => `  - ${issue2}`).join("\n")}`);
 
 // src/config.ts
 var import_dotenv2 = __toESM(require_main(), 1);
-var UNEXPANDED_PLACEHOLDER = /^\$(\{[^}]*\}|[A-Za-z_][A-Za-z0-9_]*)$/;
-var TOKEN_PREFIXES = ["pbt_", "plt_"];
 var apiTokenSchema2 = external_exports.string().min(1).superRefine((value, ctx) => {
-  if (UNEXPANDED_PLACEHOLDER.test(value)) {
+  if (isUnexpandedPlaceholder(value)) {
     ctx.addIssue({
       code: "custom",
       message: `is the literal string \`${value}\` \u2014 an unexpanded shell placeholder, not a token. The variable was unset in the environment that launched this server, so nothing substituted it. Export a pbt_ token before launching, or point the launcher at a wrapper that reads your token file.`
     });
     return;
   }
-  if (!TOKEN_PREFIXES.some((prefix) => value.startsWith(prefix))) {
+  if (!isAcceptedTokenShape(value)) {
     ctx.addIssue({
       code: "custom",
       message: "is not a Pipebrain API token \u2014 expected `pbt_\u2026` (legacy `plt_\u2026` accepted) (value withheld). Mint one under Settings \u2192 Organization \u2192 API tokens."
@@ -17232,7 +17361,7 @@ function loadMcpConfig() {
 }
 
 // src/version.ts
-var VERSION = "0.16.0";
+var VERSION = "0.17.0";
 
 // src/main.ts
 var config2 = loadMcpConfig();
@@ -17241,7 +17370,10 @@ var client = new ApiClient({
   auth: { bearer: config2.token }
 });
 var orgInstructions = await fetchOrgInstructionsSafe(client);
-var server = createMcpServer(client, config2.apiUrl, orgInstructions, { version: VERSION });
+var server = createMcpServer(client, config2.apiUrl, orgInstructions, {
+  version: VERSION,
+  surface: "local"
+});
 var transport = new StdioServerTransport();
 await server.connect(transport);
 var notice = successorNotice();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipebrain-mcp",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Pipebrain MCP server for Claude Code and Claude Desktop — issues, requirements, content, assets, and metadata-only secrets over the Pipebrain API.",
   "type": "module",
   "license": "MIT",
@@ -13,7 +13,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fvcsolutions/pipeline.git",
+    "url": "git+https://github.com/fvcsolutions/pipebrain.git",
     "directory": "apps/mcp"
   },
   "publishConfig": {
@@ -26,7 +26,7 @@
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
     "build": "node build.mjs",
     "build:mcpb": "nx build pipebrain-mcp && node mcpb/build-mcpb.mjs",
-    "prepack": "npx nx build pipebrain-mcp"
+    "prepack": "npx nx build pipebrain-mcp && node ../../scripts/check-publishable.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0"