@pipeshub-ai/mcp 2.4.0 → 2.4.1

package/esm/mcp-server/instructions.d.ts

@@ -1,2 +1,2 @@
-export declare const PIPESHUB_INSTRUCTIONS = "# PipesHub MCP \u2014 instructions for the LLM\n\nPipesHub is the user's workplace AI platform. It indexes their documents,\nknowledge base content, and connector sources (Drive, Box, Confluence,\nSlack, Jira, Gmail, ...). When in doubt, the answer is in PipesHub.\n\n## Full-document tasks: `pipeshub_search` \u2192 `pipeshub_get_record_content`\n\n`pipeshub_chat` answers from a handful of retrieved passages \u2014 it never\nreads a whole document. Whenever the task depends on a document's\nCOMPLETE content, fetch the document itself:\n\n1. `pipeshub_search` with the document's name / topic.\n2. Take the top hit's `recordId`.\n3. `pipeshub_get_record_content`, and answer from the returned content.\n\nTasks that need this path \u2014 anything where missing part of the document\ncould make the answer wrong:\n\n- Summarize / TL;DR / key points / takeaways / action items of a doc.\n- Extract or list ALL of something (dates, owners, requirements, ...).\n- Check whether / where a doc mentions something.\n- Translate, rewrite, outline, review, or reformat a doc.\n- Compare named docs (fetch each `recordId`).\n- Any question explicitly scoped to ONE named document \u2014 chat retrieval\n  cannot be restricted to a single record.\n\n## Default tool: `pipeshub_chat`\n\n**Use `pipeshub_chat` for any question that could plausibly be answered\nby the user's PipesHub-indexed data** and is not a full-document task:\n\n- A question that may span several documents, or where you don't yet\n  know which record holds the answer (e.g. \"what did Aashil say about\n  onboarding?\").\n- Anything about company / org policies, processes, decisions, or\n  history (e.g. \"what's our vacation policy?\", \"who owns the auth\n  service?\").\n- Anything explicitly mentioning PipesHub itself, or its sources\n  (Drive / Box / Confluence / Slack / Gmail / Jira / etc.) when the\n  user has those connected.\n- Open-ended \"what do we know about X\" questions where the answer\n  likely lives in the org's documents.\n\nDo NOT answer those from your own knowledge \u2014 `pipeshub_chat` grounds\nthe answer in the user's actual indexed content and returns citations\nthe user can verify.\n\n## When to use the other tools\n\n- `pipeshub_search` \u2014 locate a document by name or topic and resolve it\n  to a `recordId`. To read or summarize one specific document, search,\n  then pass the top hit's `recordId` to `pipeshub_get_record_content`.\n- `pipeshub_download_record` \u2014 when the user wants the actual file\n  bytes (download, attach, open). Get the `recordId` either from\n  citations on a prior `pipeshub_chat` response or from\n  `pipeshub_search`.\n- `pipeshub_get_record_content` \u2014 when you need a record's full parsed\n  content (returned as a single `content` string: metadata header plus\n  the document's text) without downloading the original file. Prefer this\n  over download when the question is about what the record says.\n- `pipeshub_directory` \u2014 people, groups, teams, and `whoami` lookups.\n  Not for documents.\n- `pipeshub_sources` \u2014 call once at the start of a session to discover\n  which connectors / KB / models are available, then cache the result.\n- `pipeshub_agents` \u2014 list the org's configured **agents** (specialized\n  assistants with their own prompt, tools, and knowledge scope).\n\n## Knowledge Sources\n\nA source (an app connector or a KB) holds record groups (a project, space,\ndrive, folder), which hold records (one ticket, page, file). Records nest \u2014\nan epic over its stories, a page over its child pages.\n\n**Every tool returns metadata or content.**\n\n- `pipeshub_search` / `pipeshub_chat` \u2014 content, but only a ranked sample of\n  blocks: never all blocks of a record, never every record that matches, never\n  a complete list of what exists.\n- `mode:\"lookup\"` and `mode:\"navigate\"` \u2014 metadata: recordIds, fields, and\n  structure. No document text. `mode:\"content\"` \u2014 one whole record.\n\n**Combining them.** Search finds a starting point by wording; navigate on a\n`recordId` reveals what search structurally cannot \u2014 siblings, children,\nlinked records, and the group's total count. For a question that must be\nexhaustive (\"all\", \"how many\", \"every\"), do NOT count search hits or trust a\nchat answer: navigate the record group, which reports the real total. For a\nrecord's siblings, navigate its parent \u2014 take the id from the `Path` line.\n\n**A named record** \u2014 an issue key, a Confluence / Drive / Slack link, an\nexternal ID \u2192 `mode:\"lookup\"` FIRST. It returns that record's metadata (for a\nticket: status, assignee, priority, dates) plus its `recordId`, which often\nanswers the question outright. Never guess a `recordId`.\n\nFor search, pass a connector id from `pipeshub_sources` as `apps: [\"<id>\"]`\nand a collection id (`kind: \"knowledgeBase\"`) as `kb: [\"<id>\"]`. Any source\nid works as `nodeId` to navigate. Navigate and lookup end in a `Next:` line\nnaming the exact follow-up call \u2014 follow it.\n\n## Agents\n\nSome orgs configure **agents** for specific jobs (e.g. a Slack messenger, a\nJira ticket creator, a Salesforce CRM updater). To run a turn against an\nagent, call `pipeshub_chat` with its `agentId` (from `pipeshub_agents`)\n\u2014 optionally with an agent `chatMode` (`auto` by default, or `quick` /\n`verification` / `deep`). Keep passing the same `agentId` plus the\nreturned `conversationId` on follow-up turns.\n\n**When to route to an agent vs plain chat:**\n- The user names a system/action that maps to an agent (e.g. \"post to\n  Slack\", \"create a Jira ticket\", \"update the Salesforce deal\") \u2192 call\n  `pipeshub_agents`, pick the matching agent, and use it.\n- Plain question about the org's knowledge or the public web \u2192 just use\n  `pipeshub_chat` (no `agentId`) with `internal_search` or `web_search`.\n\n**If you are unsure which agent or route fits the request**, call\n`pipeshub_agents` FIRST and read the returned names/descriptions, then\neither pick the best match or present the list to the user and let them\nchoose. Do NOT guess an agent blindly, and do NOT refuse \u2014 list the agents\nand decide from real data. The list may be empty (no agents configured),\nin which case fall back to plain `pipeshub_chat`.\n\n## Conversation lifecycle\n\n`pipeshub_chat` is a single tool that handles both starting and\ncontinuing conversations (plain or with an `agentId`). On the first turn\nomit `conversationId`; on every subsequent turn pass back the\n`conversationId` returned by the previous call (along with the same\n`agentId` if you used one). Server-side context is preserved \u2014 do NOT\nreplay prior messages. Only start a fresh conversation when the user\nexplicitly asks to clear context.\n";
+export declare const PIPESHUB_INSTRUCTIONS = "# PipesHub MCP \u2014 instructions for the LLM\n\nPipesHub is the user's workplace AI platform. It indexes their documents,\nknowledge base content, and connector sources (Drive, Box, Confluence,\nSlack, Jira, Gmail, ...). When in doubt, the answer is in PipesHub.\n\n## Full-document tasks: `pipeshub_search` \u2192 `pipeshub_get_record_content`\n\n`pipeshub_chat` answers from a handful of retrieved passages \u2014 it never\nreads a whole document. Whenever the task depends on a document's\nCOMPLETE content, fetch the document itself:\n\n1. `pipeshub_search` with the document's name / topic.\n2. Take the top hit's `recordId`.\n3. `pipeshub_get_record_content`, and answer from the returned content.\n\nTasks that need this path \u2014 anything where missing part of the document\ncould make the answer wrong:\n\n- Summarize / TL;DR / key points / takeaways / action items of a doc.\n- Extract or list ALL of something (dates, owners, requirements, ...).\n- Check whether / where a doc mentions something.\n- Translate, rewrite, outline, review, or reformat a doc.\n- Compare named docs (fetch each `recordId`).\n- Any question explicitly scoped to ONE named document \u2014 chat retrieval\n  cannot be restricted to a single record.\n\n## Default tool: `pipeshub_chat`\n\n**Use `pipeshub_chat` for any question that could plausibly be answered\nby the user's PipesHub-indexed data** and is not a full-document task:\n\n- A question that may span several documents, or where you don't yet\n  know which record holds the answer (e.g. \"what did Aashil say about\n  onboarding?\").\n- Anything about company / org policies, processes, decisions, or\n  history (e.g. \"what's our vacation policy?\", \"who owns the auth\n  service?\").\n- Anything explicitly mentioning PipesHub itself, or its sources\n  (Drive / Box / Confluence / Slack / Gmail / Jira / etc.) when the\n  user has those connected.\n- Open-ended \"what do we know about X\" questions where the answer\n  likely lives in the org's documents.\n\nDo NOT answer those from your own knowledge \u2014 `pipeshub_chat` grounds\nthe answer in the user's actual indexed content and returns citations\nthe user can verify.\n\n## When to use the other tools\n\n- `pipeshub_search` \u2014 locate a document by name or topic and resolve it\n  to a `recordId`. To read or summarize one specific document, search,\n  then pass the top hit's `recordId` to `pipeshub_get_record_content`.\n- `pipeshub_download_record` \u2014 when the user wants the file as stored\n  (download, attach, open). Never to read or summarize \u2014 that is\n  `pipeshub_get_record_content` `mode:\"content\"`, which returns\n  parsed text with a metadata header. Get the `recordId` from a chat\n  citation or from `pipeshub_search`. `convertTo` is only\n  `application/pdf`.\n- `pipeshub_get_record_content` \u2014 when you need a record's full parsed\n  content (returned as a single `content` string: metadata header plus\n  the document's text) without downloading the original file. Prefer this\n  over download when the question is about what the record says.\n- `pipeshub_directory` \u2014 people, groups, teams, and `whoami` lookups.\n  Not for documents.\n- `pipeshub_sources` \u2014 call once at the start of a session to discover\n  which connectors / KB / models are available, then cache the result.\n- `pipeshub_agents` \u2014 list the org's configured **agents** (specialized\n  assistants with their own prompt, tools, and knowledge scope).\n\n## Knowledge Sources\n\nA source (an app connector or a KB) holds record groups (a project, space,\ndrive, folder), which hold records (one ticket, page, file). Records nest \u2014\nan epic over its stories, a page over its child pages.\n\n**Every tool returns metadata or content.**\n\n- `pipeshub_search` / `pipeshub_chat` \u2014 content, but only a ranked sample of\n  blocks: never all blocks of a record, never every record that matches, never\n  a complete list of what exists.\n- `mode:\"lookup\"` and `mode:\"navigate\"` \u2014 metadata: recordIds, fields, and\n  structure. No document text. `mode:\"content\"` \u2014 one whole record.\n\n**Combining them.** Search finds a starting point by wording; navigate on a\n`recordId` reveals what search structurally cannot \u2014 siblings, children,\nlinked records, and the group's total count. For a question that must be\nexhaustive (\"all\", \"how many\", \"every\"), do NOT count search hits or trust a\nchat answer: navigate the record group, which reports the real total. For a\nrecord's siblings, navigate its parent \u2014 take the id from the `Path` line.\n\n**A named record** \u2014 an issue key, a Confluence / Drive / Slack link, an\nexternal ID \u2192 `mode:\"lookup\"` FIRST. It returns that record's metadata (for a\nticket: status, assignee, priority, dates) plus its `recordId`, which often\nanswers the question outright. Never guess a `recordId`.\n\nFor search, pass a connector id from `pipeshub_sources` as `apps: [\"<id>\"]`\nand a collection id (`kind: \"knowledgeBase\"`) as `kb: [\"<id>\"]`. Any source\nid works as `nodeId` to navigate. Navigate and lookup end in a `Next:` line\nnaming the exact follow-up call \u2014 follow it.\n\n## Agents\n\nSome orgs configure **agents** for specific jobs (e.g. a Slack messenger, a\nJira ticket creator, a Salesforce CRM updater). To run a turn against an\nagent, call `pipeshub_chat` with its `agentId` (from `pipeshub_agents`)\n\u2014 optionally with an agent `chatMode` (`auto` by default, or `quick` /\n`verification` / `deep`). Keep passing the same `agentId` plus the\nreturned `conversationId` on follow-up turns.\n\n**When to route to an agent vs plain chat:**\n- The user names a system/action that maps to an agent (e.g. \"post to\n  Slack\", \"create a Jira ticket\", \"update the Salesforce deal\") \u2192 call\n  `pipeshub_agents`, pick the matching agent, and use it.\n- Plain question about the org's knowledge or the public web \u2192 just use\n  `pipeshub_chat` (no `agentId`) with `internal_search` or `web_search`.\n\n**If you are unsure which agent or route fits the request**, call\n`pipeshub_agents` FIRST and read the returned names/descriptions, then\neither pick the best match or present the list to the user and let them\nchoose. Do NOT guess an agent blindly, and do NOT refuse \u2014 list the agents\nand decide from real data. The list may be empty (no agents configured),\nin which case fall back to plain `pipeshub_chat`.\n\n## Conversation lifecycle\n\n`pipeshub_chat` is a single tool that handles both starting and\ncontinuing conversations (plain or with an `agentId`). On the first turn\nomit `conversationId`; on every subsequent turn pass back the\n`conversationId` returned by the previous call (along with the same\n`agentId` if you used one). Server-side context is preserved \u2014 do NOT\nreplay prior messages. Only start a fresh conversation when the user\nexplicitly asks to clear context.\n";
 //# sourceMappingURL=instructions.d.ts.map

package/esm/mcp-server/instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/mcp-server/instructions.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,qBAAqB,upNAmIjC,CAAC"}
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/mcp-server/instructions.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,qBAAqB,0yNAqIjC,CAAC"}

package/esm/mcp-server/instructions.js

@@ -55,10 +55,12 @@ the user can verify.
 - \`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_download_record\` — when the user wants the file as stored
+  (download, attach, open). Never to read or summarize — that is
+  \`pipeshub_get_record_content\` \`mode:"content"\`, which returns
+  parsed text with a metadata header. Get the \`recordId\` from a chat
+  citation or from \`pipeshub_search\`. \`convertTo\` is only
+  \`application/pdf\`.
 - \`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

package/esm/mcp-server/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/mcp-server/instructions.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,sEAAsE;AACtE,sEAAsE;AACtE,gEAAgE;AAEhE,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmIpC,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/mcp-server/instructions.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,sEAAsE;AACtE,sEAAsE;AACtE,gEAAgE;AAEhE,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqIpC,CAAC"}

package/esm/mcp-server/tools/pipeshubDownloadRecord.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeshubDownloadRecord.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubDownloadRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAgB,cAAc,EAAE,MAAM,aAAa,CAAC;AAG3D,QAAA,MAAM,IAAI;;;CAUT,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,cAAc,CAAC,OAAO,IAAI,CAiCnE,CAAC"}
+{"version":3,"file":"pipeshubDownloadRecord.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubDownloadRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAgB,cAAc,EAAE,MAAM,aAAa,CAAC;AAG3D,QAAA,MAAM,IAAI;;;CAaT,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,cAAc,CAAC,OAAO,IAAI,CAiCnE,CAAC"}

package/esm/mcp-server/tools/pipeshubDownloadRecord.js

@@ -6,23 +6,26 @@ 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."),
-    convertTo: z.string().optional().describe("Optional server-side format conversion target (e.g. `pdf`). When "
-        + "omitted, the original file bytes are returned."),
+    convertTo: z.string().optional().describe("The only conversion target connectors honour is `application/pdf` "
+        + "(the MIME type, not `pdf`). A bare `pdf` is ignored and the "
+        + "original file is returned with no error. Omit for the file as "
+        + "stored. Does not parse the document — use "
+        + "`pipeshub_get_record_content` `mode:\"content\"` for that."),
 };
 export const tool$pipeshubDownloadRecord = {
     name: "pipeshub_download_record",
-    description: `Stream the binary content of a single record from PipesHub.
+    description: `Download the file as stored for one record — not PipesHub's parsed
+content, metadata header, or summary.
 
-Typical sources for the \`recordId\`:
-- A chat citation:
-  \`pipeshub_chat\` response → \`citations[*].recordId\`.
-- A search result:
-  \`pipeshub_search\` response → \`hits[*].recordId\` /
-  \`uniqueRecords[*].recordId\`.
+Use this when the user wants the file itself (download, attach, open).
+Get \`recordId\` from a chat citation or a \`pipeshub_search\` hit.
 
-Response \`Content-Type\` is forwarded from the upstream service —
-\`application/pdf\`, \`application/octet-stream\`, etc. Binary content is
-returned base64-encoded; text content is returned inline.`,
+Do not use this to read, summarize, or answer "what does this doc
+say?" regardless of format. That is \`pipeshub_get_record_content\`
+\`mode:"content"\`. Text formats come back inline; images, audio, and
+binary as base64.
+
+\`convertTo\` accepts only \`application/pdf\`; anything else is ignored.`,
     scopes: ["read"],
     annotations: {
         title: "Download a document by record id",

package/esm/mcp-server/tools/pipeshubDownloadRecord.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeshubDownloadRecord.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubDownloadRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,EAAE,YAAY,EAAkB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,IAAI,GAAG;IACX,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAClC,sEAAsE;UAClE,mEAAmE;UACnE,qEAAqE,CAC1E;IACD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CACvC,mEAAmE;UAC/D,gDAAgD,CACrD;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAgC;IACtE,IAAI,EAAE,0BAA0B;IAChC,WAAW,EACT;;;;;;;;;;;0DAWsD;IACxD,MAAM,EAAE,CAAC,MAAM,CAAC;IAChB,WAAW,EAAE;QACX,KAAK,EAAE,kCAAkC;QACzC,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;QACpB,YAAY,EAAE,IAAI;KACnB;IACD,IAAI;IACJ,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAChC,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,yBAAyB,CAAC,MAAM,EAAE;YACvD,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,EAAE,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;QACxD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEzD,OAAO,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;CACF,CAAC"}
+{"version":3,"file":"pipeshubDownloadRecord.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubDownloadRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,EAAE,YAAY,EAAkB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,IAAI,GAAG;IACX,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAClC,sEAAsE;UAClE,mEAAmE;UACnE,qEAAqE,CAC1E;IACD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CACvC,oEAAoE;UAChE,8DAA8D;UAC9D,gEAAgE;UAChE,4CAA4C;UAC5C,4DAA4D,CACjE;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAgC;IACtE,IAAI,EAAE,0BAA0B;IAChC,WAAW,EACT;;;;;;;;;;;0EAWsE;IACxE,MAAM,EAAE,CAAC,MAAM,CAAC;IAChB,WAAW,EAAE;QACX,KAAK,EAAE,kCAAkC;QACzC,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;QACpB,YAAY,EAAE,IAAI;KACnB;IACD,IAAI;IACJ,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAChC,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,yBAAyB,CAAC,MAAM,EAAE;YACvD,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,EAAE,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;QACxD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEzD,OAAO,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;CACF,CAAC"}

package/esm/tool-names.js

@@ -14,7 +14,7 @@ export const toolNames = [
     },
     {
         "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."
+        "description": "Download the file as stored for one record — not PipesHub's parsed\ncontent, metadata header, or summary.\n\nUse this when the user wants the file itself (download, attach, open).\nGet `recordId` from a chat citation or a `pipeshub_search` hit.\n\nDo not use this to read, summarize, or answer \"what does this doc\nsay?\" regardless of format. That is `pipeshub_get_record_content`\n`mode:\"content\"`. Text formats come back inline; images, audio, and\nbinary as base64.\n\n`convertTo` accepts only `application/pdf`; anything else is ignored."
     },
     {
         "name": "pipeshub_get_record_content",

package/esm/tool-names.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-names.js","sourceRoot":"","sources":["../src/tool-names.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,MAAM,CAAC,MAAM,SAAS,GAAgD;IACpE;QACE,MAAM,EAAE,kBAAkB;QAC1B,aAAa,EAAE,4wBAA4wB;KAC5xB;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,w+EAAw+E;KACx/E;IACD;QACE,MAAM,EAAE,iBAAiB;QACzB,aAAa,EAAE,0iDAA0iD;KAC1jD;IACD;QACE,MAAM,EAAE,0BAA0B;QAClC,aAAa,EAAE,8dAA8d;KAC9e;IACD;QACE,MAAM,EAAE,6BAA6B;QACrC,aAAa,EAAE,06HAA06H;KAC17H;IACD;QACE,MAAM,EAAE,oBAAoB;QAC5B,aAAa,EAAE,uqBAAuqB;KACvrB;IACD;QACE,MAAM,EAAE,iBAAiB;QACzB,aAAa,EAAE,82CAA82C;KAC93C;CACF,CAAC"}
+{"version":3,"file":"tool-names.js","sourceRoot":"","sources":["../src/tool-names.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,MAAM,CAAC,MAAM,SAAS,GAAgD;IACpE;QACE,MAAM,EAAE,kBAAkB;QAC1B,aAAa,EAAE,4wBAA4wB;KAC5xB;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,w+EAAw+E;KACx/E;IACD;QACE,MAAM,EAAE,iBAAiB;QACzB,aAAa,EAAE,0iDAA0iD;KAC1jD;IACD;QACE,MAAM,EAAE,0BAA0B;QAClC,aAAa,EAAE,miBAAmiB;KACnjB;IACD;QACE,MAAM,EAAE,6BAA6B;QACrC,aAAa,EAAE,06HAA06H;KAC17H;IACD;QACE,MAAM,EAAE,oBAAoB;QAC5B,aAAa,EAAE,uqBAAuqB;KACvrB;IACD;QACE,MAAM,EAAE,iBAAiB;QACzB,aAAa,EAAE,82CAA82C;KAC93C;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipeshub-ai/mcp",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "mcpName": "io.github.pipeshub-ai/mcp",
   "author": "Pipeshub",
   "type": "module",

package/qm/sandbox/Dockerfile

@@ -13,7 +13,7 @@ FROM ghcr.io/yc-software/qm/sandbox-base
 # separate package. Pin the exact version: the sandbox image and the PipesHub
 # instance's MCP tool surface need to stay compatible, and an unpinned install
 # turns a remote release into a silent change in agent behaviour.
-ARG PIPESHUB_CLI_VERSION=2.4.0
+ARG PIPESHUB_CLI_VERSION=2.4.1
 RUN npm install -g "@pipeshub-ai/mcp@${PIPESHUB_CLI_VERSION}" \
  && pipeshub --help >/dev/null
 

package/src/mcp-server/instructions.ts

@@ -56,10 +56,12 @@ the user can verify.
 - \`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_download_record\` — when the user wants the file as stored
+  (download, attach, open). Never to read or summarize — that is
+  \`pipeshub_get_record_content\` \`mode:"content"\`, which returns
+  parsed text with a metadata header. Get the \`recordId\` from a chat
+  citation or from \`pipeshub_search\`. \`convertTo\` is only
+  \`application/pdf\`.
 - \`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

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

@@ -10,26 +10,29 @@ const args = {
       + "citation (`citations[*].recordId`) or from a `pipeshub_search` hit.",
   ),
   convertTo: z.string().optional().describe(
-    "Optional server-side format conversion target (e.g. `pdf`). When "
-      + "omitted, the original file bytes are returned.",
+    "The only conversion target connectors honour is `application/pdf` "
+      + "(the MIME type, not `pdf`). A bare `pdf` is ignored and the "
+      + "original file is returned with no error. Omit for the file as "
+      + "stored. Does not parse the document — use "
+      + "`pipeshub_get_record_content` `mode:\"content\"` for that.",
   ),
 };
 
 export const tool$pipeshubDownloadRecord: ToolDefinition<typeof args> = {
   name: "pipeshub_download_record",
   description:
-    `Stream the binary content of a single record from PipesHub.
+    `Download the file as stored for one record — not PipesHub's parsed
+content, metadata header, or summary.
 
-Typical sources for the \`recordId\`:
-- A chat citation:
-  \`pipeshub_chat\` response → \`citations[*].recordId\`.
-- A search result:
-  \`pipeshub_search\` response → \`hits[*].recordId\` /
-  \`uniqueRecords[*].recordId\`.
+Use this when the user wants the file itself (download, attach, open).
+Get \`recordId\` from a chat citation or a \`pipeshub_search\` hit.
 
-Response \`Content-Type\` is forwarded from the upstream service —
-\`application/pdf\`, \`application/octet-stream\`, etc. Binary content is
-returned base64-encoded; text content is returned inline.`,
+Do not use this to read, summarize, or answer "what does this doc
+say?" regardless of format. That is \`pipeshub_get_record_content\`
+\`mode:"content"\`. Text formats come back inline; images, audio, and
+binary as base64.
+
+\`convertTo\` accepts only \`application/pdf\`; anything else is ignored.`,
   scopes: ["read"],
   annotations: {
     title: "Download a document by record id",

package/src/tool-names.ts

@@ -14,7 +14,7 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "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."
+    "description": "Download the file as stored for one record — not PipesHub's parsed\ncontent, metadata header, or summary.\n\nUse this when the user wants the file itself (download, attach, open).\nGet `recordId` from a chat citation or a `pipeshub_search` hit.\n\nDo not use this to read, summarize, or answer \"what does this doc\nsay?\" regardless of format. That is `pipeshub_get_record_content`\n`mode:\"content\"`. Text formats come back inline; images, audio, and\nbinary as base64.\n\n`convertTo` accepts only `application/pdf`; anything else is ignored."
   },
   {
     "name": "pipeshub_get_record_content",