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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.22.0-dev.457",
+  "version": "0.23.0-dev.459",
   "description": "MCP server for Taiga -- gives AI assistants access to documents and products",
   "type": "module",
   "main": "./dist/index.js",

package/src/server.integration.test.ts

@@ -2009,6 +2009,8 @@ describe('MCP server integration', () => {
       expect(bundle.initiatives.items.map((row: { id: string }) => row.id)).toEqual([ITEM_ID]);
       expect(bundle.initiatives.items[0]).not.toHaveProperty('description');
       expect(bundle.initiatives.truncated).toBe(false);
+      // Every open column, zeros too, so an empty backlog reads as empty (PRO-2800).
+      expect(bundle.initiatives.byColumn).toEqual({ backlog: 0, todo: 0, queue: 0, plan: 0, build: 1 });
       expect(bundle.repositories).toEqual({
         items: [
           {
@@ -2033,7 +2035,8 @@ describe('MCP server integration', () => {
         },
       ]);
       // PRO-2800: "how does it stand" in the same call, as counts.
-      expect(bundle.actionRequired).toEqual({ open: 3, byKind: { review_pr: 2, setup_secret: 1 }, snoozed: 1 });
+      // Counted as the Action Required summary counts: a put-off item is snoozed, not open (PRO-2800).
+      expect(bundle.actionRequired).toEqual({ open: 2, byKind: { review_pr: 2 }, snoozed: 1 });
       expect(bundle.maintenance).toEqual({
         openFindings: 1,
         bySeverity: { critical: 0, high: 1 },
@@ -3546,6 +3549,7 @@ describe('MCP server integration', () => {
         initiativeId: ITEM_ID,
         status: 'stopped',
         failedReason: 'user_stopped',
+        failedReasonMeans: 'it was stopped, by a person or because its initiative was settled',
         completedSteps: 1,
         totalSteps: 3,
         prUrl: null,
@@ -6296,7 +6300,8 @@ describe('MCP server integration', () => {
         await client.callTool({ name: 'taiga_list_linkable_repositories', arguments: { installationId: INSTALL_ID_2 } })
       );
 
-      expect(found.accounts.map((a: { accountLogin: string }) => a.accountLogin)).toEqual(['acme', 'acme-labs']);
+      // Only the account asked for (PRO-2800): the others were noise on every filtered call.
+      expect(found.accounts.map((a: { accountLogin: string }) => a.accountLogin)).toEqual(['acme-labs']);
       expect(found.repositories).toEqual({ data: [], nextCursor: null });
       expect(sentUrl(fetchSpy, 'cursor=p2').searchParams.get('limit')).toBe('100');
     });
@@ -8069,8 +8074,15 @@ describe('what the fourth agent review found (PRO-2800)', () => {
           ],
           nextCursor: null,
         },
-        [`GET /v1/products/${PRODUCT_ID}/backlog`]: { data: [], nextCursor: null },
-        [`GET /v1/products/${OTHER}/backlog`]: { data: [{ id: 'b1', status: 'backlog' }], nextCursor: null },
+        // One initiative in Build is past review; the other product's one in todo still waits on it.
+        [`GET /v1/products/${PRODUCT_ID}/backlog`]: {
+          data: [{ id: 'b0', status: 'in_progress', state: 'build' }],
+          nextCursor: null,
+        },
+        [`GET /v1/products/${OTHER}/backlog`]: {
+          data: [{ id: 'b1', status: 'in_progress', state: 'todo' }],
+          nextCursor: null,
+        },
       },
     });
 
@@ -8080,7 +8092,7 @@ describe('what the fourth agent review found (PRO-2800)', () => {
     );
 
     expect(list.data.map((row: { id: string; stale?: string }) => [row.id, row.stale ?? null])).toEqual([
-      ['emptied', 'no initiative is open now: the ones it asked about are all done or canceled'],
+      ['emptied', 'no initiative is in the backlog or todo now: the ones it asked about have moved on'],
       ['waiting', null],
       ['pr', null],
     ]);
@@ -8363,3 +8375,218 @@ describe('what the fourth agent review found (PRO-2800)', () => {
     expect(me.capabilities.some((capability: string) => /^(projects|teams):/.test(capability))).toBe(false);
   });
 });
+
+describe('what the sixth agent review found (PRO-2800)', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('keeps Action Required rows to what differs, a sentence of summary, and the read that opens each', async () => {
+    const row = (id: string, kind: string, subjectType: string, extra: Record<string, unknown> = {}) => ({
+      id,
+      productId: PRODUCT_ID,
+      kind,
+      subjectType,
+      subjectId: 'x',
+      title: id,
+      summary: 'First sentence here. ' + 'Quoted document text. '.repeat(40),
+      status: 'open',
+      blocking: false,
+      createdAt: new Date().toISOString(),
+      ...extra,
+    });
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read', 'backlog:read'],
+      routes: {
+        'GET /v1/inbox': {
+          data: [
+            row('doc', 'review_doc', 'product_document', {
+              summary:
+                'The architecture document has 2 issues it could not resolve:\n1. This document says ' +
+                'x'.repeat(900),
+            }),
+            row('plan', 'review_plan', 'backlog_item', { blocking: true }),
+            row('task', 'setup_secret', 'inbox_task', { status: 'in_progress' }),
+          ],
+          nextCursor: null,
+        },
+      },
+    });
+
+    const list = parseToolResult(await client.callTool({ name: 'taiga_list_action_required', arguments: {} }));
+    const full = parseToolResult(
+      await client.callTool({ name: 'taiga_list_action_required', arguments: { full: true } })
+    );
+
+    const [doc, plan, task] = list.data;
+    // The opening paragraph, not the quoted list after it; a long one cut at a sentence.
+    expect(doc.summary).toBe('The architecture document has 2 issues it could not resolve: (full: true has the rest)');
+    expect(plan.summary).toMatch(/^First sentence here\. Quoted document text\..*\.\.\. \(full: true has the rest\)$/);
+    expect(plan.summary.length).toBeLessThan(240);
+    expect(doc).not.toHaveProperty('status');
+    expect(doc).not.toHaveProperty('blocking');
+    expect(doc.readWith).toBe('taiga_list_product_documents (productId)');
+    expect(plan.blocking).toBe(true);
+    expect(plan.readWith).toBe('taiga_get_plan (initiativeId: subjectId)');
+    expect(task.status).toBe('in_progress');
+    expect(task.readWith).toBe('taiga_list_setup_tasks (productId)');
+    expect(full.data[0].summary.length).toBeGreaterThan(500);
+    expect(full.data[0].status).toBe('open');
+
+    // Without backlog:read the initiative reads are not offered, so no row names one.
+    const { client: productsOnly } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        'GET /v1/inbox': { data: [row('plan', 'review_plan', 'backlog_item')], nextCursor: null },
+      },
+    });
+    const bare = parseToolResult(await productsOnly.callTool({ name: 'taiga_list_action_required', arguments: {} }));
+    expect(bare.data[0]).not.toHaveProperty('readWith');
+  });
+
+  it("says once that a violation's words may be older than its evidence", async () => {
+    const VIOLATION = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4f0a';
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        [`GET /v1/products/${PRODUCT_ID}/maintenance/policies`]: {
+          data: {
+            productId: PRODUCT_ID,
+            controls: [{ controlId: 'SEC-5.1', divergenceCount: 1 }],
+            divergences: [{ id: VIOLATION, controlId: 'SEC-5.1', severity: 'high', title: 'Old words' }],
+            resolvedDivergences: [],
+          },
+        },
+      },
+    });
+
+    const standing = parseToolResult(
+      await client.callTool({ name: 'taiga_get_policy_standing', arguments: { productId: PRODUCT_ID } })
+    );
+    const one = parseToolResult(
+      await client.callTool({
+        name: 'taiga_get_policy_standing',
+        arguments: { productId: PRODUCT_ID, violationId: VIOLATION },
+      })
+    );
+
+    expect(standing.wordingNote).toMatch(/^A violation's evidence is from its assessedAt/);
+    expect(one.wordingNote).toBe(standing.wordingNote);
+
+    // Resolved violations carry the same words, so a product with only those says it too.
+    const { client: resolvedOnly } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        [`GET /v1/products/${PRODUCT_ID}/maintenance/policies`]: {
+          data: { productId: PRODUCT_ID, controls: [], divergences: [], resolvedDivergences: [{ id: VIOLATION }] },
+        },
+      },
+    });
+    const closed = parseToolResult(
+      await resolvedOnly.callTool({ name: 'taiga_get_policy_standing', arguments: { productId: PRODUCT_ID } })
+    );
+    expect(closed.wordingNote).toBe(standing.wordingNote);
+  });
+
+  it('refuses a board column and a status that cannot meet', async () => {
+    const { client } = await bootMcpPair({ capabilities: ['backlog:read'] });
+
+    const result = parseToolResult(
+      await client.callTool({
+        name: 'taiga_list_initiatives',
+        arguments: { productId: PRODUCT_ID, state: 'backlog', status: 'done' },
+      })
+    );
+
+    expect(result).toMatchObject({ error: 'VALIDATION_ERROR' });
+    expect(result.message).toMatch(/^No initiative is in the backlog column with status done/);
+  });
+
+  it('answers a factory that does not exist with NOT_FOUND, not an empty list', async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read', 'factories:read'],
+      routes: {
+        'GET /v1/products': { data: [], nextCursor: null },
+        [`GET /v1/factories/${FACTORY_ID}`]: refusal(404, 'NOT_FOUND', 'Factory not found'),
+      },
+    });
+
+    const result = parseToolResult(
+      await client.callTool({ name: 'taiga_list_products', arguments: { factoryId: FACTORY_ID } })
+    );
+    const searched = parseToolResult(
+      await client.callTool({ name: 'taiga_list_products', arguments: { factoryId: FACTORY_ID, query: 'web' } })
+    );
+
+    expect(result).toMatchObject({ error: 'NOT_FOUND' });
+    expect(result.message).toMatch(/taiga_list_factories/);
+    expect(searched).toMatchObject({ error: 'NOT_FOUND' });
+
+    // A key that cannot read factories says it could not check, rather than answer an unexplained empty list.
+    const { client: productsOnly } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: { 'GET /v1/products': { data: [], nextCursor: null } },
+    });
+    const unchecked = parseToolResult(
+      await productsOnly.callTool({ name: 'taiga_list_products', arguments: { factoryId: FACTORY_ID } })
+    );
+    expect(unchecked.data).toEqual([]);
+    expect(unchecked.note).toMatch(/cannot read factories/);
+  });
+
+  it('names the branch list when a branch does not exist', async () => {
+    const LINK = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4f09';
+    const { client } = await bootMcpPair({
+      capabilities: ALL_CAPABILITIES,
+      routes: {
+        [`PATCH /v1/products/${PRODUCT_ID}/repositories/${LINK}`]: refusal(
+          400,
+          'VALIDATION_ERROR',
+          'Branch "mian" does not exist in acme/web'
+        ),
+      },
+    });
+
+    const result = parseToolResult(
+      await client.callTool({
+        name: 'taiga_set_repository_branch',
+        arguments: { productId: PRODUCT_ID, repositoryId: LINK, baseBranch: 'mian' },
+      })
+    );
+
+    expect(result.message).toBe(
+      'Branch "mian" does not exist in acme/web. taiga_list_repository_branches lists the branches it has.'
+    );
+  });
+
+  it('says what a failure reason means and that hardening left blocking findings, without the runtime', async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        [`/v1/builds/${BUILD_ID}/steps`]: { data: [] },
+        [`/v1/builds/${BUILD_ID}`]: {
+          data: {
+            id: BUILD_ID,
+            productId: PRODUCT_ID,
+            status: 'failed',
+            failedReason: 'dispatch_rejected',
+            runtime: 'legacy',
+            completedSteps: 0,
+            totalSteps: 3,
+            hardeningResult: { passed: false, scanners: {}, blockingFindings: 1, advisoryFindings: 0 },
+          },
+        },
+      },
+    });
+
+    const run = parseToolResult(await client.callTool({ name: 'taiga_get_run', arguments: { runId: BUILD_ID } }));
+
+    expect(run.failedReasonMeans).toBe(
+      'the agent never started (its environment or credentials failed); resuming dispatches it again'
+    );
+    expect(run.hardeningNote).toBe(
+      'Hardening ended with 1 blocking finding it could not fix; the run records how many, not which.'
+    );
+    expect(run).not.toHaveProperty('runtime');
+  });
+});

package/src/tools/backlogs.ts

@@ -259,6 +259,17 @@ const outcomeOf = (item: Item) =>
 
 const outcome = (item: Item) => toolResult(outcomeOf(item));
 
+/** The statuses an initiative in each board column can have: the API keeps in_progress after a first run. */
+const COLUMN_STATUSES: Record<(typeof INITIATIVE_STATES)[number], readonly string[]> = {
+  backlog: ['all', 'open', 'backlog', 'in_progress'],
+  todo: ['all', 'open', 'backlog', 'in_progress'],
+  queue: ['all', 'open', 'backlog', 'in_progress'],
+  plan: ['all', 'open', 'backlog', 'in_progress'],
+  build: ['all', 'open', 'in_progress'],
+  done: ['all', 'done'],
+  canceled: ['all', 'canceled'],
+};
+
 /**
  * Each tool is registered under the capability its route requires, so a
  * key sees exactly what it may call: reads on backlog:read; the board move on
@@ -335,6 +346,13 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const { query, state, status = state === undefined ? 'open' : 'all', ...filters } = params;
+        // A column and a status that cannot meet answered an empty list with no complaint (PRO-2800).
+        if (state !== undefined && !COLUMN_STATUSES[state].includes(status)) {
+          return toolError(
+            'VALIDATION_ERROR',
+            `No initiative is in the ${state} column with status ${status}: pass state alone, or a status it can have (${COLUMN_STATUSES[state].join(', ')}).`
+          );
+        }
         // Two reviews asked "what is in the backlog" and got the whole history, done and canceled first
         // (PRO-2800): open is the default. The API filters by one status only, so open, a board column and a
         // title are read across pages here.

package/src/tools/builds.ts

@@ -24,7 +24,6 @@ export const BUILD_SUMMARY_FIELDS = [
   'planId',
   'status',
   'failedReason',
-  'runtime',
   'repositoryFullName',
   'branch',
   'baseBranch',
@@ -223,6 +222,20 @@ export function runOutcome(run: Record<string, unknown>): { disposition: string;
   return { disposition, outcome: sentence[disposition] ?? status };
 }
 
+/**
+ * What each failedReason means for the next move (PRO-2800): reviewers met dispatch_rejected and agent_reported as
+ * bare enums. As @taiga/types documents them.
+ */
+const FAILED_REASON_MEANS: Record<string, string> = {
+  agent_reported: 'the agent stopped and said why (error); resuming would likely hit the same wall',
+  server_orphan: 'the run stopped reporting (its machine died or ran out of memory); resuming can recover',
+  agent_stalled: 'the agent kept running but stopped making progress; resuming can recover',
+  user_stopped: 'it was stopped, by a person or because its initiative was settled',
+  timeout: 'it ran past its time limit; resuming continues from the unfinished step',
+  dispatch_rejected: 'the agent never started (its environment or credentials failed); resuming dispatches it again',
+  context_exhaustion: 'the agent ran out of context on a step; resuming starts that step fresh',
+};
+
 /**
  * A run row as an agent reads it: its outcome added, and prDraft only where
  * there is a pull request. The column defaults to true, so a run that never
@@ -230,10 +243,20 @@ export function runOutcome(run: Record<string, unknown>): { disposition: string;
  * text out: its first sentence is in the outcome, and taiga_get_run has it all.
  */
 export function readableRun(run: Record<string, unknown>, opts: { row?: boolean } = {}): Record<string, unknown> {
-  const { prDraft, error, reviewEscalation, ...rest } = run;
+  // runtime names the machinery a run used (legacy or engineer): nothing an agent acts on.
+  const { prDraft, error, reviewEscalation, runtime: _runtime, ...rest } = run;
   const said = runOutcome(run);
+  const means = FAILED_REASON_MEANS[String(run['failedReason'])];
+  const hardening = run['hardeningResult'] as { blockingFindings?: unknown } | null | undefined;
+  const blocking = typeof hardening?.blockingFindings === 'number' ? hardening.blockingFindings : 0;
   return {
     ...rest,
+    ...(means ? { failedReasonMeans: means } : {}),
+    ...(blocking > 0
+      ? {
+          hardeningNote: `Hardening ended with ${blocking} blocking finding${blocking === 1 ? '' : 's'} it could not fix; the run records how many, not which.`,
+        }
+      : {}),
     // A row's outcome says the error and the handback; the full read keeps them whole.
     ...(opts.row || error === undefined ? {} : { error }),
     ...(opts.row || reviewEscalation === undefined ? {} : { reviewEscalation }),
@@ -514,7 +537,8 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         'Read one run with its steps: outcome, disposition, pull request, hardening, and per step its title, ' +
         "status, commit, files changed, verification and headline (first paragraph of the agent's report). " +
         "verification is Taiga's own check after the step (tests, lint, build), so a docs-only step can fail on " +
-        "the repository's failing tests. A failed or stopped run has stoppedIn and lastProgressAt. full: true " +
+        "the repository's failing tests (verificationNote says when one failed throughout). A failed or stopped " +
+        'run has stoppedIn, lastProgressAt and failedReasonMeans (what its failedReason means). full: true ' +
         'adds complete instructions and reports. actions: resume and retry_from_failed_step are ' +
         'taiga_resume_initiative; start_over is web only; to stop it, move the initiative out of Build. A ' +
         'maintenance run has no initiative and is retried from its finding.',

package/src/tools/context.ts

@@ -31,6 +31,7 @@ import { pickFields } from './summarize.js';
 import { initiativeStates, readableRow, withInitiativeState } from './builds.js';
 import { setupReadiness } from './readiness.js';
 import { standingSummary } from './maintenance.js';
+import { attentionCounts } from './inbox.js';
 
 /**
  * One call at the start of a coding session: everything the model would
@@ -301,7 +302,11 @@ async function backlogPart(client: TaigaClient, productId: string) {
     String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0
   );
   if (rows.length > BACKLOG_IN_CONTEXT) truncated = true;
+  // Every open column counted, zeros too: two reviews could not tell an empty backlog from a cut list (PRO-2800).
+  const byColumn: Record<string, number> = { backlog: 0, todo: 0, queue: 0, plan: 0, build: 0 };
+  for (const row of rows) if (row.state) byColumn[row.state] = (byColumn[row.state] ?? 0) + 1;
   return {
+    byColumn,
     items: situatedRows(rows.slice(-BACKLOG_IN_CONTEXT)),
     truncated,
     // The list pages oldest first and takes no order, so a status past the
@@ -311,7 +316,7 @@ async function backlogPart(client: TaigaClient, productId: string) {
       ? {
           note:
             `More than ${BACKLOG_PAGE_LIMIT * 100} open items in one status: only the oldest of them were read, so ` +
-            'the newest may be missing here; taiga_list_initiatives pages the rest.',
+            'the newest may be missing here and byColumn counts only those read; taiga_list_initiatives pages the rest.',
         }
       : {}),
   };
@@ -338,28 +343,17 @@ async function buildsPart(client: TaigaClient, productId: string) {
 }
 
 /**
- * What waits on a person for this product, counted by kind (PRO-2800): the
- * reviewing agent called four tools to answer "how does it stand"; the
- * counts say whether taiga_list_action_required is worth a call.
+ * What waits on a person for this product, counted as taiga_list_action_required's summary counts it (PRO-2800):
+ * the reviewing agent called four tools to answer "how does it stand", and two later reviews found this count and
+ * the list's disagree (18 open here, 16 there), because this one counted stale reviews and put-off items as open.
  */
 async function attentionPart(client: TaigaClient, productId: string) {
-  const result = await client.listInbox({ productId, limit: 100, withTotal: true });
-  const now = Date.now();
-  const rows = result.data as Record<string, unknown>[];
-  const byKind: Record<string, number> = {};
-  for (const row of rows) byKind[String(row['kind'])] = (byKind[String(row['kind'])] ?? 0) + 1;
-  // Snoozed items are open too, so they count; the number says how many of
-  // them the team has put off for now.
-  const snoozed = rows.filter(
-    (row) =>
-      row['status'] === 'snoozed' && typeof row['snoozedUntil'] === 'string' && Date.parse(row['snoozedUntil']) > now
-  ).length;
+  const result = await client.listInbox({ productId, limit: 100 });
+  const counts = await attentionCounts(client, result.data as Record<string, unknown>[]);
   return {
-    open: typeof result.totalCount === 'number' ? result.totalCount : rows.length,
-    byKind,
-    ...(snoozed > 0 ? { snoozed } : {}),
+    ...counts,
     ...(result.nextCursor
-      ? { note: 'byKind and snoozed count the first 100; taiga_list_action_required pages the rest.' }
+      ? { note: 'These count the first 100 items; taiga_list_action_required pages the rest.' }
       : {}),
   };
 }
@@ -471,7 +465,8 @@ export function registerContextTools(server: McpServer, client: TaigaClient) {
         'Read where a product stands in one call; the first read for any product question. Name it by ID, slug ' +
         'or git remote URL. Returns product (in setup, readiness and next move), factory with its instructions, ' +
         'specification and architecture outlines (section ids, sizes), policies with section counts, open ' +
-        "initiatives (taiga_list_initiatives status: 'all' has the done and canceled), repositories, the latest ten runs, and counts for Action Required, open findings and " +
+        "initiatives with a count per board column (byColumn; taiga_list_initiatives status: 'all' has the done " +
+        'and canceled), repositories, the latest ten runs, and counts for Action Required, open findings and ' +
         'policy violations. A part that failed is under unavailable, one the key cannot read under notGranted; ' +
         `neither shows as empty. documents: budget returns whole sections up to about ${DOCUMENT_BUDGET / 1000}k ` +
         'characters each, full returns all.',

package/src/tools/errors.ts

@@ -46,6 +46,11 @@ export function inProductWording(said: string): string {
       .replace(/^Build run step not found/i, 'Run step not found')
       .replace(/^Build run not found/i, 'Run not found')
       .replace(/^Custom document not found/i, 'Knowledge file not found')
+      // A missing branch names the list of the ones that exist, as every other miss does.
+      .replace(
+        /^(Branch "[^"]*" does not exist in \S+?)\.?$/i,
+        '$1. taiga_list_repository_branches lists the branches it has.'
+      )
       // The API's word for a second link names no way out; the tool has two.
       .replace(
         /^This product already has a repository\. Change it instead of linking another\./i,