@pipeshub-ai/mcp 2.1.0 → 2.3.0

package/src/models/navigateknowledgegraphop.ts

@@ -0,0 +1,56 @@
+/*
+ * Adapted from Speakeasy-generated navigateknowledgegraphop.
+ *
+ * Request only. The generated file also declared a `NavigateKnowledgeGraphResponse`
+ * union, which pulls in ~10 further response models; the func returns a raw
+ * `Response` (errorCodes: []) and the tool parses it with `readJson`, so none of
+ * that is used here.
+ */
+
+import * as z from "zod";
+
+export type NavigateKnowledgeGraphRequest = {
+  nodeId?: string | undefined;
+  page?: number | undefined;
+  limit?: number | undefined;
+  depth?: number | undefined;
+  nodeTypes?: Array<string> | undefined;
+  createdAfter?: string | undefined;
+  createdBefore?: string | undefined;
+  modifiedAfter?: string | undefined;
+  modifiedBefore?: string | undefined;
+};
+
+// Bounds come from the OpenAPI spec rather than the generated schema, which
+// dropped them: the endpoint 400s on `limit` outside 50-200, `depth` outside
+// 1-3, `page` below 1, or an empty `nodeId`. Rejecting client-side turns each
+// of those into a validation message instead of a round-trip.
+export const NavigateKnowledgeGraphRequest$zodSchema: z.ZodType<
+  NavigateKnowledgeGraphRequest
+> = z.object({
+  createdAfter: z.string().describe(
+    "Filter children by source creation time. ISO 8601 `YYYY-MM-DD`, or a full datetime that MUST carry a timezone offset — a naive datetime is rejected rather than assumed to be UTC.",
+  ).optional(),
+  createdBefore: z.string().describe(
+    "Filter children by source creation time. `YYYY-MM-DD` is inclusive of the whole day.",
+  ).optional(),
+  depth: z.int().min(1).max(3).describe(
+    "Levels of descendants to return in one call. Above 1, `rows` is a flat list of all descendants down to that level rather than only direct children, and each row carries its own `level`.",
+  ).optional(),
+  limit: z.int().min(50).max(200).describe(
+    "Children per page. The minimum is 50 — smaller values are rejected rather than silently raised.",
+  ).optional(),
+  modifiedAfter: z.string().describe(
+    "Filter children by source modification time.",
+  ).optional(),
+  modifiedBefore: z.string().describe(
+    "Filter children by source modification time.",
+  ).optional(),
+  nodeId: z.string().min(1).max(2048).describe(
+    "The node to open. Take it from an `id` in a previous navigate or lookup response. Omit it entirely for the flat listing of everything reachable — the usual starting point. A URL or an issue key such as `PA-1787` also works: it is resolved to its record automatically.",
+  ).optional(),
+  nodeTypes: z.array(z.string()).describe(
+    "Restrict children to these node types. Repeat the parameter for multiple types: `?nodeTypes=record&nodeTypes=folder`.",
+  ).optional(),
+  page: z.int().min(1).describe("Page number, 1-indexed.").optional(),
+});

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": "Ask a question, get an answer grounded in the org's indexed data with\ncitations. It reads a few retrieved passages — never a whole document,\nnever a complete list.\n\n**Three questions this tool gets WRONG. Check them first:**\n- **Structure** — \"what's under this epic?\", \"which pages are in this\n  space?\", \"what links to this ticket?\", \"what's in this folder?\" →\n  `pipeshub_get_record_content` `mode:\"navigate\"`. Ranking cannot see how\n  records relate.\n- **Exhaustive** — \"how many X?\", \"list ALL the Y\", \"every Z\" →\n  `mode:\"navigate\"`, which reports the group's real total. This tool\n  undercounts and will not say so.\n- **One named document** — summarize it, extract from it, what does it say\n  about X → `pipeshub_search` for the `recordId`, then `mode:\"content\"`.\n\nEverything else about the org's knowledge belongs here: policies,\nprocesses, decisions, history, \"what do we know about X\", and any question\nspanning several documents.\n\n**Internal search** (default, `chatMode: \"internal_search\"`): the user's\ndocuments, files, knowledge base, company policies — anything in their\nPipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the\norg's KB, ...).\n\n**Web search** (`chatMode: \"web_search\"`): current events or public\ninformation unlikely to be in the org's knowledge base.\n\nBoth are plain-chat modes. **Agent chat** — pass an `agentId` from\n`pipeshub_agents` — runs against that agent's own prompt, tools and knowledge;\n`quick` is its only mode, requires the `agentId`, and is sent automatically.\n\n- \"What's our policy on Y?\" → `pipeshub_chat` (internal_search)\n- \"What's in the news about Z?\" → `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\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)."
   },
   {
     "name": "pipeshub_download_record",
     "description": "Stream the binary content of a single record from PipesHub.\n\nTypical sources for the `recordId`:\n- A chat citation:\n  `pipeshub_chat` response → `citations[*].recordId`.\n- A search result:\n  `pipeshub_search` response → `hits[*].recordId` /\n  `uniqueRecords[*].recordId`.\n\nResponse `Content-Type` is forwarded from the upstream service —\n`application/pdf`, `application/octet-stream`, etc. Binary content is\nreturned base64-encoded; text content is returned inline."
   },
+  {
+    "name": "pipeshub_get_record_content",
+    "description": "Three operations on the org's records. Pick by what you hold:\n\n  `mode:\"lookup\"`   — a URL, issue key (PA-1787), or external ID\n                    → its recordId plus the record's metadata\n  `mode:\"navigate\"` — a question about structure: what is under X,\n                    what links to Y → browses the hierarchy\n  `mode:\"content\"`  — a recordId, and you need the document's COMPLETE text\n\n**`mode:\"content\"` (default)** — the only way to see a document's complete\ntext. Use it whenever missing part of the document could make the answer\nwrong: summarize, extract or list ALL of something, check whether or where\na doc mentions X, review, or compare named docs. `pipeshub_chat` cannot do\nthese — it never sees a whole document.\n\nJudge by the user's INTENT, not their keywords: \"what's this doc about?\",\n\"walk me through the report\", \"anything in here about Y?\" are all\nfull-content tasks. Get the `recordId` from a `pipeshub_search` top hit, a\nchat citation, or `mode:\"lookup\"`.\n\nReturns one `content` string: a metadata header (title, source, key fields,\npre-generated summary) then the full parsed text. A record with no\nextractable content returns the literal `No record found`. Use\n`pipeshub_download_record` only for the original file bytes.\n\n**`mode:\"navigate\"`** — browse the hierarchy: RecordGroup (project /\nspace / drive / folder) → Record (epic / story / page / file) → children,\nwith breadcrumbs, related links and record IDs.\n\nUse it when the question depends on structure rather than wording: what is\nunder this epic, which pages sit in this space, what is linked to this\nticket, what is in this folder — and every \"how many\" / \"all of\" / \"every\"\nquestion. Search ranks by content; only this shows how records relate, and\nonly this gives a count you can trust.\n\nOmit `nodeId` for a flat listing of everything reachable, most recently\nupdated first — the usual starting point. A URL, an issue key, or a\n`pipeshub_sources` id also works and resolves automatically.\n\nPass `depth:2` or `depth:3` to see several levels in ONE call — an epic's\nstories AND their subtasks, a space's pages AND their children — instead of\none call per level. Use it whenever the question needs an overview of a\nhierarchy rather than a single node.\n\nOpening a record also prints that record's own metadata — for a ticket,\nstatus, assignee, priority and dates — so a question about one record is\noften answered by this call alone. It returns no document text; for that,\nre-call with `mode:\"content\"`.\n\nReturns `Path` breadcrumbs, the current node's metadata, a children listing\ncarrying `record_id=` or `node_id=` per row plus the group's total\n(`Children 1-50 of 61`), `Related` cross-references, and a `Next:` line.\nOne page is usually every child, so only pass `page:2` when that `Next:`\nline says more exist.\n\n**`mode:\"lookup\"`** — turn an external reference into a recordId, the first\nstep whenever the question names one. Returns that record's metadata (for a\nticket: status, assignee, priority, dates) plus its recordId, which\n`mode:\"navigate\"` takes to list what is under it and `mode:\"content\"` takes\nto read it.\n\nHandles Jira keys and URLs, Confluence, Drive, Slack permalinks, Linear,\nNotion, ServiceNow sys_id, SharePoint, Gmail/Outlook, and any connector\nwhose records index a web URL. Resolution searches ALL connectors you can\naccess, regardless of any source filter you used elsewhere.\n\nA miss is a 200 with empty `matches` and the input echoed in\n`not_found_identifiers` — that may mean no-access, not non-existence. Use\n`mode:\"navigate\"` to confirm the record exists before telling the user it\ndoes not. If `ambiguous` is true, pick from `matches` rather than taking\nthe first.\n\nNavigate and lookup return a rendered text view whose closing `Next:` line\nnames the exact follow-up call — follow it. When presenting a record, link\nit using the `Web URL` from its metadata header (when present)."
+  },
   {
     "name": "pipeshub_directory",
     "description": "Look up people, groups, and teams in PipesHub. One tool with five\nactions — pick the right `action`:\n\n- `whoami` — who is the caller?  Use this whenever you need the\n  authenticated user's own id, email, or full name (e.g. before\n  `get_user` on themselves).\n- `list_users` — search / page through org users.\n- `get_user` — full `User` document for one user (requires `userId`).\n- `list_groups` — list user groups with `userCount`.\n- `list_my_teams` — teams the caller belongs to, with capability flags\n  (`canEdit` / `canDelete` / `canManageMembers`).\n\nOutput shape varies by action; see each action's docs above."