@rockhopper-co/mcp-server 2.0.1 → 2.1.1

package/dist/enrollment.js

@@ -0,0 +1,247 @@
+/**
+ * ENG-2200 (plan 13 / SP03) — the vocabulary and the refusal mapping behind
+ * `enroll_file`, kept out of the tool so the branch table can be tested
+ * without a registered server and so neither file crosses 300 lines.
+ *
+ * **Why this tool exists.** A customer asked Claude to enroll a SharePoint
+ * workbook. A name-substring search matched a DIFFERENT, already-enrolled file
+ * and the assistant answered "already enrolled". Told it had the wrong file,
+ * it enumerated its tools and found no enroll tool existed at all (ENG-1647).
+ * Two failures: a wrong match reported as a fact, and a dead end. Every
+ * decision below is aimed at one of those — an outcome is never inferred from
+ * a name, and no path ends without a next action the user can take.
+ */
+import { RockhopperApiError } from './api-client.js';
+/**
+ * The refusal codes the enrollment routes emit, mirrored rather than imported
+ * — this package ships to customers over npm and cannot depend on the backend
+ * tree. Sources: `enrollment-access.types.ts` (`EnrollmentAccessDenialCode`)
+ * and `graph-url-resolution.types.ts` (`UrlResolutionError`).
+ */
+const URL_UNSUPPORTED_PROVIDER = 'URL_UNSUPPORTED_PROVIDER';
+const URL_UNRESOLVABLE = 'URL_UNRESOLVABLE';
+const URL_FOREIGN_TENANT = 'URL_FOREIGN_TENANT';
+const ACCESS_UNPROVEN = 'ACCESS_UNPROVEN';
+const MS_SIGN_IN_REQUIRED = 'MS_SIGN_IN_REQUIRED';
+/** ENG-2614 — the tenant has not approved Rockhopper, and only an
+ * administrator can. Its own code because it is the one refusal in this
+ * list the user cannot act on themselves. */
+const ADMIN_CONSENT_REQUIRED = 'ADMIN_CONSENT_REQUIRED';
+const FILE_ACCESS_DENIED = 'FILE_ACCESS_DENIED';
+/**
+ * There is deliberately NO client-side host allow-list here.
+ *
+ * The obvious optimisation is to screen `docs.google.com` locally and save a
+ * round trip. It was written and removed: the backend's real rule is narrower
+ * than the plausible guess — `/(^|\.)sharepoint\.com$/` ONLY, so
+ * `onedrive.live.com` and `*.sharepoint.us` are refused there — and only
+ * Google earns `unsupported_provider`, while Dropbox and Box are
+ * `unresolvable`. A second copy of that rule in a package customers upgrade on
+ * their own schedule would answer differently from the server the moment
+ * either side moved, and a pre-screen that refuses a link the backend would
+ * have taken is invisible: the user simply cannot add their file. One rule,
+ * one place; {@link classifyEnrollmentFailure} maps what it says.
+ */
+/** The outcome an already-known enrollment state implies, before any write. */
+export function outcomeForState(state) {
+    if (state === 'enrolled')
+        return 'already_enrolled';
+    if (state === 'hidden')
+        return 'restore_confirmation_required';
+    return null;
+}
+/**
+ * ENG-2536 — turn the outcome the SERVER reported into what the user is told.
+ *
+ * Two things make this worth a function rather than a ternary at the call site.
+ *
+ * First, it is exhaustive with a `never` arm. `ServerEnrollmentOutcome` is a
+ * hand-kept mirror of a backend enum (this package ships over npm and cannot
+ * import the backend tree), so the only moment anybody notices a fourth value
+ * is when they edit that union — and this is what breaks and makes them handle
+ * it. ENG-2580 is the same shape gone wrong: fifteen if-chains where a new
+ * value fell into every `else` and nothing failed.
+ *
+ * Second, `already_enrolled` is the one answer that is not a promise about the
+ * future. Everything else here says "we are reading the workbook, come back";
+ * that one says nothing was written and nothing will be. Saying "Rockhopper
+ * reads the workbook in the background" about a file it read months ago sends
+ * the user to wait for an event that will never arrive — the ENG-1647 dead end
+ * with a friendlier voice.
+ */
+export function describeServerOutcome(serverOutcome, fileName, who) {
+    const subject = `"${fileName || 'The workbook'}"`;
+    const background = 'Rockhopper reads the workbook in the background, so its versions and ' +
+        'change history appear shortly — check with `search_files` if the user ' +
+        'wants confirmation.';
+    switch (serverOutcome) {
+        case 'enrolled':
+            return {
+                outcome: 'enrolled',
+                text: `${subject} is being added to Rockhopper${who}. ${background}`,
+            };
+        case 'restored':
+            return {
+                outcome: 'restored',
+                text: `${subject} is being restored${who}. ${background}`,
+            };
+        case 'already_enrolled':
+            return {
+                outcome: 'already_enrolled',
+                text: `${subject} was already in Rockhopper, so nothing was added${who}. ` +
+                    'Its versions and history are available now through ' +
+                    '`get_file_versions` and `get_cell_history` — there is nothing to ' +
+                    'wait for.',
+            };
+        default: {
+            const exhaustive = serverOutcome;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Turn a thrown API error into one of the named outcomes.
+ *
+ * Keyed on the backend's `code` first and the HTTP status only as a fallback,
+ * because the codes each name a DIFFERENT remedy and the statuses do not: four
+ * distinct refusals share 403, and answering all of them "you do not have
+ * permission" sends three of the four users to fix the wrong thing.
+ */
+export function classifyEnrollmentFailure(error) {
+    if (!(error instanceof RockhopperApiError)) {
+        return {
+            outcome: 'error',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // A route this deployment does not serve. The npm package and the backend
+    // ship on separate clocks, and a customer running `npx` picks up `latest`
+    // the moment it publishes — so calling an unelevated backend is a REAL
+    // case, not a theoretical one, and it must not read as "your file is gone".
+    if (error.status === 404) {
+        return {
+            outcome: 'backend_unsupported',
+            message: 'This Rockhopper deployment does not support adding files from an ' +
+                'assistant yet. Add the file from the Rockhopper web app instead. ' +
+                'Nothing was changed.',
+        };
+    }
+    switch (error.code) {
+        // FIRST, because it is the one refusal here that names an action the
+        // user cannot take. Telling them to run `connect_microsoft` sends them
+        // to a Microsoft screen that refuses them and returns them here — a
+        // loop, and one that reads as our bug rather than a missing approval.
+        case ADMIN_CONSENT_REQUIRED:
+            return {
+                outcome: 'admin_approval_required',
+                message: 'Rockhopper cannot add this file because the user\'s organisation ' +
+                    'has not approved Rockhopper yet. Microsoft only lets a Microsoft ' +
+                    '365 administrator approve this — the user cannot grant it ' +
+                    'themselves, and connecting or signing in again will not change ' +
+                    'the answer. Ask them to send their IT administrator to ' +
+                    'https://docs.rockhopper.co/it-setup/approve-file-access, which ' +
+                    'has the approval link and what it grants. Nothing was changed, ' +
+                    'and retrying will not help.',
+            };
+        case ACCESS_UNPROVEN:
+            return {
+                outcome: 'access_unproven',
+                message: 'Rockhopper cannot confirm you can open this file, because this ' +
+                    'session has no Microsoft account linked to it. Run ' +
+                    '`connect_microsoft` to link one, then try again. Nothing was ' +
+                    'changed.',
+            };
+        case MS_SIGN_IN_REQUIRED:
+            return {
+                outcome: 'access_unproven',
+                message: 'Your Microsoft sign-in could not be used to confirm you can open ' +
+                    'this file. Run `connect_microsoft` to link your account again, ' +
+                    'then try again. Nothing was changed.',
+            };
+        case FILE_ACCESS_DENIED:
+            return {
+                outcome: 'access_unproven',
+                message: 'Microsoft says you cannot open that file, so Rockhopper will not ' +
+                    'add it. Ask whoever owns the file to share it with you first. ' +
+                    'Retrying will not help.',
+            };
+        case URL_UNSUPPORTED_PROVIDER:
+            return {
+                outcome: 'unsupported_provider',
+                message: 'That link is not a Microsoft SharePoint or OneDrive file. ' +
+                    '`enroll_file` adds Microsoft Excel workbooks only. Do not ask for ' +
+                    'another link — this provider is not supported.',
+            };
+        case URL_UNRESOLVABLE:
+            return {
+                outcome: 'unresolvable',
+                message: 'That link does not point at a file Rockhopper can find. Ask the ' +
+                    'user to open the workbook in Excel or SharePoint and paste the ' +
+                    'address from the browser bar.',
+            };
+        case URL_FOREIGN_TENANT:
+            return {
+                outcome: 'unresolvable',
+                message: 'That file belongs to a different Microsoft organisation, so ' +
+                    'Rockhopper cannot add it. Retrying will not help.',
+            };
+        default:
+            break;
+    }
+    // No code, so fall back to the status. A 400 from the resolver is always
+    // "we could not make sense of this link"; anything else is a real failure
+    // and is reported as one rather than dressed up as a named outcome.
+    if (error.status === 400) {
+        return {
+            outcome: 'unresolvable',
+            message: 'Rockhopper could not read that link as a file. Ask the user to open ' +
+                'the workbook and paste the address from their browser bar.',
+        };
+    }
+    return { outcome: 'error', message: error.message };
+}
+/** Raised when `share_with: 'team'` names a team we cannot resolve. */
+export class TeamUnresolvedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TeamUnresolvedError';
+    }
+}
+/**
+ * The teammates a `share_with: 'team'` enroll fans the file out to.
+ *
+ * Mirrors the web enrollment wizard exactly — the caller's FIRST team
+ * membership, its roster, minus the caller — because SP04 defines "team" as
+ * "the wizard's default set" and two surfaces answering the same question
+ * differently is worse than either answer. The backend has no team-vs-private
+ * enum to lean on: `POST /enrolled-files/batch` takes an explicit list of
+ * platform ids and nothing else, so the expansion happens here or nowhere.
+ *
+ * THROWS rather than returning an empty list when there is no team or no
+ * teammate. Enrolling privately after the user said "my team" is a silent
+ * substitution of a different answer for the one they gave, and it is
+ * invisible: the file simply never appears for anyone else.
+ */
+export async function resolveTeamShareTargets(api) {
+    const me = await api.getMe();
+    const membership = me.teamMembers?.find((m) => m.team != null);
+    const teamId = membership?.team?.id ?? membership?.team?.internalId;
+    if (teamId === undefined) {
+        throw new TeamUnresolvedError('You are not on a team yet, so there is nobody to share this file ' +
+            'with. Call `enroll_file` again with share_with="me" to add it just ' +
+            'for yourself, or set up a team in the Rockhopper web app first. ' +
+            'Nothing was changed.');
+    }
+    const team = await api.getTeam(teamId);
+    const mine = me.msId ?? me.googleId ?? null;
+    const targets = (team.teamMembers ?? [])
+        .map((member) => member.user?.msId ?? null)
+        .filter((id) => !!id && id !== mine);
+    if (targets.length === 0) {
+        throw new TeamUnresolvedError(`You are the only member of ${team.name ? `the ${team.name} team` : 'your team'}, so sharing with the team would share it with nobody. Call ` +
+            '`enroll_file` again with share_with="me" to add it just for ' +
+            'yourself. Nothing was changed.');
+    }
+    return targets;
+}
+//# sourceMappingURL=enrollment.js.map

package/dist/enrollment.js.map

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

package/dist/resources/orchestration-guide.md

@@ -12,6 +12,7 @@ Rockhopper uses four distinct identifiers. Mixing them is the most common cause
 | `versionId` | number | `get_file_versions` response (`internalId` field), `create_version` response | Tools that act on a specific version snapshot: `get_reviews`, `create_review_request`, `approve_review`, `cancel_review` |
 | `versionInternalId` | number | `get_file_comments` response (comments scope to a version) | Comment-thread tools: `add_comment`, `reply_to_comment`, `resolve_comment` |
 | user / team id | uuid string **or** number | `rockhopper://teams/{teamId}` resource — each record carries an `id` (uuid) and an `internalId` (number) | `reviewerIds` on `create_review_request`; the `{teamId}` in `rockhopper://teams/{teamId}` |
+| `url` / `driveMsId` + `msId` | strings | The user's browser address bar, or a Microsoft file listing | `enroll_file` only — these name a file Rockhopper does **not** have yet, which is why no `fileMsId` exists for it |
 
 Decision tree:
 
@@ -28,7 +29,56 @@ A user or team can be named by its `id` (a uuid, e.g. `0198f3a1-2b4c-7d8e-9f01-2
 
 If a tool returns an error like "expected versionId but received fileMsId", you used the wrong identifier — check the tool description for which type it accepts.
 
-## 2. Reading workflow
+## 2. Adding a file to Rockhopper (enrollment)
+
+Every other tool works on files Rockhopper ALREADY has. `enroll_file` is the only one that adds a new one, and reaching for it is the right move more often than it looks: `list_files` and `search_files` see only enrolled files, so a workbook the user is talking about that appears in neither is very probably one nobody has added yet — not one that does not exist. `search_drive_files` is how you find it.
+
+**Identity.** Two ways to name the file, mutually exclusive:
+
+- `url` — the SharePoint or OneDrive address, copied from the browser bar. Prefer this always: it names exactly one file, so there is no wrong-match risk.
+- `driveMsId` + `msId` — the Microsoft pair, when another tool already produced it. Both are required together.
+
+### Finding the file first: `search_drive_files` → confirm → `enroll_file`
+
+Most users cannot produce a link on request. `search_drive_files` looks across the user's own OneDrive and SharePoint — **including workbooks Rockhopper has never seen** — and marks each candidate `not in Rockhopper yet`, `already in Rockhopper`, or `previously removed`. It is the only tool that can see an un-enrolled file.
+
+The two steps are one flow and the middle one is not optional:
+
+1. `search_drive_files({ query: "Q3 forecast" })` — or `scope: "recent"` when the user cannot remember the name.
+2. **Show the candidates and ask which one they meant.** Quote the names; never choose for them, and never report a file as already enrolled because one result looked similar — that specific mistake is why this tool exists. Call `search_drive_files` again with their `confirm_index` and the `confirm_token` from that answer. Some clients render the question themselves; either way, one comes back confirmed.
+3. Pass the `driveMsId` + `msId` the confirmation returned to `enroll_file`, which then asks who may see the file.
+
+Only files that came back from the search can be confirmed. A pick that names anything else answers `unknown_candidate` and adds nothing.
+
+**Searching is capped per session.** A fixed number of searches, after which `search_limit_reached` is the only answer and waiting does not restore it. Search deliberately — two or three well-chosen queries, not a browse. If the cap is reached, ask the user for the workbook link and use `enroll_file` directly.
+
+**No Microsoft account connected?** `search_drive_files` answers `microsoft_not_connected` and hands back a sign-in link Rockhopper built. Give the user that link verbatim. Never compose a Microsoft sign-in URL yourself — a link the assistant made up sends the user's consent wherever whoever wrote it wanted.
+
+**Microsoft only.** SharePoint and OneDrive-for-Business workbooks. A Google Drive or Sheets link returns `unsupported_provider`; that is final, so do not ask the user for a different link.
+
+**You must ask who may see it.** `share_with` is required and has two values: `"me"` (visible to the user alone) and `"team"` (also fanned out to their teammates). Ask the user every time — do not assume, and do not carry an answer over from a previous file. Calling without it enrolls nothing and returns `share_with_required` plus the question to put to them.
+
+**A removed file is restored, never re-added.** Rockhopper keeps three states, not two: `enrolled`, `hidden` and `not_enrolled`. `hidden` means somebody deliberately removed the file from the file lists — its versions, comments and change history all survived. Enrolling a hidden file therefore RESTORES the original, and because that undoes a person's decision it needs their say-so: the first call answers `restore_confirmation_required` and writes nothing; only a second call carrying `confirm_restore: true` restores it.
+
+**Enrollment is asynchronous, and re-calling is safe.** The answer says the file was accepted, not that it is ready — Rockhopper reads the workbook in the background and its versions appear shortly after. If the answer is lost to a dropped connection mid-call, just call again: the file row is written before the background work starts, so the second call answers `already_enrolled` rather than adding anything twice.
+
+**Outcomes.** Every response ends with a JSON object carrying an `outcome` field, so these can be branched on without reading the prose:
+
+| `outcome` | Meaning | What to do |
+|-----------|---------|------------|
+| `enrolled` | Accepted; the file was not here before | Tell the user it is being added |
+| `restored` | Accepted; a file they had removed is back | Tell the user it is being restored |
+| `already_enrolled` | It is already here and visible | Nothing — go straight to reading it |
+| `share_with_required` | No `share_with`, or a `"team"` that resolves to nobody | Ask the user, then call again |
+| `restore_confirmation_required` | The target is hidden | Ask the user, then call again with `confirm_restore: true` |
+| `access_unproven` | Rockhopper cannot confirm the user can open the file | Run `connect_microsoft`, then retry |
+| `unresolvable` | The link names no file Rockhopper can find | Ask for the address from the browser bar |
+| `unsupported_provider` | Not a Microsoft link | Stop; do not ask for another link |
+| `backend_unsupported` | This Rockhopper deployment predates the enrollment API | Tell the user to add the file from the web app |
+
+**Why `access_unproven` is common from a chat client.** Rockhopper will not add a file on the user's say-so; it checks with Microsoft that they can actually open it. An assistant session carries no Microsoft sign-in of its own, so the user has to link their account once with `connect_microsoft`. Until they do, every enroll is refused — deliberately, not as a bug.
+
+## 3. Reading workflow
 
 Standard sequence to inspect a file:
 
@@ -52,7 +102,7 @@ A refusal means **nothing is known yet**. It is not an empty history, not zero c
 and not evidence that the file is unmodified. Wait `retryAfterSeconds` and ask again;
 never answer a user's question about what changed from a not-ready response.
 
-## 3. Commenting workflow
+## 4. Commenting workflow
 
 Comments are scoped to a version. The default version is the latest **committed** one.
 
@@ -65,7 +115,7 @@ Comments on historical versions:
 - Pass `versionInternalId` explicitly to `add_comment` to comment on a historical version snapshot.
 - `get_file_comments` accepts `versionInternalId` if you want to read historical-version comments rather than the current set.
 
-## 4. Review lifecycle
+## 5. Review lifecycle
 
 Reviews follow a strict state machine: **`pending` → `approved`** or **`pending` → `cancelled`**. No other transitions are valid.
 
@@ -75,7 +125,7 @@ Reviews follow a strict state machine: **`pending` → `approved`** or **`pendin
 
 Calling `approve_review` before `create_review_request` returns a 404 — there is no review to approve. Calling `approve_review` on an already-approved or cancelled review returns a 409 conflict.
 
-## 5. Versioning
+## 6. Versioning
 
 `create_version` snapshots the file's current uncommitted state as a new version.
 
@@ -87,7 +137,7 @@ Rules:
 
 `discard_changes(fileMsId)` is the **destructive** alternative: it wipes uncommitted edits without creating a snapshot. Use only when the user explicitly asks to throw away unsaved work — call `get_unattributed_changes(fileMsId)` first and confirm with the user before discarding anything substantive.
 
-## 6. Uncommitted changes vs. committed history
+## 7. Uncommitted changes vs. committed history
 
 Two distinct concepts. Tools work with one or the other; do not mix.
 
@@ -96,7 +146,7 @@ Two distinct concepts. Tools work with one or the other; do not mix.
 
 Note: on files served from the change ledger (most Microsoft files), `get_cell_history` also includes live edits not yet captured by a committed version — those entries carry the literal versionId `uncommitted`. On files still served from the legacy store, only committed values appear; use `get_unattributed_changes` for pending edits there.
 
-## 7. Cross-cloud differences
+## 8. Cross-cloud differences
 
 Rockhopper supports both Microsoft Excel files (M365 / OneDrive) and Google Sheets. Tool calls work transparently across both, but the identifiers carry different meanings:
 
@@ -108,7 +158,7 @@ Rockhopper supports both Microsoft Excel files (M365 / OneDrive) and Google Shee
 
 If a tool description references "drive ID" or "platform ID", it works identically across both clouds. If you need to know the platform, inspect `fileType`.
 
-## 8. Error handling
+## 9. Error handling
 
 Tool failures return structured responses with `isError: true` and a human-readable message in `content`. Common patterns:
 
@@ -119,7 +169,7 @@ Tool failures return structured responses with `isError: true` and a human-reada
 
 When a tool returns `isError: true`, do not silently retry with the same arguments. Either correct the arguments based on the error message or surface the failure.
 
-## 9. Resources
+## 10. Resources
 
 The MCP server exposes two static resources via `resources/list`:
 

package/dist/tools/connect-microsoft.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { ApiClient } from '../api-client.js';
+/**
+ * `connect_microsoft` — the local half of SP07 §3.
+ *
+ * WHAT THIS TOOL DELIBERATELY CANNOT DO, and why the shape matters more than
+ * the feature. It takes NO authorize URL, no redirect URI, no client id and no
+ * scope list. It asks the backend to build the consent URL and relays what
+ * comes back.
+ *
+ * The reason is the threat this tool sits inside. An MCP tool's arguments are
+ * chosen by a language model, and that model reads content it did not author —
+ * file names, comments, review text. A tool that accepted a URL would let
+ * anything that model reads steer where a user's Microsoft consent is sent,
+ * and the user would see a real Microsoft consent screen the whole way. So the
+ * URL is not a parameter, and the callback re-pins the client id and redirect
+ * server-side when it redeems the code. Two independent places refuse to take
+ * the caller's word for it.
+ */
+export declare function registerConnectMicrosoftTool(server: McpServer, api: ApiClient): void;
+//# sourceMappingURL=connect-microsoft.d.ts.map

package/dist/tools/connect-microsoft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-microsoft.d.ts","sourceRoot":"","sources":["../../src/tools/connect-microsoft.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAgJN"}

package/dist/tools/connect-microsoft.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+/**
+ * `connect_microsoft` — the local half of SP07 §3.
+ *
+ * WHAT THIS TOOL DELIBERATELY CANNOT DO, and why the shape matters more than
+ * the feature. It takes NO authorize URL, no redirect URI, no client id and no
+ * scope list. It asks the backend to build the consent URL and relays what
+ * comes back.
+ *
+ * The reason is the threat this tool sits inside. An MCP tool's arguments are
+ * chosen by a language model, and that model reads content it did not author —
+ * file names, comments, review text. A tool that accepted a URL would let
+ * anything that model reads steer where a user's Microsoft consent is sent,
+ * and the user would see a real Microsoft consent screen the whole way. So the
+ * URL is not a parameter, and the callback re-pins the client id and redirect
+ * server-side when it redeems the code. Two independent places refuse to take
+ * the caller's word for it.
+ */
+export function registerConnectMicrosoftTool(server, api) {
+    server.registerTool('connect_microsoft', {
+        title: 'Connect Microsoft Account',
+        description: 'Start connecting the user\'s Microsoft account so Rockhopper can search ' +
+            'their OneDrive and SharePoint files as them. Returns a Microsoft sign-in ' +
+            'link the USER must open themselves. Call `microsoft_link_status` afterwards ' +
+            'to confirm they finished. Use this when a file search reports that no ' +
+            'Microsoft account is connected.',
+        inputSchema: z.object({}),
+        annotations: {
+            // Creates no Rockhopper data by itself — it hands back a link. The
+            // grant only exists once the USER completes the consent.
+            readOnlyHint: true,
+            // It sends the user to Microsoft.
+            openWorldHint: true,
+        },
+    }, async () => {
+        try {
+            const handoff = await api.beginMicrosoftConnect();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Open this link to connect your Microsoft account:\n\n' +
+                            `${handoff.authorizeUrl}\n\n` +
+                            `The link expires at ${handoff.expiresAt}. ` +
+                            'Rockhopper asks only to READ your files. ' +
+                            'After you approve, run `microsoft_link_status` to confirm.',
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to start the Microsoft connection: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('microsoft_link_status', {
+        title: 'Microsoft Connection Status',
+        description: 'Check whether the user has connected a Microsoft account, which account ' +
+            'it is, and what access was granted. Never returns any token.',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            const status = await api.getMicrosoftLink();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: status.linked
+                            ? `Connected${status.msAccountLabel ? ` as ${status.msAccountLabel}` : ''}.` +
+                                (status.grantedScopes.length
+                                    ? ` Granted: ${status.grantedScopes.join(', ')}.`
+                                    : '') +
+                                (status.linkedAt ? ` Connected on ${status.linkedAt}.` : '')
+                            : 'No Microsoft account is connected. Run `connect_microsoft` to connect one.',
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to read the Microsoft connection: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('disconnect_microsoft', {
+        title: 'Disconnect Microsoft Account',
+        description: 'Remove the stored Microsoft connection, deleting the credential Rockhopper ' +
+            'holds for this user. Requires an interactive login; a personal access token ' +
+            'cannot sever a connection it did not create.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        try {
+            const result = await api.unlinkMicrosoft();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: result.removed
+                            ? 'Microsoft account disconnected. The stored credential has been deleted.'
+                            : 'No Microsoft account was connected.',
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to disconnect: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=connect-microsoft.js.map

package/dist/tools/connect-microsoft.js.map

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

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"}