@taiga-ai/mcp-server 0.21.0-rc.456 → 0.22.0-dev.457

package/src/tools/inbox.ts

@@ -52,8 +52,11 @@ function itemRow(row: Row, now: number, full: boolean): Row {
   const { snoozedUntil, resolvedAt, ...rest } = picked;
   const metadata = (row['metadata'] ?? {}) as Row;
   const created = typeof row['createdAt'] === 'string' ? Date.parse(row['createdAt']) : NaN;
+  // A pull request review's summary is one sentence per row ("The coding agent finished its turn on X. Review PR
+  // #N...") that the title and kind already say: the org-wide page was 5k tokens of it (PRO-2800).
+  const { summary, ...lean } = rest;
   return {
-    ...rest,
+    ...(row['kind'] === 'review_pr' && !full ? lean : { ...lean, summary }),
     ...(snoozedUntil ? { snoozedUntil } : {}),
     ...(resolvedAt ? { resolvedAt } : {}),
     ...(typeof metadata['prUrl'] === 'string' ? { prUrl: metadata['prUrl'] } : {}),
@@ -63,7 +66,10 @@ function itemRow(row: Row, now: number, full: boolean): Row {
   };
 }
 
-/** What is open, counted by product and kind: the answer to "what needs attention" without reading every row. */
+/**
+ * What is open, counted by product and kind: the answer to "what needs attention" without reading every row. An item
+ * that no longer stands is counted under stale, not open or byKind, so nobody subtracts by hand (PRO-2800).
+ */
 function summaryOf(rows: Row[], stale: Map<string, string>): Row[] {
   const byProduct = new Map<
     string,
@@ -77,9 +83,12 @@ function summaryOf(rows: Row[], stale: Map<string, string>): Row[] {
       (row['productName']
         ? { productId: key, product: row['productName'], open: 0, byKind: {} }
         : { productId: key, open: 0, byKind: {} });
-    entry.open += 1;
-    entry.byKind[String(row['kind'])] = (entry.byKind[String(row['kind'])] ?? 0) + 1;
-    if (stale.has(String(row['id']))) entry.stale = (entry.stale ?? 0) + 1;
+    if (stale.has(String(row['id']))) {
+      entry.stale = (entry.stale ?? 0) + 1;
+    } else {
+      entry.open += 1;
+      entry.byKind[String(row['kind'])] = (entry.byKind[String(row['kind'])] ?? 0) + 1;
+    }
     byProduct.set(key, entry);
   }
   return [...byProduct.values()].sort((a, b) => b.open - a.open);
@@ -130,9 +139,54 @@ async function staleReviews(
       }
     })
   );
+  unchecked += await staleBacklogReviews(client, rows, out);
   return { stale: out, unchecked };
 }
 
+/**
+ * "Review Initiatives" items whose product has no open initiative left (PRO-2800): two reviews found one
+ * waiting 15 days on a product whose initiatives had all moved on, with nothing an agent could act on. Best effort,
+ * a handful of products; returns how many could not be checked.
+ */
+async function staleBacklogReviews(client: TaigaClient, rows: Row[], out: Map<string, string>): Promise<number> {
+  // The page and the summary's read can carry the same row: each item once.
+  const asks = [
+    ...new Map(
+      rows
+        .filter((row) => row['kind'] === 'review_backlog' && typeof row['productId'] === 'string')
+        .map((row) => [String(row['id']), row])
+    ).values(),
+  ];
+  if (asks.length === 0) return 0;
+  if (!client.hasCapability('backlog:read')) return asks.length;
+  const products = [...new Set(asks.map((row) => String(row['productId'])))];
+  const checked = products.slice(0, STALE_CHECKS);
+  let unchecked = asks.filter((row) => !checked.includes(String(row['productId']))).length;
+  const empty = new Set<string>();
+  await Promise.all(
+    checked.map(async (productId) => {
+      try {
+        // Any open initiative keeps the item standing: status stays in_progress after a first run even when the
+        // initiative is moved back to todo, so backlog alone would call waiting work gone.
+        const [waiting, started] = await Promise.all([
+          client.listBacklogItems(productId, { status: 'backlog', limit: 1 }),
+          client.listBacklogItems(productId, { status: 'in_progress', limit: 1 }),
+        ]);
+        if (waiting.data.length === 0 && started.data.length === 0) empty.add(productId);
+      } catch (error) {
+        if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
+        unchecked += asks.filter((row) => row['productId'] === productId).length;
+      }
+    })
+  );
+  for (const row of asks) {
+    if (empty.has(String(row['productId']))) {
+      out.set(String(row['id']), 'no initiative is open now: the ones it asked about are all done or canceled');
+    }
+  }
+  return unchecked;
+}
+
 /** Pages read for the summary; past this it says it counted only those. */
 const SUMMARY_PAGE = 100;
 
@@ -291,7 +345,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
           // Past the cap a review is not checked, so no stale on it is not "live".
           ...(checked.unchecked > 0
             ? {
-                staleNote: `${checked.unchecked} pull request review${checked.unchecked === 1 ? ' was' : 's were'} not checked for staleness (past the cap, or the read was refused).`,
+                staleNote: `${checked.unchecked} review${checked.unchecked === 1 ? ' was' : 's were'} not checked for staleness (past the cap, or the read was refused).`,
               }
             : {}),
         });

package/src/tools/index.ts

@@ -1,6 +1,6 @@
-import type { McpServer } from '@modelcontextprotocol/server';
+import type { CallToolResult, McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import type { TaigaClient } from '../client.js';
+import { TaigaApiError, type TaigaClient } from '../client.js';
 import { registerProductTools } from './products.js';
 import { registerDocumentTools } from './documents.js';
 import { registerBacklogTools } from './backlogs.js';
@@ -19,7 +19,7 @@ import { registerRepositoryTools } from './repositories.js';
 import { registerResources } from './resources.js';
 import { registerSetupTools } from './setup.js';
 import { notFoundHint, notFoundHints } from './hints.js';
-import { runTool, toolResult } from './errors.js';
+import { isNetworkFailure, runTool, toolResult } from './errors.js';
 import { READ_ONLY } from './annotations.js';
 import { DEFAULT_WAIT_OPTIONS, registerWaitTools, type WaitOptions } from './wait.js';
 
@@ -32,7 +32,11 @@ import { DEFAULT_WAIT_OPTIONS, registerWaitTools, type WaitOptions } from './wai
  * model learns the tool's real shape. Applied here, once, so no tool can be
  * registered without it.
  */
-function withStrictInputs(server: McpServer, registered: Map<string, ToolAnnotations | undefined>): McpServer {
+function withStrictInputs(
+  server: McpServer,
+  client: TaigaClient,
+  registered: Map<string, ToolAnnotations | undefined>
+): McpServer {
   const register = server.registerTool.bind(server) as (...args: unknown[]) => unknown;
   server.registerTool = ((
     name: string,
@@ -47,8 +51,8 @@ function withStrictInputs(server: McpServer, registered: Map<string, ToolAnnotat
     // .strict() keeps the object's own checks (a refine stays a refine).
     // The call runs with its not-found hint in scope, for runTool to add to a 404.
     const handler = callback as (args: unknown, ctx: unknown) => unknown;
-    const withHint = (args: unknown, ctx: unknown) =>
-      notFoundHints.run(notFoundHint(name, args), () => handler(args, ctx));
+    const withHint = async (args: unknown, ctx: unknown) =>
+      withIdKind(client, args, await notFoundHints.run(notFoundHint(name, args), () => handler(args, ctx)));
     const described = {
       ...config,
       description: `${writeNotice(name, config.annotations)}${config.description ?? ''}`,
@@ -59,6 +63,46 @@ function withStrictInputs(server: McpServer, registered: Map<string, ToolAnnotat
   return server;
 }
 
+/**
+ * A product the API does not know may be a factory's ID passed as one (PRO-2800): the hint can only say a product
+ * ID is wanted, so on that miss alone one read names what the ID is.
+ */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+async function withIdKind(client: TaigaClient, args: unknown, result: unknown): Promise<unknown> {
+  const productId = typeof args === 'object' && args !== null ? (args as Record<string, unknown>)['productId'] : null;
+  const answer = result as CallToolResult;
+  const first = answer?.isError ? answer.content?.[0] : undefined;
+  if (typeof productId !== 'string' || first?.type !== 'text') return result;
+  let body: { error?: unknown; message?: unknown };
+  try {
+    body = JSON.parse(first.text) as typeof body;
+  } catch {
+    return result;
+  }
+  // The API's own miss for the product, not a hint that mentions products; one read, with a key that can make it.
+  if (
+    body.error !== 'NOT_FOUND' ||
+    !/\b(product|project) not found|No product with that ID/i.test(String(body.message))
+  ) {
+    return result;
+  }
+  if (!UUID.test(productId) || !client.hasCapability('factories:read')) return result;
+  try {
+    const factory = (await client.getFactory(productId)).data;
+    const message =
+      `${String(body.message)} That ID is the factory "${factory.name}", not a product: taiga_list_products ` +
+      'with factoryId lists its products.';
+    return {
+      ...answer,
+      content: [{ type: 'text', text: JSON.stringify({ ...body, message }) }, ...answer.content.slice(1)],
+    };
+  } catch (error) {
+    if (error instanceof TaigaApiError || isNetworkFailure(error)) return result;
+    throw error;
+  }
+}
+
 type ToolAnnotations = { readOnlyHint?: boolean; destructiveHint?: boolean; openWorldHint?: boolean };
 
 /**
@@ -122,7 +166,7 @@ export const PAID_WORK = new Set([
  */
 export function registerAllTools(server: McpServer, client: TaigaClient, options: { wait?: WaitOptions } = {}): void {
   const registered = new Map<string, ToolAnnotations | undefined>();
-  withStrictInputs(server, registered);
+  withStrictInputs(server, client, registered);
   registerProductTools(server, client);
   registerDocumentTools(server, client);
   registerBacklogTools(server, client);

package/src/tools/inputs.ts

@@ -10,7 +10,7 @@ import { z } from 'zod';
 export function idInput(what: string, from: string) {
   return z
     .string()
-    .uuid({ message: `A ${what} ID is a UUID, not a name: ${from}` })
+    .uuid({ message: `${/^[aeiou]/i.test(what) ? 'An' : 'A'} ${what} ID is a UUID, not a name: ${from}` })
     .describe(`${what[0]!.toUpperCase()}${what.slice(1)} ID -- ${from}`);
 }
 

package/src/tools/instructions.ts

@@ -16,7 +16,7 @@ export const SERVER_INSTRUCTIONS = [
   '**Which read.** Where a product stands: taiga_get_product_context (by git remote URL, slug or ID). What waits on',
   'people: taiga_list_action_required. A policy: taiga_get_document (sections: [] for the outline, or a control id',
   'such as SEC-5.1). Findings: taiga_list_findings. One initiative or run: taiga_get_initiative, taiga_get_run.',
-  "This key's role and tools: taiga_whoami.",
+  "This key's role and which tools write: taiga_whoami.",
   '',
   '**Words.** An initiative is a unit of work; its board columns are backlog, todo, queue, plan, build, done, canceled. The',
   "line is the product's queue, worked one initiative at a time through plan and build. A run is one attempt by the",
@@ -28,8 +28,9 @@ export const SERVER_INSTRUCTIONS = [
   '(derived from the code). outcome, situation and nextStep are one-sentence summaries of their record.',
   '',
   '**Writing.** A tool that writes opens with "Writes.", "Ask first (paid agent work)." or "Ask first (others see',
-  'it)."; before an ask-first tool, tell the person what you will do and wait for their yes. A taken factory or',
-  'product name is refused unless allowDuplicateName.',
+  'it)."; before an ask-first tool, tell the person what you will do and wait for their yes. Others share this',
+  'organization: a taken factory name (or product name in its factory) is refused unless allowDuplicateName, and',
+  "the one that exists may not be this person's.",
   '',
   '**Only in the web:** connecting GitHub, members and roles, the Discovery conversation of a product started from',
   'scratch, stamping checks, starting a run over, and deleting factories and products.',

package/src/tools/maintenance.ts

@@ -45,6 +45,48 @@ const FINDING_ROW_FIELDS = [
   'ignoreExpiresAt',
 ] as const;
 
+/**
+ * Whether taiga_fix_finding would take a finding, said on the row (PRO-2800): three reviews found a dependency
+ * marked remediableBy coding_agent with no fixed version, which the API refuses to fix. The API's own refusals,
+ * read off the row; remediableBy stays as the sweep recorded it.
+ */
+function withFixability(row: Row): Row {
+  const dependency = row['kind'] === 'vulnerable_dependency' || row['kind'] === 'outdated_dependency';
+  if (dependency && !row['recommendedVersion'] && row['remediableBy'] === 'coding_agent') {
+    return {
+      ...row,
+      fixable: false,
+      fixNote: 'No fixed version is known yet: taiga_fix_finding refuses it until one is published.',
+    };
+  }
+  return row;
+}
+
+/** The parts of an advisory record an agent reads; the rest (every affected range, every reference) is full: true. */
+const ADVISORY_KEPT = ['id', 'aliases', 'summary', 'details', 'severity', 'published'];
+const ADVISORY_TEXT_LIMIT = 1_500;
+
+function leanAdvisory(data: unknown): unknown {
+  if (typeof data !== 'object' || data === null || !('affected' in data || 'references' in data)) return data;
+  const record = data as Row;
+  const kept = Object.fromEntries(ADVISORY_KEPT.filter((key) => key in record).map((key) => [key, record[key]]));
+  const details = kept['details'];
+  if (typeof details === 'string' && details.length > ADVISORY_TEXT_LIMIT) {
+    kept['details'] =
+      `${details.slice(0, ADVISORY_TEXT_LIMIT)}... [cut at ${ADVISORY_TEXT_LIMIT} of ${details.length} characters; full: true reads it whole]`;
+  }
+  const references = Array.isArray(record['references']) ? record['references'] : [];
+  return {
+    ...kept,
+    ...(references.length > 0
+      ? {
+          references: references.slice(0, 3),
+          ...(references.length > 3 ? { referencesNote: `3 of ${references.length}; full: true has every one.` } : {}),
+        }
+      : {}),
+  };
+}
+
 /** A sweep as the record of when the product was last checked, and whether that check held. */
 const SWEEP_FIELDS = [
   'id',
@@ -206,7 +248,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
             : sweep
               ? { sweep }
               : {}),
-          ...page(pickFields(result.data, FINDING_ROW_FIELDS), result.nextCursor),
+          ...page(pickFields(result.data, FINDING_ROW_FIELDS).map(withFixability), result.nextCursor),
           ...(typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {}),
         });
       })
@@ -217,18 +259,26 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Get a maintenance finding',
       description:
-        'Read one maintenance finding in full: exploit likelihood (EPSS, known-exploited list), advisory and ' +
+        'Read one maintenance finding: exploit likelihood (EPSS, known-exploited list), the advisory summarized ' +
+        '(full: true for its whole record: every affected range and reference) and ' +
         'fixed version, code location, breached policy controls, why it ranks where it does, history ' +
-        "(reintroduced, previously resolved) and the remediation under way. A secret's value is never stored, " +
-        'only the rule and location.',
-      inputSchema: z.object({ findingId }),
+        '(reintroduced, previously resolved) and the remediation under way. fixable: false with fixNote says ' +
+        "taiga_fix_finding would refuse it. A secret's value is never stored, only the rule and location.",
+      inputSchema: z.object({
+        findingId,
+        full: z
+          .boolean()
+          .optional()
+          .describe("Carry the advisory's whole record: every affected range and reference (default false)"),
+      }),
       annotations: READ_ONLY,
     },
     (params) =>
       runTool(async () => {
         // The finding's runId is the sweep that found it, not a coding run:
         // in the product's words runId is what taiga_get_run takes (PRO-2800).
-        const { runId, ...finding } = (await client.getFinding(params.findingId)).data as Row;
+        const { runId, ...raw } = (await client.getFinding(params.findingId)).data as Row;
+        const finding = withFixability(params.full ? raw : { ...raw, data: leanAdvisory(raw['data']) });
         return toolResult(runId === undefined ? finding : { sweepId: runId, ...finding });
       })
   );

package/src/tools/products.ts

@@ -278,7 +278,9 @@ export async function resolveProductRef(
       if (!isMissOrRefusal(error)) throw error;
       return refusal(
         apiFailureCode(error),
-        `No product with that ID the key can see (${apiFailureText(error)}); taiga_list_products shows the ones it can.`
+        error instanceof TaigaApiError && error.status === 404
+          ? 'No product with that ID the key can see; taiga_list_products shows the ones it can.'
+          : `No product with that ID the key can see (${apiFailureText(error)}); taiga_list_products shows the ones it can.`
       );
     }
   }

package/src/tools/repositories.ts

@@ -1,9 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import type { GithubRepository } from '@taiga/types';
-import type { TaigaClient, WithoutTenant } from '../client.js';
+import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
-import { runTool, toolError, toolResult } from './errors.js';
+import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
+import { setupReadiness } from './readiness.js';
 import { idInput, pagination, productId } from './inputs.js';
 import { SEARCH_WITH_CURSOR, page, pickFields } from './summarize.js';
 
@@ -65,6 +66,24 @@ export function interleave<T>(lists: T[][]): T[] {
   return out;
 }
 
+/**
+ * A product in setup says what it still needs after a repository write, as create_product and get_product do
+ * (PRO-2800): a reviewer had to read the product again to learn that the import came next. Best effort: the write
+ * is done, so a failed read leaves readiness out rather than failing it.
+ */
+async function readinessAfter(client: TaigaClient, productId: string): Promise<{ readiness?: unknown }> {
+  try {
+    const readiness = await setupReadiness(
+      client,
+      (await client.getProduct(productId)).data as unknown as Record<string, unknown>
+    );
+    return readiness ? { readiness } : {};
+  } catch (error) {
+    if (error instanceof TaigaApiError || isNetworkFailure(error)) return {};
+    throw error;
+  }
+}
+
 export function registerRepositoryTools(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('products:read')) {
     server.registerTool(
@@ -226,7 +245,10 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
           githubRepositoryId: params.githubRepositoryId,
           ...(params.replacesRepositoryId ? { replacesRepositoryId: params.replacesRepositoryId } : {}),
         });
-        return toolResult(pickFields([linked.data], LINK_FIELDS)[0]);
+        return toolResult({
+          ...pickFields([linked.data], LINK_FIELDS)[0],
+          ...(await readinessAfter(client, params.productId)),
+        });
       })
   );
 
@@ -267,6 +289,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         return toolResult({
           ...pickFields([updated], LINK_FIELDS)[0],
           baseBranchProtection: updated.baseBranchProtection ?? null,
+          ...(await readinessAfter(client, params.productId)),
         });
       })
   );

package/src/tools/setup.ts

@@ -85,7 +85,7 @@ 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 }>(
+async function firstNamed<T extends { id: string; name: string; slug?: string; createdAt?: unknown }>(
   name: string,
   read: (cursor: string | undefined) => Promise<{ data: T[]; nextCursor: string | null }>
 ): Promise<T | null> {
@@ -104,11 +104,20 @@ async function firstNamed<T extends { id: string; name: string; slug?: string }>
   return null;
 }
 
-function duplicateName(kind: 'factory' | 'product', existing: { id: string; name: string; slug?: string }) {
+/**
+ * The refusal names the one that exists and leaves the choice to the person: another session may have made it, so
+ * "use it" would hand the agent someone else's work (PRO-2800, review 6).
+ */
+function duplicateName(
+  kind: 'factory' | 'product',
+  existing: { id: string; name: string; slug?: string; createdAt?: unknown },
+  where: string
+) {
+  const made = typeof existing.createdAt === 'string' ? `, created ${existing.createdAt}` : '';
   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.',
+    `A ${kind} named "${existing.name}" already exists ${where} (${existing.id}${made}). It may not be this ` +
+      "person's: ask whether they meant that one, want another name, or want a second (allowDuplicateName: true).",
     { existingId: existing.id, ...(existing.slug ? { existingSlug: existing.slug } : {}) }
   );
 }
@@ -179,7 +188,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
         runTool(async () => {
           if (!params.allowDuplicateName) {
             const same = await firstNamed(params.name, async (cursor) => client.listFactories({ limit: 100, cursor }));
-            if (same) return duplicateName('factory', same);
+            if (same) return duplicateName('factory', same, 'in this organization');
           }
           return toolResult(pickFields([(await client.createFactory({ name: params.name })).data], FACTORY_FIELDS)[0]);
         })
@@ -279,10 +288,10 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Create a product',
       description:
-        '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 ' +
+        'Create a product in a factory and return it with readiness (what it needs next). start cannot change ' +
+        'later. import (brownfield): Taiga drafts the documents from existing code; link it with ' +
+        'taiga_link_repository (owners and admins only), then taiga_start_import. scratch (greenfield): Discovery ' +
+        'is a conversation in the web that writes the specification. 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({
@@ -300,8 +309,11 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
         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);
+          // Within the factory it goes into: the same name in another factory is a different product.
+          const same = await firstNamed(params.name, async (cursor) =>
+            client.listProducts({ factoryId: params.factoryId, limit: 100, cursor })
+          );
+          if (same) return duplicateName('product', same, 'in this factory');
         }
         const product = (
           await client.createProduct({