@pipeshub-ai/mcp 2.1.0 → 2.2.0

package/src/hooks/requestid.ts

@@ -0,0 +1,62 @@
+/*
+ * Stamp an x-request-id trace header onto every outbound SDK request, reusing
+ * the id bound for the current MCP tool/resource/prompt call (see
+ * request-context.ts) so all backend calls from one invocation share it.
+ *
+ * Format mirrors the TypeScript SDK's own RequestIDHook: `mcp-<userId>-<random>`
+ * when the bearer JWT carries a userId claim, else `mcp-<random>`. The userId
+ * is only knowable once a request actually carries a resolved Authorization
+ * header, so it's decoded off the first outbound request of the tool call and
+ * cached on the bound context for every subsequent call to reuse verbatim.
+ */
+
+import { getRequestContextStore, newRequestId } from "./request-context.js";
+import { BeforeRequestContext, BeforeRequestHook } from "./types.js";
+
+const REQUEST_ID_HEADER = "x-request-id";
+
+/** Decodes the JWT payload without verifying the signature. */
+function decodeJwtPayload(token: string): Record<string, unknown> | null {
+  try {
+    const base64Url = token.split(".")[1];
+    if (!base64Url) return null;
+    const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.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: Request): string | null {
+  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"] as string) || null;
+}
+
+export class RequestIDHook implements BeforeRequestHook {
+  beforeRequest(_hookCtx: BeforeRequestContext, request: Request): Request {
+    if (request.headers.get(REQUEST_ID_HEADER)) {
+      return request;
+    }
+
+    const store = getRequestContextStore();
+    if (!store) {
+      // No bound tool-call context (shouldn't happen in practice).
+      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;
+  }
+}

package/src/mcp-server/instructions.ts

@@ -9,14 +9,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?").
@@ -32,15 +53,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

package/src/mcp-server/server.ts

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 import { PIPESHUB_INSTRUCTIONS } from "./instructions.js";
 import { PipeshubCore } from "../core.js";
+import { bindNewRequestId } from "../hooks/request-context.js";
 import { SDKOptions } from "../lib/config.js";
 import type { ConsoleLogger } from "./console-logger.js";
 import { createRegisterPrompt } from "./prompts.js";
@@ -14,6 +15,7 @@ import { createRegisterTool, registerDynamicTools } from "./tools.js";
 import { tool$pipeshubChat } from "./tools/pipeshubChat.js";
 import { tool$pipeshubSearch } from "./tools/pipeshubSearch.js";
 import { tool$pipeshubDownloadRecord } from "./tools/pipeshubDownloadRecord.js";
+import { tool$pipeshubGetRecordContent } from "./tools/pipeshubGetRecordContent.js";
 import { tool$pipeshubDirectory } from "./tools/pipeshubDirectory.js";
 import { tool$pipeshubSources } from "./tools/pipeshubSources.js";
 import { tool$pipeshubAgents } from "./tools/pipeshubAgents.js";
@@ -40,7 +42,7 @@ export function createMCPServer(deps: {
     },
   );
 
-  const getClient = deps.getSDK || (() =>
+  const resolveClient = deps.getSDK || (() =>
     new PipeshubCore({
       security: deps.security,
       serverURL: deps.serverURL,
@@ -55,6 +57,11 @@ export function createMCPServer(deps: {
         : undefined,
     }));
 
+  const getClient = () => {
+    bindNewRequestId();
+    return resolveClient();
+  };
+
   const scopes = new Set(deps.scopes);
 
   const allowedTools = deps.allowedTools && new Set(deps.allowedTools);
@@ -87,8 +94,9 @@ export function createMCPServer(deps: {
   tool(tool$pipeshubChat);             // 2. ask questions (start + continue)
   tool(tool$pipeshubSearch);           // 3. resolve filename → recordId
   tool(tool$pipeshubDownloadRecord);   // 4. fetch a document by id
-  tool(tool$pipeshubDirectory);        // 5. people / groups / teams / whoami
-  tool(tool$pipeshubAgents);           // 6. discover org agents
+  tool(tool$pipeshubGetRecordContent); // 5. fetch a record's parsed content
+  tool(tool$pipeshubDirectory);        // 6. people / groups / teams / whoami
+  tool(tool$pipeshubAgents);           // 7. discover org agents
 
   // Curated prompt: user-invokable tool-routing guidance.
   prompt(prompt$pipeshubAssistant);

package/src/mcp-server/tools/pipeshubChat.ts

@@ -100,6 +100,9 @@ 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.
+Answers come from a few retrieved passages, not whole documents — for
+any task needing a document's full content, use
+\`pipeshub_get_record_content\` instead.
 
 **Web search** (\`chatMode: "web_search"\`): Use when the user asks about
 current events, public information, or anything unlikely to be in the org's
@@ -107,8 +110,11 @@ 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)
+- "Summarize <doc>" / "key points of <doc>" / "what does <document> say
+  about X?" → NOT this tool. Use \`pipeshub_search\` →
+  \`pipeshub_get_record_content\`: answering for a specific document
+  requires its full content, and chat only sees a few retrieved
+  passages, never the whole document.
 - "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)

package/src/mcp-server/tools/pipeshubGetRecordContent.ts

@@ -0,0 +1,67 @@
+import * as z from "zod";
+import { connectorGetRecordContent } from "../../funcs/connectorGetRecordContent.js";
+import { ToolDefinition } from "../tools.js";
+import { errorResult, httpErrorResult, readJson } from "./_helpers.js";
+
+const args = {
+  recordId: z.string().min(1).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.",
+  ),
+};
+
+export const tool$pipeshubGetRecordContent: ToolDefinition<typeof args> = {
+  name: "pipeshub_get_record_content",
+  description:
+    `Read a record's full parsed content by \`recordId\` — the only way to
+see a document's COMPLETE text.
+
+Use it whenever the answer depends on a document's full content — any
+task where missing a part could make the answer wrong: summarize / key
+points / action items; extract or list ALL of something; check whether
+or where the doc mentions X; translate, rewrite, outline, or review the
+doc; compare named docs (fetch each); any question scoped to one named
+document. \`pipeshub_chat\` cannot do these — it only sees a few
+retrieved passages, never the whole document. Get the \`recordId\` from
+a \`pipeshub_search\` top hit or a chat citation.
+
+Judge by the user's INTENT, not their keywords: they need not say
+"summarize", "key points", or "extract". Reason about what a good
+answer requires — if it would need the whole document (e.g. "what's
+this doc about?", "walk me through the report", "anything in here
+about Y?"), that is a full-content task, so call this tool.
+
+Returns a single \`content\` string: a short metadata header (title,
+source, key fields, and a pre-generated summary) followed by the
+record's full parsed text — paragraphs, tables, and lists in reading
+order. For a record with no extractable content, \`content\` is the
+literal \`No record found\`. Use \`pipeshub_download_record\` only when
+you need the original file bytes.`,
+  scopes: ["read"],
+  annotations: {
+    title: "Get a record's full parsed content",
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result] = await connectorGetRecordContent(client, {
+      recordId: args.recordId,
+    }, { fetchOptions: { signal: ctx.signal } }).$inspect();
+    if (!result.ok) return errorResult(result.error.message);
+
+    // The SDK func uses errorCodes:[], so any non-2xx comes back as an
+    // ok=false Response — surface it as an error rather than parsing it.
+    const httpErr = await httpErrorResult(result.value, "Get record content");
+    if (httpErr) return httpErr;
+
+    // Success: the endpoint returns { content: <string> }. Hand the LLM the
+    // plain text (real newlines), not the JSON wrapper.
+    const parsed = await readJson<{ content?: string }>(result.value);
+    if (!parsed.ok) return parsed.result;
+    return { content: [{ type: "text", text: parsed.value.content ?? "" }] };
+  },
+};

package/src/mcp-server/tools/pipeshubSearch.ts

@@ -23,12 +23,16 @@ export const tool$pipeshubSearch: ToolDefinition<typeof args> = {
   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 /

package/src/mcp-server/tools.ts

@@ -75,9 +75,22 @@ export async function formatResult(
     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 };

package/src/models/getrecordcontentop.ts

@@ -0,0 +1,11 @@
+import * as z from "zod";
+
+export type GetRecordContentRequest = { recordId: string };
+
+export const GetRecordContentRequest$zodSchema: z.ZodType<
+  GetRecordContentRequest
+> = z.object({
+  recordId: z.string().describe(
+    "Record ID to fetch. Obtain it from a `pipeshub_search` result (`hits[*].recordId`) or a chat citation (`citations[*].recordId`).",
+  ),
+});

package/src/tool-names.ts

@@ -6,16 +6,20 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "pipeshub_chat",
-    "description": "**Primary chat tool — handles both internal knowledge queries and web search.**\n\n**Internal search** (default, `chatMode: \"internal_search\"`): Use whenever\nthe user asks about their documents, files, knowledge base, company policies,\nor anything that could plausibly be answered by content in their PipesHub-indexed\nsources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).\nGrounds the answer in the user's actual data and returns citations.\n\n**Web search** (`chatMode: \"web_search\"`): Use when the user asks about\ncurrent events, public information, or anything unlikely to be in the org's\ninternal knowledge base. Pass `chatMode: \"web_search\"` and this tool will\nsearch the public web instead.\n\n**When to pick this over other tools:**\n- \"What does <document> say about X?\" → `pipeshub_chat` (internal_search)\n- \"Summarize <topic / doc>.\" → `pipeshub_chat` (internal_search)\n- \"What's our policy on Y?\" → `pipeshub_chat` (internal_search)\n- \"What's in the news about Z?\" → `pipeshub_chat` (web_search)\n- \"What is the latest version of <library>?\" → `pipeshub_chat` (web_search)\n- \"Find / locate the file named X\" → `pipeshub_search` (then\n  `pipeshub_download_record` if the user wants the bytes).\n\n**Conversation lifecycle** — one tool, both start and continue:\n\n- **First turn**: omit `conversationId`. The server creates a new\n  conversation; capture `conversationId` from the response.\n- **Follow-up turn**: pass the `conversationId` from the previous\n  response. Server-side context is preserved — do NOT replay earlier\n  messages, and `filters` is ignored on follow-ups (set once at\n  creation).\n\nOnly re-omit `conversationId` (start a fresh conversation) when the\nuser explicitly asks to start over / clear context.\n\nThe response contains the AI's `answer` plus `citations`. To download a\ncited document, take `citations[*].recordId` and call\n`pipeshub_download_record`."
+    "description": "**Primary chat tool — handles both internal knowledge queries and web search.**\n\n**Internal search** (default, `chatMode: \"internal_search\"`): Use whenever\nthe user asks about their documents, files, knowledge base, company policies,\nor anything that could plausibly be answered by content in their PipesHub-indexed\nsources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).\nGrounds the answer in the user's actual data and returns citations.\nAnswers come from a few retrieved passages, not whole documents — for\nany task needing a document's full content, use\n`pipeshub_get_record_content` instead.\n\n**Web search** (`chatMode: \"web_search\"`): Use when the user asks about\ncurrent events, public information, or anything unlikely to be in the org's\ninternal knowledge base. Pass `chatMode: \"web_search\"` and this tool will\nsearch the public web instead.\n\n**When to pick this over other tools:**\n- \"Summarize <doc>\" / \"key points of <doc>\" / \"what does <document> say\n  about X?\" → NOT this tool. Use `pipeshub_search` →\n  `pipeshub_get_record_content`: answering for a specific document\n  requires its full content, and chat only sees a few retrieved\n  passages, never the whole document.\n- \"What's our policy on Y?\" → `pipeshub_chat` (internal_search)\n- \"What's in the news about Z?\" → `pipeshub_chat` (web_search)\n- \"What is the latest version of <library>?\" → `pipeshub_chat` (web_search)\n- \"Find / locate the file named X\" → `pipeshub_search` (then\n  `pipeshub_download_record` if the user wants the bytes).\n\n**Conversation lifecycle** — one tool, both start and continue:\n\n- **First turn**: omit `conversationId`. The server creates a new\n  conversation; capture `conversationId` from the response.\n- **Follow-up turn**: pass the `conversationId` from the previous\n  response. Server-side context is preserved — do NOT replay earlier\n  messages, and `filters` is ignored on follow-ups (set once at\n  creation).\n\nOnly re-omit `conversationId` (start a fresh conversation) when the\nuser explicitly asks to start over / clear context.\n\nThe response contains the AI's `answer` plus `citations`. To download a\ncited document, take `citations[*].recordId` and call\n`pipeshub_download_record`."
   },
   {
     "name": "pipeshub_search",
-    "description": "Vector / semantic search across the org's indexed documents.\n\n**Use this only when the user wants to LOCATE a document** — by name,\ntopic, or a phrase to grep for. For \"what does the document say about\nX?\" or any open-ended question, use `pipeshub_chat` instead, which\ndoes the retrieval internally and grounds the answer in citations.\n\nTypical uses:\n- Resolve a filename / phrase into a `recordId` for\n  `pipeshub_download_record`.\n- Show the user a ranked list of matching files when they ask \"find /\n  search for X\".\n\nThe response is trimmed to one row per hit:\n`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }`.\nHighest `score` first; multiple hits may share the same `recordId`\n(different chunks of the same record)."
+    "description": "Vector / semantic search across the org's indexed documents.\n\n**Use this when the user wants to LOCATE a document** — by name, topic,\nor a phrase to grep for — and to resolve it to a `recordId`. For\nopen-ended questions across many documents, use `pipeshub_chat`\ninstead, which does the retrieval internally and grounds the answer in\ncitations.\n\nTypical uses:\n- Resolve a doc name / topic into a `recordId` for\n  `pipeshub_get_record_content` — step 1 of any full-document task\n  (summarize, extract, review, \"what does the doc say?\").\n- Resolve a filename / phrase into a `recordId` for\n  `pipeshub_download_record`.\n- Show the user a ranked list of matching files when they ask \"find /\n  search for X\".\n\nThe response is trimmed to one row per hit:\n`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }`.\nHighest `score` first; multiple hits may share the same `recordId`\n(different chunks of the same record)."
   },
   {
     "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": "Read a record's full parsed content by `recordId` — the only way to\nsee a document's COMPLETE text.\n\nUse it whenever the answer depends on a document's full content — any\ntask where missing a part could make the answer wrong: summarize / key\npoints / action items; extract or list ALL of something; check whether\nor where the doc mentions X; translate, rewrite, outline, or review the\ndoc; compare named docs (fetch each); any question scoped to one named\ndocument. `pipeshub_chat` cannot do these — it only sees a few\nretrieved passages, never the whole document. Get the `recordId` from\na `pipeshub_search` top hit or a chat citation.\n\nJudge by the user's INTENT, not their keywords: they need not say\n\"summarize\", \"key points\", or \"extract\". Reason about what a good\nanswer requires — if it would need the whole document (e.g. \"what's\nthis doc about?\", \"walk me through the report\", \"anything in here\nabout Y?\"), that is a full-content task, so call this tool.\n\nReturns a single `content` string: a short metadata header (title,\nsource, key fields, and a pre-generated summary) followed by the\nrecord's full parsed text — paragraphs, tables, and lists in reading\norder. For a record with no extractable content, `content` is the\nliteral `No record found`. Use `pipeshub_download_record` only when\nyou need the original file bytes."
+  },
   {
     "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."