@pipeshub-ai/mcp 2.3.3 → 2.4.1

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/mcp-server/tools/pipeshubSearch.d.ts

@@ -4,6 +4,7 @@ declare const args: {
     query: z.ZodString;
     limit: z.ZodOptional<z.ZodNumber>;
     apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kb: z.ZodOptional<z.ZodArray<z.ZodString>>;
 };
 export declare const tool$pipeshubSearch: ToolDefinition<typeof args>;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"pipeshubSearch.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubSearch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,QAAA,MAAM,IAAI;;;;CAYT,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,cAAc,CAAC,OAAO,IAAI,CA8E3D,CAAC"}
+{"version":3,"file":"pipeshubSearch.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubSearch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAa7C,QAAA,MAAM,IAAI;;;;;CAiBT,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,cAAc,CAAC,OAAO,IAAI,CAwF3D,CAAC"}

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

@@ -1,12 +1,17 @@
 import * as z from "zod";
 import { semanticSearchSearch } from "../../funcs/semanticSearchSearch.js";
-import { errorResult, jsonResult, readJson, trimSearchHit } from "./_helpers.js";
+import { errorResult, jsonResult, readJson, resolveSourceScope, searchFilters, trimSearchHit, } from "./_helpers.js";
+/** Matches the SDK request default (`src/models/semanticsearchrequest.ts`). */
+const DEFAULT_LIMIT = 10;
 const args = {
     query: z.string().min(1).describe("Natural language query. Vector search across the org's indexed records."),
-    limit: z.number().int().min(1).max(100).optional().describe("Max number of result chunks. Default 10. Use a small value (5–10) "
-        + "when the goal is to resolve a filename / topic into a recordId."),
-    apps: z.array(z.string()).optional().describe("Source-scoping ids — connector instance UUIDs and / or "
-        + "`knowledgeBase_<orgId>`. Get them from `pipeshub_sources`."),
+    limit: z.number().int().min(1).max(100).optional().describe("Number of results. Default 10. Use 5–10 when you only need a "
+        + "`recordId`."),
+    apps: z.array(z.string()).optional().describe("Connector ids to search (for example a Jira or Google Drive connection). "
+        + "Get them from `pipeshub_sources`, where `kind` is \"connector\". "
+        + "Collection ids go in `kb`, not here."),
+    kb: z.array(z.string()).optional().describe("Collection (knowledge base) ids to search. Get them from "
+        + "`pipeshub_sources`, where `kind` is \"knowledgeBase\"."),
 };
 export const tool$pipeshubSearch = {
     name: "pipeshub_search",
@@ -37,13 +42,12 @@ 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 blocks of the same record).
+By default it searches everything. To search only some sources, pass
+connector ids in \`apps\` and collection ids in \`kb\`.
 
-When presenting results to the user, link each record using its
-\`webUrl\` (when present).`,
+Each hit is one matching passage, best match first:
+\`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }\`.
+One record can appear in several hits. Link a record by its \`webUrl\`.`,
     scopes: ["read"],
     annotations: {
         title: "Semantic search",
@@ -54,10 +58,14 @@ When presenting results to the user, link each record using its
     },
     args,
     tool: async (client, args, ctx) => {
+        const limit = args.limit ?? DEFAULT_LIMIT;
+        // Each id is sent in the list the backend reads it from: a collection id
+        // in `apps` or a connector id in `kb` is dropped by the backend.
+        const { scope, notes } = await resolveSourceScope(client, args.apps, args.kb, { signal: ctx.signal });
         const [result] = await semanticSearchSearch(client, {
             query: args.query,
-            limit: args.limit,
-            filters: args.apps ? { apps: args.apps, kb: [] } : undefined,
+            limit,
+            filters: searchFilters(scope),
         }, { fetchOptions: { signal: ctx.signal } }).$inspect();
         if (!result.ok)
             return errorResult(result.error.message);
@@ -75,6 +83,7 @@ When presenting results to the user, link each record using its
                 mimeType: r.mimeType,
                 webUrl: r.webUrl,
             })),
+            ...(notes.length > 0 ? { notes } : {}),
         });
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"pipeshubSearch.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubSearch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAE3E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEjF,MAAM,IAAI,GAAG;IACX,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAC/B,yEAAyE,CAC1E;IACD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CACzD,oEAAoE;UAChE,iEAAiE,CACtE;IACD,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAC3C,yDAAyD;UACrD,4DAA4D,CACjE;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAgC;IAC9D,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAiCuB;IACzB,MAAM,EAAE,CAAC,MAAM,CAAC;IAChB,WAAW,EAAE;QACX,KAAK,EAAE,iBAAiB;QACxB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,IAAI;QACnB,YAAY,EAAE,KAAK;KACpB;IACD,IAAI;IACJ,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAChC,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,oBAAoB,CAAC,MAAM,EAAE;YAClD,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS;SAC7D,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,MAAM,MAAM,GAAG,MAAM,QAAQ,CAQ1B,MAAM,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC,MAAM,CAAC;QAErC,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC;QAC7C,OAAO,UAAU,CAAC;YAChB,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ;YAC/B,IAAI,EAAE,CAAC,EAAE,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC;YACjD,aAAa,EAAE,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;gBACjD,QAAQ,EAAE,CAAC,CAAC,IAAI;gBAChB,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,SAAS,EAAE,CAAC,CAAC,aAAa;gBAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,MAAM,EAAE,CAAC,CAAC,MAAM;aACjB,CAAC,CAAC;SACJ,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}
+{"version":3,"file":"pipeshubSearch.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubSearch.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"pipeshubSources.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubSources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAGzB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,QAAA,MAAM,IAAI;;;;;;CAOT,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,cAAc,CAAC,OAAO,IAAI,CAgF5D,CAAC"}
+{"version":3,"file":"pipeshubSources.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/pipeshubSources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ7C,QAAA,MAAM,IAAI;;;;;;CAOT,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,cAAc,CAAC,OAAO,IAAI,CAqE5D,CAAC"}

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

@@ -1,7 +1,6 @@
 import * as z from "zod";
-import { knowledgeHubGetKnowledgeHubRootNodes } from "../../funcs/knowledgeHubGetKnowledgeHubRootNodes.js";
 import { aiModelsProvidersGetAvailableModelsByType } from "../../funcs/aiModelsProvidersGetAvailableModelsByType.js";
-import { errorResult, jsonResult, readJson } from "./_helpers.js";
+import { errorResult, jsonResult, listAllSources, readJson, } from "./_helpers.js";
 const args = {
     include: z.array(z.enum(["sources", "llmModels", "embeddingModels"]))
         .optional()
@@ -14,20 +13,19 @@ export const tool$pipeshubSources = {
 
 Returns up to three sections:
 
-- \`sources\` — every connector instance the org has wired up plus the
-  synthetic \`knowledgeBase_<orgId>\` entry for the org's KB. Each
-  item's \`id\` is exactly the value to put in \`pipeshub_chat\`'s or
-  \`pipeshub_search\`'s \`apps\` filter.
+- \`sources\` — connectors (\`kind: "connector"\`) and collections
+  (\`kind: "knowledgeBase"\`). For \`pipeshub_search\` and
+  \`pipeshub_chat\`, put a connector \`id\` in \`apps\` and a collection
+  \`id\` in \`kb\`. \`sourcesTruncated: true\` means the list stopped at
+  1,000 sources.
 - \`llmModels\` — chat / generation models. Each item's \`modelKey\`
-  is the value to pass on \`pipeshub_chat\` / \`pipeshub_search\` as
-  \`modelKey\`. Pick \`isDefault: true\` unless the user asks for a
-  specific model.
+  is the value to pass on \`pipeshub_chat\` as \`modelKey\`. Pick
+  \`isDefault: true\` unless the user asks for a specific model.
 - \`embeddingModels\` — vector embedding models (only fetched when
   explicitly requested via \`include\`).
 
 Call this once at the start of a session and cache the result —
-sources and models change infrequently. \`sources\` and \`llmModels\`
-are returned by default; pass \`include\` to override.`,
+sources and models change infrequently.`,
     scopes: ["read"],
     annotations: {
         title: "List PipesHub sources and AI models",
@@ -44,22 +42,12 @@ are returned by default; pass \`include\` to override.`,
         const want = (s) => include.includes(s);
         const result = {};
         if (want("sources")) {
-            const [r] = await knowledgeHubGetKnowledgeHubRootNodes(client, {
-                page: 1,
-                limit: 200,
-            }, { fetchOptions }).$inspect();
-            if (!r.ok)
-                return errorResult(`sources: ${r.error.message}`);
-            const parsed = await readJson(r.value, "Knowledge base listing");
-            if (!parsed.ok)
-                return parsed.result;
-            result["sources"] = (parsed.value.items ?? []).map((n) => ({
-                id: n.id,
-                name: n.name,
-                kind: n.connector === "KB" ? "knowledgeBase" : "connector",
-                connector: n.connector,
-                hasChildren: n.hasChildren,
-            }));
+            const listed = await listAllSources(client, { signal: ctx.signal });
+            if (!listed.ok)
+                return listed.result;
+            result["sources"] = listed.sources;
+            if (listed.truncated)
+                result["sourcesTruncated"] = true;
         }
         for (const [key, modelType] of [
             ["llmModels", "llm"],

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

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

package/esm/tool-names.js

@@ -2,7 +2,7 @@
 export const toolNames = [
     {
         "name": "pipeshub_sources",
-        "description": "Discover available chat sources and AI models in one call.\n\nReturns up to three sections:\n\n- `sources` — every connector instance the org has wired up plus the\n  synthetic `knowledgeBase_<orgId>` entry for the org's KB. Each\n  item's `id` is exactly the value to put in `pipeshub_chat`'s or\n  `pipeshub_search`'s `apps` filter.\n- `llmModels` — chat / generation models. Each item's `modelKey`\n  is the value to pass on `pipeshub_chat` / `pipeshub_search` as\n  `modelKey`. Pick `isDefault: true` unless the user asks for a\n  specific model.\n- `embeddingModels` — vector embedding models (only fetched when\n  explicitly requested via `include`).\n\nCall this once at the start of a session and cache the result —\nsources and models change infrequently. `sources` and `llmModels`\nare returned by default; pass `include` to override."
+        "description": "Discover available chat sources and AI models in one call.\n\nReturns up to three sections:\n\n- `sources` — connectors (`kind: \"connector\"`) and collections\n  (`kind: \"knowledgeBase\"`). For `pipeshub_search` and\n  `pipeshub_chat`, put a connector `id` in `apps` and a collection\n  `id` in `kb`. `sourcesTruncated: true` means the list stopped at\n  1,000 sources.\n- `llmModels` — chat / generation models. Each item's `modelKey`\n  is the value to pass on `pipeshub_chat` as `modelKey`. Pick\n  `isDefault: true` unless the user asks for a specific model.\n- `embeddingModels` — vector embedding models (only fetched when\n  explicitly requested via `include`).\n\nCall this once at the start of a session and cache the result —\nsources and models change infrequently."
     },
     {
         "name": "pipeshub_chat",
@@ -10,11 +10,11 @@ export const toolNames = [
     },
     {
         "name": "pipeshub_search",
-        "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\nNot for structural questions — what is under this epic, which pages are\nin this space, what links to this ticket. Ranking by content cannot show\nhow records relate; use `pipeshub_get_record_content` `mode:\"navigate\"`.\n\n**A ranked sample, never a complete list.** Hits are the top-scoring\nblocks from the best-matching records — not all blocks of any record, and\nnot every record that matches. Never count them to answer \"how many\" /\n\"all\" / \"every\"; navigate the record group instead, which reports its\nreal total.\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 blocks of the same record).\n\nWhen presenting results to the user, link each record using its\n`webUrl` (when present)."
+        "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\nNot for structural questions — what is under this epic, which pages are\nin this space, what links to this ticket. Ranking by content cannot show\nhow records relate; use `pipeshub_get_record_content` `mode:\"navigate\"`.\n\n**A ranked sample, never a complete list.** Hits are the top-scoring\nblocks from the best-matching records — not all blocks of any record, and\nnot every record that matches. Never count them to answer \"how many\" /\n\"all\" / \"every\"; navigate the record group instead, which reports its\nreal total.\n\nBy default it searches everything. To search only some sources, pass\nconnector ids in `apps` and collection ids in `kb`.\n\nEach hit is one matching passage, best match first:\n`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }`.\nOne record can appear in several hits. Link a record by its `webUrl`."
     },
     {
         "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,80BAA80B;KAC91B;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,w+EAAw+E;KACx/E;IACD;QACE,MAAM,EAAE,iBAAiB;QACzB,aAAa,EAAE,uiDAAuiD;KACvjD;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.3.3",
+  "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.3.3
+ARG PIPESHUB_CLI_VERSION=2.4.1
 RUN npm install -g "@pipeshub-ai/mcp@${PIPESHUB_CLI_VERSION}" \
  && pipeshub --help >/dev/null
 

package/qm/sandbox/skills/pipeshub/SKILL.md

@@ -35,6 +35,7 @@ fresh sandbox before the install.
 | "Find the file called security-review.pdf" | `pipeshub search "security-review"` |
 | "Download that file" | `pipeshub get <recordId> --out <path>` |
 | First call of a session | `pipeshub sources` (cache the ids) |
+| "Search only the <X> collection / connector" | `pipeshub sources`, then `pipeshub search "..." --kb <id>` for `kind: knowledgeBase`, or `--app <id>` for `kind: connector` |
 
 `ask` sees a few retrieved passages, not whole documents. For anything that
 needs a document's full text — summarizing it, quoting it exactly — locate it

package/src/cli/commands.ts

@@ -191,9 +191,11 @@ export async function search(
   query: string,
   limit: number,
   apps: string[],
+  kb: string[],
 ): Promise<Outcome> {
   const args: Record<string, unknown> = { query, limit };
   if (apps.length > 0) args["apps"] = apps;
+  if (kb.length > 0) args["kb"] = kb;
   const raw = decodeToolJson(await callTool(ctx, "pipeshub_search", args));
   const obj = asRecord(raw);
 
@@ -229,6 +231,7 @@ export async function search(
       query,
       contentWarning: CONTENT_WARNING,
       hitCount: hits.length,
+      notes: arr(obj["notes"]).filter((n): n is string => typeof n === "string"),
       hits,
       records,
     },

package/src/cli/pipeshub.ts

@@ -38,7 +38,7 @@ COMMANDS
   auth status                 show connection, user, org, scopes, expiry
   auth connect-help           print the keychain setup steps
   init-qm <dir>               scaffold the QM deployment-layer bundle (admin)
-  sources                     list searchable sources (ids for --app)
+  sources                     list searchable sources (ids for --app / --kb)
   search <query>              locate records
   ask <question>              ask a grounded question; returns citations
   get <recordId>              fetch a record's content
@@ -47,8 +47,9 @@ COMMANDS
 OPTIONS
   --json                      JSON output (default)
   --text                      human-readable output where available
-  --limit <n>                 search: max results (default 10)
-  --app <id>                  search: restrict to a source id (repeatable)
+  --limit <n>                 search: result limit, 1-100 (default 10)
+  --app <id>                  search: restrict to a connector id (repeatable)
+  --kb <id>                   search: restrict to a collection id (repeatable)
   --conversation <id>         ask: continue an existing conversation
   --mode <internal|web>       ask: retrieval strategy (default internal)
   --as <format>               get: server-side conversion, e.g. pdf
@@ -73,6 +74,7 @@ interface Flags {
   json: boolean;
   limit: number;
   apps: string[];
+  kb: string[];
   conversation: string | null;
   mode: string;
   as: string | null;
@@ -87,6 +89,7 @@ function parseFlags(argv: string[]): { positional: string[]; flags: Flags } {
     json: true,
     limit: 10,
     apps: [],
+    kb: [],
     conversation: null,
     mode: "internal",
     as: null,
@@ -114,6 +117,7 @@ function parseFlags(argv: string[]): { positional: string[]; flags: Flags } {
       case "--force": flags.force = true; break;
       case "--limit": flags.limit = Number(needValue(a, argv[++i])); break;
       case "--app": flags.apps.push(needValue(a, argv[++i])); break;
+      case "--kb": flags.kb.push(needValue(a, argv[++i])); break;
       case "--conversation": flags.conversation = needValue(a, argv[++i]); break;
       case "--mode": flags.mode = needValue(a, argv[++i]); break;
       case "--as": flags.as = needValue(a, argv[++i]); break;
@@ -127,8 +131,10 @@ function parseFlags(argv: string[]): { positional: string[]; flags: Flags } {
         positional.push(a);
     }
   }
-  if (!Number.isFinite(flags.limit) || flags.limit <= 0) {
-    throw new CliError("--limit must be a positive number", EXIT.USAGE);
+  // The tool rejects anything outside 1-100; catching it here makes it a usage
+  // error (exit 2) instead of a generic tool failure.
+  if (!Number.isInteger(flags.limit) || flags.limit < 1 || flags.limit > 100) {
+    throw new CliError("--limit must be a whole number from 1 to 100", EXIT.USAGE);
   }
   if (!Number.isFinite(flags.maxChars) || flags.maxChars <= 0) {
     throw new CliError("--max-chars must be a positive number", EXIT.USAGE);
@@ -290,7 +296,7 @@ async function run(argv: string[]): Promise<number> {
     case "search": {
       const query = positional.slice(1).join(" ").trim();
       if (query === "") throw new CliError("search requires a query", EXIT.USAGE);
-      outcome = await search(ctx, query, flags.limit, flags.apps);
+      outcome = await search(ctx, query, flags.limit, flags.apps, flags.kb);
       break;
     }
     case "ask": {

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
@@ -97,8 +99,9 @@ external ID → \`mode:"lookup"\` FIRST. It returns that record's metadata (for
 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
+For search, pass a connector id from \`pipeshub_sources\` as \`apps: ["<id>"]\`
+and a collection id (\`kind: "knowledgeBase"\`) as \`kb: ["<id>"]\`. Any source
+id works as \`nodeId\` to navigate. Navigate and lookup end in a \`Next:\` line
 naming the exact follow-up call — follow it.
 
 ## Agents