@taiga-ai/mcp-server 0.18.0-rc.445 → 0.19.0-dev.451

package/src/tools/builds.ts

@@ -1,6 +1,13 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import type { TaigaClient } from '../client.js';
+import {
+  type BuildRunStep,
+  type BuildRunWithContext,
+  BUILD_RUN_STATUSES,
+  dispositionOf,
+  type BuildRunStatus,
+} from '@taiga/types';
+import type { TaigaClient, WithoutTenant } from '../client.js';
 import { OPERATE, READ_ONLY } from './annotations.js';
 import { idInput, pagination, productId } from './inputs.js';
 import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
@@ -43,7 +50,9 @@ const RUN_OUTCOME_FIELDS = [
   'failedReason',
   'completedSteps',
   'totalSteps',
+  'prNumber',
   'prUrl',
+  'prMerged',
   'actions',
 ] as const;
 
@@ -54,7 +63,10 @@ const RUN_OUTCOME_FIELDS = [
  * stalled in the hardening pass after the steps and the retry continues it.
  * Null for a run still going or that finished.
  */
-export function stoppedIn(run: Record<string, unknown>, steps: Record<string, unknown>[]): string | null {
+export function stoppedIn(
+  run: Pick<WithoutTenant<BuildRunWithContext>, 'prMerged' | 'status' | 'hardeningResult'>,
+  steps: readonly Pick<WithoutTenant<BuildRunStep>, 'status' | 'stepOrder' | 'title'>[]
+): string | null {
   // A merged run is finished, whatever its status still says: the merge is
   // latched apart from the status, which can stay at a stale failed or stopped.
   if (run.prMerged === true || (run.status !== 'failed' && run.status !== 'stopped')) return null;
@@ -77,10 +89,80 @@ export function stoppedIn(run: Record<string, unknown>, steps: Record<string, un
   return 'after the steps and hardening, at the pull request';
 }
 
+/**
+ * The disposition with the merge latch authoritative: a run whose pull
+ * request merged landed, whatever settled status it kept when the completion
+ * write after the merge failed (build.ts allows a merged run to stay failed
+ * or stopped). A run still executing keeps its in-flight disposition.
+ */
+export function landedDisposition(status: BuildRunStatus, prMerged: boolean): string {
+  const disposition = dispositionOf(status, prMerged);
+  return prMerged && disposition !== 'in_flight' ? 'succeeded' : disposition;
+}
+
+/** What each executing status is doing, in a phrase. */
+const RUNNING: Partial<Record<BuildRunStatus, string>> = {
+  cloning: 'setting up the workspace',
+  implementing: 'implementing the steps',
+  hardening: 'hardening: running the security scanners and fixing what they find',
+  pushing: 'pushing the branch',
+  ci_checking: "waiting for the pull request's CI",
+  ci_fixing: 'fixing what CI found',
+  reviewing: 'answering review comments on the pull request',
+};
+
+/**
+ * How a run stands, in one sentence, with its disposition: the meaning the
+ * status and the pull request facts carry between them
+ * (PRO-2800). An agent read `closed` with failedReason null, every step
+ * completed and hardening passed, and could not tell what had happened; the
+ * status alone cannot say whether a completed run merged (dispositionOf).
+ */
+export function runOutcome(run: Record<string, unknown>): { disposition: string; outcome: string } | null {
+  const status = run['status'] as BuildRunStatus;
+  if (!(BUILD_RUN_STATUSES as readonly string[]).includes(status)) return null;
+  const disposition = landedDisposition(status, run['prMerged'] === true);
+  const pr = typeof run['prNumber'] === 'number' ? `PR #${run['prNumber']}` : 'its pull request';
+  const progress =
+    typeof run['completedSteps'] === 'number' && typeof run['totalSteps'] === 'number'
+      ? ` (${run['completedSteps']} of ${run['totalSteps']} steps done)`
+      : '';
+  const reason = typeof run['failedReason'] === 'string' && run['failedReason'] ? `: ${run['failedReason']}` : '';
+  const sentence: Record<string, string> = {
+    in_flight: status === 'pending' ? 'Queued: waiting to start.' : `Running: ${RUNNING[status] ?? status}${progress}.`,
+    gated: `Waiting for a person to review and merge ${pr}.`,
+    succeeded: `Merged: ${pr} is in ${typeof run['baseBranch'] === 'string' ? run['baseBranch'] : 'the base branch'}.`,
+    unmerged:
+      typeof run['prNumber'] === 'number' || run['prUrl']
+        ? `Settled without merging: ${pr} was left unmerged.`
+        : 'Settled without a merged pull request.',
+    failed: `Failed${reason}${progress}.`,
+    stopped: `Stopped before it finished${progress}.`,
+    rejected: `${pr} was closed without merging, so the work did not land.`,
+  };
+  return { disposition, outcome: sentence[disposition] ?? status };
+}
+
+/**
+ * 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
+ * opened one said it had a draft (PRO-2800).
+ */
+export function readableRun(run: Record<string, unknown>): Record<string, unknown> {
+  const { prDraft, ...rest } = run;
+  const said = runOutcome(run);
+  return {
+    ...rest,
+    // A PR number proves a PR exists (isSettledWithoutPr); the URL is nullable apart from it.
+    ...(typeof rest['prNumber'] === 'number' || rest['prUrl'] ? { prDraft } : {}),
+    ...(said ?? {}),
+  };
+}
+
 /** How many products the org-wide list names; past this a row keeps its productId only. */
 const NAMED_PRODUCTS = 100;
 
-const buildId = idInput('build run', 'taiga_list_builds gives it');
+const runId = idInput('run', 'taiga_list_runs gives it');
 
 /** A step without its instructions: what it is, how it stands and what it changed. */
 const STEP_SUMMARY_FIELDS = [
@@ -131,14 +213,16 @@ async function activityRows(
       throw error;
     }),
   ]);
-  const nameById = new Map<string, { name: unknown; slug: unknown }>();
-  for (const product of (products?.data ?? []) as Record<string, unknown>[]) {
-    nameById.set(String(product.id), { name: product.name, slug: product.slug });
+  const nameById = new Map<string, { name: string; slug: string }>();
+  for (const product of products?.data ?? []) {
+    nameById.set(product.id, { name: product.name, slug: product.slug });
   }
-  const rows = pickFields(runs.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS).map((row) => {
-    const product = nameById.get(String(row.productId));
-    return product ? { ...row, product } : row;
-  });
+  const rows = pickFields(runs.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS)
+    .map(readableRun)
+    .map((row) => {
+      const product = nameById.get(String(row['productId']));
+      return product ? { ...row, product } : row;
+    });
   const unnamed = rows.some((row) => !('product' in row));
   // Why a row stayed unnamed, by what the products read said: it failed, it
   // was cut before that product, or it listed everything the key can see and
@@ -157,24 +241,23 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
 
   server.registerTool(
-    'taiga_list_builds',
+    'taiga_list_runs',
     {
-      title: 'List build runs',
+      title: 'List runs',
       description:
-        "List the coding agent's runs, newest first: status, branch, pull request, step progress and the " +
-        'actions a person may take on each. A run is the record of an attempt: work is carried on from its ' +
-        'initiative (resume and retry_from_failed_step are taiga_resume_backlog_item; start_over is in the web ' +
-        'only for now) and stopped by moving the initiative out of Build; a maintenance run, which has no ' +
-        'initiative, is retried from its finding. With productId, ' +
-        'the runs of that product, optionally of one backlog item; without it, the runs of every product the ' +
-        'key can see, each row naming its product, and active: true narrows to the runs executing right now. ' +
-        'Use this to see what Taiga already built or is building, then read one run with taiga_get_build. ' +
-        'A run of a deleted initiative keeps its title.',
+        "List the coding agent's runs, newest first. A run is one attempt at building an initiative: its branch, " +
+        'pull request and step progress. Each row says how it stands in one sentence (outcome) and as a ' +
+        'disposition: in_flight (the agent is working), gated (a person owes a review and merge), succeeded ' +
+        '(merged), failed, stopped, rejected (the pull request was closed without merging) or unmerged. actions ' +
+        'name what a person may do with it. With productId, the runs of that product, optionally of one ' +
+        'initiative; without it, the runs of every product the key can see, each row naming its product, and ' +
+        'active: true narrows to the runs executing now. taiga_get_run reads one with its steps. Work is carried ' +
+        'on from the initiative (taiga_resume_initiative), not the run.',
       inputSchema: z.object({
         productId: productId.optional(),
-        backlogItemId: idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it')
+        initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it')
           .optional()
-          .describe("Only this backlog item's runs -- get from taiga_list_backlog_items; needs productId"),
+          .describe("Only this initiative's runs -- get from taiga_list_initiatives; needs productId"),
         active: z
           .boolean()
           .optional()
@@ -188,10 +271,10 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        if (!params.productId && params.backlogItemId) {
+        if (!params.productId && params.initiativeId) {
           return toolError(
             'VALIDATION_ERROR',
-            'backlogItemId narrows the runs of one product: pass its productId as well (the item carries it).'
+            'initiativeId narrows the runs of one product: pass its productId as well (the initiative carries it).'
           );
         }
         // The product route has no such filter; a silently ignored one would
@@ -203,9 +286,16 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
           );
         }
         if (params.productId) {
-          const result = await client.listBuildRuns(params.productId, params);
+          const result = await client.listBuildRuns(params.productId, {
+            backlogItemId: params.initiativeId,
+            limit: params.limit,
+            cursor: params.cursor,
+          });
           return toolResult(
-            page(pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS), result.nextCursor)
+            page(
+              pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS).map(readableRun),
+              result.nextCursor
+            )
           );
         }
         return toolResult(await activityRows(client, params));
@@ -213,21 +303,21 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
   );
 
   server.registerTool(
-    'taiga_get_build',
+    'taiga_get_run',
     {
-      title: 'Get build run',
+      title: 'Get run',
       description:
-        "Get one run with its steps: the run (status, pull request, hardening, metrics) and each step's title, " +
-        'status, commit, files changed, checks, any error and headline, the first paragraph of what the agent ' +
-        "reported. Pass full: true for each step's complete instructions and report, several thousand tokens on " +
-        'a long run. Use this to pick up where the coding agent stopped, or to understand the pull request it ' +
-        'opened. A run that failed or was stopped says where (stoppedIn: a step, or the hardening pass after ' +
-        'them) and when it last made progress (lastProgressAt). Its actions name what the initiative accepts ' +
-        'for it: resume and retry_from_failed_step (which continues from the first unfinished part) are ' +
-        'taiga_resume_backlog_item, start_over is in the web only for now; to stop it, move the initiative out of ' +
-        'Build. A maintenance run has no initiative and is retried from its finding.',
+        'Get one run with its steps: how it stands (outcome, disposition), its pull request and hardening, and ' +
+        "each step's title, status, commit, files changed, verification and headline, the first paragraph of " +
+        "what the agent reported. A step's verification is Taiga's own check after the step (tests, lint, build), " +
+        'independent of what the agent says it ran: a docs-only step can show tests failed because the ' +
+        "repository's tests fail. A run that failed or was stopped says where (stoppedIn) and when it last made " +
+        "progress (lastProgressAt). Pass full: true for each step's complete instructions and report, several " +
+        'thousand tokens on a long run. Its actions name what the initiative accepts: resume and ' +
+        'retry_from_failed_step are taiga_resume_initiative; start_over is in the web only; to stop it, move the ' +
+        'initiative out of Build. A maintenance run has no initiative and is retried from its finding.',
       inputSchema: z.object({
-        buildId,
+        runId,
         full: z
           .boolean()
           .optional()
@@ -240,16 +330,16 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         // Two routes, one answer: fanned out here rather than in the model's
         // context, like the six-tool pattern asks.
         const [run, steps] = await Promise.all([
-          client.getBuildRun(params.buildId),
-          client.listBuildRunSteps(params.buildId),
+          client.getBuildRun(params.runId),
+          client.listBuildRunSteps(params.runId),
         ]);
-        const runRow = run.data as Record<string, unknown>;
-        const rows = steps.data as Record<string, unknown>[];
+        const runRow = run.data;
+        const rows = steps.data;
         const where = stoppedIn(runRow, rows);
         const stop = where ? { stoppedIn: where } : {};
-        if (params.full) return toolResult({ ...runRow, ...stop, steps: steps.data });
+        if (params.full) return toolResult({ ...readableRun(runRow), ...stop, steps: steps.data });
         return toolResult({
-          ...runRow,
+          ...readableRun(runRow),
           ...stop,
           steps: pickFields(rows, STEP_SUMMARY_FIELDS).map((step, index) => ({
             ...step,
@@ -262,23 +352,22 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:write')) return;
 
   server.registerTool(
-    'taiga_stop_build',
+    'taiga_stop_run',
     {
-      title: 'Stop a build run',
+      title: 'Stop a run',
       description:
         'The emergency brake: stop a run the coding agent is executing when its initiative cannot be moved. The ' +
-        'way to stop work is on the initiative: move it out of Build (taiga_move_backlog_item), which stops the ' +
+        'way to stop work is on the initiative: move it out of Build (taiga_move_initiative), which stops the ' +
         'plan or run in flight. Use this only for a run whose initiative does not offer that (it is finished, ' +
         'canceled or gone) yet the run is still going. The agent halts, its branch and any draft pull request ' +
-        'stay. Only a run whose actions include stop; the API refuses the rest with CONFLICT. Ask the person ' +
-        'before calling this: it interrupts work in progress.',
-      inputSchema: z.object({ buildId }),
+        'stay. Only a run whose actions include stop; the API refuses the rest with CONFLICT.',
+      inputSchema: z.object({ runId }),
       annotations: OPERATE,
     },
     (params) =>
       runTool(async () => {
-        const result = await client.stopBuildRun(params.buildId);
-        return toolResult(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]);
+        const result = await client.stopBuildRun(params.runId);
+        return toolResult(readableRun(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]!));
       })
   );
 }

package/src/tools/catalogue.test.ts

@@ -10,7 +10,7 @@ import {
 } from '@taiga/types';
 import { TaigaClient } from '../client.js';
 import { registerAllTools, writeNotice } from './index.js';
-import { INSTRUCTIONS_HEAD, INSTRUCTIONS_HEAD_LIMIT, SERVER_INSTRUCTIONS } from './instructions.js';
+import { SERVER_INSTRUCTIONS, SERVER_INSTRUCTIONS_LIMIT } from './instructions.js';
 import { PRODUCT_DOCUMENT_NAMES } from './catalogue.js';
 
 /**
@@ -104,11 +104,10 @@ describe('tool descriptions against the catalogue', () => {
     const tools = await allTools();
     const list = tools.find((t) => t.name === 'taiga_list_documents')!;
     const get = tools.find((t) => t.name === 'taiga_get_document')!;
-    const typeEnum = (get.inputSchema.properties as Record<string, { enum?: string[] }>).type!.enum;
+    const typeEnum = (get.inputSchema.properties as Record<string, { enum?: string[] }>)['type']!.enum;
 
     for (const type of POLICY_TYPES) {
       expect(list.description, type).toContain(type);
-      expect(SERVER_INSTRUCTIONS, type).toContain(type);
     }
     expect(typeEnum).toEqual([...TENANT_DOCUMENT_TYPES]);
   });
@@ -118,10 +117,10 @@ describe('tool descriptions against the catalogue', () => {
     const props = (name: string) =>
       tools.find((t) => t.name === name)!.inputSchema.properties as Record<string, { enum?: string[] }>;
 
-    expect(props('taiga_list_products').status!.enum).toEqual([...PRODUCT_STATUSES]);
-    expect(props('taiga_get_product_document').type!.enum).toEqual([...PRODUCT_DOCUMENT_TYPES]);
-    expect(props('taiga_get_product_document').origin!.enum).toEqual(['plan', 'reality']);
-    expect(props('taiga_get_factory_document').type!.enum).toEqual([...FACTORY_DOCUMENT_TYPES]);
+    expect(props('taiga_list_products')['status']!.enum).toEqual([...PRODUCT_STATUSES]);
+    expect(props('taiga_get_product_document')['type']!.enum).toEqual([...PRODUCT_DOCUMENT_TYPES]);
+    expect(props('taiga_get_product_document')['origin']!.enum).toEqual(['plan', 'reality']);
+    expect(props('taiga_get_factory_document')['type']!.enum).toEqual([...FACTORY_DOCUMENT_TYPES]);
   });
 
   it('has a display name for every product document type, the one the web uses', () => {
@@ -130,23 +129,30 @@ describe('tool descriptions against the catalogue', () => {
     expect(PRODUCT_DOCUMENT_NAMES.ui_direction).toBe('Look & Feel');
   });
 
-  it('explains both timelines and the section metadata in the server instructions', () => {
-    expect(SERVER_INSTRUCTIONS).toMatch(/plan: .*discovery/);
-    expect(SERVER_INSTRUCTIONS).toMatch(/reality: .*merged pull request/);
-    for (const term of ['`source`', '`priority: core`', 'overlay-<id>', 'cloud-preset:<providers>', 'brownfield']) {
-      expect(SERVER_INSTRUCTIONS).toContain(term);
-    }
-    // Nothing writes a `user` source: a hand edit keeps the source it had.
-    expect(SERVER_INSTRUCTIONS).not.toMatch(/user: edited/);
+  it('explains both timelines where a product document is read', async () => {
+    const tools = await allTools();
+    const origin = (
+      tools.find((t) => t.name === 'taiga_get_product_document')!.inputSchema.properties as Record<
+        string,
+        { description?: string }
+      >
+    )['origin']!.description;
+    expect(origin).toMatch(/plan: .*discovery/);
+    expect(origin).toMatch(/reality: .*merged pull request/);
   });
 
-  it('opens the instructions with where to start and when to ask, inside what a client shows before it cuts', () => {
-    // Claude Code shows about the first 2,000 characters; the review that
-    // found the cut read only the document taxonomy (PRO-2759).
-    expect(SERVER_INSTRUCTIONS.startsWith(INSTRUCTIONS_HEAD)).toBe(true);
-    expect(INSTRUCTIONS_HEAD.length).toBeLessThanOrEqual(INSTRUCTIONS_HEAD_LIMIT);
-    for (const must of ['taiga_get_product_context', 'Before you write', 'NOT_FOUND', 'initiative']) {
-      expect(INSTRUCTIONS_HEAD).toContain(must);
+  it('fits the whole instructions inside what Claude Code keeps, and says where to start and when to ask', () => {
+    // Claude Code loads only tool names and the instructions until the model
+    // searches, and cuts the instructions at 2,048 characters (PRO-2800).
+    expect(SERVER_INSTRUCTIONS.length).toBeLessThanOrEqual(SERVER_INSTRUCTIONS_LIMIT);
+    for (const must of [
+      'taiga_get_product_context',
+      'Before you write',
+      'NOT_FOUND',
+      'initiative',
+      'Only in the web',
+    ]) {
+      expect(SERVER_INSTRUCTIONS).toContain(must);
     }
   });
 });