@rockhopper-co/mcp-server 2.0.1 → 2.1.1-staging.2786a25

package/dist/tools/drive-search-lanes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ENG-2204 — how the confirmation question reaches a human, given a client
+ * that may support one, two or three ways of asking one.
+ *
+ * There are three lanes and they are not alternatives to pick between — they
+ * are a ladder, and every client can climb at least the bottom rung:
+ *
+ * 1. **The tool result** (universal). The answer says "ask the user which one,
+ *    then call again with their number". Works on every client that has ever
+ *    spoken MCP, because it is just text.
+ * 2. **`elicitation/create`** (2025-era sessions that advertise it). The client
+ *    renders a real picker; the server waits for the answer inside the call.
+ * 3. **`InputRequiredResult`** (2026-07-28 sessions). Elicitation is gone from
+ *    that revision as a server→client request; the same question rides back as
+ *    a result the client fulfils and retries.
+ *
+ * The ladder matters more than any one rung. A client that supports none of
+ * the richer lanes still gets a usable question — it does NOT get an enrolment
+ * it never confirmed, and it does not get an error. Degrading is the design.
+ */
+import { type ServerContext } from '@modelcontextprotocol/server';
+/** The key both richer lanes carry the confirmation under. */
+export declare const CONFIRM_KEY = "confirm_file";
+export type ConfirmationLane = 'input_required' | 'elicitation' | 'tool_result';
+/**
+ * Whether this REQUEST is on the 2026-07-28 wire.
+ *
+ * Read off the request envelope rather than off the connection, because that
+ * is where the SDK puts it: `_meta['io.modelcontextprotocol/protocolVersion']`
+ * arrives on every modern request, and `stdio-2026-07-28.e2e.test.ts` drives
+ * exactly that shape.
+ */
+export declare function isModernEra(ctx: ServerContext | undefined): boolean;
+/**
+ * Whether the client said it can render an elicitation.
+ *
+ * Two sources, checked in this order and for different reasons. A modern
+ * request carries the client's capabilities in its own envelope, which is the
+ * authority for THAT request. A 2025-era session declared them once at
+ * `initialize`, and the connection is the only place that survives.
+ *
+ * ABSENT means NO. A client that never said it can ask a question is not
+ * assumed to be able to — the cost of guessing wrong is a call that hangs
+ * waiting for an answer nobody will ever be shown.
+ */
+export declare function advertisesElicitation(ctx: ServerContext | undefined, connectionCapabilities: Record<string, unknown> | undefined): boolean;
+/**
+ * The best rung this request can climb.
+ *
+ * Lane 2 is deliberately unreachable on the modern era even when the client
+ * advertises `elicitation`: the SDK's `ctx.mcpReq.elicitInput` THROWS on a
+ * 2026-07-28 request, so treating the capability as sufficient would turn the
+ * richest client into the only one that fails.
+ */
+export declare function selectLane(ctx: ServerContext | undefined, connectionCapabilities: Record<string, unknown> | undefined): ConfirmationLane;
+/**
+ * The nonce a retried modern request is echoing back.
+ *
+ * Untrusted by construction — it round-trips through the client, nothing signs
+ * it, and the SDK hands back whatever arrived. It is used as a Map key and for
+ * nothing else: an unrecognised one finds no candidate set, which is the same
+ * answer as a malicious one.
+ */
+export declare function readRequestState(ctx: ServerContext | undefined): string | null;
+//# sourceMappingURL=drive-search-lanes.d.ts.map

package/dist/tools/drive-search-lanes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-search-lanes.d.ts","sourceRoot":"","sources":["../../src/tools/drive-search-lanes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAKtC,8DAA8D;AAC9D,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAE1C,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,aAAa,GAAG,aAAa,CAAC;AAQhF;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,SAAS,GAAG,OAAO,CAEnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,aAAa,GAAG,SAAS,EAC9B,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1D,OAAO,CAMT;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,aAAa,GAAG,SAAS,EAC9B,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1D,gBAAgB,CAIlB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAS9E"}

package/dist/tools/drive-search-lanes.js

@@ -0,0 +1,95 @@
+/**
+ * ENG-2204 — how the confirmation question reaches a human, given a client
+ * that may support one, two or three ways of asking one.
+ *
+ * There are three lanes and they are not alternatives to pick between — they
+ * are a ladder, and every client can climb at least the bottom rung:
+ *
+ * 1. **The tool result** (universal). The answer says "ask the user which one,
+ *    then call again with their number". Works on every client that has ever
+ *    spoken MCP, because it is just text.
+ * 2. **`elicitation/create`** (2025-era sessions that advertise it). The client
+ *    renders a real picker; the server waits for the answer inside the call.
+ * 3. **`InputRequiredResult`** (2026-07-28 sessions). Elicitation is gone from
+ *    that revision as a server→client request; the same question rides back as
+ *    a result the client fulfils and retries.
+ *
+ * The ladder matters more than any one rung. A client that supports none of
+ * the richer lanes still gets a usable question — it does NOT get an enrolment
+ * it never confirmed, and it does not get an error. Degrading is the design.
+ */
+import { CLIENT_CAPABILITIES_META_KEY, PROTOCOL_VERSION_META_KEY, } from '@modelcontextprotocol/server';
+/** The protocol revision on which lane 3 is the only richer lane there is. */
+const MRTR_PROTOCOL_VERSION = '2026-07-28';
+/** The key both richer lanes carry the confirmation under. */
+export const CONFIRM_KEY = 'confirm_file';
+/** Read one key off the per-request envelope, which is typed as an open bag. */
+function envelopeValue(ctx, key) {
+    const envelope = ctx?.mcpReq?.envelope;
+    return envelope?.[key];
+}
+/**
+ * Whether this REQUEST is on the 2026-07-28 wire.
+ *
+ * Read off the request envelope rather than off the connection, because that
+ * is where the SDK puts it: `_meta['io.modelcontextprotocol/protocolVersion']`
+ * arrives on every modern request, and `stdio-2026-07-28.e2e.test.ts` drives
+ * exactly that shape.
+ */
+export function isModernEra(ctx) {
+    return envelopeValue(ctx, PROTOCOL_VERSION_META_KEY) === MRTR_PROTOCOL_VERSION;
+}
+/**
+ * Whether the client said it can render an elicitation.
+ *
+ * Two sources, checked in this order and for different reasons. A modern
+ * request carries the client's capabilities in its own envelope, which is the
+ * authority for THAT request. A 2025-era session declared them once at
+ * `initialize`, and the connection is the only place that survives.
+ *
+ * ABSENT means NO. A client that never said it can ask a question is not
+ * assumed to be able to — the cost of guessing wrong is a call that hangs
+ * waiting for an answer nobody will ever be shown.
+ */
+export function advertisesElicitation(ctx, connectionCapabilities) {
+    const fromEnvelope = envelopeValue(ctx, CLIENT_CAPABILITIES_META_KEY);
+    if (fromEnvelope && typeof fromEnvelope === 'object') {
+        return 'elicitation' in fromEnvelope;
+    }
+    return !!connectionCapabilities && 'elicitation' in connectionCapabilities;
+}
+/**
+ * The best rung this request can climb.
+ *
+ * Lane 2 is deliberately unreachable on the modern era even when the client
+ * advertises `elicitation`: the SDK's `ctx.mcpReq.elicitInput` THROWS on a
+ * 2026-07-28 request, so treating the capability as sufficient would turn the
+ * richest client into the only one that fails.
+ */
+export function selectLane(ctx, connectionCapabilities) {
+    if (isModernEra(ctx))
+        return 'input_required';
+    if (advertisesElicitation(ctx, connectionCapabilities))
+        return 'elicitation';
+    return 'tool_result';
+}
+/**
+ * The nonce a retried modern request is echoing back.
+ *
+ * Untrusted by construction — it round-trips through the client, nothing signs
+ * it, and the SDK hands back whatever arrived. It is used as a Map key and for
+ * nothing else: an unrecognised one finds no candidate set, which is the same
+ * answer as a malicious one.
+ */
+export function readRequestState(ctx) {
+    try {
+        const state = ctx?.mcpReq?.requestState?.();
+        return typeof state === 'string' ? state : null;
+    }
+    catch {
+        // A configured verify hook rejecting the state is a refusal, not a crash:
+        // the caller treats "no usable nonce" and "a nonce we do not know" alike.
+        return null;
+    }
+}
+//# sourceMappingURL=drive-search-lanes.js.map

package/dist/tools/drive-search-lanes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-search-lanes.js","sourceRoot":"","sources":["../../src/tools/drive-search-lanes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,4BAA4B,EAC5B,yBAAyB,GAE1B,MAAM,8BAA8B,CAAC;AAEtC,8EAA8E;AAC9E,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAE3C,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAI1C,gFAAgF;AAChF,SAAS,aAAa,CAAC,GAA8B,EAAE,GAAW;IAChE,MAAM,QAAQ,GAAG,GAAG,EAAE,MAAM,EAAE,QAA+C,CAAC;IAC9E,OAAO,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,GAA8B;IACxD,OAAO,aAAa,CAAC,GAAG,EAAE,yBAAyB,CAAC,KAAK,qBAAqB,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAA8B,EAC9B,sBAA2D;IAE3D,MAAM,YAAY,GAAG,aAAa,CAAC,GAAG,EAAE,4BAA4B,CAAC,CAAC;IACtE,IAAI,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;QACrD,OAAO,aAAa,IAAI,YAAY,CAAC;IACvC,CAAC;IACD,OAAO,CAAC,CAAC,sBAAsB,IAAI,aAAa,IAAI,sBAAsB,CAAC;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CACxB,GAA8B,EAC9B,sBAA2D;IAE3D,IAAI,WAAW,CAAC,GAAG,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAC9C,IAAI,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,CAAC;QAAE,OAAO,aAAa,CAAC;IAC7E,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAA8B;IAC7D,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,CAAC;QAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,0EAA0E;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/tools/drive-search.contract.d.ts

@@ -0,0 +1,165 @@
+/**
+ * ENG-2204 — everything `search_drive_files` SAYS, split from everything it
+ * DOES (`drive-search.ts`), on the seam ENG-2200 cut for `enroll_file`.
+ *
+ * This half is the only interface a language model ever sees: it cannot read
+ * the handler, so the tool description and the schema descriptions ARE the
+ * contract, and a wrong word here is a behaviour bug no type checks. Keeping
+ * it apart means a person can review it as prose — deciding whether a model
+ * would do the right thing — without the lane branching in the way.
+ */
+import type { ElicitRequestFormParams } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import { type Candidate, type DriveSearchOutcome } from '../drive-search.js';
+export declare const DRIVE_SEARCH_INPUT_SCHEMA: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        search: "search";
+        recent: "recent";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    confirm_index: z.ZodOptional<z.ZodNumber>;
+    confirm_token: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const DRIVE_SEARCH_DESCRIPTION: string;
+export declare const DRIVE_SEARCH_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: true;
+};
+/** The machine-readable half of every answer, so a model can branch on it. */
+export interface DriveSearchAnswer {
+    outcome: DriveSearchOutcome;
+    text: string;
+    isError?: boolean;
+    detail?: Record<string, unknown>;
+}
+/**
+ * Render an answer as a tool result: prose for the human, then one JSON line
+ * for the model. Both, because prose alone invites the model to paraphrase a
+ * refusal into a success, and JSON alone gives the user nothing to read.
+ * Same shape as `enroll_file`'s, so the two tools read alike in a transcript.
+ */
+export declare function toolResult(answer: DriveSearchAnswer): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * How one candidate reads to a user, without its identifiers.
+ *
+ * ENG-2787 — the enrolment marking comes FIRST, and that ordering is the whole
+ * fix. The flag was already on the wire; the client truncated it off the END of
+ * the row, so ten candidates rendered as
+ * `RE_Forecast.xlsx · /drives/b!YmtA8jQX3OSHJRQ88O…` and the tool
+ * description's promise that "each candidate comes back marked as already in
+ * Rockhopper or not" was true of the payload and false of the screen. A marking
+ * whose position depends on the length of a customer's file name is not
+ * visible; one at position zero always is.
+ *
+ * `lastModifiedAt` and `parentPath` are dropped for the same reason they did
+ * harm: an ISO timestamp and a raw `/drives/b!…` id are forty characters
+ * nobody can read, sitting in front of the one phrase that decides whether
+ * this row is worth picking. Both still appear in the prompt's own message,
+ * which wraps instead of truncating.
+ */
+export declare function candidateLabel(candidate: Candidate): string;
+/** The numbered list the user picks from, and the model quotes back. */
+export declare function renderCandidates(candidates: readonly Candidate[]): string;
+/** The question the model puts to the user when no richer lane exists. */
+export declare function confirmationPrompt(candidates: readonly Candidate[], token: string): string;
+/**
+ * The elicitation form both richer lanes send.
+ *
+ * NOTHING IS REQUIRED, and that is deliberate (ENG-2789). A required `choice`
+ * is what turned an unreadable prompt into a trap: the only visible buttons
+ * were Accept and Decline, and Accept was REFUSED because the invisible field
+ * was unset, leaving Decline as the sole affordance that did anything. An
+ * unanswered form now comes back as `dismissed` — a state the tool can name
+ * and act on — instead of a button the user is herded into pressing.
+ */
+export declare function confirmationForm(candidates: readonly Candidate[]): Omit<ElicitRequestFormParams, 'mode'>;
+/** The answer that means "none of these" rather than a position. */
+export declare const DECLINE_CHOICE = "none";
+/**
+ * The answer once a specific candidate has been confirmed by a human.
+ *
+ * It hands over identifiers and stops. Enrolling here would mean a second copy
+ * of `enroll_file`'s logic — the share_with question, the hidden-file restore
+ * — living in a read tool, and two copies of a rule is how the two answers
+ * start to differ.
+ */
+export declare function confirmedAnswer(candidate: Candidate): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** The answer when the user was asked and said none of these. */
+export declare function declinedAnswer(): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * The answer when the prompt closed without the user answering it (ENG-2789).
+ *
+ * Its own outcome and not a flavour of `declined`, because the two say opposite
+ * things about what the user knows. `declined` means they read ten workbooks
+ * and none was theirs — searching again with a different word is the right next
+ * move. This means they never told us anything, and the honest next move is to
+ * put the same list to them in the conversation, where it cannot be collapsed.
+ * Folding them together is what let three unreadable prompts report themselves
+ * as a decision the user had made.
+ */
+export declare function dismissedAnswer(candidates?: readonly Candidate[]): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * The answer when the user pasted a link rather than picking a row (ENG-2784).
+ *
+ * The URL is the user's own typing, from a field only they can fill — it is
+ * not a model-chosen argument, and it is handed straight to `enroll_file`,
+ * which is the tool that resolves and validates it. Nothing here tries to
+ * parse it: `enroll_file`'s own description calls a pasted address "the only
+ * input that names one specific file with no guessing", and re-deriving that
+ * judgement in a second place is how two answers start to differ.
+ */
+export declare function linkSuppliedAnswer(url: string): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * A pasted value this tool will pass on, or `null`.
+ *
+ * The only check is that it is an http(s) address, and it exists so an empty
+ * box or a stray keystroke does not get announced to the model as "the user
+ * gave us the file". Anything further — which tenant, which drive, whether the
+ * file exists — is `enroll_file`'s to decide against Microsoft, not this
+ * tool's to guess from a string.
+ */
+export declare function usableLink(raw: unknown): string | null;
+/** The answer when a confirmation names something this session never offered. */
+export declare function unknownCandidateAnswer(): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** Told to the model when the session has searched as much as it may. */
+export declare const BUDGET_EXHAUSTED_TEXT: string;
+/** Told to the model when the user has no delegated Microsoft grant. */
+export declare function connectPrompt(authorizeUrl: string, expiresAt: string): string;
+//# sourceMappingURL=drive-search.contract.d.ts.map

package/dist/tools/drive-search.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-search.contract.d.ts","sourceRoot":"","sources":["../../src/tools/drive-search.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,yBAAyB;;;;;;;;;iBAsDpC,CAAC;AAEH,eAAO,MAAM,wBAAwB,QAoBQ,CAAC;AAE9C,eAAO,MAAM,wBAAwB;;;CAI3B,CAAC;AAEX,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,iBAAiB;;;;;;EAWnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAE3D;AA4BD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAIzE;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,KAAK,EAAE,MAAM,GACZ,MAAM,CAUR;AA6BD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,IAAI,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAuCvC;AAED,oEAAoE;AACpE,eAAO,MAAM,cAAc,SAAS,CAAC;AAErC;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS;;;;;;EA0BnD;AAED,iEAAiE;AACjE,wBAAgB,cAAc;;;;;;EAS7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE;;;;;;EAehE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM;;;;;;EAW7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUtD;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB;;;;;;EASrC;AAED,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,QAIqC,CAAC;AAExE,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAS7E"}