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

package/src/tools/autonomy.ts

@@ -70,7 +70,7 @@ export function registerAutonomyTools(server: McpServer, client: TaigaClient) {
           'organization and factories allow: where either has turned autonomous merge off, true changes nothing. ' +
           'Taiga merges through your rules, never around them.',
         inputSchema: z.object({
-          itemId: 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'),
           autoMerge: z
             .boolean()
             .nullable()
@@ -80,7 +80,7 @@ export function registerAutonomyTools(server: McpServer, client: TaigaClient) {
       },
       (params) =>
         runTool(async () => {
-          const item = (await client.updateBacklogItem(params.itemId, { autoMerge: params.autoMerge })).data;
+          const item = (await client.updateBacklogItem(params.initiativeId, { autoMerge: params.autoMerge })).data;
           return toolResult(pickFields([item], ['id', 'title', 'state', 'autoMerge', 'autoBuild'])[0]);
         })
     );

package/src/tools/backlogs.ts

@@ -1,14 +1,26 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import type { ActivityEvent, ActivityActor, BacklogItem } from '@taiga/types';
+import {
+  type ActivityEvent,
+  type ActivityActor,
+  type BacklogItem,
+  BUILD_RUN_STATUSES,
+  PLAN_REJECTION_COMMENT_MAX_CHARS,
+  PR_CLOSING_STATES,
+  USER_DROP_STATES,
+  renderHalt,
+  resolveAutoBuild,
+  type BuildRunStatus,
+  type Halt,
+} from '@taiga/types';
 import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
-import { PLAN_REJECTION_COMMENT_MAX_CHARS, PR_CLOSING_STATES, USER_DROP_STATES, resolveAutoBuild } from '@taiga/types';
 import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
 import { idInput, pagination, productId } from './inputs.js';
 import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { jobReport } from './jobs.js';
 import { requestPrompt } from './request-prompt.js';
 import { queueView } from './queue.js';
+import { landedDisposition } from './builds.js';
 import {
   SEARCH_NOTE,
   SEARCH_PAGE_SIZE,
@@ -62,11 +74,106 @@ const ITEM_OUTCOME_FIELDS = [
  * leaves it null, and the lifecycle is what says why and what moves it on.
  */
 const LIFECYCLE_MEANING =
-  'lifecycle says whose turn it is and what moves it on: cta start_plan is taiga_queue_backlog_item, ' +
+  'situation says in one sentence where it stands, whose turn it is and the call that moves it on. The same ' +
+  'as fields: lifecycle says whose turn it is and what moves it on: cta start_plan is taiga_queue_initiative, ' +
   'retry_plan taiga_plan_again (planFailureCause says why the plan stopped), start_build taiga_approve_plan, ' +
-  'resume_build taiga_resume_backlog_item, retry_build a fresh run (start over, in the web), review_pr and ' +
+  'resume_build taiga_resume_initiative, retry_build a fresh run (start over, in the web), review_pr and ' +
   'view_pr the pull request. needsHumanCause is set only when the line stopped on it.';
 
+/** The move each call to action is, in the tools' words. */
+const CTA_MOVE: Record<string, string> = {
+  start_plan: 'taiga_queue_initiative puts it on the line to be planned and built (paid work: ask first)',
+  retry_plan: 'taiga_plan_again asks for a new plan (paid work: ask first)',
+  start_build:
+    'read the plan with taiga_get_plan, then taiga_approve_plan builds it or taiga_reject_plan sends it back',
+  resume_build: 'taiga_resume_initiative carries the run on (paid work: ask first)',
+  retry_build: 'a new run starts over from the web; taiga_move_initiative takes it off the line',
+  review_pr: 'a person reviews and merges the pull request',
+  view_pr: 'the line merges the pull request once its checks pass',
+};
+
+/** How a run stands, as the end of "its latest run ...", by disposition. */
+const RUN_STANDS: Record<string, string> = {
+  in_flight: 'is running',
+  gated: 'is in review',
+  succeeded: 'merged',
+  unmerged: 'settled unmerged',
+  failed: 'failed',
+  stopped: 'was stopped',
+  rejected: 'had its pull request closed without merging',
+};
+
+/** Where an initiative is, in a phrase, by its lifecycle stage. */
+const STAGE: Record<string, string> = {
+  backlog: 'In the backlog, not on the line yet',
+  planning: 'Being planned',
+  planned: 'Planned',
+  building: 'Being built',
+  in_review: 'Its pull request is in review',
+  done: 'Done',
+  canceled: 'Canceled',
+};
+
+/**
+ * Where an initiative stands and what moves it on, in one sentence (PRO-2800).
+ * Five fields carried it (status, state, planningStatus, needsHumanCause,
+ * lifecycle) and a reviewing agent had to read the queue, the initiative and
+ * the run together to say what had happened; the lifecycle the API derives
+ * already decides it. Null for a row without a lifecycle.
+ */
+export function situationOf(item: Record<string, unknown>): string | null {
+  const life = item['lifecycle'] as
+    | { turn?: unknown; stage?: unknown; cta?: unknown; planFailureCause?: unknown; latestBuild?: unknown }
+    | null
+    | undefined;
+  if (!life || typeof life.stage !== 'string') return null;
+  const parts: string[] = [];
+  let stage = STAGE[life.stage] ?? life.stage;
+  if (life.stage === 'planning' && life.turn === 'you') {
+    stage = `Planning stopped${typeof life.planFailureCause === 'string' ? ` (${life.planFailureCause})` : ''}`;
+  }
+  const build = life.latestBuild as { status?: unknown; prNumber?: unknown; prMerged?: unknown } | null | undefined;
+  if (build && typeof build.status === 'string' && life.stage !== 'done' && life.stage !== 'canceled') {
+    const pr = typeof build.prNumber === 'number' ? ` (PR #${build.prNumber})` : '';
+    const said = (BUILD_RUN_STATUSES as readonly string[]).includes(build.status)
+      ? RUN_STANDS[landedDisposition(build.status as BuildRunStatus, build.prMerged === true)]
+      : build.status;
+    stage += `; its latest run ${said}${pr}`;
+  }
+  parts.push(`${stage}.`);
+  if (typeof item['needsHumanCause'] === 'string') {
+    const halt = renderHalt({ cause: item['needsHumanCause'], params: {} } as unknown as Halt);
+    const detail = typeof item['needsHumanDetail'] === 'string' ? item['needsHumanDetail'] : '';
+    // The halt says what stopped the line; the detail is the run's own reason, kept beside it.
+    const why = [halt, detail]
+      .filter(Boolean)
+      .map((text) => text.replace(/\.$/, ''))
+      .join('. ');
+    if (why) parts.push(`The line stopped on it: ${why}.`);
+  }
+  const turn = life.turn === 'you' ? "A person's turn" : life.turn === 'agent' ? "The agent's turn" : null;
+  const move = typeof life.cta === 'string' ? CTA_MOVE[life.cta] : undefined;
+  if (life.cta === 'view_pr') parts.push(`Nothing to do: ${move}.`);
+  else if (turn && move) parts.push(`${turn}: ${move}.`);
+  else if (turn) parts.push(`${turn}.`);
+  else if (move) parts.push(`Next: ${move}.`);
+  return parts.join(' ');
+}
+
+/** A row or item with its situation added when it has a lifecycle. */
+export function withSituation(
+  item: Record<string, unknown>,
+  row: Record<string, unknown> = item
+): Record<string, unknown> {
+  const situation = situationOf(item);
+  return situation ? { ...row, situation } : row;
+}
+
+/** List rows, each with its situation. */
+export function situatedRows(items: Record<string, unknown>[]): Record<string, unknown>[] {
+  return itemRows(items, BACKLOG_SUMMARY_FIELDS).map((row, index) => withSituation(items[index]!, row));
+}
+
 /** What each plan failure cause means for whoever reads it next (PLAN_FAILURE_CAUSES in @taiga/types). */
 const PLAN_FAILURE_MEANING: Record<string, string> = {
   agent_error: 'The planning agent failed. Planning again is the usual next step.',
@@ -81,12 +188,12 @@ const PLAN_FAILURE_MEANING: Record<string, string> = {
  */
 async function planFailureOf(
   client: TaigaClient,
-  itemId: string,
+  initiativeId: string,
   itemCause: unknown
 ): Promise<Record<string, unknown> | null> {
   let events: WithoutTenant<ActivityEvent>[];
   try {
-    events = (await client.listBacklogItemActivity(itemId)).data;
+    events = (await client.listBacklogItemActivity(initiativeId)).data;
   } catch (error) {
     if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
     throw error;
@@ -126,7 +233,7 @@ async function planFailureOf(
 
 const planId = idInput('plan', "taiga_get_plan gives the initiative's active plan and its ID");
 
-const itemId = idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it');
+const initiativeId = idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it');
 
 /** The plan without its steps' prose: enough to approve it or say what a run will do. */
 const PLAN_SUMMARY_FIELDS = ['id', 'backlogItemId', 'version', 'status', 'createdAt'] as const;
@@ -143,8 +250,12 @@ const PLAN_STEP_SUMMARY_FIELDS = [
 
 type Item = WithoutTenant<BacklogItem>;
 
-/** The outcome fields of an initiative, with how many of its criteria are met. */
-const outcomeOf = (item: Item) => ({ ...pickFields([item], ITEM_OUTCOME_FIELDS)[0], criteria: criteriaCounts(item) });
+/** The outcome fields of an initiative, with how many of its criteria are met, and where it stands. */
+const outcomeOf = (item: Item) =>
+  withSituation(item as unknown as Record<string, unknown>, {
+    ...pickFields([item], ITEM_OUTCOME_FIELDS)[0],
+    criteria: criteriaCounts(item),
+  });
 
 const outcome = (item: Item) => toolResult(outcomeOf(item));
 
@@ -180,15 +291,16 @@ export function registerBacklogTools(server: McpServer, client: TaigaClient) {
 
 function registerBacklogReads(server: McpServer, client: TaigaClient) {
   server.registerTool(
-    'taiga_list_backlog_items',
+    'taiga_list_initiatives',
     {
-      title: 'List backlog items',
+      title: 'List initiatives',
       description:
-        "List a product's backlog items (initiatives): titles, category, status, where each one is on the " +
-        'line (backlog, todo, queue, plan, build, done) and criteria, how many of its acceptance criteria are met ' +
+        "List a product's initiatives, its backlog: titles, category, status, where each one is on the " +
+        'line (backlog, todo, queue, plan, build, done), situation (where it stands and what moves it on, in a ' +
+        'sentence) and criteria, how many of its acceptance criteria are met ' +
         '(null before it is planned; met counts the criteria the agent confirmed with evidence or a person checked ' +
         'off, so a done item can show fewer met than it has). Use this to find the item you are working on (query ' +
-        'finds one by title), then read its acceptance criteria and technical context with taiga_get_backlog_item. ' +
+        'finds one by title), then read its acceptance criteria and technical context with taiga_get_initiative. ' +
         'Archived items are left out unless asked for.',
       inputSchema: z.object({
         productId,
@@ -218,7 +330,7 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
         const { query, ...filters } = params;
         if (query === undefined) {
           const result = await client.listBacklogItems(params.productId, filters);
-          return toolResult(page(itemRows(result.data, BACKLOG_SUMMARY_FIELDS), result.nextCursor));
+          return toolResult(page(situatedRows(result.data as Record<string, unknown>[]), result.nextCursor));
         }
         if (params.cursor !== undefined) {
           return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
@@ -230,36 +342,37 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
           params.limit ?? 25
         );
         return toolResult({
-          ...page(itemRows(found.rows, BACKLOG_SUMMARY_FIELDS), null),
+          ...page(situatedRows(found.rows), null),
           ...(found.more ? { more: SEARCH_NOTE } : {}),
         });
       })
   );
 
   server.registerTool(
-    'taiga_get_backlog_item',
+    'taiga_get_initiative',
     {
-      title: 'Get backlog item',
+      title: 'Get initiative',
       description:
-        'Get one backlog item in full: description, acceptance criteria (and which are met), technical ' +
+        'Get one initiative in full: description, acceptance criteria (and which are met), technical ' +
         'context (patterns, constraints, and the assumptions to verify before starting), dependencies and source documents. Read this before ' +
-        'implementing an item, and read its runs with taiga_list_builds to see what the coding agent already did. ' +
+        'implementing an item, and read its runs with taiga_list_runs to see what the coding agent already did. ' +
         'A failed plan carries planFailure: the cause, what it means, when, and by whom. ' +
         LIFECYCLE_MEANING,
       inputSchema: z.object({
-        itemId,
+        initiativeId,
       }),
       annotations: READ_ONLY,
     },
     (params) =>
       runTool(async () => {
-        const item = (await client.getBacklogItem(params.itemId)).data;
-        if (item.planningStatus !== 'failed') return toolResult(item);
+        const item = (await client.getBacklogItem(params.initiativeId)).data;
+        const row = item as unknown as Record<string, unknown>;
+        if (item.planningStatus !== 'failed') return toolResult(withSituation(row));
         // Always undefined: the API sends the cause only under `lifecycle`, so
         // planFailureOf's cross-check never fires (PRO-2799). Kept as it was.
         const ownCause = (item as { planFailureCause?: unknown }).planFailureCause;
-        const planFailure = await planFailureOf(client, params.itemId, ownCause);
-        return toolResult(planFailure ? { ...item, planFailure } : item);
+        const planFailure = await planFailureOf(client, params.initiativeId, ownCause);
+        return toolResult(withSituation(row, planFailure ? { ...item, planFailure } : item));
       })
   );
 
@@ -275,14 +388,14 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
         "full: true for each step's complete instructions, several thousand tokens on a large plan. NOT_FOUND " +
         'when the initiative has no active plan yet (planningStatus says whether one is being generated).',
       inputSchema: z.object({
-        itemId,
+        initiativeId,
         full: z.boolean().optional().describe("Carry each step's complete instructions (default false: a summary)"),
       }),
       annotations: READ_ONLY,
     },
     (params) =>
       runTool(async () => {
-        const plan = (await client.getActivePlan(params.itemId)).data;
+        const plan = (await client.getActivePlan(params.initiativeId)).data;
         if (params.full) return toolResult(plan);
         const steps = Array.isArray(plan.steps) ? plan.steps : [];
         return toolResult({
@@ -340,12 +453,12 @@ function registerRequest(server: McpServer, client: TaigaClient) {
 
 function registerMove(server: McpServer, client: TaigaClient) {
   server.registerTool(
-    'taiga_move_backlog_item',
+    'taiga_move_initiative',
     {
-      title: 'Move backlog item on the board',
+      title: 'Move initiative on the board',
       description:
         'Move an initiative on the board, or order it within a column: backlog and todo are yours and the line ' +
-        'never moves an initiative out of them; queue puts it in the line (taiga_queue_backlog_item says more); ' +
+        'never moves an initiative out of them; queue puts it in the line (taiga_queue_initiative says more); ' +
         'done and canceled finish it by hand. The queue is the only way to start work: there is no "plan this ' +
         'now", and nothing is moved into Build by a person. Moving an initiative out of Build stops the plan ' +
         'being written or the run in flight: that is how work is stopped, and it throws that work away. A move to ' +
@@ -356,9 +469,9 @@ function registerMove(server: McpServer, client: TaigaClient) {
         'archived: true files the initiative where it stands (pass its current column as state; never from the Build station, plan or build) ' +
         'and archived: false brings it back; archived work is left out of lists unless includeArchived asks for it.',
       inputSchema: z.object({
-        itemId,
+        initiativeId,
         state: z.enum(USER_DROP_STATES).describe('The column to move into'),
-        afterId: idInput('backlog item', 'taiga_list_backlog_items gives it')
+        afterId: idInput('initiative', 'taiga_list_initiatives gives it')
           .nullable()
           .optional()
           .describe('The initiative to follow in that column; null for the head; omit to keep rank order'),
@@ -371,7 +484,7 @@ function registerMove(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        const { itemId: id, ...body } = params;
+        const { initiativeId: id, ...body } = params;
         // What the route checks on top of backlog:write for a drop into the
         // queue; refused here so the model learns which capability, not just
         // that it was forbidden.
@@ -401,10 +514,10 @@ function registerPlanAgain(server: McpServer, client: TaigaClient) {
         'stays open. Offered only when the turn is yours: refused (CONFLICT) while an agent holds it (planning, ' +
         'building, reviewing). Also refused while a dependency is still in flight or a UI direction has no ' +
         'chosen concept, unless force says to plan anyway, which only the person decides. Anywhere off the ' +
-        'Build station, put the initiative in the queue instead (taiga_queue_backlog_item): the queue is the ' +
+        'Build station, put the initiative in the queue instead (taiga_queue_initiative): the queue is the ' +
         'only way to start work. To send a plan back with direction, taiga_reject_plan. Starts a planner run.',
       inputSchema: z.object({
-        itemId,
+        initiativeId,
         force: z
           .boolean()
           .optional()
@@ -416,16 +529,16 @@ function registerPlanAgain(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        const item = (await client.getBacklogItem(params.itemId)).data;
+        const item = (await client.getBacklogItem(params.initiativeId)).data;
         if (!BUILD_STATION.has(String(item.state))) {
           return toolError(
             'CONFLICT',
             `This initiative is in ${String(item.state)}, not at the Build station. The queue is the only way to ` +
-              'start work: put it in the queue with taiga_queue_backlog_item and it is planned when its turn comes.'
+              'start work: put it in the queue with taiga_queue_initiative and it is planned when its turn comes.'
           );
         }
         const body = { state: 'plan', ...(params.force ? { force: true } : {}) };
-        return outcome((await client.transitionInitiative(params.itemId, body)).data);
+        return outcome((await client.transitionInitiative(params.initiativeId, body)).data);
       })
   );
 }
@@ -481,9 +594,9 @@ const autoBuildInput = z
 
 function registerQueue(server: McpServer, client: TaigaClient) {
   server.registerTool(
-    'taiga_queue_backlog_item',
+    'taiga_queue_initiative',
     {
-      title: 'Queue backlog item',
+      title: 'Queue initiative',
       description:
         'Add an initiative to the product queue, the line the coding agent works: queued initiatives are ' +
         'planned and built one at a time, each advancing when the previous pull request merges. This starts ' +
@@ -491,12 +604,12 @@ function registerQueue(server: McpServer, client: TaigaClient) {
         "repository. Whether the plan is built at once or waits for a person is the initiative's review gate: " +
         "pass autoBuild: false to read the plan before anything is built (the product's default applies " +
         'otherwise, and the outcome says which it is); the gate is set first and stays set if the move is then ' +
-        'refused. Ask the person before calling this. An initiative already ' +
+        'refused. An initiative already ' +
         'in the queue stays where it is unless afterId says where to go; one being planned or built cannot move ' +
         '(CONFLICT). Returns the initiative with its new state, its review gate and its place in the queue.',
       inputSchema: z.object({
-        itemId,
-        afterId: idInput('backlog item', 'taiga_list_backlog_items gives it')
+        initiativeId,
+        afterId: idInput('initiative', 'taiga_list_initiatives gives it')
           .nullable()
           .optional()
           .describe(
@@ -513,7 +626,7 @@ function registerQueue(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        const { itemId: id, autoBuild, ...placement } = params;
+        const { initiativeId: id, autoBuild, ...placement } = params;
         // The gate first: set after the move, a plan landing in between
         // would be built under the old answer.
         if (autoBuild !== undefined) await client.setAutoBuild(id, autoBuild);
@@ -527,7 +640,7 @@ function registerQueue(server: McpServer, client: TaigaClient) {
           queue,
           ...(gate && queue
             ? {}
-            : { note: 'Part of the outcome could not be read; taiga_get_queue and taiga_get_product say the rest.' }),
+            : { note: 'Part of the outcome could not be read; taiga_get_line and taiga_get_product say the rest.' }),
         });
       })
   );
@@ -543,12 +656,12 @@ function registerReviewGate(server: McpServer, client: TaigaClient) {
         "approve or reject it (false); null follows the product's default. Standing: it applies to every plan the " +
         'initiative gets, including one being written now. Opening the gate on a plan that is already waiting ' +
         'starts its build at once. Returns the initiative with the gate that now applies.',
-      inputSchema: z.object({ itemId, autoBuild: autoBuildInput }),
+      inputSchema: z.object({ initiativeId, autoBuild: autoBuildInput }),
       annotations: OPERATE_SETTING,
     },
     (params) =>
       runTool(async () => {
-        const item = (await client.setAutoBuild(params.itemId, params.autoBuild)).data;
+        const item = (await client.setAutoBuild(params.initiativeId, params.autoBuild)).data;
         const gate = await reviewGate(client, item);
         return toolResult({
           ...outcomeOf(item),
@@ -561,9 +674,9 @@ function registerReviewGate(server: McpServer, client: TaigaClient) {
 
 function registerResume(server: McpServer, client: TaigaClient) {
   server.registerTool(
-    'taiga_resume_backlog_item',
+    'taiga_resume_initiative',
     {
-      title: 'Resume backlog item',
+      title: 'Resume initiative',
       description:
         'Resume an initiative the line stopped on, which is when needsHumanCause is set (the line sets it): a ' +
         'failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished ' +
@@ -572,10 +685,10 @@ function registerResume(server: McpServer, client: TaigaClient) {
         'initiative. Refused (CONFLICT) when nothing is flagged or the cause has no resume: a plan that failed ' +
         'with needsHumanCause null (lifecycle.cta retry_plan, planFailureCause says why) is planned again with ' +
         'taiga_plan_again. Starts paid work.',
-      inputSchema: z.object({ itemId }),
+      inputSchema: z.object({ initiativeId }),
       annotations: OPERATE,
     },
-    (params) => runTool(async () => outcome((await client.resumeInitiative(params.itemId)).data))
+    (params) => runTool(async () => outcome((await client.resumeInitiative(params.initiativeId)).data))
   );
 }