@taiga-ai/mcp-server 0.16.0-rc.431 → 0.17.0-dev.439

package/src/tools/products.ts

@@ -2,26 +2,33 @@ import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { TaigaApiError, type TaigaClient } from '../client.js';
 import { READ_ONLY } from './annotations.js';
-import { pagination, productId, remoteUrl, slug } from './inputs.js';
+import { idInput, pagination, productId, remoteUrl, slug } from './inputs.js';
 import {
   ORIGIN_MEANING,
   PRODUCT_DOCUMENT_ORIGINS,
   PRODUCT_DOCUMENT_TYPES,
   PRODUCT_STATUSES,
+  DISCOVERY_STEP_MEANING,
   defaultOriginFor,
   emptyOriginNote,
   isImportedProduct,
   productDocumentName,
   type ProductDocumentOrigin,
+  setupNextStep,
   type ProductSettingsView,
 } from './catalogue.js';
 import { apiFailureCode, apiFailureText, isMissOrRefusal, runTool, toolError, toolResult } from './errors.js';
 import { parseRemote } from './remote.js';
-import { pickSections, stripProvenance } from './sections.js';
-import { page, pickFields } from './summarize.js';
+import { sectionReadResult, stripProvenance } from './sections.js';
+import { SEARCH_NOTE, SEARCH_PAGE_SIZE, SEARCH_WITH_CURSOR, page, pickFields, searchPages } from './summarize.js';
 
 /** What a product row needs to say for the model to pick one and read it in full. */
-export const PRODUCT_SUMMARY_FIELDS = ['id', 'name', 'slug', 'status', 'factoryId', 'kind', 'discoveryStep'] as const;
+// Not `kind`: it is parked behind a flag that is on nowhere, so every row said null.
+export const PRODUCT_SUMMARY_FIELDS = ['id', 'name', 'slug', 'status', 'factoryId', 'discoveryStep'] as const;
+
+/** A list's name search: part of a name, any case. */
+const query = (what: string) =>
+  z.string().trim().min(1).max(200).optional().describe(`Part of the ${what}, any case: only the rows that contain it`);
 
 /**
  * What a document row needs to say for the model to pick one and read it in
@@ -217,7 +224,7 @@ export async function resolveProductRef(
   if (given !== 1) {
     const how =
       given === 0 ? (usage ?? 'taiga_list_products shows what exists.') : 'Two names could mean two products.';
-    return refusal('VALIDATION_FAILED', `Name the product exactly once: ${accepted.join(' or ')}. ${how}`);
+    return refusal('VALIDATION_ERROR', `Name the product exactly once: ${accepted.join(' or ')}. ${how}`);
   }
   if (ref.productId) {
     try {
@@ -277,18 +284,29 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
         title: 'List factories',
         description:
           'List all factories in the organization. A factory is the group that owns a set of products. ' +
-          'Use this to find factory IDs for reading factory instructions. ' +
+          'Use this to find factory IDs for reading factory instructions; query finds one by name. ' +
           "Factory instructions carry the factory's standing guidance: domain context, tech preferences, " +
           'and the conventions its products follow.',
         inputSchema: z.object({
+          query: query('factory name'),
           ...pagination,
         }),
         annotations: READ_ONLY,
       },
       (params) =>
         runTool(async () => {
-          const result = await client.listFactories(params);
-          return toolResult(page(result.data, result.nextCursor));
+          if (params.query === undefined) {
+            const result = await client.listFactories(params);
+            return toolResult(page(result.data, result.nextCursor));
+          }
+          if (params.cursor !== undefined) return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
+          const found = await searchPages(
+            (cursor) => client.listFactories({ limit: SEARCH_PAGE_SIZE, cursor }),
+            params.query,
+            (row) => [row.name, row.slug],
+            params.limit ?? 25
+          );
+          return toolResult({ ...page(found.rows, null), ...(found.more ? { more: SEARCH_NOTE } : {}) });
         })
     );
   }
@@ -299,15 +317,14 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       {
         title: 'List products',
         description:
-          'List products in the organization, as summaries (id, name, slug, status, factory, kind). ' +
-          'Use this to find a product by name; inside a git checkout, taiga_resolve_product finds it from ' +
-          'the remote URL instead. taiga_get_product reads one in full.',
+          'List products in the organization, as summaries (id, name, slug, status, factory, discoveryStep). ' +
+          'Use this to find a product by name (query); inside a git checkout, taiga_resolve_product finds it ' +
+          `from the remote URL instead. taiga_get_product reads one in full. ${DISCOVERY_STEP_MEANING}`,
         inputSchema: z.object({
-          factoryId: z
-            .string()
-            .uuid()
+          query: query('product name or slug'),
+          factoryId: idInput('factory', 'taiga_list_factories (query finds one by name) gives it')
             .optional()
-            .describe('Filter by factory ID -- get factory IDs from taiga_list_factories'),
+            .describe('Only the products of this factory'),
           status: z
             .enum(PRODUCT_STATUSES)
             .optional()
@@ -321,10 +338,30 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       },
       (params) =>
         runTool(async () => {
-          const result = await client.listProducts(params);
-          return toolResult(
-            page(pickFields(result.data as Record<string, unknown>[], PRODUCT_SUMMARY_FIELDS), result.nextCursor)
+          const { query: text, ...filters } = params;
+          if (text === undefined) {
+            const result = await client.listProducts(filters);
+            return toolResult(
+              page(pickFields(result.data as Record<string, unknown>[], PRODUCT_SUMMARY_FIELDS), result.nextCursor)
+            );
+          }
+          if (params.cursor !== undefined) return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
+          const found = await searchPages(
+            (cursor) =>
+              client.listProducts({
+                factoryId: filters.factoryId,
+                status: filters.status,
+                limit: SEARCH_PAGE_SIZE,
+                cursor,
+              }),
+            text,
+            (row) => [row.name, row.slug],
+            params.limit ?? 25
           );
+          return toolResult({
+            ...page(pickFields(found.rows, PRODUCT_SUMMARY_FIELDS), null),
+            ...(found.more ? { more: SEARCH_NOTE } : {}),
+          });
         })
     );
 
@@ -335,8 +372,10 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
         description:
           'Get one product in full, by ID or by slug: name, slug, factory, what Taiga owns for it ' +
           '(application, infrastructure, deployment) and its settings; the list and resolve tools carry ' +
-          'summaries. Use taiga_list_product_documents for its specification and design, ' +
-          'taiga_list_backlog_items for its work and taiga_list_builds for what the coding agent did.',
+          'summaries; taiga_get_product_context carries this summary with the rest a session starts from. Use ' +
+          'taiga_list_product_documents for its specification and design, ' +
+          'taiga_list_backlog_items for its work and taiga_list_builds for what the coding agent did. A product ' +
+          'still in setup carries nextStep: what it waits for and the call that moves it on.',
         inputSchema: z.object({
           productId: productId.optional(),
           slug: slug.optional(),
@@ -346,9 +385,9 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       (params) =>
         runTool(async () => {
           const resolved = await resolveProductRef(client, params, ['productId', 'slug']);
-          return 'refusal' in resolved
-            ? toolError(resolved.refusal.code, resolved.refusal.message)
-            : toolResult(resolved.product);
+          if ('refusal' in resolved) return toolError(resolved.refusal.code, resolved.refusal.message);
+          const nextStep = setupNextStep(resolved.product);
+          return toolResult(nextStep ? { ...resolved.product, nextStep } : resolved.product);
         })
     );
 
@@ -425,7 +464,8 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           'threat_model (security risks), technology_decisions. Read reality, when the product has it, to ' +
           "learn what the code actually does before changing it. Omit origin for the product's own timeline. " +
           'A large document runs to tens of thousands of characters: name the sections you need (the ids ' +
-          'taiga_get_product_context lists) and the read carries only those, listing the rest with their sizes. ' +
+          'taiga_get_product_context lists) and the read carries only those, listing the rest with their sizes ' +
+          'and any id the document lacks (unknownSections). ' +
           'A read that finds nothing says which documents and timelines the product does have.',
         inputSchema: z.object({
           productId,
@@ -453,22 +493,7 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
             const result = await client.getProductDocument(params.productId, params.type, origin);
             const doc = stripProvenance(result.data as Record<string, unknown>);
             if (!params.sections) return toolResult(doc);
-            const cut = pickSections(doc, new Set(params.sections));
-            if (!cut) {
-              return toolError(
-                'VALIDATION_FAILED',
-                `The ${origin} ${params.type} is not made of sections; read it without sections.`
-              );
-            }
-            const all = Object.keys((doc.data as { sections: Record<string, unknown> }).sections);
-            const unknown = params.sections.filter((id) => !all.includes(id));
-            if (unknown.length > 0) {
-              return toolError(
-                'NOT_FOUND',
-                `The ${origin} ${params.type} has no section ${unknown.join(', ')}; its sections are ${all.join(', ')}.`
-              );
-            }
-            return toolResult({ ...cut.doc, omittedSections: cut.omittedSections });
+            return sectionReadResult(doc, params.sections, `${origin} ${params.type}`);
           } catch (error) {
             if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
             // A product the key cannot see is a product miss, not a document

package/src/tools/prompts.ts

@@ -4,7 +4,7 @@ import { TaigaApiError, type TaigaClient } from '../client.js';
 import { POLICY_TYPES, defaultOriginFor, type ProductSettingsView } from './catalogue.js';
 import { productContext } from './context.js';
 import { apiFailureCode, apiFailureText, isMissOrRefusal, isNetworkFailure, networkFailureDetail } from './errors.js';
-import { productId as idInput, remoteUrl, slug } from './inputs.js';
+import { idInput, productId, remoteUrl, slug } from './inputs.js';
 import { fence as fenced, renderDocument } from './markdown.js';
 import { resolveProductRef } from './products.js';
 import { instructionsText, sectionsOf, stripProvenance } from './sections.js';
@@ -72,7 +72,7 @@ export function registerPrompts(server: McpServer, client: TaigaClient) {
         // first one, and the slug is the name a person knows from the URL.
         argsSchema: z.object({
           slug: slug.optional(),
-          productId: idInput.optional(),
+          productId: productId.optional(),
           remoteUrl: remoteUrl.optional(),
         }),
       },
@@ -116,7 +116,9 @@ export function registerPrompts(server: McpServer, client: TaigaClient) {
           'Implement one initiative: its description and acceptance criteria, the architecture of the product ' +
           "from its own timeline, the factory's instructions and the policy sections to check against. " +
           'taiga_list_backlog_items gives the item ID.',
-        argsSchema: z.object({ itemId: idInput.describe('The backlog item ID') }),
+        argsSchema: z.object({
+          itemId: idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it'),
+        }),
       },
       async (args) => {
         const item = (

package/src/tools/repositories.ts

@@ -3,8 +3,8 @@ import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
 import { runTool, toolError, toolResult } from './errors.js';
-import { pagination, productId } from './inputs.js';
-import { page, pickFields } from './summarize.js';
+import { idInput, pagination, productId } from './inputs.js';
+import { SEARCH_WITH_CURSOR, page, pickFields } from './summarize.js';
 
 /**
  * A product's repository (docs.tai.ga, Administration: Integrations and
@@ -49,10 +49,10 @@ const GITHUB_REPOSITORY_FIELDS = [
   'language',
 ] as const;
 
-const repositoryId = z
-  .string()
-  .uuid()
-  .describe("The product's repository link ID -- taiga_list_product_repositories gives it");
+const repositoryId = idInput(
+  'repository link',
+  'taiga_list_product_repositories gives it; a GitHub repository id is not one'
+);
 
 export function registerRepositoryTools(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('products:read')) {
@@ -104,7 +104,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
           'in the web, by someone who can install the app.',
         inputSchema: z.object({
           query: z.string().trim().min(1).max(256).optional().describe('Part of the repository name'),
-          installationId: z.string().uuid().optional().describe('One GitHub account -- this tool lists them'),
+          installationId: idInput('GitHub account', 'this tool lists them').optional(),
           ...pagination,
         }),
         annotations: READ_ONLY,
@@ -128,10 +128,10 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
           // A cursor belongs to one account's pages, and a search answers one
           // ranked page: either way a cursor would quietly start over.
           if (params.cursor !== undefined && params.query !== undefined) {
-            return toolError('VALIDATION_FAILED', 'A search answers one page; narrow the query instead of paging it.');
+            return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
           }
           if (chosen.length > 1 && params.cursor !== undefined) {
-            return toolError('VALIDATION_FAILED', 'A cursor pages one account: name its installationId.', { accounts });
+            return toolError('VALIDATION_ERROR', 'A cursor pages one account: name its installationId.', { accounts });
           }
           // `limit` is the most rows the answer carries, however many accounts
           // are read: a search answers its ranked matches whatever the page
@@ -185,10 +185,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         'sweeps scan it, and its deployment history is imported in the background. Ask the person first.',
       inputSchema: z.object({
         productId,
-        githubRepositoryId: z
-          .string()
-          .uuid()
-          .describe('The repository id -- taiga_list_linkable_repositories gives it'),
+        githubRepositoryId: idInput('GitHub repository', 'taiga_list_linkable_repositories gives it'),
         replacesRepositoryId: repositoryId.optional().describe('The link this one replaces'),
       }),
       annotations: OPERATE,
@@ -230,7 +227,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
     (params) =>
       runTool(async () => {
         if (params.baseBranch === undefined && params.label === undefined) {
-          return toolError('VALIDATION_FAILED', 'Set baseBranch, label or both.');
+          return toolError('VALIDATION_ERROR', 'Set baseBranch, label or both.');
         }
         const updated = (
           await client.updateRepository(params.productId, params.repositoryId, {

package/src/tools/sections.ts

@@ -11,6 +11,9 @@
  * surface loses what the other preserved.
  */
 
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import { toolError, toolResult } from './errors.js';
+
 /** A section as stored: an object with `content` and metadata, or (older rows) a bare string. */
 export type Sections = Record<string, unknown>;
 
@@ -125,3 +128,24 @@ export function budgetSections(doc: Record<string, unknown>, budget: number): Se
   }
   return cutTo(doc, sections, Object.fromEntries(kept));
 }
+
+/**
+ * The answer to a read that names sections: the ones the document has, the
+ * rest listed with their sizes, and the asked-for ids it lacks under
+ * unknownSections. One wrong id does not throw away the right ones (the
+ * model retries only the miss); none right is a miss that lists the real ids.
+ */
+export function sectionReadResult(doc: Record<string, unknown>, ids: readonly string[], label: string): CallToolResult {
+  const cut = pickSections(doc, new Set(ids));
+  if (!cut) return toolError('VALIDATION_ERROR', `The ${label} is not made of sections; read it without sections.`);
+  const all = Object.keys(sectionsOf(doc.data as Record<string, unknown>) ?? {});
+  const unknownSections = ids.filter((id) => !all.includes(id));
+  if (unknownSections.length === ids.length) {
+    return toolError('NOT_FOUND', `The ${label} has no section ${ids.join(', ')}; its sections are ${all.join(', ')}.`);
+  }
+  return toolResult({
+    ...cut.doc,
+    omittedSections: cut.omittedSections,
+    ...(unknownSections.length > 0 ? { unknownSections } : {}),
+  });
+}

package/src/tools/setup.ts

@@ -1,11 +1,12 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { DEPLOYMENT_NOTES_MAX_LENGTH, REALITY_DERIVED_DOCUMENT_TYPES } from '@taiga/types';
 import { z } from 'zod';
-import type { TaigaClient } from '../client.js';
+import { TaigaApiError, type TaigaClient } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY, WRITE } from './annotations.js';
-import { isImportedProduct, type ProductSettingsView } from './catalogue.js';
-import { runTool, toolError, toolResult } from './errors.js';
-import { productId } from './inputs.js';
+import { isImportedProduct, setupNextStep, type ProductSettingsView } from './catalogue.js';
+import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
+import { withStop } from './hints.js';
+import { idInput, productId } from './inputs.js';
 import { pickFields } from './summarize.js';
 
 /**
@@ -34,7 +35,7 @@ const PRODUCT_FIELDS = [
 
 const FACTORY_FIELDS = ['id', 'name', 'slug', 'isDefault'] as const;
 
-const factoryId = z.string().uuid().describe('Factory ID -- taiga_list_factories gives it');
+const factoryId = idInput('factory', 'taiga_list_factories (query finds one by name) gives it');
 
 const buildScope = {
   ownsInfrastructure: z
@@ -56,10 +57,56 @@ const deploymentNotes = z
   .max(DEPLOYMENT_NOTES_MAX_LENGTH)
   .describe('When a half is off: a sentence on how it is done today, which Taiga designs and plans against');
 
+/** How a missing required document comes to exist, said with a documents_incomplete refusal. */
+const MISSING_DOCUMENTS_HOW =
+  'An imported product gets them from its import (taiga_start_import); a product started from scratch gets the ' +
+  'specification from the Discovery conversation in the web and the rest from taiga_generate_product_documents. ' +
+  'A draft is published with taiga_publish_product_document.';
+
 /** A product row the model can act on, saying how it started as the other product tools say it. */
-function productRow(product: Row): Row {
+async function productRow(client: TaigaClient, product: Row): Promise<Row> {
   const { settings: _settings, ...rest } = pickFields([product], PRODUCT_FIELDS)[0]!;
-  return { ...rest, projectType: isImportedProduct(product as ProductSettingsView) ? 'brownfield' : 'greenfield' };
+  const nextStep = setupNextStep(await withDiscoveryStep(client, product));
+  return {
+    ...rest,
+    projectType: isImportedProduct(product as ProductSettingsView) ? 'brownfield' : 'greenfield',
+    ...(nextStep ? { nextStep } : {}),
+  };
+}
+
+/**
+ * The product with its discoveryStep. The API derives it on reads only, not
+ * on the answer to a write (products.ts), and a draft started from scratch
+ * needs it to say what comes next; an imported one reads its import status
+ * instead. Best effort: a failed read leaves the product without a nextStep
+ * rather than failing the write that already happened.
+ */
+async function withDiscoveryStep(client: TaigaClient, product: Row): Promise<Row> {
+  if (product.status !== 'draft' || 'discoveryStep' in product || isImportedProduct(product as ProductSettingsView)) {
+    return product;
+  }
+  try {
+    return (await client.getProduct(String(product.id))).data as Row;
+  } catch (error) {
+    if (error instanceof TaigaApiError || isNetworkFailure(error)) return product;
+    throw error;
+  }
+}
+
+/**
+ * A half turned off with nothing said about how it is done today. Allowed (the
+ * web asks for the sentence but does not insist), so a warning rather than a
+ * refusal: plans then design against a gap.
+ */
+function missingNotesWarning(product: Row): string[] {
+  const off = product.ownsInfrastructure === false || product.ownsDeployment === false;
+  const notes = typeof product.deploymentNotes === 'string' ? product.deploymentNotes.trim() : '';
+  return off && !notes
+    ? [
+        'A half Taiga does not build has no deploymentNotes: plans cannot design against how it is done today. ' +
+          'Ask the person for a sentence and set it.',
+      ]
+    : [];
 }
 
 /**
@@ -75,7 +122,7 @@ function notesWithNothingToDescribe(params: {
     params.ownsInfrastructure === true &&
     params.ownsDeployment === true
     ? toolError(
-        'VALIDATION_FAILED',
+        'VALIDATION_ERROR',
         'deploymentNotes describes a half Taiga does not build; both are on, so leave it out.'
       )
     : null;
@@ -165,7 +212,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
             ...(params.stopLine ? { stopLine: true } : {}),
           });
           return toolResult({
-            product: productRow(moved.data as Row),
+            product: await productRow(client, moved.data as Row),
             changed: moved.changed,
             previousFactoryId: moved.previousFactoryId,
             lineStopped: moved.lineStopped,
@@ -214,7 +261,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
             ...(params.deploymentNotes !== undefined ? { deploymentNotes: params.deploymentNotes } : {}),
           })
         ).data as Row;
-        return toolResult(productRow(product));
+        return toolResult(await productRow(client, product));
       })
   );
 
@@ -246,11 +293,13 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       runTool(async () => {
         const { productId: id, ...changes } = params;
         if (Object.values(changes).every((value) => value === undefined)) {
-          return toolError('VALIDATION_FAILED', 'Change at least one setting.');
+          return toolError('VALIDATION_ERROR', 'Change at least one setting.');
         }
         const contradiction = notesWithNothingToDescribe(params);
         if (contradiction) return contradiction;
-        return toolResult(productRow((await client.updateProduct(id, changes)).data as Row));
+        const updated = (await client.updateProduct(id, changes)).data as Row;
+        const warnings = missingNotesWarning(updated);
+        return toolResult({ ...(await productRow(client, updated)), ...(warnings.length > 0 ? { warnings } : {}) });
       })
   );
 
@@ -285,7 +334,8 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       title: 'Finish Discovery',
       description:
         "Finish a product's Discovery. Refused (CONFLICT) with details.reason: documents_incomplete names the " +
-        'required documents still unpublished (details.missingDocuments); not_in_setup means it is already ' +
+        'required documents still unpublished (details.missingDocuments) and how they are made; not_in_setup ' +
+        'means it is already ' +
         'finished; a required check left unstamped (stamped in the web) is refused with its details too. It ' +
         'locks the document set ' +
         'and opens the rest of the product; for an ' +
@@ -294,7 +344,21 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },
-    (params) => runTool(async () => toolResult(productRow((await client.completeSetup(params.productId)).data as Row)))
+    (params) =>
+      runTool(async () => {
+        try {
+          return toolResult(await productRow(client, (await client.completeSetup(params.productId)).data as Row));
+        } catch (error) {
+          // The refusal names what is missing; it does not say how a missing
+          // document comes to exist, which is what the agent asks next.
+          if (!(error instanceof TaigaApiError) || error.details?.reason !== 'documents_incomplete') throw error;
+          return toolError(
+            error.code ?? 'CONFLICT',
+            `${withStop(error.apiMessage ?? 'Required documents are not published yet')} ${MISSING_DOCUMENTS_HOW}`,
+            error.details
+          );
+        }
+      })
   );
 
   server.registerTool(
@@ -307,7 +371,10 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },
-    (params) => runTool(async () => toolResult(productRow((await client.reopenSetup(params.productId)).data as Row)))
+    (params) =>
+      runTool(async () =>
+        toolResult(await productRow(client, (await client.reopenSetup(params.productId)).data as Row))
+      )
   );
 
   if (!client.hasCapability('products:read')) return;

package/src/tools/summarize.ts

@@ -43,3 +43,47 @@ export function itemRows(items: Record<string, unknown>[], fields: readonly stri
     'acceptanceCriteria' in items[index]! ? { ...row, criteria: criteriaCounts(items[index]!) } : row
   );
 }
+
+/** Pages a name search reads before it stops and says so: 1,000 rows at the API's page ceiling. */
+const SEARCH_PAGE_LIMIT = 10;
+
+/**
+ * Rows whose text contains `query`, ignoring case, read page by page until
+ * `limit` match or the rows run out. The API has no name search, and a model
+ * told the person's word for a thing ("the Sandbox factory") otherwise pages
+ * the whole list to find its ID. `more` is true when it stopped before the end.
+ */
+export async function searchPages(
+  fetchPage: (cursor: string | undefined) => Promise<{ data: unknown[]; nextCursor: string | null }>,
+  query: string,
+  text: (row: Record<string, unknown>) => unknown[],
+  limit: number
+): Promise<{ rows: Record<string, unknown>[]; more: boolean }> {
+  const needle = query.toLowerCase();
+  const rows: Record<string, unknown>[] = [];
+  let cursor: string | undefined;
+  for (let index = 0; index < SEARCH_PAGE_LIMIT; index += 1) {
+    const result = await fetchPage(cursor);
+    const page = result.data as Record<string, unknown>[];
+    for (const [at, row] of page.entries()) {
+      if (!text(row).some((value) => typeof value === 'string' && value.toLowerCase().includes(needle))) continue;
+      rows.push(row);
+      // Full: stop reading. \`more\` then means "there may be more", not
+      // that a further match was seen; reading on to find out cost up to ten
+      // sequential pages for one bit.
+      if (rows.length === limit) return { rows, more: at < page.length - 1 || result.nextCursor !== null };
+    }
+    if (!result.nextCursor) return { rows, more: false };
+    cursor = result.nextCursor;
+  }
+  return { rows, more: true };
+}
+
+/** The page size a search reads at: the API's ceiling. */
+export const SEARCH_PAGE_SIZE = 100;
+
+/** A search reads its own pages, so a cursor from a plain page has nothing to continue. */
+export const SEARCH_WITH_CURSOR = 'A search answers one page; narrow the query instead of paging it.';
+
+/** What a search says when it stopped before reading every row. */
+export const SEARCH_NOTE = 'There may be more matches than the limit carries; narrow the query or raise the limit.';

package/src/tools/wait.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { BUILD_RUN_TERMINAL_STATUSES, resolveAutoBuild } from '@taiga/types';
 import { z } from 'zod';
+import { idInput } from './inputs.js';
 import { TaigaApiError, type TaigaClient } from '../client.js';
 import { READ_ONLY } from './annotations.js';
 import { isNetworkFailure, runTool, toolResult } from './errors.js';
@@ -356,7 +357,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
           'settled answers run_settled at once; item is null when not even the first read answered in time. ' +
           'Planning takes minutes and a build up to an hour.',
         inputSchema: z.object({
-          itemId: z.string().uuid().describe('Backlog item ID -- get from taiga_list_backlog_items'),
+          itemId: idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it'),
           until: z.enum(ITEM_CONDITIONS).describe('What to wait for'),
           timeoutSeconds,
         }),
@@ -417,7 +418,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
           'call again to keep waiting. Conditions are states: a run already settled answers settled at once; run ' +
           'is null when not even the first read answered in time.',
         inputSchema: z.object({
-          buildId: z.string().uuid().describe('Build run ID -- get from taiga_list_builds'),
+          buildId: idInput('build run', 'taiga_list_builds gives it'),
           until: z.enum(BUILD_CONDITIONS).describe('What to wait for'),
           timeoutSeconds,
         }),
@@ -457,7 +458,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
           'as it settles (reached: true), or at the timeout with reached: false: call again to keep waiting. Most ' +
           'jobs take a few minutes.',
         inputSchema: z.object({
-          jobId: z.string().uuid().describe('Agent job ID -- a request tool returns it'),
+          jobId: idInput('job', 'the tool that started the job returned it'),
           timeoutSeconds,
         }),
         annotations: READ_ONLY,