@taiga-ai/mcp-server 0.22.0-dev.457 → 0.23.0-dev.459

package/src/tools/inbox.ts

@@ -46,17 +46,66 @@ function waitedUntil(resolvedAt: unknown, now: number): number {
   return Number.isNaN(at) ? now : at;
 }
 
+/**
+ * The read that opens an item's subject (PRO-2800): rows carried subjectType and subjectId, and the reviewing agent
+ * had to infer which tool takes them.
+ */
+function readWith(row: Row, backlogRead: boolean): string | undefined {
+  switch (row['subjectType']) {
+    case 'build_run':
+      return 'taiga_get_run (runId: subjectId)';
+    case 'backlog_item':
+      // Only a tool the key has: the backlog reads need backlog:read.
+      return backlogRead ? 'taiga_get_plan (initiativeId: subjectId)' : undefined;
+    case 'product_document':
+      return 'taiga_list_product_documents (productId)';
+    case 'inbox_task':
+      return 'taiga_list_setup_tasks (productId)';
+    case 'product':
+      return {
+        // Open, not one column: the item stands while one sits in backlog or todo.
+        review_backlog: backlogRead ? 'taiga_list_initiatives (productId)' : undefined,
+        review_maintenance: 'taiga_list_findings (productId)',
+        review_policy: 'taiga_get_policy_standing (productId)',
+        review_doc: 'taiga_list_product_documents (productId)',
+      }[String(row['kind'])];
+    default:
+      return undefined;
+  }
+}
+
+/** A summary past its first sentence: review_doc rows quoted two documents, 800 to 1,200 characters each. */
+const SUMMARY_LIMIT = 200;
+
+function firstSentence(text: unknown): unknown {
+  if (typeof text !== 'string') return text;
+  // The opening paragraph, as far as SUMMARY_LIMIT: a list after a colon ("could not resolve:\n1. ...") is where
+  // the quoted documents start, and a short summary keeps its second sentence ("N manual setup tasks flagged").
+  const head = text.split(/\n/)[0]!.trim();
+  if (head.length <= SUMMARY_LIMIT)
+    return head.length < text.trim().length ? `${head} (full: true has the rest)` : head;
+  const cut = head.slice(0, SUMMARY_LIMIT);
+  const end = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('; '));
+  return `${end > 40 ? cut.slice(0, end + 1) : cut}... (full: true has the rest)`;
+}
+
 /** A row as an agent reads it: the pull request to open when there is one, and how many days it has waited. */
-function itemRow(row: Row, now: number, full: boolean): Row {
+function itemRow(row: Row, now: number, full: boolean, backlogRead: boolean): Row {
   const picked = pickFields([row], ITEM_FIELDS)[0]!;
   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;
+  // Fields at their usual value say nothing: open, not blocking (the org-wide page repeated them on every row).
+  const { summary, status, blocking, ...lean } = rest;
+  const read = readWith(row, backlogRead);
   return {
-    ...(row['kind'] === 'review_pr' && !full ? lean : { ...lean, summary }),
+    ...lean,
+    ...(full ? { summary } : row['kind'] === 'review_pr' ? {} : { summary: firstSentence(summary) }),
+    ...(full || status !== 'open' ? { status } : {}),
+    ...(full || blocking === true ? { blocking } : {}),
+    ...(read ? { readWith: read } : {}),
     ...(snoozedUntil ? { snoozedUntil } : {}),
     ...(resolvedAt ? { resolvedAt } : {}),
     ...(typeof metadata['prUrl'] === 'string' ? { prUrl: metadata['prUrl'] } : {}),
@@ -144,7 +193,7 @@ async function staleReviews(
 }
 
 /**
- * "Review Initiatives" items whose product has no open initiative left (PRO-2800): two reviews found one
+ * "Review Initiatives" items whose product has no initiative left in its backlog or todo column (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.
  */
@@ -166,13 +215,23 @@ async function staleBacklogReviews(client: TaigaClient, rows: Row[], out: Map<st
   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);
+        // The item asks for initiatives to be reviewed before they are planned: it stands while one sits in the
+        // backlog or todo column. Read by column, not status: status stays in_progress after a first run even when
+        // the initiative is moved back to todo, and one in Build is past review.
+        const pages = await Promise.all(
+          (['backlog', 'in_progress'] as const).map((status) =>
+            client.listBacklogItems(productId, { status, limit: 100 })
+          )
+        );
+        const waiting = pages.some((page) =>
+          page.data.some((item) => item.state === 'backlog' || item.state === 'todo')
+        );
+        if (waiting) return;
+        if (pages.some((page) => page.nextCursor)) {
+          unchecked += asks.filter((row) => row['productId'] === productId).length;
+          return;
+        }
+        empty.add(productId);
       } catch (error) {
         if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
         unchecked += asks.filter((row) => row['productId'] === productId).length;
@@ -181,12 +240,48 @@ async function staleBacklogReviews(client: TaigaClient, rows: Row[], out: Map<st
   );
   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');
+      out.set(String(row['id']), 'no initiative is in the backlog or todo now: the ones it asked about have moved on');
     }
   }
   return unchecked;
 }
 
+/**
+ * One product's Action Required as counts, the way the list's summary counts them: open is what still stands and is
+ * not put off, stale and snoozed are counted apart. The product context reports these, so the two reads agree.
+ */
+export async function attentionCounts(
+  client: TaigaClient,
+  rows: Row[]
+): Promise<{ open: number; byKind: Record<string, number>; stale?: number; snoozed?: number; staleNote?: string }> {
+  const now = Date.now();
+  const due = rows.filter((row) => isDue(row, now));
+  const { stale, unchecked } = await staleReviews(client, due);
+  const [entry] = summaryOf(due, stale);
+  const snoozed = rows.length - due.length;
+  return {
+    open: entry ? Number(entry['open']) : 0,
+    byKind: entry ? (entry['byKind'] as Record<string, number>) : {},
+    ...(entry && typeof entry['stale'] === 'number' ? { stale: entry['stale'] } : {}),
+    ...(snoozed > 0 ? { snoozed } : {}),
+    // Past the cap a review is counted open: say so, as the list does.
+    ...(unchecked > 0
+      ? {
+          staleNote: `${unchecked} review${unchecked === 1 ? ' was' : 's were'} not checked for staleness and count as open.`,
+        }
+      : {}),
+  };
+}
+
+/** An item the team has not put off: the page hides one until its snooze ends, and so does this. */
+function isDue(row: Row, now: number): boolean {
+  return !(
+    row['status'] === 'snoozed' &&
+    typeof row['snoozedUntil'] === 'string' &&
+    Date.parse(row['snoozedUntil']) > now
+  );
+}
+
 /** Pages read for the summary; past this it says it counted only those. */
 const SUMMARY_PAGE = 100;
 
@@ -270,8 +365,10 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'List what waits on a person (Action Required), across every product the key can open or one; the list ' +
         "is the team's. Reviews (plans, initiative sets, documents, pull requests, findings, policy violations) " +
         'and setup only a person can do (secrets, variables, accounts, permissions). The first page opens with ' +
-        'summary (open items by product and kind) and totalCount. Rows carry waitingDays and, for a pull ' +
-        'request, prUrl; a review that no longer stands is marked stale. category: gate or setup; resolved: true ' +
+        'summary (open items by product and kind; stale ones apart) and totalCount. Rows carry waitingDays, ' +
+        'readWith (the read that opens the subject), summary (its opening paragraph, up to 200 characters; none ' +
+        'on a pull request review, whose title says it) and, for a pull request, prUrl; ' +
+        'status and blocking appear when not open or when blocking; a review that no longer stands is marked stale. category: gate or setup; resolved: true ' +
         'reads the archive; snoozed items are hidden (snoozedHidden); full: true adds metadata. Unlike ' +
         'taiga_list_setup_tasks, which says exactly what to set and where.',
       inputSchema: z.object({
@@ -311,16 +408,11 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         // one until its snooze ends, and so does this, so an agent does not
         // act on what the team put off.
         const now = Date.now();
-        const isDue = (row: Row) =>
-          !(
-            row['status'] === 'snoozed' &&
-            typeof row['snoozedUntil'] === 'string' &&
-            Date.parse(row['snoozedUntil']) > now
-          );
+        const due_ = (row: Row) => isDue(row, now);
         const rows = result.data as Row[];
-        const due = rows.filter(isDue);
+        const due = rows.filter(due_);
         const hidden = rows.length - due.length;
-        const overviewDue = overview ? (overview.data as Row[]).filter(isDue) : [];
+        const overviewDue = overview ? (overview.data as Row[]).filter(due_) : [];
         const checked = resolved
           ? { stale: new Map<string, string>(), unchecked: 0 }
           : await staleReviews(client, [...due, ...overviewDue]);
@@ -334,7 +426,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
             : {}),
           ...page(
             due.map((row) => {
-              const item = itemRow(row, now, full === true);
+              const item = itemRow(row, now, full === true, client.hasCapability('backlog:read'));
               const why = stale.get(String(row['id']));
               return why ? { ...item, stale: why } : item;
             }),

package/src/tools/instructions.ts

@@ -10,30 +10,31 @@
  * (PRO-2800).
  */
 export const SERVER_INSTRUCTIONS = [
-  'Taiga is a policy-aware software delivery platform. Use these tools (taiga_*) whenever the person asks about a',
-  'Taiga product, its initiatives or runs, policies, findings, deployments, or setting a product up.',
+  'Taiga is a policy-aware software delivery platform. Use these tools (taiga_*) when the person asks about a Taiga',
+  'product, its initiatives or runs, policies, findings, deployments, or setting a product up.',
   '',
-  '**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 which tools write: taiga_whoami.",
+  '**Which read.** Where a product stands (counts, not detail): 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: [], or a',
+  'control id such as SEC-5.1). Findings: taiga_list_findings. One initiative or run: taiga_get_initiative,',
+  'taiga_get_run. Which tools this key may call: 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",
-  'coding agent; hardening is its pass of security scans and fixes; handed back means the agent stopped and a person',
-  'must act. A factory owns products. People stamp checks in the web. IDs are UUIDs, never names; a NOT_FOUND names',
-  'the tool that lists them, and a GitHub repository id is not a repository link id.',
+  '**Words.** An initiative is a unit of work, on a board of columns (backlog, todo, queue, plan, build, done,',
+  'canceled); the plan and build columns are stations. The line works the queue one initiative at a time. A run is',
+  'one coding-agent attempt; hardening is its security pass; handed back means a person must act. A gate is a review',
+  'a person makes; a sweep is a scan for findings; standing is how a product meets the policies. Discovery is the web',
+  'conversation that specifies a new product. A factory owns products. People stamp checks in the web.',
   '',
-  '**Reading.** Lists page with nextCursor. A document has two timelines: plan (what was meant) and reality',
-  '(derived from the code). outcome, situation and nextStep are one-sentence summaries of their record.',
+  '**IDs** are UUIDs; the product, factory and initiative lists take query to find one by name. A NOT_FOUND names the tool that lists the right',
+  'ones. Lists page with nextCursor. outcome, situation and nextStep are one-sentence summaries; setup writes',
+  'return readiness with nextStep, so there is no need to read the product again. A product document has two',
+  'timelines: plan (what was meant) and reality (derived from the code).',
   '',
-  '**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. 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.",
+  '**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 and wait for their yes. Others share the organization: a',
+  "taken name 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.',
+  '**Only in the web:** connecting GitHub, members and roles, Discovery, stamping checks, starting a run over, and',
+  'deleting factories and products.',
 ].join('\n');
 
 /** The most the instructions may take: Claude Code cuts each server's at 2,048 characters. */

package/src/tools/maintenance.ts

@@ -326,6 +326,17 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
               'all-clear. An assessment runs when the reality documents are derived or refreshed ' +
               '(taiga_refresh_reality_documents, paid work: ask first).'
             : null;
+        // Each assessment refreshes a violation's evidence but rewords its title and summary only when it
+        // re-describes the gap, so the words can describe code the evidence says is gone (PRO-2810). Said once.
+        const resolvedAny = Array.isArray(standing.resolvedDivergences) && standing.resolvedDivergences.length > 0;
+        const wording =
+          violations.length > 0 || resolvedAny
+            ? {
+                wordingNote:
+                  "A violation's evidence is from its assessedAt; its title and summary may be from when it was " +
+                  'first recorded. Where they disagree, the evidence is current.',
+              }
+            : {};
         if (params.violationId) {
           const one = [
             ...violations,
@@ -337,7 +348,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
               'No violation with that ID on this product; this tool without violationId lists them.'
             );
           }
-          return toolResult(one);
+          return toolResult({ ...(one as Row), ...wording });
         }
         // The full form ran to 228k characters on a product with eleven violations (PRO-2800): each text is
         // cut and the resolved list bounded; violationId reads one whole.
@@ -346,6 +357,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
           return toolResult({
             summary,
             ...(note ? { note } : {}),
+            ...wording,
             ...standing,
             // Only the controls something is recorded against, as the summary answer lists them.
             controls: listed,
@@ -359,6 +371,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         return toolResult({
           summary,
           ...(note ? { note } : {}),
+          ...wording,
           productId: standing.productId,
           hasPolicies: standing.hasPolicies,
           assessment: standing.assessment,

package/src/tools/products.ts

@@ -323,6 +323,30 @@ export async function resolveProductRef(
   return { product: products[0]! };
 }
 
+/**
+ * NOT_FOUND for a factory ID the key cannot see; null when it exists or the read failed. A key that cannot read
+ * factories cannot tell an empty factory from a wrong ID, and the answer says so.
+ */
+async function factoryMissing(client: TaigaClient, factoryId: string) {
+  if (!client.hasCapability('factories:read')) {
+    return toolResult({
+      data: [],
+      nextCursor: null,
+      note: 'No products here. This key cannot read factories, so whether that factoryId exists was not checked.',
+    });
+  }
+  try {
+    await client.getFactory(factoryId);
+    return null;
+  } catch (error) {
+    if (error instanceof TaigaApiError && error.status === 404) {
+      return toolError('NOT_FOUND', 'Factory not found. taiga_list_factories lists the factories the key can see.');
+    }
+    if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
+    throw error;
+  }
+}
+
 export function registerProductTools(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('factories:read')) {
     server.registerTool(
@@ -387,6 +411,11 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           const { query: text, ...filters } = params;
           if (text === undefined) {
             const result = await client.listProducts(filters);
+            // A factory that does not exist is a miss, as everywhere else, not an empty factory (PRO-2800).
+            if (result.data.length === 0 && filters.factoryId && !filters.cursor) {
+              const missing = await factoryMissing(client, filters.factoryId);
+              if (missing) return missing;
+            }
             return toolResult(
               page(await withFactoryNames(client, pickFields(result.data, PRODUCT_SUMMARY_FIELDS)), result.nextCursor)
             );
@@ -404,6 +433,10 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
             (row) => [row.name, row.slug],
             params.limit ?? 25
           );
+          if (found.rows.length === 0 && filters.factoryId) {
+            const missing = await factoryMissing(client, filters.factoryId);
+            if (missing) return missing;
+          }
           return toolResult({
             ...page(await withFactoryNames(client, pickFields(found.rows, PRODUCT_SUMMARY_FIELDS)), null),
             ...(found.more ? { more: SEARCH_NOTE } : {}),

package/src/tools/repositories.ts

@@ -132,7 +132,8 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         title: 'Find a repository to link',
         description:
           "List the repositories the organization's GitHub connection can reach, to link one with " +
-          'taiga_link_repository (it takes the id). query searches by name; account (login, owner, or ' +
+          "taiga_link_repository (it takes the row's id: Taiga's record of the repository, not GitHub's numeric " +
+          'id, and not a link ID). query searches by name; account (login, owner, or ' +
           'installationId) reads one account, else rows come from every account in turn. linked: true means a ' +
           'product already links it (taiga_get_product with its URL says which). No connection means GitHub is not ' +
           'connected yet; someone who can install the app does that once, in the web.',
@@ -194,7 +195,8 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
             });
             const found = rows(result.data);
             return toolResult({
-              accounts,
+              // The account asked for, not every connected one (PRO-2800).
+              accounts: params.account || params.installationId ? pickFields(chosen, INSTALLATION_FIELDS) : accounts,
               repositories: page(found.slice(0, max), result.nextCursor),
               ...(found.length > max
                 ? { more: 'More matched than the limit; narrow the query or raise the limit.' }
@@ -234,7 +236,10 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         'history is imported.',
       inputSchema: z.object({
         productId,
-        githubRepositoryId: idInput('GitHub repository', 'taiga_list_linkable_repositories gives it'),
+        githubRepositoryId: idInput(
+          'GitHub repository',
+          "taiga_list_linkable_repositories gives it (the row's id, Taiga's record; not GitHub's numeric id)"
+        ),
         replacesRepositoryId: repositoryId.optional().describe('The link this one replaces'),
       }),
       annotations: OPERATE,