@taiga-ai/mcp-server 0.20.0-dev.454 → 0.21.0-dev.455

package/src/tools/setup.ts

@@ -5,7 +5,7 @@ import type { Product } from '@taiga/types';
 import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY, WRITE } from './annotations.js';
 import { isImportedProduct } from './catalogue.js';
-import { runTool, toolError, toolResult } from './errors.js';
+import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { setupReadiness } from './readiness.js';
 import { withStop } from './hints.js';
 import { idInput, productId } from './inputs.js';
@@ -65,6 +65,54 @@ const MISSING_DOCUMENTS_HOW =
 
 type ProductRow = WithoutTenant<Product>;
 
+/**
+ * Refuse a name already taken (PRO-2800): the API appends -2 to the slug and
+ * creates a second one, so a retried call or two agents at once left
+ * duplicates nobody asked for. allowDuplicateName says the person means it.
+ */
+const allowDuplicateName = z
+  .boolean()
+  .optional()
+  .describe('Create it even when one with the same name exists (default false: refused, naming the existing one)');
+
+/** The same name, as a person would read it: case and surrounding space aside. */
+const sameName = (a: string, b: string) => a.trim().toLowerCase() === b.trim().toLowerCase();
+
+/** Pages read looking for a taken name; past this the create goes ahead. */
+const NAME_PAGES = 5;
+
+/**
+ * The first row with this name, across pages. Best effort: a list the API
+ * refuses or fails leaves the check out rather than the create.
+ */
+async function firstNamed<T extends { id: string; name: string; slug?: string }>(
+  name: string,
+  read: (cursor: string | undefined) => Promise<{ data: T[]; nextCursor: string | null }>
+): Promise<T | null> {
+  let cursor: string | undefined;
+  try {
+    for (let pageIndex = 0; pageIndex < NAME_PAGES; pageIndex += 1) {
+      const result = await read(cursor);
+      const same = result.data.find((row) => sameName(row.name, name));
+      if (same) return same;
+      if (!result.nextCursor) return null;
+      cursor = result.nextCursor;
+    }
+  } catch (error) {
+    if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
+  }
+  return null;
+}
+
+function duplicateName(kind: 'factory' | 'product', existing: { id: string; name: string; slug?: string }) {
+  return toolError(
+    'DUPLICATE_NAME',
+    `A ${kind} named "${existing.name}" already exists (${existing.id}). Use it, choose another name, or pass ` +
+      'allowDuplicateName: true if the person wants a second one.',
+    { existingId: existing.id, ...(existing.slug ? { existingSlug: existing.slug } : {}) }
+  );
+}
+
 /** A product row the model can act on: how it started, and while in setup what it still needs. */
 async function productRow(client: TaigaClient, product: ProductRow) {
   const { settings: _settings, ...rest } = pickFields([product], PRODUCT_FIELDS)[0]!;
@@ -118,17 +166,23 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       {
         title: 'Create a factory',
         description:
-          'Create a factory: a group of products that share a knowledge base, one instructions document and ' +
-          'their members, so products under it work from the same context. Members are added in the web. Then put ' +
-          'products in it with taiga_create_product, or move one there with taiga_move_product. Owners and admins ' +
-          'create factories.',
-        inputSchema: z.object({ name: z.string().trim().min(1).max(255).describe('The factory name') }),
+          'Create a factory: a group of products sharing knowledge, one instructions document and members. Owners ' +
+          'and admins only; members are added in the web. Then add products with taiga_create_product or ' +
+          'taiga_move_product.',
+        inputSchema: z.object({
+          name: z.string().trim().min(1).max(255).describe('The factory name'),
+          allowDuplicateName: allowDuplicateName,
+        }),
         annotations: WRITE,
       },
       (params) =>
-        runTool(async () =>
-          toolResult(pickFields([(await client.createFactory({ name: params.name })).data], FACTORY_FIELDS)[0])
-        )
+        runTool(async () => {
+          if (!params.allowDuplicateName) {
+            const same = await firstNamed(params.name, async (cursor) => client.listFactories({ limit: 100, cursor }));
+            if (same) return duplicateName('factory', same);
+          }
+          return toolResult(pickFields([(await client.createFactory({ name: params.name })).data], FACTORY_FIELDS)[0]);
+        })
     );
 
     server.registerTool(
@@ -136,8 +190,8 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       {
         title: 'Rename a factory',
         description:
-          'Rename a factory. Its products, members, knowledge and instructions stay as they are, but its slug ' +
-          'follows the new name, so links to the factory change.',
+          'Rename a factory. Its slug follows the new name, so links to it change; products, members, knowledge ' +
+          'and instructions stay as they are.',
         inputSchema: z.object({ factoryId, name: z.string().trim().min(1).max(255).describe('The new name') }),
         annotations: OPERATE_SETTING,
       },
@@ -154,10 +208,9 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       {
         title: 'Preview moving a product to another factory',
         description:
-          'Who gains and who loses access if a product moves to another factory: people reach a product through ' +
-          "its factory, so the source factory's members lose it and the target's gain it. People on both, the " +
-          "product's own members, and owners and admins keep it, and are named with why. Read this, and show it " +
-          'to the person, before taiga_move_product.',
+          "Show who gains and who loses access if a product moves to another factory: the source factory's members " +
+          "lose it, the target's gain it; people in both, the product's own members, and owners and admins keep " +
+          'it, named with why. Show it to the person before taiga_move_product.',
         inputSchema: z.object({ productId, factoryId: factoryId.describe('The factory to move it to') }),
         annotations: READ_ONLY,
       },
@@ -170,11 +223,10 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       {
         title: 'Move a product to another factory',
         description:
-          'Move a product to another factory. Access follows the factory, so this changes who can reach the ' +
-          "product (taiga_preview_product_move says who); the product's own knowledge files are re-filed onto " +
-          'the new factory, and factory knowledge and instructions stay with the factory that owns them. Refused ' +
-          '(WORK_IN_FLIGHT) while a plan or build is in flight. Then ask the person: stopLine: true stops the ' +
-          'line first and then moves, which interrupts that work.',
+          'Move a product to another factory. Access follows the factory, so this changes who can reach it ' +
+          "(taiga_preview_product_move says who). The product's own knowledge moves with it; factory knowledge and " +
+          'instructions stay. Refused (WORK_IN_FLIGHT) while a plan or run is in flight; then ask the person: ' +
+          'stopLine: true stops the line first, interrupting that work.',
         inputSchema: z.object({
           productId,
           factoryId: factoryId.describe('The factory to move it to'),
@@ -227,21 +279,19 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Create a product',
       description:
-        'Create a product in a factory, the way New product does. It starts one of two ways, chosen now and not ' +
-        'later: scratch (afterwards projectType greenfield), where Discovery is a conversation that writes the ' +
-        'specification (held in the web), or import (projectType brownfield), where Taiga reads an existing repository and drafts the documents from ' +
-        'the code: link the repository (taiga_link_repository; linking is for owners and admins, so a member ' +
-        'asks one), then taiga_start_import. Also what Taiga builds for it: its ' +
-        'infrastructure code and its CI/CD pipelines, each following the organization unless decided here; when ' +
-        'one is off, deploymentNotes says in a sentence how that half is done today. Material the product should ' +
-        'be built from is worth adding before Discovery starts (taiga_add_knowledge with the productId): what is ' +
-        'added first shapes the specification.',
+        'Create a product in a factory, as New product does, and return it. Choose now how it starts; it cannot ' +
+        'change later: scratch (projectType greenfield), where Discovery is a conversation in the web that ' +
+        'writes the specification, or import (brownfield), where Taiga drafts the documents from a repository: ' +
+        'taiga_link_repository (owners and admins only), then taiga_start_import. Infrastructure code and CI/CD ' +
+        'pipelines follow the organization unless set here; when one is off, deploymentNotes says how that half ' +
+        'is done today. Add source material first with taiga_add_knowledge (productId): Discovery writes from it.',
       inputSchema: z.object({
         factoryId,
         name: z.string().trim().min(1).max(255).describe('The product name'),
         start: z.enum(['scratch', 'import']).describe('scratch: describe it in Discovery; import: from a repository'),
         ...buildScope,
         deploymentNotes: deploymentNotes.optional(),
+        allowDuplicateName: allowDuplicateName,
       }),
       annotations: WRITE,
     },
@@ -249,6 +299,10 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       runTool(async () => {
         const contradiction = notesWithNothingToDescribe(params);
         if (contradiction) return contradiction;
+        if (!params.allowDuplicateName) {
+          const same = await firstNamed(params.name, async (cursor) => client.listProducts({ limit: 100, cursor }));
+          if (same) return duplicateName('product', same);
+        }
         const product = (
           await client.createProduct({
             name: params.name,
@@ -268,11 +322,10 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     {
       title: "Change a product's settings",
       description:
-        "Change a product's name or what Taiga builds for it. A new name changes the slug, so links to the product change. What Taiga " +
-        'builds for it: its infrastructure code and CI/CD pipelines (null ' +
-        'returns one to the organization default), the sentence on how a half Taiga does not build is done today, ' +
-        "and whether it inherits the organization's design standards (null follows the default for how the " +
-        'product started). Later plans read the new answer; work already planned is not redone. Autonomy is ' +
+        "Change a product's name or what Taiga builds for it. A new name changes the slug, so links change. " +
+        'Infrastructure code and CI/CD pipelines: null returns one to the organization default; deploymentNotes ' +
+        'says how a half Taiga does not build is done; emitDesignStandards: null follows the default for how the ' +
+        'product started. Later plans read the change; planned work is not redone. Autonomy is ' +
         'taiga_set_product_autonomy.',
       inputSchema: z.object({
         productId,
@@ -306,11 +359,9 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     {
       title: "Refresh a product's documents from its code",
       description:
-        "Derive the reality documents again from the code, on the branch Taiga works on (the link's effectiveBranch: " +
-        "the chosen branch, or the repository's default): all of them, or the ones named (with " +
-        'what they are derived from). For a document the import misread, refresh it rather than importing ' +
-        'again; unchanged sections are not republished. Runs an agent in the background and returns the job; ' +
-        'taiga_wait_for_job says when it is done.',
+        'Derive the reality documents again from the code on the branch Taiga works on (effectiveBranch): all, ' +
+        'or the ones named. For a document the import misread, refresh it instead of importing again; unchanged ' +
+        'sections are not republished. Returns the job; taiga_wait_for_job says when it is done.',
       inputSchema: z.object({
         productId,
         docTypes: z
@@ -331,14 +382,11 @@ 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) 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 ' +
-        'imported product it is also when the first initiatives are planned. A locked document changes only ' +
-        'after taiga_reopen_discovery. Ask the person first: it is their decision that the documents are right.',
+        "Finish a product's Discovery: it locks the documents and opens the rest of the product; for an imported " +
+        'product the first initiatives are planned. Refused (CONFLICT) with details.reason: documents_incomplete ' +
+        '(details.missingDocuments lists them and how they are made), not_in_setup (already finished), or a ' +
+        'required check not yet stamped (stamped in the web). A locked document changes only after ' +
+        'taiga_reopen_discovery. The person decides the documents are right: ask first.',
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },
@@ -380,13 +428,11 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Import a codebase into a product',
       description:
-        'Start the import of a product created to import a codebase: Taiga reads its linked repository and ' +
-        'derives the full document set from the code, each document citing the files it came from. Importing ' +
-        'is one decision; the rest runs by itself. The scanners then sweep the repository, the documents are ' +
-        "assessed against the organization's policies, and the first initiatives are planned when Discovery is " +
-        'finished. Refused for a product started from scratch (the choice is made at creation), without a ' +
-        'linked repository, or while an import runs. Runs agents in the background and returns the job; ' +
-        'taiga_wait_for_job says when it is done (it takes a while).',
+        'Start importing a product created for import, and return the job. Taiga reads the linked repository and ' +
+        'derives the full document set from the code, citing the files. Then the scanners sweep it, the ' +
+        'documents are assessed against policies, and the first initiatives are planned when Discovery finishes. ' +
+        'Refused for a scratch product, without a linked repository, or while an import runs. taiga_wait_for_job ' +
+        'says when it is done (it takes a while).',
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },

package/src/tools/summarize.ts

@@ -61,7 +61,9 @@ export async function searchPages<T>(
   fetchPage: (cursor: string | undefined) => Promise<{ data: T[]; nextCursor: string | null }>,
   query: string,
   text: (row: T) => unknown[],
-  limit: number
+  limit: number,
+  /** A further condition a row must meet, besides the query. */
+  keep: (row: T) => boolean = () => true
 ): Promise<{ rows: T[]; more: boolean }> {
   const needle = query.toLowerCase();
   const rows: T[] = [];
@@ -70,6 +72,7 @@ export async function searchPages<T>(
     const result = await fetchPage(cursor);
     const page = result.data;
     for (const [at, row] of page.entries()) {
+      if (!keep(row)) continue;
       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

package/src/tools/wait.ts

@@ -360,17 +360,12 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
       {
         title: 'Wait for an initiative',
         description:
-          'Wait for an initiative to reach a point (planned, building, a pull request, done), instead of reading it again and again: changed (anything ' +
-          'about where it is or its latest run), planned (its plan landed), your_turn (it waits on a person: a ' +
-          'plan to review, a pull request, a flag), pr_open (a pull request open now; a merged or closed one does ' +
-          'not count), run_settled (its latest run stopped moving) or done (finished; a canceled one stops the wait). ' +
-          'Returns as soon as that holds (reached: true), early when it cannot hold without a person (a flag, a ' +
-          'failed plan, a plan waiting for its verdict, a pull request waiting for a review, a cancelled ' +
-          'initiative, or a landed plan whose review gate cannot be read; stoppedBecause says which), or at the ' +
-          'timeout with reached: false: ' +
-          'call again to keep waiting. Conditions are states, not events: an initiative whose latest run is already ' +
-          '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.',
+          'Wait until an initiative reaches a condition instead of polling: changed, planned, your_turn (waits on ' +
+          'a person), pr_open (open now; merged or closed does not count), run_settled (latest run stopped moving) ' +
+          'or done. Returns reached: true when it ' +
+          'holds; early with stoppedBecause when only a person can move it (a flag, failed plan, plan or pull ' +
+          'request awaiting review, a cancel); or reached: false at the timeout: call again. A condition already ' +
+          'true answers at once. Planning takes minutes, a run up to an hour.',
         inputSchema: z.object({
           initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it'),
           until: z.enum(ITEM_CONDITIONS).describe('What to wait for'),
@@ -425,13 +420,10 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
       {
         title: 'Wait for a run',
         description:
-          'Wait for a run to reach a point (a step, a pull request, settled): changed (status, steps or pull request), step_done ' +
-          '(one more step finished), pr_open (open now, not merged or closed) or settled (it stopped moving: in ' +
-          'review, completed, failed, stopped). ' +
-          'Returns as soon as that holds (reached: true), early when the run settled without it (stoppedBecause; ' +
-          'changed waits on, since a person resuming the run is a change), or at the timeout with reached: false: ' +
-          '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.',
+          'Wait until a run reaches a condition: changed, step_done (one more step finished), pr_open (open now) ' +
+          'or settled (in review, completed, failed, stopped). Returns reached: true when it holds; early with ' +
+          'stoppedBecause if the run settled without it; or reached: false at the timeout: call again. A settled ' +
+          'run answers settled at once; run is null if the first read timed out.',
         inputSchema: z.object({
           runId: idInput('run', 'taiga_list_runs gives it'),
           until: z.enum(BUILD_CONDITIONS).describe('What to wait for'),
@@ -468,10 +460,9 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
       {
         title: 'Wait for an agent job',
         description:
-          'Wait until an agent job finishes (completed, failed or cancelled): an initiative request, a document, ' +
-          'a refresh. Returns the job as taiga_get_job reads it, with what came of an initiative request, as soon ' +
-          'as it settles (reached: true), or at the timeout with reached: false: call again to keep waiting. Most ' +
-          'jobs take a few minutes.',
+          'Wait until an agent job finishes (completed, failed or cancelled). Returns the job as taiga_get_job ' +
+          "reads it, with an initiative request's outcome, and reached: true; or reached: false at the timeout: " +
+          'call again to keep waiting. Most jobs take a few minutes.',
         inputSchema: z.object({
           jobId: idInput('job', 'the tool that started the job returned it'),
           timeoutSeconds,