@pipeshub-ai/mcp 2.1.0 → 2.3.0

package/src/funcs/connectorGetRecordContent.ts

@@ -0,0 +1,179 @@
+/*
+ * Adapted from Speakeasy-generated connectorGetRecordContent.
+ */
+
+import { PipeshubCore } from "../core.js";
+import { encodeSimple } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  GetRecordContentRequest,
+  GetRecordContentRequest$zodSchema,
+} from "../models/getrecordcontentop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Get a record's full parsed content and metadata
+ *
+ * @remarks
+ * Retrieve the full parsed content and metadata of a single record —
+ * the same content PipesHub's own RAG/chat pipeline uses to answer
+ * questions, returned directly instead of via chat.
+ *
+ * **When to use this vs. the other record endpoints:**
+ * - `GET /knowledgeBase/record/{recordId}` returns metadata only
+ *   (name, type, indexing status, size) — no content.
+ * - `GET /knowledgeBase/stream/record/{recordId}` returns the original,
+ *   unparsed file bytes — use it to download/open the source file.
+ * - **This endpoint** returns the record's full parsed content as a
+ *   single plain-text `content` string (a metadata header, then the
+ *   block/table text in reading order) — use it when you need the
+ *   record's actual textual/tabular content without downloading and
+ *   re-parsing the original file yourself.
+ *
+ * **Typical flow:** obtain a `recordId` from a `pipeshub_search` hit or
+ * a chat citation's `recordId`, then call this endpoint to read the
+ * full content when the search snippet or citation excerpt isn't
+ * enough to answer the question.
+ *
+ * **Permission scoping:**
+ *
+ * The requesting user/token must have access to the record; access is
+ * verified via the knowledge graph before content is returned — a
+ * caller with a valid scope but no access to this specific record gets
+ * a `403`.
+ *
+ * If set, this operation will use either {@link Security.bearerAuth} or {@link Security.oauth2} from the global security.
+ */
+export function connectorGetRecordContent(
+  client$: PipeshubCore,
+  request: GetRecordContentRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: PipeshubCore,
+  request: GetRecordContentRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    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,
+  }];
+}

package/src/funcs/connectorLookupRecordByIdentifier.ts

@@ -0,0 +1,200 @@
+/*
+ * Adapted from Speakeasy-generated connectorLookupRecordByIdentifier.
+ */
+
+import { PipeshubCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  LookupRecordByIdentifierRequest,
+  LookupRecordByIdentifierRequest$zodSchema,
+} from "../models/lookuprecordbyidentifierop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Resolve a URL, issue key or external ID to a Record ID
+ *
+ * @remarks
+ * Turn an external reference into the matching PipesHub record. Accepts a
+ * pasted link, a Jira-style issue key, or a bare external system ID from
+ * any connected source. Repeat `identifiers` to batch-resolve up to ten
+ * in one call.
+ *
+ * The response carries a rendered `text` view — each match's metadata
+ * block followed by a `Next:` line naming a follow-up call. The structured
+ * fields carry the same information for programmatic use.
+ *
+ * **Accepted identifiers**
+ * - Jira issue URL — `https://acme.atlassian.net/browse/PA-1787`
+ * - Jira issue key — `PA-1787`
+ * - Confluence page URL —
+ *   `https://acme.atlassian.net/wiki/spaces/SD/pages/450625553/Agent+Loop`
+ * - Google Drive / Docs URL — `https://docs.google.com/document/d/1AbC.../edit`
+ * - Slack message link — `https://acme.slack.com/archives/C0123/p1720000000000100`
+ * - Bare external system ID — `450625553`
+ *
+ * **When to use this vs. the other record endpoints:**
+ * - **This endpoint** converts an *external* reference into an internal
+ *   Record ID. Reach for it whenever you meet a link or ticket key and
+ *   need the record behind it.
+ * - `GET /connectors/record/{recordId}/content` reads a record you have
+ *   already identified. It needs an internal Record ID, which is exactly
+ *   what this endpoint returns.
+ * - `GET /connectors/navigate` browses the hierarchy when you have a
+ *   position in the tree rather than a specific identifier.
+ *
+ * **Typical flow:** call this with the reference, take a match's `id`
+ * from the response, then call
+ * `GET /connectors/record/{recordId}/content` to read the record.
+ *
+ * **Multiple matches:** one identifier can legitimately match more than
+ * one record — the same external ID may exist in several connected
+ * instances. In that case the response sets `ambiguous: true` and
+ * `matches` holds every candidate. Present the choice rather than taking
+ * the first; `connectorName` narrows a retry.
+ *
+ * **Misses are not errors.**
+ *
+ * Only records the caller can see are returned, and a miss is a `200`
+ * with an empty `matches` array and the input echoed in
+ * `not_found_identifiers` — not a `404`. The identifier resolved to
+ * nothing *or* to something the caller may not access; the two are
+ * deliberately indistinguishable, because an identifier is
+ * caller-supplied and guessable, and confirming existence would leak
+ * records across organizations. `searched_connectors` names what was
+ * covered, so a retry with `connectorName` is often the right next move.
+ *
+ * **Scope:** resolution searches every connector the caller can access,
+ * regardless of any source filter used elsewhere.
+ *
+ * If set, this operation will use either {@link Security.bearerAuth} or {@link Security.oauth2} from the global security.
+ */
+export function connectorLookupRecordByIdentifier(
+  client$: PipeshubCore,
+  request: LookupRecordByIdentifierRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: PipeshubCore,
+  request: LookupRecordByIdentifierRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    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,
+  }];
+}

package/src/funcs/connectorNavigateKnowledgeGraph.ts

@@ -0,0 +1,215 @@
+/*
+ * Adapted from Speakeasy-generated connectorNavigateKnowledgeGraph.
+ */
+
+import { PipeshubCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  NavigateKnowledgeGraphRequest,
+  NavigateKnowledgeGraphRequest$zodSchema,
+} from "../models/navigateknowledgegraphop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Browse the knowledge graph from a node
+ *
+ * @remarks
+ * Open a node in the knowledge graph and see what is inside it — a file
+ * explorer across every connected source.
+ *
+ * Call it with no `nodeId` for a flat listing of every record group and
+ * record the caller can reach, newest first. This is a starting point to
+ * pick a node from, not a roster of connected apps — app nodes are never
+ * returned in a listing, though an app's `id` is accepted as a `nodeId`
+ * and lists that app's record groups. Pass a node's `id` to descend:
+ * record groups contain records and folders, and a record contains its
+ * own children — comments, attachments, sub-tasks — plus a `related`
+ * section of cross-referenced records, such as the Confluence page linked
+ * from a Jira ticket. `nodeId` is tolerant: a URL or an issue key such as
+ * `PA-1787` is resolved to its record before navigating, so a link can be
+ * pasted straight in without a separate lookup call.
+ *
+ * The response carries a rendered `text` view — breadcrumbs, the current
+ * node, the children listing, `Related:`, and a closing `Next:` line
+ * naming a follow-up call. The structured fields carry the same
+ * information for programmatic use.
+ *
+ * **When to use this vs. the other record endpoints:**
+ * - **This endpoint** is for structural exploration — "what is in this
+ *   project", "what is attached to this ticket", "what else links to this
+ *   page". It returns names, types and IDs; it never returns document
+ *   text.
+ * - `GET /connectors/record/{recordId}/content` returns one record's
+ *   actual parsed text. Use it once navigation has identified the record
+ *   you want to read.
+ * - `GET /connectors/record/lookup` is the way in when you hold a URL or
+ *   an issue key rather than a position in the tree.
+ *
+ * **Typical flow:** call with no `nodeId` to see what is reachable → pass
+ * a record group's `id` to list its records → take a row whose
+ * `is_record` is true and call
+ * `GET /connectors/record/{recordId}/content` to read it.
+ *
+ * **Paging and depth:** results are paginated; `pagination.has_next`
+ * tells you whether to request the next `page`. `depth` above 1 returns
+ * all descendants down to that level as one flat list, each row carrying
+ * its own `level`, instead of only direct children.
+ *
+ * **Scope:** everything the caller can read, across both connectors and
+ * Knowledge Base collections. No connector-level filter is applied — the
+ * listing is bounded by per-node permissions alone.
+ *
+ * **Permission scoping:**
+ *
+ * `rows` and `related` carry only nodes the caller can see, and the
+ * opened node itself is access-checked before any of its details are
+ * returned. A node that does not exist and a node the caller cannot
+ * access are deliberately indistinguishable — both return an empty view
+ * rather than an error.
+ *
+ * `breadcrumbs` is the exception: the ancestor trail is resolved by id
+ * alone, without a permission check. For a record shared directly with
+ * the caller, it can therefore name ancestors the caller cannot open.
+ * Treat breadcrumb entries as labels, not as nodes guaranteed to be
+ * navigable.
+ *
+ * If set, this operation will use either {@link Security.bearerAuth} or {@link Security.oauth2} from the global security.
+ */
+export function connectorNavigateKnowledgeGraph(
+  client$: PipeshubCore,
+  request?: NavigateKnowledgeGraphRequest | undefined,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: PipeshubCore,
+  request?: NavigateKnowledgeGraphRequest | undefined,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    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,
+  }];
+}

package/src/funcs/conversationsStreamConversation.ts

@@ -87,7 +87,7 @@ async function $do(
     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

package/src/funcs/userGroupsGetAllUserGroups.ts

@@ -114,7 +114,7 @@ async function $do(
     options: client$._options,
     baseURL: options?.serverURL ?? client$._baseURL ?? "",
     operationID: "getAllUserGroups",
-    oAuth2Scopes: [],
+    oAuth2Scopes: ["usergroup:read"],
     resolvedSecurity: requestSecurity,
     securitySource: client$._options.security,
     retryConfig: options?.retries

package/src/hooks/registration.ts

@@ -1,3 +1,4 @@
+import { RequestIDHook } from "./requestid.js";
 import { Hooks } from "./types.js";
 
 /*
@@ -6,9 +7,9 @@ import { Hooks } from "./types.js";
  * in this file or in separate files in the hooks folder.
  */
 
-// @ts-expect-error remove this line when you add your first hook and hooks is used
 export function initHooks(hooks: Hooks) {
   // Add hooks by calling hooks.register{ClientInit/BeforeCreateRequest/BeforeRequest/AfterSuccess/AfterError}Hook
   // with an instance of a hook that implements that specific Hook interface
   // Hooks are registered per SDK instance, and are valid for the lifetime of the SDK instance
+  hooks.registerBeforeRequestHook(new RequestIDHook());
 }

package/src/hooks/request-context.ts

@@ -0,0 +1,47 @@
+/*
+ * Ambient per-tool-call request-id context (AsyncLocalStorage). Mirrors the
+ * pipeshub-ai backend's own request-context pattern (same header name,
+ * `x-request-id`) so a single id traces one MCP tool/resource/prompt
+ * invocation across every backend HTTP call it makes.
+ *
+ * `tools.ts` / `resources.ts` / `prompts.ts` are Speakeasy-generated and
+ * regenerated on every build, so there is no `next()`-style wrapper point to
+ * bind context around a call. Instead `bindNewRequestId` is called from the
+ * hand-written `getClient` closure in `server.ts`, which every generated
+ * dispatch site calls synchronously as the first thing before invoking a
+ * tool/resource/prompt handler — `enterWith` binds the store for the rest of
+ * that handler's execution (sync remainder + everything it awaits).
+ *
+ * The final id (`mcp-<userId>-<random>` or `mcp-<random>`) can't be composed
+ * at bind time — `getClient` only has a `PipeshubCore`, not yet a resolved
+ * `Authorization` header, and resolving security may be async (OAuth2)
+ * while `getClient` must stay sync (generated call sites pass its return
+ * value straight into a handler, never await it). So only the random suffix
+ * is fixed here; `requestid.ts`'s hook fills in `finalId` off the first
+ * outbound request's `Authorization` header and every later call in the
+ * same tool invocation reuses that cached value.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { nanoid } from "nanoid";
+
+export interface RequestContextStore {
+  random: string;
+  finalId?: string;
+}
+
+const storage = new AsyncLocalStorage<RequestContextStore>();
+
+/** Bind a fresh request-id context for the remainder of the current async chain. */
+export function bindNewRequestId(): void {
+  storage.enterWith({ random: nanoid() });
+}
+
+export function getRequestContextStore(): RequestContextStore | undefined {
+  return storage.getStore();
+}
+
+/** One-off id for the rare case a backend call happens with no bound tool-call context. */
+export function newRequestId(): string {
+  return `mcp-${nanoid()}`;
+}