@pipeshub-ai/mcp 2.1.0 → 2.3.0

package/bin/mcp-server.js

@@ -50394,14 +50394,35 @@ PipesHub is the user's workplace AI platform. It indexes their documents,
 knowledge base content, and connector sources (Drive, Box, Confluence,
 Slack, Jira, Gmail, ...). When in doubt, the answer is in PipesHub.
 
+## Full-document tasks: \`pipeshub_search\` → \`pipeshub_get_record_content\`
+
+\`pipeshub_chat\` answers from a handful of retrieved passages — it never
+reads a whole document. Whenever the task depends on a document's
+COMPLETE content, fetch the document itself:
+
+1. \`pipeshub_search\` with the document's name / topic.
+2. Take the top hit's \`recordId\`.
+3. \`pipeshub_get_record_content\`, and answer from the returned content.
+
+Tasks that need this path — anything where missing part of the document
+could make the answer wrong:
+
+- Summarize / TL;DR / key points / takeaways / action items of a doc.
+- Extract or list ALL of something (dates, owners, requirements, ...).
+- Check whether / where a doc mentions something.
+- Translate, rewrite, outline, review, or reformat a doc.
+- Compare named docs (fetch each \`recordId\`).
+- Any question explicitly scoped to ONE named document — chat retrieval
+  cannot be restricted to a single record.
+
 ## Default tool: \`pipeshub_chat\`
 
 **Use \`pipeshub_chat\` for any question that could plausibly be answered
-by the user's PipesHub-indexed data.** That includes:
+by the user's PipesHub-indexed data** and is not a full-document task:
 
-- Anything about a specific document, file, report, ticket, message, or
-  page (e.g. "what's in the Q4 sales report?", "summarize the langchain
-  doc", "what did Aashil say about onboarding?").
+- A question that may span several documents, or where you don't yet
+  know which record holds the answer (e.g. "what did Aashil say about
+  onboarding?").
 - Anything about company / org policies, processes, decisions, or
   history (e.g. "what's our vacation policy?", "who owns the auth
   service?").
@@ -50417,15 +50438,17 @@ the user can verify.
 
 ## When to use the other tools
 
-- \`pipeshub_search\` — only when the user asks specifically to **find /
-  locate** a document by name or topic (so you can hand them a list, or
-  resolve a filename to a \`recordId\` for download). For "what does
-  the doc say?" use \`pipeshub_chat\` instead — it does the retrieval
-  internally.
+- \`pipeshub_search\` — locate a document by name or topic and resolve it
+  to a \`recordId\`. To read or summarize one specific document, search,
+  then pass the top hit's \`recordId\` to \`pipeshub_get_record_content\`.
 - \`pipeshub_download_record\` — when the user wants the actual file
   bytes (download, attach, open). Get the \`recordId\` either from
   citations on a prior \`pipeshub_chat\` response or from
   \`pipeshub_search\`.
+- \`pipeshub_get_record_content\` — when you need a record's full parsed
+  content (returned as a single \`content\` string: metadata header plus
+  the document's text) without downloading the original file. Prefer this
+  over download when the question is about what the record says.
 - \`pipeshub_directory\` — people, groups, teams, and \`whoami\` lookups.
   Not for documents.
 - \`pipeshub_sources\` — call once at the start of a session to discover
@@ -50433,6 +50456,36 @@ the user can verify.
 - \`pipeshub_agents\` — list the org's configured **agents** (specialized
   assistants with their own prompt, tools, and knowledge scope).
 
+## Knowledge Sources
+
+A source (an app connector or a KB) holds record groups (a project, space,
+drive, folder), which hold records (one ticket, page, file). Records nest —
+an epic over its stories, a page over its child pages.
+
+**Every tool returns metadata or content.**
+
+- \`pipeshub_search\` / \`pipeshub_chat\` — content, but only a ranked sample of
+  blocks: never all blocks of a record, never every record that matches, never
+  a complete list of what exists.
+- \`mode:"lookup"\` and \`mode:"navigate"\` — metadata: recordIds, fields, and
+  structure. No document text. \`mode:"content"\` — one whole record.
+
+**Combining them.** Search finds a starting point by wording; navigate on a
+\`recordId\` reveals what search structurally cannot — siblings, children,
+linked records, and the group's total count. For a question that must be
+exhaustive ("all", "how many", "every"), do NOT count search hits or trust a
+chat answer: navigate the record group, which reports the real total. For a
+record's siblings, navigate its parent — take the id from the \`Path\` line.
+
+**A named record** — an issue key, a Confluence / Drive / Slack link, an
+external ID → \`mode:"lookup"\` FIRST. It returns that record's metadata (for a
+ticket: status, assignee, priority, dates) plus its \`recordId\`, which often
+answers the question outright. Never guess a \`recordId\`.
+
+Pass a source's id from \`pipeshub_sources\` as \`apps: ["<id>"]\` to search or
+chat, and as \`nodeId\` to navigate. Navigate and lookup end in a \`Next:\` line
+naming the exact follow-up call — follow it.
+
 ## Agents
 
 Some orgs configure **agents** for specific jobs (e.g. a Slack messenger, a
@@ -50467,13 +50520,122 @@ replay prior messages. Only start a fresh conversation when the user
 explicitly asks to clear context.
 `;
 
+// node_modules/nanoid/url-alphabet/index.js
+var urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+
+// node_modules/nanoid/index.js
+import { webcrypto as crypto3 } from "node:crypto";
+function fillPool(bytes) {
+  if (bytes < 0)
+    throw new RangeError("Wrong ID size");
+  try {
+    if (!pool || pool.length < bytes) {
+      pool = Buffer.allocUnsafe(bytes * POOL_SIZE_MULTIPLIER);
+      crypto3.getRandomValues(pool);
+      poolOffset = 0;
+    } else if (poolOffset + bytes > pool.length) {
+      crypto3.getRandomValues(pool);
+      poolOffset = 0;
+    }
+  } catch (e) {
+    pool = undefined;
+    throw e;
+  }
+  poolOffset += bytes;
+}
+function nanoid2(size = 21) {
+  fillPool(size |= 0);
+  let id = "";
+  for (let i = poolOffset - size;i < poolOffset; i++) {
+    id += urlAlphabet[pool[i] & 63];
+  }
+  return id;
+}
+var POOL_SIZE_MULTIPLIER = 128, pool, poolOffset;
+var init_nanoid = () => {};
+
+// src/hooks/request-context.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+function bindNewRequestId() {
+  storage.enterWith({ random: nanoid2() });
+}
+function getRequestContextStore() {
+  return storage.getStore();
+}
+function newRequestId() {
+  return `mcp-${nanoid2()}`;
+}
+var storage;
+var init_request_context = __esm(() => {
+  init_nanoid();
+  storage = new AsyncLocalStorage;
+});
+
+// src/hooks/requestid.ts
+function decodeJwtPayload(token) {
+  try {
+    const base64Url = token.split(".")[1];
+    if (!base64Url)
+      return null;
+    const base642 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base642 + "=".repeat((4 - base642.length % 4) % 4);
+    const claims = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    return typeof claims === "object" && claims !== null ? claims : null;
+  } catch {
+    return null;
+  }
+}
+function userIdFromRequest(request) {
+  const auth = request.headers.get("authorization") ?? "";
+  if (!auth.toLowerCase().startsWith("bearer "))
+    return null;
+  const token = auth.slice(7).trim();
+  const claims = decodeJwtPayload(token);
+  return claims?.["userId"] || null;
+}
+
+class RequestIDHook {
+  beforeRequest(_hookCtx, request) {
+    if (request.headers.get(REQUEST_ID_HEADER)) {
+      return request;
+    }
+    const store = getRequestContextStore();
+    if (!store) {
+      request.headers.set(REQUEST_ID_HEADER, newRequestId());
+      return request;
+    }
+    if (!store.finalId) {
+      const userId = userIdFromRequest(request);
+      store.finalId = userId ? `mcp-${userId}-${store.random}` : `mcp-${store.random}`;
+    }
+    request.headers.set(REQUEST_ID_HEADER, store.finalId);
+    return request;
+  }
+}
+var REQUEST_ID_HEADER = "x-request-id";
+var init_requestid = __esm(() => {
+  init_request_context();
+});
+
 // src/hooks/registration.ts
-function initHooks(hooks) {}
+function initHooks(hooks) {
+  hooks.registerBeforeRequestHook(new RequestIDHook);
+}
+var init_registration = __esm(() => {
+  init_requestid();
+});
 
-// src/lib/base64.ts
+// src/lib/bytes-to-base64.ts
 function bytesToBase64(u8arr) {
-  return btoa(String.fromCodePoint(...u8arr));
+  let binary = "";
+  for (let i = 0;i < u8arr.length; i += BASE64_CHUNK) {
+    binary += String.fromCharCode(...u8arr.subarray(i, i + BASE64_CHUNK));
+  }
+  return btoa(binary);
 }
+var BASE64_CHUNK = 32768;
+
+// src/lib/base64.ts
 function bytesFromBase64(encoded) {
   return Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
 }
@@ -51058,6 +51220,7 @@ class SDKHooks {
   }
 }
 var init_hooks = __esm(() => {
+  init_registration();
   init_clientcredentials();
 });
 
@@ -51793,9 +51956,6 @@ function createRegisterPrompt(logger, server, getSDK, allowedScopes) {
 }
 
 // src/mcp-server/shared.ts
-function bytesToBase642(u8arr) {
-  return btoa(String.fromCodePoint(...u8arr));
-}
 async function consumeStream(stream) {
   const reader = stream.getReader();
   const chunks = [];
@@ -51816,13 +51976,13 @@ async function valueToBase64(value) {
   if (value == null) {
     return null;
   } else if (value instanceof Uint8Array) {
-    return bytesToBase642(value);
+    return bytesToBase64(value);
   } else if (value instanceof ArrayBuffer) {
-    return bytesToBase642(new Uint8Array(value));
+    return bytesToBase64(new Uint8Array(value));
   } else if (value instanceof Response || value instanceof Blob) {
-    return bytesToBase642(new Uint8Array(await value.arrayBuffer()));
+    return bytesToBase64(new Uint8Array(await value.arrayBuffer()));
   } else if (value instanceof ReadableStream) {
-    return bytesToBase642(await consumeStream(value));
+    return bytesToBase64(await consumeStream(value));
   } else if (typeof value === "string") {
     return base64Schema.parse(value);
   } else {
@@ -51882,9 +52042,15 @@ async function formatResult(response) {
   } else if (contentType.startsWith("audio/")) {
     const data = await valueToBase64(await response.arrayBuffer());
     content = data == null ? [] : [{ type: "audio", data, mimeType: contentType }];
-  } else {
+  } else if (contentType.startsWith("text/") || contentType.includes("json") || contentType.includes("xml") || contentType.includes("yaml")) {
     const text = await response.text();
     content = [{ type: "text", text }];
+  } else {
+    const blob = await valueToBase64(await response.arrayBuffer());
+    content = blob == null ? [] : [{
+      type: "resource",
+      resource: { uri: response.url, mimeType: contentType, blob }
+    }];
   }
   return response.ok ? { content } : { content, isError: true };
 }
@@ -52382,7 +52548,7 @@ async function $do(client$, request, options) {
     options: client$._options,
     baseURL: options?.serverURL ?? client$._baseURL ?? "",
     operationID: "streamConversation",
-    oAuth2Scopes: ["conversation:write"],
+    oAuth2Scopes: ["conversation:chat"],
     resolvedSecurity: requestSecurity,
     securitySource: client$._options.security,
     retryConfig: options?.retries || client$._options.retryConfig || { strategy: "none" },
@@ -52780,6 +52946,77 @@ var init_agentsStreamMessage = __esm(() => {
   init_async();
 });
 
+// src/mcp-server/tools/_agui.ts
+function newChatStreamState() {
+  return {
+    conversation: null,
+    recordsUsed: undefined,
+    error: null,
+    conversationId: null,
+    title: null,
+    text: new Map,
+    rootMessageIds: new Set
+  };
+}
+function applyAGUIFrame(state, frame) {
+  const data = frame.data;
+  const d = data && typeof data === "object" ? data : {};
+  switch (frame.event) {
+    case AGUIEvent.RUN_FINISHED: {
+      const result = d.result;
+      if (!result || typeof result !== "object")
+        return false;
+      state.conversation = result.conversation ?? null;
+      state.recordsUsed = result.recordsUsed ?? result.meta?.recordsUsed;
+      return true;
+    }
+    case AGUIEvent.RUN_ERROR: {
+      state.error = (typeof data === "string" ? data : null) ?? d.message ?? d.error ?? frame.raw ?? "Stream error";
+      return true;
+    }
+    case AGUIEvent.CUSTOM: {
+      if (d.name === "conversation_created") {
+        const value = d.value ?? {};
+        state.conversationId = value.conversationId ?? state.conversationId;
+        state.title = value.title ?? state.title;
+      }
+      return false;
+    }
+    case AGUIEvent.TEXT_MESSAGE_CONTENT: {
+      if (typeof d.delta !== "string" || d.delta.length === 0)
+        return false;
+      const id = typeof d.messageId === "string" ? d.messageId : "";
+      state.text.set(id, (state.text.get(id) ?? "") + d.delta);
+      if (d.parentRunId == null)
+        state.rootMessageIds.add(id);
+      return false;
+    }
+    default:
+      return false;
+  }
+}
+function salvagedText(state) {
+  const pick2 = (ids) => {
+    let best = null;
+    for (const id of ids) {
+      const text = state.text.get(id);
+      if (text && (best === null || text.length > best.length))
+        best = text;
+    }
+    return best;
+  };
+  return pick2(state.rootMessageIds) ?? pick2(state.text.keys());
+}
+var AGUIEvent;
+var init__agui = __esm(() => {
+  AGUIEvent = {
+    RUN_FINISHED: "RUN_FINISHED",
+    RUN_ERROR: "RUN_ERROR",
+    CUSTOM: "CUSTOM",
+    TEXT_MESSAGE_CONTENT: "TEXT_MESSAGE_CONTENT"
+  };
+});
+
 // src/funcs/agentsListAgents.ts
 function agentsListAgents(client$, request, options) {
   return new APIPromise($do5(client$, request, options));
@@ -52989,15 +53226,17 @@ function trimCitations(citations) {
   if (!Array.isArray(citations))
     return [];
   return citations.map((c) => {
-    const md = c?.metadata ?? {};
+    const cd = c?.citationData ?? c;
+    const md = cd?.metadata ?? c?.metadata ?? {};
+    const content = typeof cd?.content === "string" ? cd.content : c?.content;
     return {
-      recordId: md.recordId ?? c?.recordId,
-      recordName: md.recordName ?? c?.recordName,
-      snippet: typeof c?.content === "string" ? c.content.slice(0, 280) : md.blockText ?? null,
+      recordId: md.recordId ?? cd?.recordId ?? c?.recordId,
+      recordName: md.recordName ?? cd?.recordName ?? c?.recordName,
+      snippet: typeof content === "string" ? content.slice(0, 280) : md.blockText ?? null,
       mimeType: md.mimeType,
       webUrl: md.webUrl,
       pageNum: md.pageNum,
-      chunkIndex: c?.chunkIndex ?? md.chunkIndex
+      chunkIndex: cd?.chunkIndex ?? c?.chunkIndex ?? md.chunkIndex
     };
   });
 }
@@ -53170,9 +53409,10 @@ var init_pipeshubChat = __esm(() => {
   init_conversationsStreamMessage();
   init_agentsStreamConversation();
   init_agentsStreamMessage();
+  init__agui();
   init__helpers();
   FiltersShape = object({
-    apps: array(string2()).optional().describe("Source-scoping ids. Mix connector instance UUIDs with the synthetic " + "`knowledgeBase_<orgId>` id (use pipeshub_sources to discover them). " + "Empty / omitted means no app-side restriction."),
+    apps: array(string2()).optional().describe("Source-scoping ids from `pipeshub_sources` — connector instance and / " + "or knowledge base ids, mixed freely. The legacy org-wide " + "`knowledgeBase_<orgId>` id is still accepted on deployments that " + "predate per-KB sources. Empty / omitted means no app-side " + "restriction."),
     kb: array(string2()).optional().describe("Legacy / unused. Leave empty.")
   }).optional();
   args = {
@@ -53186,34 +53426,45 @@ var init_pipeshubChat = __esm(() => {
     chatMode: _enum([
       "internal_search",
       "web_search",
-      "auto",
-      "quick",
-      "verification",
-      "deep"
+      "quick"
     ]).optional().describe("Response strategy. The valid values depend on whether `agentId` is set:\n" + "- WITHOUT `agentId` (plain chat): `internal_search` — answer from the " + "org's indexed knowledge (default) — or `web_search` — answer from the " + `live web.
-` + "- WITH `agentId` (agent chat): `auto` (let the agent decide; default), " + "`quick`, `verification`, or `deep`.")
+` + "- WITH `agentId` (agent chat): `quick` is the only supported mode and " + "is sent automatically, so this argument can be omitted.")
   };
   tool$pipeshubChat = {
     name: "pipeshub_chat",
-    description: `**Primary chat tool — handles both internal knowledge queries and web search.**
-
-**Internal search** (default, \`chatMode: "internal_search"\`): Use whenever
-the user asks about their documents, files, knowledge base, company policies,
-or anything that could plausibly be answered by content in their PipesHub-indexed
-sources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).
-Grounds the answer in the user's actual data and returns citations.
-
-**Web search** (\`chatMode: "web_search"\`): Use when the user asks about
-current events, public information, or anything unlikely to be in the org's
-internal knowledge base. Pass \`chatMode: "web_search"\` and this tool will
-search the public web instead.
-
-**When to pick this over other tools:**
-- "What does <document> say about X?" → \`pipeshub_chat\` (internal_search)
-- "Summarize <topic / doc>." → \`pipeshub_chat\` (internal_search)
+    description: `Ask a question, get an answer grounded in the org's indexed data with
+citations. It reads a few retrieved passages — never a whole document,
+never a complete list.
+
+**Three questions this tool gets WRONG. Check them first:**
+- **Structure** — "what's under this epic?", "which pages are in this
+  space?", "what links to this ticket?", "what's in this folder?" →
+  \`pipeshub_get_record_content\` \`mode:"navigate"\`. Ranking cannot see how
+  records relate.
+- **Exhaustive** — "how many X?", "list ALL the Y", "every Z" →
+  \`mode:"navigate"\`, which reports the group's real total. This tool
+  undercounts and will not say so.
+- **One named document** — summarize it, extract from it, what does it say
+  about X → \`pipeshub_search\` for the \`recordId\`, then \`mode:"content"\`.
+
+Everything else about the org's knowledge belongs here: policies,
+processes, decisions, history, "what do we know about X", and any question
+spanning several documents.
+
+**Internal search** (default, \`chatMode: "internal_search"\`): the user's
+documents, files, knowledge base, company policies — anything in their
+PipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the
+org's KB, ...).
+
+**Web search** (\`chatMode: "web_search"\`): current events or public
+information unlikely to be in the org's knowledge base.
+
+Both are plain-chat modes. **Agent chat** — pass an \`agentId\` from
+\`pipeshub_agents\` — runs against that agent's own prompt, tools and knowledge;
+\`quick\` is its only mode, requires the \`agentId\`, and is sent automatically.
+
 - "What's our policy on Y?" → \`pipeshub_chat\` (internal_search)
 - "What's in the news about Z?" → \`pipeshub_chat\` (web_search)
-- "What is the latest version of <library>?" → \`pipeshub_chat\` (web_search)
 - "Find / locate the file named X" → \`pipeshub_search\` (then
   \`pipeshub_download_record\` if the user wants the bytes).
 
@@ -53243,9 +53494,10 @@ cited document, take \`citations[*].recordId\` and call
     args,
     tool: async (client, args2, ctx) => {
       const fetchOptions = { signal: ctx.signal };
+      const plainChatMode = args2.chatMode === "web_search" ? "web_search" : "internal_search";
       let response;
       if (args2.agentId) {
-        const agentChatMode = args2.chatMode ?? "auto";
+        const agentChatMode = "quick";
         if (args2.conversationId) {
           const [result] = await agentsStreamMessage(client, {
             agentKey: args2.agentId,
@@ -53285,7 +53537,7 @@ cited document, take \`citations[*].recordId\` and call
             modelKey: args2.modelKey,
             modelName: args2.modelName,
             modelFriendlyName: args2.modelFriendlyName,
-            chatMode: args2.chatMode ?? "internal_search"
+            chatMode: plainChatMode
           }
         }, { fetchOptions }).$inspect();
         if (!result.ok)
@@ -53298,7 +53550,7 @@ cited document, take \`citations[*].recordId\` and call
           modelKey: args2.modelKey,
           modelName: args2.modelName,
           modelFriendlyName: args2.modelFriendlyName,
-          chatMode: args2.chatMode ?? "internal_search"
+          chatMode: plainChatMode
         }, { fetchOptions }).$inspect();
         if (!result.ok)
           return errorResult(result.error.message);
@@ -53307,62 +53559,36 @@ cited document, take \`citations[*].recordId\` and call
       const httpErr = await httpErrorResult(response, "PipesHub chat request");
       if (httpErr)
         return httpErr;
-      let finalConversation = null;
-      let recordsUsed;
-      let lastAccumulated = null;
-      let errorMessage = null;
+      const state = newChatStreamState();
       try {
         for await (const frame of iterateSSE(response)) {
-          switch (frame.event) {
-            case "complete": {
-              const d = frame.data ?? {};
-              finalConversation = d.conversation ?? null;
-              recordsUsed = d.recordsUsed ?? d.meta?.recordsUsed;
-              break;
-            }
-            case "error": {
-              const d = frame.data ?? {};
-              errorMessage = typeof d === "string" ? d : d.error ?? d.message ?? frame.raw ?? "Stream error";
-              break;
-            }
-            case "answer_chunk": {
-              const d = frame.data ?? {};
-              if (typeof d.accumulated === "string") {
-                lastAccumulated = d.accumulated;
-              } else if (typeof d.content === "string") {
-                lastAccumulated = (lastAccumulated ?? "") + d.content;
-              }
-              break;
-            }
-            default:
-              break;
-          }
-          if (finalConversation || errorMessage)
+          if (applyAGUIFrame(state, frame))
             break;
         }
       } catch (e) {
         return errorResult(`SSE stream failed: ${e.message}`);
       }
-      if (errorMessage)
-        return errorResult(errorMessage);
-      if (finalConversation) {
+      if (state.error)
+        return errorResult(state.error);
+      if (state.conversation) {
         return jsonResult({
-          ...trimConversation(finalConversation),
-          recordsUsed
+          ...trimConversation(state.conversation),
+          recordsUsed: state.recordsUsed
         });
       }
-      if (lastAccumulated) {
+      const salvaged = salvagedText(state);
+      if (salvaged) {
         return jsonResult({
-          conversationId: null,
-          title: null,
+          conversationId: state.conversationId,
+          title: state.title,
           status: "Inprogress",
-          answer: lastAccumulated,
+          answer: salvaged,
           confidence: null,
           citations: [],
           followUpQuestions: [],
           messageCount: 0,
-          recordsUsed,
-          warning: "Stream ended without a `complete` frame; answer is " + "the last accumulated chunk and citations are unavailable."
+          recordsUsed: state.recordsUsed,
+          warning: "Stream ended without a terminal RUN_FINISHED; answer is the " + "accumulated TEXT_MESSAGE_CONTENT and citations are unavailable."
         });
       }
       return errorResult("Stream ended without any usable frames.");
@@ -53516,21 +53742,38 @@ var init_pipeshubSearch = __esm(() => {
     name: "pipeshub_search",
     description: `Vector / semantic search across the org's indexed documents.
 
-**Use this only when the user wants to LOCATE a document** — by name,
-topic, or a phrase to grep for. For "what does the document say about
-X?" or any open-ended question, use \`pipeshub_chat\` instead, which
-does the retrieval internally and grounds the answer in citations.
+**Use this when the user wants to LOCATE a document** — by name, topic,
+or a phrase to grep for — and to resolve it to a \`recordId\`. For
+open-ended questions across many documents, use \`pipeshub_chat\`
+instead, which does the retrieval internally and grounds the answer in
+citations.
 
 Typical uses:
+- Resolve a doc name / topic into a \`recordId\` for
+  \`pipeshub_get_record_content\` — step 1 of any full-document task
+  (summarize, extract, review, "what does the doc say?").
 - Resolve a filename / phrase into a \`recordId\` for
   \`pipeshub_download_record\`.
 - Show the user a ranked list of matching files when they ask "find /
   search for X".
 
+Not for structural questions — what is under this epic, which pages are
+in this space, what links to this ticket. Ranking by content cannot show
+how records relate; use \`pipeshub_get_record_content\` \`mode:"navigate"\`.
+
+**A ranked sample, never a complete list.** Hits are the top-scoring
+blocks from the best-matching records — not all blocks of any record, and
+not every record that matches. Never count them to answer "how many" /
+"all" / "every"; navigate the record group instead, which reports its
+real total.
+
 The response is trimmed to one row per hit:
 \`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }\`.
 Highest \`score\` first; multiple hits may share the same \`recordId\`
-(different chunks of the same record).`,
+(different blocks of the same record).
+
+When presenting results to the user, link each record using its
+\`webUrl\` (when present).`,
     scopes: ["read"],
     annotations: {
       title: "Semantic search",
@@ -53737,6 +53980,455 @@ returned base64-encoded; text content is returned inline.`,
   };
 });
 
+// src/models/getrecordcontentop.ts
+var GetRecordContentRequest$zodSchema;
+var init_getrecordcontentop = __esm(() => {
+  init_zod();
+  GetRecordContentRequest$zodSchema = object({
+    recordId: string2().describe("Record ID to fetch. Obtain it from a `pipeshub_search` result (`hits[*].recordId`) or a chat citation (`citations[*].recordId`).")
+  });
+});
+
+// src/funcs/connectorGetRecordContent.ts
+function connectorGetRecordContent(client$, request, options) {
+  return new APIPromise($do8(client$, request, options));
+}
+async function $do8(client$, request, options) {
+  const parsed$ = safeParse4(request, (value$) => GetRecordContentRequest$zodSchema.parse(value$), "Input validation failed");
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const pathParams$ = {
+    recordId: encodeSimple("recordId", payload$.recordId, {
+      explode: false,
+      charEncoding: "percent"
+    })
+  };
+  const path$ = pathToFunc("/connectors/record/{recordId}/content")(pathParams$);
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json"
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "getRecordContent",
+    oAuth2Scopes: ["connector:read"],
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries || client$._options.retryConfig || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504"
+    ]
+  };
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs || -1
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    request: req$,
+    response: doResult.value
+  }];
+}
+var init_connectorGetRecordContent = __esm(() => {
+  init_encodings();
+  init_primitives();
+  init_schemas4();
+  init_security2();
+  init_url();
+  init_getrecordcontentop();
+  init_async();
+});
+
+// src/models/lookuprecordbyidentifierop.ts
+var LookupRecordByIdentifierRequest$zodSchema;
+var init_lookuprecordbyidentifierop = __esm(() => {
+  init_zod();
+  LookupRecordByIdentifierRequest$zodSchema = object({
+    connectorName: string2().describe("Connector hint to prioritise resolution order, e.g. `JIRA`, `CONFLUENCE`, `GOOGLE_DRIVE`, `SLACK`. Cannot widen beyond the connectors the caller can access.").optional(),
+    identifiers: array(string2().min(1).max(2048)).min(1).max(10).describe("The references to resolve: URLs, issue keys such as `PA-1787`, or bare external system IDs. Paste each exactly as you found it — tracking parameters and fragments are handled. Up to 10 per call.")
+  });
+});
+
+// src/funcs/connectorLookupRecordByIdentifier.ts
+function connectorLookupRecordByIdentifier(client$, request, options) {
+  return new APIPromise($do9(client$, request, options));
+}
+async function $do9(client$, request, options) {
+  const parsed$ = safeParse4(request, (value$) => LookupRecordByIdentifierRequest$zodSchema.parse(value$), "Input validation failed");
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/connectors/record/lookup")();
+  const query$ = encodeFormQuery({
+    connectorName: payload$.connectorName,
+    identifiers: payload$.identifiers
+  });
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json"
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "lookupRecordByIdentifier",
+    oAuth2Scopes: ["kb:read", "connector:read"],
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries || client$._options.retryConfig || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504"
+    ]
+  };
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs || -1
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    request: req$,
+    response: doResult.value
+  }];
+}
+var init_connectorLookupRecordByIdentifier = __esm(() => {
+  init_encodings();
+  init_primitives();
+  init_schemas4();
+  init_security2();
+  init_url();
+  init_lookuprecordbyidentifierop();
+  init_async();
+});
+
+// src/models/navigateknowledgegraphop.ts
+var NavigateKnowledgeGraphRequest$zodSchema;
+var init_navigateknowledgegraphop = __esm(() => {
+  init_zod();
+  NavigateKnowledgeGraphRequest$zodSchema = object({
+    createdAfter: string2().describe("Filter children by source creation time. ISO 8601 `YYYY-MM-DD`, or a full datetime that MUST carry a timezone offset — a naive datetime is rejected rather than assumed to be UTC.").optional(),
+    createdBefore: string2().describe("Filter children by source creation time. `YYYY-MM-DD` is inclusive of the whole day.").optional(),
+    depth: int().min(1).max(3).describe("Levels of descendants to return in one call. Above 1, `rows` is a flat list of all descendants down to that level rather than only direct children, and each row carries its own `level`.").optional(),
+    limit: int().min(50).max(200).describe("Children per page. The minimum is 50 — smaller values are rejected rather than silently raised.").optional(),
+    modifiedAfter: string2().describe("Filter children by source modification time.").optional(),
+    modifiedBefore: string2().describe("Filter children by source modification time.").optional(),
+    nodeId: string2().min(1).max(2048).describe("The node to open. Take it from an `id` in a previous navigate or lookup response. Omit it entirely for the flat listing of everything reachable — the usual starting point. A URL or an issue key such as `PA-1787` also works: it is resolved to its record automatically.").optional(),
+    nodeTypes: array(string2()).describe("Restrict children to these node types. Repeat the parameter for multiple types: `?nodeTypes=record&nodeTypes=folder`.").optional(),
+    page: int().min(1).describe("Page number, 1-indexed.").optional()
+  });
+});
+
+// src/funcs/connectorNavigateKnowledgeGraph.ts
+function connectorNavigateKnowledgeGraph(client$, request, options) {
+  return new APIPromise($do10(client$, request, options));
+}
+async function $do10(client$, request, options) {
+  const parsed$ = safeParse4(request, (value$) => NavigateKnowledgeGraphRequest$zodSchema.optional().parse(value$), "Input validation failed");
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/connectors/navigate")();
+  const query$ = encodeFormQuery({
+    createdAfter: payload$?.createdAfter,
+    createdBefore: payload$?.createdBefore,
+    depth: payload$?.depth,
+    limit: payload$?.limit,
+    modifiedAfter: payload$?.modifiedAfter,
+    modifiedBefore: payload$?.modifiedBefore,
+    nodeId: payload$?.nodeId,
+    nodeTypes: payload$?.nodeTypes,
+    page: payload$?.page
+  });
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json"
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "navigateKnowledgeGraph",
+    oAuth2Scopes: ["kb:read", "connector:read"],
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries || client$._options.retryConfig || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504"
+    ]
+  };
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs || -1
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    request: req$,
+    response: doResult.value
+  }];
+}
+var init_connectorNavigateKnowledgeGraph = __esm(() => {
+  init_encodings();
+  init_primitives();
+  init_schemas4();
+  init_security2();
+  init_url();
+  init_navigateknowledgegraphop();
+  init_async();
+});
+
+// src/mcp-server/tools/pipeshubGetRecordContent.ts
+async function renderedResult(response) {
+  const parsed = await readJson(response);
+  if (!parsed.ok)
+    return parsed.result;
+  const text = parsed.value?.text;
+  return typeof text === "string" && text.trim().length > 0 ? { content: [{ type: "text", text }] } : jsonResult(parsed.value);
+}
+var args4, tool$pipeshubGetRecordContent;
+var init_pipeshubGetRecordContent = __esm(() => {
+  init_zod();
+  init_connectorGetRecordContent();
+  init_connectorLookupRecordByIdentifier();
+  init_connectorNavigateKnowledgeGraph();
+  init__helpers();
+  args4 = {
+    mode: _enum(["content", "navigate", "lookup"]).default("content").describe("`content` (default) reads a record's full text by `recordId`. " + "`lookup` resolves a URL / issue key / external ID to a recordId. " + "`navigate` browses the knowledge graph tree."),
+    recordId: string2().min(1).optional().describe("Record identifier — usually a UUID for connector-sourced records or " + "a 24-character ObjectId for uploaded records. Get it from a chat " + "citation (`citations[*].recordId`) or from a `pipeshub_search` hit. " + "Required when `mode` is `content`."),
+    nodeId: string2().min(1).max(2048).optional().describe("The node to open. Take it from a `record_id=` or `node_id=` shown in a " + "previous navigate or lookup response, from a search hit's `recordId`, " + "or from a `pipeshub_sources` id — a KB or connector id opens that " + "source directly. Omit it entirely for the flat listing of everything " + "reachable, newest first — the usual starting point. A URL or an issue " + "key such as `PA-1787` also works: it is resolved to its record " + "automatically, so no separate lookup is needed."),
+    page: int().min(1).default(1).describe("Page number, 1-indexed."),
+    limit: int().min(50).max(200).default(50).describe("Children per page. The minimum is 50 — smaller values are rejected " + "rather than silently raised."),
+    depth: int().min(1).max(3).default(1).describe("Levels of descendants to return in one call. Above 1, the listing is a " + "flat list of all descendants down to that level rather than only " + "direct children, and each row carries its own `level`."),
+    nodeTypes: array(string2()).optional().describe('Restrict children to these node types, e.g. `["record", "folder"]`.'),
+    createdAfter: string2().optional().describe("Filter children by source creation time. ISO 8601 `YYYY-MM-DD`, or a " + "full datetime that MUST carry a timezone offset — a naive datetime is " + "rejected rather than assumed to be UTC."),
+    createdBefore: string2().optional().describe("Filter children by source creation time. `YYYY-MM-DD` is inclusive of " + "the whole day."),
+    modifiedAfter: string2().optional().describe("Filter children by source modification time. Same formats as " + "`createdAfter`."),
+    modifiedBefore: string2().optional().describe("Filter children by source modification time. Same formats as " + "`createdBefore`."),
+    identifiers: union([
+      string2().min(1).max(2048),
+      array(string2().min(1).max(2048)).min(1).max(10)
+    ]).optional().describe("The reference(s) to resolve: a URL, an issue key such as `PA-1787`, or " + "a bare external system ID. Paste each exactly as you found it — " + "tracking parameters and fragments are handled. Pass a single string, " + "or an array of up to 10 to resolve them in one call. Required when " + "`mode` is `lookup`."),
+    connectorName: string2().optional().describe("Optional hint that prioritises resolution order, e.g. `JIRA`, " + "`CONFLUENCE`, `GOOGLE_DRIVE`, `SLACK`. It cannot widen the search beyond the " + "connectors you can already access. Useful on a retry when a lookup " + "came back empty.")
+  };
+  tool$pipeshubGetRecordContent = {
+    name: "pipeshub_get_record_content",
+    description: `Three operations on the org's records. Pick by what you hold:
+
+  \`mode:"lookup"\`   — a URL, issue key (PA-1787), or external ID
+                    → its recordId plus the record's metadata
+  \`mode:"navigate"\` — a question about structure: what is under X,
+                    what links to Y → browses the hierarchy
+  \`mode:"content"\`  — a recordId, and you need the document's COMPLETE text
+
+**\`mode:"content"\` (default)** — the only way to see a document's complete
+text. Use it whenever missing part of the document could make the answer
+wrong: summarize, extract or list ALL of something, check whether or where
+a doc mentions X, review, or compare named docs. \`pipeshub_chat\` cannot do
+these — it never sees a whole document.
+
+Judge by the user's INTENT, not their keywords: "what's this doc about?",
+"walk me through the report", "anything in here about Y?" are all
+full-content tasks. Get the \`recordId\` from a \`pipeshub_search\` top hit, a
+chat citation, or \`mode:"lookup"\`.
+
+Returns one \`content\` string: a metadata header (title, source, key fields,
+pre-generated summary) then the full parsed text. A record with no
+extractable content returns the literal \`No record found\`. Use
+\`pipeshub_download_record\` only for the original file bytes.
+
+**\`mode:"navigate"\`** — browse the hierarchy: RecordGroup (project /
+space / drive / folder) → Record (epic / story / page / file) → children,
+with breadcrumbs, related links and record IDs.
+
+Use it when the question depends on structure rather than wording: what is
+under this epic, which pages sit in this space, what is linked to this
+ticket, what is in this folder — and every "how many" / "all of" / "every"
+question. Search ranks by content; only this shows how records relate, and
+only this gives a count you can trust.
+
+Omit \`nodeId\` for a flat listing of everything reachable, most recently
+updated first — the usual starting point. A URL, an issue key, or a
+\`pipeshub_sources\` id also works and resolves automatically.
+
+Pass \`depth:2\` or \`depth:3\` to see several levels in ONE call — an epic's
+stories AND their subtasks, a space's pages AND their children — instead of
+one call per level. Use it whenever the question needs an overview of a
+hierarchy rather than a single node.
+
+Opening a record also prints that record's own metadata — for a ticket,
+status, assignee, priority and dates — so a question about one record is
+often answered by this call alone. It returns no document text; for that,
+re-call with \`mode:"content"\`.
+
+Returns \`Path\` breadcrumbs, the current node's metadata, a children listing
+carrying \`record_id=\` or \`node_id=\` per row plus the group's total
+(\`Children 1-50 of 61\`), \`Related\` cross-references, and a \`Next:\` line.
+One page is usually every child, so only pass \`page:2\` when that \`Next:\`
+line says more exist.
+
+**\`mode:"lookup"\`** — turn an external reference into a recordId, the first
+step whenever the question names one. Returns that record's metadata (for a
+ticket: status, assignee, priority, dates) plus its recordId, which
+\`mode:"navigate"\` takes to list what is under it and \`mode:"content"\` takes
+to read it.
+
+Handles Jira keys and URLs, Confluence, Drive, Slack permalinks, Linear,
+Notion, ServiceNow sys_id, SharePoint, Gmail/Outlook, and any connector
+whose records index a web URL. Resolution searches ALL connectors you can
+access, regardless of any source filter you used elsewhere.
+
+A miss is a 200 with empty \`matches\` and the input echoed in
+\`not_found_identifiers\` — that may mean no-access, not non-existence. Use
+\`mode:"navigate"\` to confirm the record exists before telling the user it
+does not. If \`ambiguous\` is true, pick from \`matches\` rather than taking
+the first.
+
+Navigate and lookup return a rendered text view whose closing \`Next:\` line
+names the exact follow-up call — follow it. When presenting a record, link
+it using the \`Web URL\` from its metadata header (when present).`,
+    scopes: ["read"],
+    annotations: {
+      title: "Read, browse, or resolve records",
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    args: args4,
+    tool: async (client, args5, ctx) => {
+      const fetchOptions = { fetchOptions: { signal: ctx.signal } };
+      if (args5.mode === "navigate") {
+        const [r] = await connectorNavigateKnowledgeGraph(client, {
+          nodeId: args5.nodeId,
+          page: args5.page,
+          limit: args5.limit,
+          depth: args5.depth,
+          nodeTypes: args5.nodeTypes,
+          createdAfter: args5.createdAfter,
+          createdBefore: args5.createdBefore,
+          modifiedAfter: args5.modifiedAfter,
+          modifiedBefore: args5.modifiedBefore
+        }, fetchOptions).$inspect();
+        if (!r.ok)
+          return errorResult(r.error.message);
+        const httpErr2 = await httpErrorResult(r.value, "Navigate knowledge graph");
+        if (httpErr2)
+          return httpErr2;
+        return renderedResult(r.value);
+      }
+      if (args5.mode === "lookup") {
+        const identifiers = typeof args5.identifiers === "string" ? [args5.identifiers] : args5.identifiers ?? [];
+        if (identifiers.length === 0) {
+          return errorResult('`identifiers` is required when mode is "lookup".');
+        }
+        const [r] = await connectorLookupRecordByIdentifier(client, {
+          identifiers,
+          connectorName: args5.connectorName
+        }, fetchOptions).$inspect();
+        if (!r.ok)
+          return errorResult(r.error.message);
+        const httpErr2 = await httpErrorResult(r.value, "Record lookup");
+        if (httpErr2)
+          return httpErr2;
+        return renderedResult(r.value);
+      }
+      if (!args5.recordId) {
+        return errorResult('`recordId` is required when mode is "content".');
+      }
+      const [result] = await connectorGetRecordContent(client, {
+        recordId: args5.recordId
+      }, fetchOptions).$inspect();
+      if (!result.ok)
+        return errorResult(result.error.message);
+      const httpErr = await httpErrorResult(result.value, "Get record content");
+      if (httpErr)
+        return httpErr;
+      const parsed = await readJson(result.value);
+      if (!parsed.ok)
+        return parsed.result;
+      return { content: [{ type: "text", text: parsed.value.content ?? "" }] };
+    }
+  };
+});
+
 // src/models/getallusersop.ts
 var GetAllUsersRequest$zodSchema;
 var init_getallusersop = __esm(() => {
@@ -53750,9 +54442,9 @@ var init_getallusersop = __esm(() => {
 
 // src/funcs/usersGetAllUsers.ts
 function usersGetAllUsers(client$, request, options) {
-  return new APIPromise($do8(client$, request, options));
+  return new APIPromise($do11(client$, request, options));
 }
-async function $do8(client$, request, options) {
+async function $do11(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetAllUsersRequest$zodSchema.optional().parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -53837,9 +54529,9 @@ var init_getuserbyidop = __esm(() => {
 
 // src/funcs/usersGetUserById.ts
 function usersGetUserById(client$, request, options) {
-  return new APIPromise($do9(client$, request, options));
+  return new APIPromise($do12(client$, request, options));
 }
-async function $do9(client$, request, options) {
+async function $do12(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetUserByIdRequest$zodSchema.parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -53926,9 +54618,9 @@ var init_getallusergroupsop = __esm(() => {
 
 // src/funcs/userGroupsGetAllUserGroups.ts
 function userGroupsGetAllUserGroups(client$, request, options) {
-  return new APIPromise($do10(client$, request, options));
+  return new APIPromise($do13(client$, request, options));
 }
-async function $do10(client$, request, options) {
+async function $do13(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetAllUserGroupsRequest$zodSchema.optional().parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -53950,7 +54642,7 @@ async function $do10(client$, request, options) {
     options: client$._options,
     baseURL: options?.serverURL ?? client$._baseURL ?? "",
     operationID: "getAllUserGroups",
-    oAuth2Scopes: [],
+    oAuth2Scopes: ["usergroup:read"],
     resolvedSecurity: requestSecurity,
     securitySource: client$._options.security,
     retryConfig: options?.retries || client$._options.retryConfig || { strategy: "none" },
@@ -54018,9 +54710,9 @@ var init_getuserteamsop = __esm(() => {
 
 // src/funcs/teamsGetUserTeams.ts
 function teamsGetUserTeams(client$, request, options) {
-  return new APIPromise($do11(client$, request, options));
+  return new APIPromise($do14(client$, request, options));
 }
-async function $do11(client$, request, options) {
+async function $do14(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetUserTeamsRequest$zodSchema.optional().parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54098,7 +54790,7 @@ var init_teamsGetUserTeams = __esm(() => {
 });
 
 // src/mcp-server/tools/pipeshubDirectory.ts
-var args4, tool$pipeshubDirectory;
+var args5, tool$pipeshubDirectory;
 var init_pipeshubDirectory = __esm(() => {
   init_zod();
   init_usersGetAllUsers();
@@ -54106,7 +54798,7 @@ var init_pipeshubDirectory = __esm(() => {
   init_userGroupsGetAllUserGroups();
   init_teamsGetUserTeams();
   init__helpers();
-  args4 = {
+  args5 = {
     action: _enum([
       "whoami",
       "list_users",
@@ -54144,10 +54836,10 @@ Output shape varies by action; see each action's docs above.`,
       openWorldHint: false,
       readOnlyHint: true
     },
-    args: args4,
-    tool: async (client, args5, ctx) => {
+    args: args5,
+    tool: async (client, args6, ctx) => {
       const fetchOptions = { signal: ctx.signal };
-      switch (args5.action) {
+      switch (args6.action) {
         case "whoami": {
           const claims = await decodeBearer(client);
           if (!claims) {
@@ -54164,9 +54856,9 @@ Output shape varies by action; see each action's docs above.`,
         }
         case "list_users": {
           const [result] = await usersGetAllUsers(client, {
-            page: args5.page,
-            limit: args5.limit,
-            search: args5.search
+            page: args6.page,
+            limit: args6.limit,
+            search: args6.search
           }, { fetchOptions }).$inspect();
           if (!result.ok)
             return errorResult(result.error.message);
@@ -54176,11 +54868,11 @@ Output shape varies by action; see each action's docs above.`,
           return jsonResult(parsed.value);
         }
         case "get_user": {
-          if (!args5.userId) {
+          if (!args6.userId) {
             return errorResult("`userId` is required when `action` is `get_user`. " + "Use `whoami` to find your own id, or `list_users` " + "to look up by name / email.");
           }
           const [result] = await usersGetUserById(client, {
-            id: args5.userId
+            id: args6.userId
           }, { fetchOptions }).$inspect();
           if (!result.ok)
             return errorResult(result.error.message);
@@ -54191,9 +54883,9 @@ Output shape varies by action; see each action's docs above.`,
         }
         case "list_groups": {
           const [result] = await userGroupsGetAllUserGroups(client, {
-            page: args5.page,
-            limit: args5.limit,
-            search: args5.search
+            page: args6.page,
+            limit: args6.limit,
+            search: args6.search
           }, { fetchOptions }).$inspect();
           if (!result.ok)
             return errorResult(result.error.message);
@@ -54204,9 +54896,9 @@ Output shape varies by action; see each action's docs above.`,
         }
         case "list_my_teams": {
           const [result] = await teamsGetUserTeams(client, {
-            page: args5.page,
-            limit: args5.limit,
-            search: args5.search
+            page: args6.page,
+            limit: args6.limit,
+            search: args6.search
           }, { fetchOptions }).$inspect();
           if (!result.ok)
             return errorResult(result.error.message);
@@ -54250,9 +54942,9 @@ var init_getknowledgehubrootnodesop = __esm(() => {
 
 // src/funcs/knowledgeHubGetKnowledgeHubRootNodes.ts
 function knowledgeHubGetKnowledgeHubRootNodes(client$, request, options) {
-  return new APIPromise($do12(client$, request, options));
+  return new APIPromise($do15(client$, request, options));
 }
-async function $do12(client$, request, options) {
+async function $do15(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetKnowledgeHubRootNodesRequest$zodSchema.optional().parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54368,9 +55060,9 @@ var init_getavailablemodelsbytypeop = __esm(() => {
 
 // src/funcs/aiModelsProvidersGetAvailableModelsByType.ts
 function aiModelsProvidersGetAvailableModelsByType(client$, request, options) {
-  return new APIPromise($do13(client$, request, options));
+  return new APIPromise($do16(client$, request, options));
 }
-async function $do13(client$, request, options) {
+async function $do16(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetAvailableModelsByTypeRequest$zodSchema.parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54445,13 +55137,13 @@ var init_aiModelsProvidersGetAvailableModelsByType = __esm(() => {
 });
 
 // src/mcp-server/tools/pipeshubSources.ts
-var args5, tool$pipeshubSources;
+var args6, tool$pipeshubSources;
 var init_pipeshubSources = __esm(() => {
   init_zod();
   init_knowledgeHubGetKnowledgeHubRootNodes();
   init_aiModelsProvidersGetAvailableModelsByType();
   init__helpers();
-  args5 = {
+  args6 = {
     include: array(_enum(["sources", "llmModels", "embeddingModels"])).optional().describe('Which sections to fetch. Default: `["sources", "llmModels"]`. ' + "Add `embeddingModels` if the user is configuring re-embedding.")
   };
   tool$pipeshubSources = {
@@ -54482,10 +55174,10 @@ are returned by default; pass \`include\` to override.`,
       openWorldHint: false,
       readOnlyHint: true
     },
-    args: args5,
-    tool: async (client, args6, ctx) => {
+    args: args6,
+    tool: async (client, args7, ctx) => {
       const fetchOptions = { signal: ctx.signal };
-      const include = args6.include ?? ["sources", "llmModels"];
+      const include = args7.include ?? ["sources", "llmModels"];
       const want = (s) => include.includes(s);
       const result = {};
       if (want("sources")) {
@@ -54535,11 +55227,11 @@ are returned by default; pass \`include\` to override.`,
 });
 
 // src/mcp-server/tools/pipeshubAgents.ts
-var args6, tool$pipeshubAgents;
+var args7, tool$pipeshubAgents;
 var init_pipeshubAgents = __esm(() => {
   init_zod();
   init__helpers();
-  args6 = {
+  args7 = {
     search: string2().optional().describe("Optional case-insensitive substring match across agent name, " + "description, and tags. Omit to return every agent.")
   };
   tool$pipeshubAgents = {
@@ -54578,10 +55270,10 @@ specific agent is needed, use \`pipeshub_chat\` WITHOUT \`agentId\` and pick a
       openWorldHint: false,
       readOnlyHint: true
     },
-    args: args6,
-    tool: async (client, args7, ctx) => {
+    args: args7,
+    tool: async (client, args8, ctx) => {
       const all = await listAllAgents(client, {
-        search: args7.search,
+        search: args8.search,
         signal: ctx.signal
       });
       if (!all.ok)
@@ -54596,25 +55288,25 @@ specific agent is needed, use \`pipeshub_chat\` WITHOUT \`agentId\` and pick a
 });
 
 // src/mcp-server/prompts/pipeshubAssistant.ts
-var args7, prompt$pipeshubAssistant;
+var args8, prompt$pipeshubAssistant;
 var init_pipeshubAssistant = __esm(() => {
   init_zod();
-  args7 = {
+  args8 = {
     query: string2().optional().describe("Optional. The user's request to route. Provide it to have the guidance " + "applied to a concrete request; omit it to just load the routing " + "guidance as a seed system prompt at the start of a session.")
   };
   prompt$pipeshubAssistant = {
     name: "pipeshub-assistant",
     description: "Load PipesHub tool-routing guidance so the assistant picks the correct " + "tool (pipeshub_chat / search / agents / directory) and lists agents " + "with pipeshub_agents when unsure which route fits the query.",
     scopes: ["read"],
-    args: args7,
-    prompt: (_client, args8, _extra) => {
-      const text = args8.query ? `${PIPESHUB_INSTRUCTIONS}
+    args: args8,
+    prompt: (_client, args9, _extra) => {
+      const text = args9.query ? `${PIPESHUB_INSTRUCTIONS}
 
 ---
 
 Follow the routing rules above to ` + `handle this request, picking the right tool (and listing agents via ` + `\`pipeshub_agents\` if unsure which route fits):
 
-${args8.query}` : PIPESHUB_INSTRUCTIONS;
+${args9.query}` : PIPESHUB_INSTRUCTIONS;
       return {
         messages: [
           {
@@ -54635,17 +55327,21 @@ function createMCPServer(deps) {
   }, {
     instructions: PIPESHUB_INSTRUCTIONS
   });
-  const getClient = deps.getSDK || (() => new PipeshubCore({
+  const resolveClient = deps.getSDK || (() => new PipeshubCore({
     security: deps.security,
     serverURL: deps.serverURL,
     serverIdx: deps.serverIdx,
     instance_url: deps.instance_url,
     debugLogger: deps.logger.level === "debug" ? {
-      log: (...args8) => console.log(...args8),
-      group: (...args8) => console.group(...args8),
-      groupEnd: (...args8) => console.groupEnd(...args8)
+      log: (...args9) => console.log(...args9),
+      group: (...args9) => console.group(...args9),
+      groupEnd: (...args9) => console.groupEnd(...args9)
     } : undefined
   }));
+  const getClient = () => {
+    bindNewRequestId();
+    return resolveClient();
+  };
   const scopes = new Set(deps.scopes);
   const allowedTools = deps.allowedTools && new Set(deps.allowedTools);
   const [tool, tools, toolMap] = createRegisterTool(deps.logger, server, getClient, scopes, allowedTools, deps.dynamic);
@@ -54657,6 +55353,7 @@ function createMCPServer(deps) {
   tool(tool$pipeshubChat);
   tool(tool$pipeshubSearch);
   tool(tool$pipeshubDownloadRecord);
+  tool(tool$pipeshubGetRecordContent);
   tool(tool$pipeshubDirectory);
   tool(tool$pipeshubAgents);
   prompt(prompt$pipeshubAssistant);
@@ -54668,11 +55365,13 @@ function createMCPServer(deps) {
 var init_server2 = __esm(() => {
   init_mcp();
   init_core3();
+  init_request_context();
   init_resources();
   init_tools();
   init_pipeshubChat();
   init_pipeshubSearch();
   init_pipeshubDownloadRecord();
+  init_pipeshubGetRecordContent();
   init_pipeshubDirectory();
   init_pipeshubSources();
   init_pipeshubAgents();
@@ -54689,25 +55388,39 @@ var init_tool_names = __esm(() => {
     },
     {
       name: "pipeshub_chat",
-      description: `**Primary chat tool — handles both internal knowledge queries and web search.**
-
-**Internal search** (default, \`chatMode: "internal_search"\`): Use whenever
-the user asks about their documents, files, knowledge base, company policies,
-or anything that could plausibly be answered by content in their PipesHub-indexed
-sources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).
-Grounds the answer in the user's actual data and returns citations.
-
-**Web search** (\`chatMode: "web_search"\`): Use when the user asks about
-current events, public information, or anything unlikely to be in the org's
-internal knowledge base. Pass \`chatMode: "web_search"\` and this tool will
-search the public web instead.
-
-**When to pick this over other tools:**
-- "What does <document> say about X?" → \`pipeshub_chat\` (internal_search)
-- "Summarize <topic / doc>." → \`pipeshub_chat\` (internal_search)
+      description: `Ask a question, get an answer grounded in the org's indexed data with
+citations. It reads a few retrieved passages — never a whole document,
+never a complete list.
+
+**Three questions this tool gets WRONG. Check them first:**
+- **Structure** — "what's under this epic?", "which pages are in this
+  space?", "what links to this ticket?", "what's in this folder?" →
+  \`pipeshub_get_record_content\` \`mode:"navigate"\`. Ranking cannot see how
+  records relate.
+- **Exhaustive** — "how many X?", "list ALL the Y", "every Z" →
+  \`mode:"navigate"\`, which reports the group's real total. This tool
+  undercounts and will not say so.
+- **One named document** — summarize it, extract from it, what does it say
+  about X → \`pipeshub_search\` for the \`recordId\`, then \`mode:"content"\`.
+
+Everything else about the org's knowledge belongs here: policies,
+processes, decisions, history, "what do we know about X", and any question
+spanning several documents.
+
+**Internal search** (default, \`chatMode: "internal_search"\`): the user's
+documents, files, knowledge base, company policies — anything in their
+PipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the
+org's KB, ...).
+
+**Web search** (\`chatMode: "web_search"\`): current events or public
+information unlikely to be in the org's knowledge base.
+
+Both are plain-chat modes. **Agent chat** — pass an \`agentId\` from
+\`pipeshub_agents\` — runs against that agent's own prompt, tools and knowledge;
+\`quick\` is its only mode, requires the \`agentId\`, and is sent automatically.
+
 - "What's our policy on Y?" → \`pipeshub_chat\` (internal_search)
 - "What's in the news about Z?" → \`pipeshub_chat\` (web_search)
-- "What is the latest version of <library>?" → \`pipeshub_chat\` (web_search)
 - "Find / locate the file named X" → \`pipeshub_search\` (then
   \`pipeshub_download_record\` if the user wants the bytes).
 
@@ -54731,26 +55444,120 @@ cited document, take \`citations[*].recordId\` and call
       name: "pipeshub_search",
       description: `Vector / semantic search across the org's indexed documents.
 
-**Use this only when the user wants to LOCATE a document** — by name,
-topic, or a phrase to grep for. For "what does the document say about
-X?" or any open-ended question, use \`pipeshub_chat\` instead, which
-does the retrieval internally and grounds the answer in citations.
+**Use this when the user wants to LOCATE a document** — by name, topic,
+or a phrase to grep for — and to resolve it to a \`recordId\`. For
+open-ended questions across many documents, use \`pipeshub_chat\`
+instead, which does the retrieval internally and grounds the answer in
+citations.
 
 Typical uses:
+- Resolve a doc name / topic into a \`recordId\` for
+  \`pipeshub_get_record_content\` — step 1 of any full-document task
+  (summarize, extract, review, "what does the doc say?").
 - Resolve a filename / phrase into a \`recordId\` for
   \`pipeshub_download_record\`.
 - Show the user a ranked list of matching files when they ask "find /
   search for X".
 
+Not for structural questions — what is under this epic, which pages are
+in this space, what links to this ticket. Ranking by content cannot show
+how records relate; use \`pipeshub_get_record_content\` \`mode:"navigate"\`.
+
+**A ranked sample, never a complete list.** Hits are the top-scoring
+blocks from the best-matching records — not all blocks of any record, and
+not every record that matches. Never count them to answer "how many" /
+"all" / "every"; navigate the record group instead, which reports its
+real total.
+
 The response is trimmed to one row per hit:
 \`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }\`.
 Highest \`score\` first; multiple hits may share the same \`recordId\`
-(different chunks of the same record).`
+(different blocks of the same record).
+
+When presenting results to the user, link each record using its
+\`webUrl\` (when present).`
     },
     {
       name: "pipeshub_download_record",
       description: "Stream the binary content of a single record from PipesHub.\n\nTypical sources for the `recordId`:\n- A chat citation:\n  `pipeshub_chat` response → `citations[*].recordId`.\n- A search result:\n  `pipeshub_search` response → `hits[*].recordId` /\n  `uniqueRecords[*].recordId`.\n\nResponse `Content-Type` is forwarded from the upstream service —\n`application/pdf`, `application/octet-stream`, etc. Binary content is\nreturned base64-encoded; text content is returned inline."
     },
+    {
+      name: "pipeshub_get_record_content",
+      description: `Three operations on the org's records. Pick by what you hold:
+
+  \`mode:"lookup"\`   — a URL, issue key (PA-1787), or external ID
+                    → its recordId plus the record's metadata
+  \`mode:"navigate"\` — a question about structure: what is under X,
+                    what links to Y → browses the hierarchy
+  \`mode:"content"\`  — a recordId, and you need the document's COMPLETE text
+
+**\`mode:"content"\` (default)** — the only way to see a document's complete
+text. Use it whenever missing part of the document could make the answer
+wrong: summarize, extract or list ALL of something, check whether or where
+a doc mentions X, review, or compare named docs. \`pipeshub_chat\` cannot do
+these — it never sees a whole document.
+
+Judge by the user's INTENT, not their keywords: "what's this doc about?",
+"walk me through the report", "anything in here about Y?" are all
+full-content tasks. Get the \`recordId\` from a \`pipeshub_search\` top hit, a
+chat citation, or \`mode:"lookup"\`.
+
+Returns one \`content\` string: a metadata header (title, source, key fields,
+pre-generated summary) then the full parsed text. A record with no
+extractable content returns the literal \`No record found\`. Use
+\`pipeshub_download_record\` only for the original file bytes.
+
+**\`mode:"navigate"\`** — browse the hierarchy: RecordGroup (project /
+space / drive / folder) → Record (epic / story / page / file) → children,
+with breadcrumbs, related links and record IDs.
+
+Use it when the question depends on structure rather than wording: what is
+under this epic, which pages sit in this space, what is linked to this
+ticket, what is in this folder — and every "how many" / "all of" / "every"
+question. Search ranks by content; only this shows how records relate, and
+only this gives a count you can trust.
+
+Omit \`nodeId\` for a flat listing of everything reachable, most recently
+updated first — the usual starting point. A URL, an issue key, or a
+\`pipeshub_sources\` id also works and resolves automatically.
+
+Pass \`depth:2\` or \`depth:3\` to see several levels in ONE call — an epic's
+stories AND their subtasks, a space's pages AND their children — instead of
+one call per level. Use it whenever the question needs an overview of a
+hierarchy rather than a single node.
+
+Opening a record also prints that record's own metadata — for a ticket,
+status, assignee, priority and dates — so a question about one record is
+often answered by this call alone. It returns no document text; for that,
+re-call with \`mode:"content"\`.
+
+Returns \`Path\` breadcrumbs, the current node's metadata, a children listing
+carrying \`record_id=\` or \`node_id=\` per row plus the group's total
+(\`Children 1-50 of 61\`), \`Related\` cross-references, and a \`Next:\` line.
+One page is usually every child, so only pass \`page:2\` when that \`Next:\`
+line says more exist.
+
+**\`mode:"lookup"\`** — turn an external reference into a recordId, the first
+step whenever the question names one. Returns that record's metadata (for a
+ticket: status, assignee, priority, dates) plus its recordId, which
+\`mode:"navigate"\` takes to list what is under it and \`mode:"content"\` takes
+to read it.
+
+Handles Jira keys and URLs, Confluence, Drive, Slack permalinks, Linear,
+Notion, ServiceNow sys_id, SharePoint, Gmail/Outlook, and any connector
+whose records index a web URL. Resolution searches ALL connectors you can
+access, regardless of any source filter you used elsewhere.
+
+A miss is a 200 with empty \`matches\` and the input echoed in
+\`not_found_identifiers\` — that may mean no-access, not non-existence. Use
+\`mode:"navigate"\` to confirm the record exists before telling the user it
+does not. If \`ambiguous\` is true, pick from \`matches\` rather than taking
+the first.
+
+Navigate and lookup return a rendered text view whose closing \`Next:\` line
+names the exact follow-up call — follow it. When presenting a record, link
+it using the \`Web URL\` from its metadata header (when present).`
+    },
     {
       name: "pipeshub_directory",
       description: "Look up people, groups, and teams in PipesHub. One tool with five\nactions — pick the right `action`:\n\n- `whoami` — who is the caller?  Use this whenever you need the\n  authenticated user's own id, email, or full name (e.g. before\n  `get_user` on themselves).\n- `list_users` — search / page through org users.\n- `get_user` — full `User` document for one user (requires `userId`).\n- `list_groups` — list user groups with `userCount`.\n- `list_my_teams` — teams the caller belongs to, with capability flags\n  (`canEdit` / `canDelete` / `canManageMembers`).\n\nOutput shape varies by action; see each action's docs above."
@@ -58386,5 +59193,5 @@ export {
   app
 };
 
-//# debugId=E589470B4E3C258364756E2164756E21
+//# debugId=90FD24D95D2C4D3664756E2164756E21
 //# sourceMappingURL=mcp-server.js.map