@rockhopper-co/mcp-server 1.0.0 → 2.0.1

package/CHANGELOG.md

@@ -4,39 +4,50 @@ All notable changes to this project are documented here. Follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] — 2026-08-10
-
-**No code changed between `0.10.0` and `1.0.0`.** This release exists to fix a
-versioning trap, and states a compatibility promise that was already true.
+## [2.0.0] — 2026-08-16
 
-### Why 1.0.0
-
-On a `0.x` version npm reads a caret range as **minor-locked**: `^0.9.0` means
-`>=0.9.0 <0.10.0`, not `<1.0.0`. Nobody reads it that way. It cost two releases
-— `mcp-gateway` sat on `^0.9.0` and could not receive `0.10.0`, the very release
-it was waiting for, and before that on the same coupling one release earlier
-(ENG-2165, ENG-2233). At `1.x` a caret finally means "any compatible version".
-
-### The compatibility promise
-
-From `1.0.0`, a breaking change to any of the following requires a major bump:
+Cuts everything that had accumulated under `[Unreleased]` below. Published by
+ENG-2533, the batched release the MCP-spec epic (ENG-2164) deferred to its end.
 
-- **Tool names and their input schemas.** These are the load-bearing ones. The
-  schemas are runtime `zod` validators that execute **on the caller's machine**,
-  before any request is sent, so narrowing one breaks that caller no matter how
-  compatible the backend is. Widening a schema is not breaking; narrowing it is.
-- **Resource URIs and templates**, and the prompts the server registers.
-- **The CLI's flags and its stdio contract.**
+### Why a major
 
-Explicitly **not** covered, and free to change in a minor: internal modules, the
-`dist/` layout, anything reachable only by deep-importing a path this package
-does not document, and log output.
+`engines.node` moved from `>=18.0.0` to `>=20.0.0` (see Breaking, below) — that
+alone requires it under the 1.0.0 compatibility promise. Separately, and more
+visibly to a caller: **which tools get registered now depends on what the
+presenting token was actually granted.** A `read-only` token that saw all 16
+tools on 1.0.0 sees 7 here, and a token holding one write family sees only that
+family's tools. That is the intended behaviour (ENG-2208, ENG-2212) and it is
+still a change a caller can observe, so it ships behind a major.
 
-### Note for consumers
+### Note on the 1.0.0 → 2.0.0 gap
 
-Move a `^0.x` range to `^1.0.0`. A `0.x` range will not pick this up.
+The `[Unreleased]` block cut here had accumulated across more than one round:
+`0.7.0`, `0.8.0` and `0.10.0` were published without their own headings, and
+`1.0.0` was cut above it rather than below. The entries below are therefore NOT
+all new since 1.0.0. They are left as written rather than retro-attributed to
+releases nobody recorded at the time — an invented attribution would read as
+fact. Everything from here on is dated.
 
-## [Unreleased]
+### Changed
+- **Moved to the v2 MCP SDK (ENG-2175).** v2 is a package **split**, not a
+  version bump: `@modelcontextprotocol/sdk` stays on the v1 line at 1.30.0
+  forever, and v2 ships as `@modelcontextprotocol/{core,server,client,node}`.
+  This package now depends on `@modelcontextprotocol/server` (and
+  `@modelcontextprotocol/client` for tests). Tool `inputSchema` and prompt
+  `argsSchema` are declared as `z.object({...})` rather than the raw
+  `{ field: schema }` shape v1 accepted.
+
+  **Nothing changes on the wire.** v2's `LATEST_PROTOCOL_VERSION` is
+  `2025-11-25` — the same value v1 1.30.0 carried — so a connected client
+  negotiates exactly the version it did before, and the advertised
+  capabilities are unchanged (`prompts`, `resources`, `tools`). Serving
+  protocol revision 2026-07-28 is separate work (ENG-2176).
+
+### Breaking
+- **`engines.node` moved from `>=18.0.0` to `>=20.0.0`.** Every v2 SDK package
+  declares `engines.node: ">=20"`, so the previous floor advertised a Node
+  version this package no longer runs on. Node 18 reached end of life on
+  2025-04-30.
 
 ### Added
 - **User and team ids are accepted as uuids (ENG-2230).** `reviewerIds` on
@@ -230,6 +241,38 @@ Move a `^0.x` range to `^1.0.0`. A `0.x` range will not pick this up.
   `@typescript-eslint/no-explicit-any` (mock-stub casts) while production
   code keeps the rule on. Lint is clean across `src/`.
 
+## [1.0.0] — 2026-08-10
+
+**No code changed between `0.10.0` and `1.0.0`.** This release exists to fix a
+versioning trap, and states a compatibility promise that was already true.
+
+### Why 1.0.0
+
+On a `0.x` version npm reads a caret range as **minor-locked**: `^0.9.0` means
+`>=0.9.0 <0.10.0`, not `<1.0.0`. Nobody reads it that way. It cost two releases
+— `mcp-gateway` sat on `^0.9.0` and could not receive `0.10.0`, the very release
+it was waiting for, and before that on the same coupling one release earlier
+(ENG-2165, ENG-2233). At `1.x` a caret finally means "any compatible version".
+
+### The compatibility promise
+
+From `1.0.0`, a breaking change to any of the following requires a major bump:
+
+- **Tool names and their input schemas.** These are the load-bearing ones. The
+  schemas are runtime `zod` validators that execute **on the caller's machine**,
+  before any request is sent, so narrowing one breaks that caller no matter how
+  compatible the backend is. Widening a schema is not breaking; narrowing it is.
+- **Resource URIs and templates**, and the prompts the server registers.
+- **The CLI's flags and its stdio contract.**
+
+Explicitly **not** covered, and free to change in a minor: internal modules, the
+`dist/` layout, anything reachable only by deep-importing a path this package
+does not document, and log output.
+
+### Note for consumers
+
+Move a `^0.x` range to `^1.0.0`. A `0.x` range will not pick this up.
+
 ## [0.6.0] — 2026-05-13
 
 > Released to npm as `0.6.0`. The release branch was prepared with

package/README.md

@@ -4,7 +4,7 @@ MCP (Model Context Protocol) server for Rockhopper. Lets AI tools like Claude, C
 
 ## Prerequisites
 
-- Node.js 18+
+- Node.js 20+
 - A Rockhopper account with at least one enrolled file
 - (Optional) A Personal Access Token — only required for headless / CI / scripted setups
 

package/dist/api-client.d.ts

@@ -50,6 +50,8 @@ export declare class ApiClient {
     private readonly surface;
     private readonly sessionId;
     private drivingHumanPlatformId;
+    private authExpiredHandler?;
+    private authExpiredNotified;
     constructor(config: ApiClientConfig);
     /**
      * ENG-1756: declare (or clear) the human driving this agent. The CLI sets
@@ -59,6 +61,22 @@ export declare class ApiClient {
      * working — this header is the explicit, forward-compatible form.
      */
     setDrivingHuman(platformId: string | null): void;
+    /**
+     * ENG-2208 — run `handler` the FIRST time this client sees a 401, and never
+     * again for the life of the client.
+     *
+     * A token that expires mid-session is silent today: the 401 becomes an error
+     * string inside a tool result, which the model reads and the human does not.
+     * The CLI registers a handler that writes one stderr line, and registers it
+     * only AFTER the `/users/me` preflight has succeeded — so a token that was
+     * already dead at launch takes the startup path (which exits with its own
+     * message) and can never double-report here.
+     *
+     * 401 only. A 403 is an authorisation answer about one resource, not a dead
+     * token, and telling a customer to re-mint their token over a permission
+     * denial sends them to fix the wrong thing.
+     */
+    setAuthExpiredHandler(handler: () => void): void;
     /**
      * KI-096: optional `responseSchema` validates the response shape with
      * zod. When supplied, drift between backend's actual response and the

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/api-client.js

@@ -44,6 +44,8 @@ export class ApiClient {
     surface;
     sessionId;
     drivingHumanPlatformId;
+    authExpiredHandler;
+    authExpiredNotified = false;
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.token = config.token;
@@ -63,6 +65,24 @@ export class ApiClient {
     setDrivingHuman(platformId) {
         this.drivingHumanPlatformId = platformId;
     }
+    /**
+     * ENG-2208 — run `handler` the FIRST time this client sees a 401, and never
+     * again for the life of the client.
+     *
+     * A token that expires mid-session is silent today: the 401 becomes an error
+     * string inside a tool result, which the model reads and the human does not.
+     * The CLI registers a handler that writes one stderr line, and registers it
+     * only AFTER the `/users/me` preflight has succeeded — so a token that was
+     * already dead at launch takes the startup path (which exits with its own
+     * message) and can never double-report here.
+     *
+     * 401 only. A 403 is an authorisation answer about one resource, not a dead
+     * token, and telling a customer to re-mint their token over a permission
+     * denial sends them to fix the wrong thing.
+     */
+    setAuthExpiredHandler(handler) {
+        this.authExpiredHandler = handler;
+    }
     /**
      * KI-096: optional `responseSchema` validates the response shape with
      * zod. When supplied, drift between backend's actual response and the
@@ -139,6 +159,15 @@ export class ApiClient {
                 durationMs,
                 classification,
             }, 'api_request_failed');
+            // ENG-2208: one-shot mid-session expiry notice (see
+            // {@link setAuthExpiredHandler}). Guarded on the handler existing so the
+            // "first 401" is the first one anybody is listening for.
+            if (response.status === 401 &&
+                this.authExpiredHandler &&
+                !this.authExpiredNotified) {
+                this.authExpiredNotified = true;
+                this.authExpiredHandler();
+            }
             const body = await response.text().catch(() => '');
             if (notReady) {
                 throw new ChangeHistoryNotReadyError({

package/dist/api-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/capabilities.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ENG-2212 — the write-capability VOCABULARY, kept apart from the registrars
+ * that act on it.
+ *
+ * Its own module because `instructions.ts` needs the tool names per family and
+ * `tools/index.ts` needs the registrars: folding both into one module means
+ * every test that mocks the registration seam also has to restate the
+ * vocabulary, and a restated vocabulary is one that drifts.
+ */
+/**
+ * The four write families a Personal Access Token may hold, in the order they
+ * are reported and rendered. Mirrors the backend's `PatCapability`
+ * (`backend/src/resources/personal-access-tokens/pat-capabilities.ts`) and the
+ * `CHK_pat_scopes_vocabulary` constraint on the stored column.
+ */
+export declare const PAT_CAPABILITIES: readonly ["comments:write", "reviews:write", "versions:write", "files:write"];
+export type PatCapability = (typeof PAT_CAPABILITIES)[number];
+export declare const CAPABILITY_SET: ReadonlySet<string>;
+/**
+ * The write tools each family covers.
+ *
+ * This is the VOCABULARY, not the registration list: `enroll_file` is named
+ * here before any registrar registers it, because plan 13's ENG-2200 adds that
+ * tool this release and is blockedBy this ticket. Carrying the edge now means
+ * that ticket adds a registrar and drops one entry from
+ * {@link PENDING_WRITE_TOOLS}, rather than re-cutting the family map in every
+ * repo that copied it.
+ */
+export declare const WRITE_TOOLS_BY_CAPABILITY: Readonly<Record<PatCapability, readonly string[]>>;
+/**
+ * Names in {@link WRITE_TOOLS_BY_CAPABILITY} that no registrar registers yet.
+ *
+ * Kept explicit so the instructions string never advertises a tool the model
+ * cannot call, and so `tools.capability-gate.test.ts` can assert that every
+ * OTHER enumerated name really is registered — a set derived from the
+ * registrars rather than a second hand-maintained list that silently drifts.
+ */
+export declare const PENDING_WRITE_TOOLS: ReadonlySet<string>;
+/** The tools a granted family actually adds to the surface today. */
+export declare function registeredToolsForCapabilities(capabilities: readonly PatCapability[]): string[];
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,+EAKnB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAA6B,CAAC;AAE7E;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAC9C,MAAM,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC,CAMzC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAElD,CAAC;AAEH,qEAAqE;AACrE,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,SAAS,aAAa,EAAE,GACrC,MAAM,EAAE,CAMV"}

package/dist/capabilities.js

@@ -0,0 +1,54 @@
+/**
+ * ENG-2212 — the write-capability VOCABULARY, kept apart from the registrars
+ * that act on it.
+ *
+ * Its own module because `instructions.ts` needs the tool names per family and
+ * `tools/index.ts` needs the registrars: folding both into one module means
+ * every test that mocks the registration seam also has to restate the
+ * vocabulary, and a restated vocabulary is one that drifts.
+ */
+/**
+ * The four write families a Personal Access Token may hold, in the order they
+ * are reported and rendered. Mirrors the backend's `PatCapability`
+ * (`backend/src/resources/personal-access-tokens/pat-capabilities.ts`) and the
+ * `CHK_pat_scopes_vocabulary` constraint on the stored column.
+ */
+export const PAT_CAPABILITIES = [
+    'comments:write',
+    'reviews:write',
+    'versions:write',
+    'files:write',
+];
+export const CAPABILITY_SET = new Set(PAT_CAPABILITIES);
+/**
+ * The write tools each family covers.
+ *
+ * This is the VOCABULARY, not the registration list: `enroll_file` is named
+ * here before any registrar registers it, because plan 13's ENG-2200 adds that
+ * tool this release and is blockedBy this ticket. Carrying the edge now means
+ * that ticket adds a registrar and drops one entry from
+ * {@link PENDING_WRITE_TOOLS}, rather than re-cutting the family map in every
+ * repo that copied it.
+ */
+export const WRITE_TOOLS_BY_CAPABILITY = {
+    'comments:write': ['add_comment', 'reply_to_comment', 'resolve_comment'],
+    'reviews:write': ['create_review_request', 'approve_review', 'cancel_review'],
+    'versions:write': ['create_version', 'discard_changes'],
+    'files:write': ['rename_file', 'enroll_file'],
+};
+/**
+ * Names in {@link WRITE_TOOLS_BY_CAPABILITY} that no registrar registers yet.
+ *
+ * Kept explicit so the instructions string never advertises a tool the model
+ * cannot call, and so `tools.capability-gate.test.ts` can assert that every
+ * OTHER enumerated name really is registered — a set derived from the
+ * registrars rather than a second hand-maintained list that silently drifts.
+ */
+export const PENDING_WRITE_TOOLS = new Set([
+    'enroll_file',
+]);
+/** The tools a granted family actually adds to the surface today. */
+export function registeredToolsForCapabilities(capabilities) {
+    return capabilities.flatMap((capability) => WRITE_TOOLS_BY_CAPABILITY[capability].filter((name) => !PENDING_WRITE_TOOLS.has(name)));
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,gBAAgB;IAChB,eAAe;IACf,gBAAgB;IAChB,aAAa;CACL,CAAC;AAIX,MAAM,CAAC,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAE7E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAElC;IACF,gBAAgB,EAAE,CAAC,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;IACxE,eAAe,EAAE,CAAC,uBAAuB,EAAE,gBAAgB,EAAE,eAAe,CAAC;IAC7E,gBAAgB,EAAE,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;IACvD,aAAa,EAAE,CAAC,aAAa,EAAE,aAAa,CAAC;CAC9C,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC;IAC9D,aAAa;CACd,CAAC,CAAC;AAEH,qEAAqE;AACrE,MAAM,UAAU,8BAA8B,CAC5C,YAAsC;IAEtC,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CACzC,yBAAyB,CAAC,UAAU,CAAC,CAAC,MAAM,CAC1C,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CACzC,CACF,CAAC;AACJ,CAAC"}

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { ApiClient } from './api-client.js';
 import { AuthResolutionError, resolveAuth, } from './auth/resolve-auth.js';
 import { flushLoggerSync, initLogger, log, serviceVersion, } from './logger.js';
@@ -63,8 +63,18 @@ const apiClient = new ApiClient({
     baseUrl: ROCKHOPPER_API_URL,
     token: resolved.accessToken,
 });
+// ENG-2208: the scope the token reports about ITSELF (ENG-2205 put it on the
+// preflight response). Left undefined by a backend older than that, and by any
+// non-PAT principal — both of which the allow-list in `tools/index.ts` denies.
+let patScope;
+// ENG-2212: the write families the token actually holds. Absent against a
+// backend older than ENG-2211, which is why `patScope` is still read — absent
+// means "the backend said nothing", and the coarse scope decides.
+let patCapabilities;
 try {
     const me = await apiClient.getMe();
+    patScope = me?.patScope;
+    patCapabilities = me?.patScopes;
     // ENG-1756 (plan §9 decision 15): the PAT owner IS the human driving this
     // local agent — reuse the preflight to declare them, so every write carries
     // `X-Driving-Human` and the backend's anonymous-agent-write admission
@@ -95,9 +105,47 @@ catch (err) {
     }
     process.exit(1);
 }
-const server = createServer(apiClient);
+// ENG-2208: the preflight succeeded, so from here a 401 means the token died
+// mid-session. Report it once on stderr — the only channel a stdio server has
+// to the human — instead of leaving it as an error string inside a tool result
+// that only the model ever reads.
+apiClient.setAuthExpiredHandler(() => {
+    log.warn({ event: 'auth_failed', reason: 'expired_mid_session' }, 'auth_failed');
+    console.error('Error: Rockhopper rejected the token (401) — it expired or was revoked after this server started. ' +
+        'Create a new Personal Access Token in Rockhopper Settings and restart this MCP server.');
+});
+// ENG-2208: register only what this token may do. `createServer(apiClient)` —
+// one argument — used to register all nine write tools for every launch, so a
+// read-only token advertised writes it could not perform and the customer's
+// scope choice surfaced as a 403 rendered into tool text.
+//
+// ENG-2176: a FACTORY now, not one instance. `serveStdio` owns the era
+// decision for the connection and calls this per connection — plus once more
+// for a `server/discover` probe it discards if the client falls back to
+// `initialize`. Each call must therefore hand back a fresh server.
+//
+// ENG-2212: the FAMILIES ride along. When the backend serves them they decide
+// which registrars run, one per family, so a token granted `comments:write`
+// alone no longer receives `discard_changes`.
+const buildServer = () => createServer(apiClient, { scope: patScope, capabilities: patCapabilities });
 // KI-225: one line per launch — anchors a session in the file.
-log.info({ event: 'mcp_server_start', version: serviceVersion }, 'mcp_server_start');
-const transport = new StdioServerTransport();
-await server.connect(transport);
+log.info({
+    event: 'mcp_server_start',
+    version: serviceVersion,
+    scope: patScope ?? 'unknown',
+    capabilities: patCapabilities ?? 'unknown',
+}, 'mcp_server_start');
+// ENG-2176: `serveStdio`, not `new StdioServerTransport()` + `connect`. The
+// modern (2026-07-28) handlers — `server/discover`, and adding `2026-07-28`
+// to the instance's supported-versions list — are installed by the SERVING
+// ENTRY, never by the server object: the SDK's default
+// `SUPPORTED_PROTOCOL_VERSIONS` names only 2025-era revisions, so a
+// hand-connected server answers `server/discover` with `-32601` forever.
+// `legacy: 'serve'` (the default) keeps a 2025-era client working unchanged —
+// it pins the connection to a 2025 instance from this same factory.
+serveStdio(buildServer, {
+    onerror: (err) => {
+        log.error({ event: 'stdio_serving_error', err }, 'stdio_serving_error');
+    },
+});
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/correlation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EACpC,IAAI,MAAM,CAAC,EACX,KAAI,MAAqB,KACxB,CAAoB,CAAC;AAExB,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,QAAO,MAAM,GAAG,SAA2B,CAAC"}
+{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EACpC,IAAI,MAAM,CAAC,EACX,KAAI,MAAqB,KACxB,CAAoB,CAAC;AAExB,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,QAAO,MAAM,GAAG,SAA2B,CAAC"}

package/dist/correlation.js

@@ -10,9 +10,8 @@ import { randomUUID } from 'node:crypto';
  * traceable as a group in backend logs.
  *
  * The id is a non-sensitive UUID v4 — never co-log the bearer token with it.
- * `randomUUID` comes from `node:crypto` (NOT the global `crypto`) because the
- * package supports Node 18, where global `crypto.randomUUID` is not
- * guaranteed.
+ * `randomUUID` comes from `node:crypto` (NOT the global `crypto`): the explicit
+ * import is the portable form and does not depend on the global being present.
  */
 const als = new AsyncLocalStorage();
 /**

package/dist/correlation.js.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;GAaG;AACH,MAAM,GAAG,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,EAAW,EACX,KAAa,UAAU,EAAE,EACtB,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAExB,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAuB,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,GAAG,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,EAAW,EACX,KAAa,UAAU,EAAE,EACtB,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAExB,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAuB,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC"}

package/dist/instructions.d.ts

@@ -0,0 +1,3 @@
+import { type PatCapability } from './capabilities.js';
+export declare function buildInstructions(capabilities: readonly PatCapability[]): string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAkC3B,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,SAAS,aAAa,EAAE,GACrC,MAAM,CA4BR"}

package/dist/instructions.js

@@ -0,0 +1,46 @@
+import { PAT_CAPABILITIES, registeredToolsForCapabilities, } from './capabilities.js';
+/**
+ * ENG-2212 — the `instructions` string the model reads, built from the SAME
+ * families that decide which registrars run.
+ *
+ * It used to say one of two things: "this token is read-only", or a list of
+ * all nine write tools. A token holding `comments:write` alone got the second
+ * sentence and was told `discard_changes` existed — so the model planned work
+ * it could not perform, and the customer's narrowing surfaced as a
+ * method-not-found error mid-task.
+ */
+const PREAMBLE = 'Rockhopper MCP server for managing Excel file metadata. ' +
+    'Use list_files first to discover available files, then drill into ' +
+    'versions, comments, reviews, or cell history. ';
+const FILE_IDS = 'File IDs use the platformId field (e.g. from list_files output).';
+/** What each family is called in a sentence a model reads. */
+const FAMILY_PROSE = {
+    'comments:write': 'comments',
+    'reviews:write': 'reviews',
+    'versions:write': 'versions',
+    'files:write': 'files',
+};
+function list(parts) {
+    if (parts.length <= 1)
+        return parts[0] ?? '';
+    return `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`;
+}
+export function buildInstructions(capabilities) {
+    if (capabilities.length === 0) {
+        return ('Rockhopper MCP server for reading Excel file metadata. ' +
+            'Use list_files first to discover available files, then drill into ' +
+            'versions, comments, reviews, or cell history. ' +
+            'This token is read-only — write operations are not available. ' +
+            FILE_IDS);
+    }
+    const granted = registeredToolsForCapabilities(capabilities);
+    const withheld = PAT_CAPABILITIES.filter((c) => !capabilities.includes(c));
+    const withheldSentence = withheld.length === 0
+        ? ''
+        : `No other write operations are available to this token — it was not granted ${list(withheld.map((c) => FAMILY_PROSE[c]))}. `;
+    return (PREAMBLE +
+        `This token may write ${list(capabilities.map((c) => FAMILY_PROSE[c]))}: ${granted.join(', ')}. ` +
+        withheldSentence +
+        FILE_IDS);
+}
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,8BAA8B,GAE/B,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AAEH,MAAM,QAAQ,GACZ,0DAA0D;IAC1D,oEAAoE;IACpE,gDAAgD,CAAC;AAEnD,MAAM,QAAQ,GACZ,kEAAkE,CAAC;AAErE,8DAA8D;AAC9D,MAAM,YAAY,GAA4C;IAC5D,gBAAgB,EAAE,UAAU;IAC5B,eAAe,EAAE,SAAS;IAC1B,gBAAgB,EAAE,UAAU;IAC5B,aAAa,EAAE,OAAO;CACvB,CAAC;AAEF,SAAS,IAAI,CAAC,KAAwB;IACpC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,YAAsC;IAEtC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,CACL,yDAAyD;YACzD,oEAAoE;YACpE,gDAAgD;YAChD,gEAAgE;YAChE,QAAQ,CACT,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,8BAA8B,CAAC,YAAY,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,MAAM,gBAAgB,GACpB,QAAQ,CAAC,MAAM,KAAK,CAAC;QACnB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,8EAA8E,IAAI,CAChF,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CACrC,IAAI,CAAC;IAEZ,OAAO,CACL,QAAQ;QACR,wBAAwB,IAAI,CAC1B,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CACzC,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QAC5B,gBAAgB;QAChB,QAAQ,CACT,CAAC;AACJ,CAAC"}

package/dist/lib.d.ts

@@ -12,12 +12,20 @@
  * with their own transport (HTTP, in-memory, etc.).
  *
  * Stable API surface (semver-bound):
- *   - `createServer(apiClient): McpServer`
+ *   - `createServer(apiClient, options?): McpServer`
+ *   - `grantsWriteTools(scope)` — the write allow-list (ENG-2208), exported so
+ *     the gateway asks the same question instead of writing a second copy of
+ *     the rule that would drift from this one.
+ *   - `PAT_CAPABILITIES`, `WRITE_TOOLS_BY_CAPABILITY`, `PENDING_WRITE_TOOLS`
+ *     and `resolveCapabilities` (ENG-2212) — the four write families, which
+ *     tools each covers, and how a grant is resolved. Exported for the same
+ *     reason: the gateway has to answer "which family does this tool need"
+ *     BEFORE it builds a server, and a hand-copied list drifts.
  *   - `ApiClient` (class) and `ApiClientConfig` (interface)
  *   - All `types` (Team, EnrolledFile, FileVersion, ...)
  */
 export { createServer } from './server.js';
-export { type RegisterToolsOptions } from './tools/index.js';
+export { grantsWriteTools, resolveCapabilities, registeredToolsForCapabilities, PAT_CAPABILITIES, PENDING_WRITE_TOOLS, WRITE_TOOLS_BY_CAPABILITY, type PatCapability, type RegisterToolsOptions, } from './tools/index.js';
 export { ApiClient, type ApiClientConfig } from './api-client.js';
 export * from './types.js';
 //# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClE,cAAc,YAAY,CAAC"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,8BAA8B,EAC9B,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClE,cAAc,YAAY,CAAC"}

package/dist/lib.js

@@ -12,11 +12,20 @@
  * with their own transport (HTTP, in-memory, etc.).
  *
  * Stable API surface (semver-bound):
- *   - `createServer(apiClient): McpServer`
+ *   - `createServer(apiClient, options?): McpServer`
+ *   - `grantsWriteTools(scope)` — the write allow-list (ENG-2208), exported so
+ *     the gateway asks the same question instead of writing a second copy of
+ *     the rule that would drift from this one.
+ *   - `PAT_CAPABILITIES`, `WRITE_TOOLS_BY_CAPABILITY`, `PENDING_WRITE_TOOLS`
+ *     and `resolveCapabilities` (ENG-2212) — the four write families, which
+ *     tools each covers, and how a grant is resolved. Exported for the same
+ *     reason: the gateway has to answer "which family does this tool need"
+ *     BEFORE it builds a server, and a hand-copied list drifts.
  *   - `ApiClient` (class) and `ApiClientConfig` (interface)
  *   - All `types` (Team, EnrolledFile, FileVersion, ...)
  */
 export { createServer } from './server.js';
+export { grantsWriteTools, resolveCapabilities, registeredToolsForCapabilities, PAT_CAPABILITIES, PENDING_WRITE_TOOLS, WRITE_TOOLS_BY_CAPABILITY, } from './tools/index.js';
 export { ApiClient } from './api-client.js';
 export * from './types.js';
 //# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -1 +1 @@
-{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAwB,MAAM,iBAAiB,CAAC;AAClE,cAAc,YAAY,CAAC"}
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,8BAA8B,EAC9B,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,GAG1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAwB,MAAM,iBAAiB,CAAC;AAClE,cAAc,YAAY,CAAC"}