@taiga-ai/mcp-server 0.11.0 → 0.12.0-dev.417

package/src/tools/instructions.ts

@@ -47,12 +47,19 @@ export const SERVER_INSTRUCTIONS = [
   'every product the key can see, and active: true the ones executing now.',
   '',
   '**Operating the line** (taiga_create_backlog_item / taiga_queue_backlog_item / taiga_move_backlog_item /',
-  'taiga_resume_backlog_item / taiga_get_plan / taiga_approve_plan / taiga_reject_plan / taiga_stop_build /',
-  'taiga_resume_build): create an initiative, put it in the queue the coding agent works, move it on the',
-  'board, read and approve or reject its plan, stop or resume a run. Queueing, approving and resuming start',
-  'paid agent work that pushes commits and opens pull requests; stopping interrupts it. Tell the person what',
-  'you are about to start or stop and wait for their yes before calling these; a client that prompts on',
-  'destructive tools does that for you. A refusal (CONFLICT) carries the API reason: say it as it is.',
+  'taiga_resume_backlog_item / taiga_set_auto_build / taiga_get_plan / taiga_approve_plan / taiga_reject_plan /',
+  'taiga_stop_build / taiga_resume_build): create an initiative, put it in the queue the coding agent works,',
+  'move it on the board, decide whether its plan waits for a review (autoBuild: false) or is built at once, read',
+  'and approve or reject its plan, stop or resume a run. Queueing, approving and resuming start paid agent work',
+  'that pushes commits and opens pull requests; stopping interrupts it. Tell the person what you are about to',
+  'start or stop and wait for their yes before calling these; a client that prompts on destructive tools does',
+  'that for you. A refusal (CONFLICT) carries the API reason: say it as it is.',
+  '',
+  '**Watching the line** (taiga_get_queue / taiga_wait_for_backlog_item / taiga_wait_for_build): the queue',
+  'read says what the line is waiting on (a plan to review, a pull request to merge, a halt and what lifts',
+  'it). Planning takes minutes and a build up to an hour: wait with the wait tools rather than reading the',
+  'same item again and again; each returns when the point is reached, when only a person can move it on,',
+  'or at its timeout (call again to keep waiting).',
   '',
   '**Sections.** Policies and instructions are maps of sections. Each section carries its text and two',
   'provenance fields you can read past: `source` says where the text originally came from (template:',
@@ -64,7 +71,8 @@ export const SERVER_INSTRUCTIONS = [
   '',
   'Workflow: start with taiga_get_product_context, naming the product by its git remote URL inside a checkout',
   '(git remote get-url origin), else by slug or ID from taiga_list_products. It returns the product, the',
-  'factory instructions, the specification and architecture, every policy as its section ids, the open backlog',
+  'factory instructions, the specification and architecture as the whole sections that fit (the rest named for',
+  'taiga_get_product_document to read by section), every policy as its section ids, the open backlog',
   'items, the repositories and the latest runs in one call, and names any part it could not read. Then read',
   'what you need in full: a policy with taiga_get_document, a backlog item with taiga_get_backlog_item.',
   'Without it, use taiga_list_factories and taiga_list_products, then read the factory instructions,',

package/src/tools/products.ts

@@ -17,7 +17,7 @@ import {
 } from './catalogue.js';
 import { apiFailureCode, apiFailureText, isMissOrRefusal, runTool, toolError, toolResult } from './errors.js';
 import { parseRemote } from './remote.js';
-import { stripProvenance } from './sections.js';
+import { pickSections, stripProvenance } from './sections.js';
 import { page, pickFields } from './summarize.js';
 
 /** What a product row needs to say for the model to pick one and read it in full. */
@@ -424,6 +424,8 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           'Read the plan to learn what to build: specification (requirements), architecture (design), ' +
           'threat_model (security risks), technology_decisions. Read reality, when the product has it, to ' +
           "learn what the code actually does before changing it. Omit origin for the product's own timeline. " +
+          'A large document runs to tens of thousands of characters: name the sections you need (the ids ' +
+          'taiga_get_product_context lists) and the read carries only those, listing the rest with their sizes. ' +
           'A read that finds nothing says which documents and timelines the product does have.',
         inputSchema: {
           productId,
@@ -431,6 +433,12 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
             .enum(PRODUCT_DOCUMENT_TYPES)
             .describe('Document type -- taiga_list_product_documents shows which ones the product has'),
           origin: originInput,
+          sections: z
+            .array(z.string().min(1).max(200))
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Only these sections, by id; omit for the whole document'),
         },
         annotations: READ_ONLY,
       },
@@ -443,7 +451,24 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           const origin = params.origin ?? defaultOriginFor(product, params.type);
           try {
             const result = await client.getProductDocument(params.productId, params.type, origin);
-            return toolResult(stripProvenance(result.data as Record<string, unknown>));
+            const doc = stripProvenance(result.data as Record<string, unknown>);
+            if (!params.sections) return toolResult(doc);
+            const cut = pickSections(doc, new Set(params.sections));
+            if (!cut) {
+              return toolError(
+                'VALIDATION_FAILED',
+                `The ${origin} ${params.type} is not made of sections; read it without sections.`
+              );
+            }
+            const all = Object.keys((doc.data as { sections: Record<string, unknown> }).sections);
+            const unknown = params.sections.filter((id) => !all.includes(id));
+            if (unknown.length > 0) {
+              return toolError(
+                'NOT_FOUND',
+                `The ${origin} ${params.type} has no section ${unknown.join(', ')}; its sections are ${all.join(', ')}.`
+              );
+            }
+            return toolResult({ ...cut.doc, omittedSections: cut.omittedSections });
           } catch (error) {
             if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
             // A product the key cannot see is a product miss, not a document

package/src/tools/prompts.ts

@@ -93,7 +93,7 @@ export function registerPrompts(server: McpServer, client: TaigaClient) {
             'taiga_list_products lists the slugs.'
         );
         if ('refusal' in resolved) refuse(resolved.refusal);
-        const result = await productContext(client, resolved.product, { fullDocuments: true });
+        const result = await productContext(client, resolved.product, { documents: 'full' });
         const bundle = (result.content[0] as { text?: string } | undefined)?.text ?? '{}';
         return message(
           [
@@ -263,8 +263,11 @@ export function registerPrompts(server: McpServer, client: TaigaClient) {
 
 /** A part the key's capabilities do not cover; named in its place rather than fetched. */
 class NotGranted extends Error {
-  constructor(readonly capability: string) {
+  readonly capability: string;
+
+  constructor(capability: string) {
     super(`needs ${capability}`);
+    this.capability = capability;
   }
   line(what: string): string {
     return `(${what} need ${this.capability}, which this key lacks.)`;

package/src/tools/queue.ts

@@ -0,0 +1,168 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { HALT_CAUSES, canResumeHalt, haltClearsItself, renderHalt, type Halt, type HaltCause } from '@taiga/types';
+import { TaigaApiError, type TaigaClient } from '../client.js';
+import { READ_ONLY } from './annotations.js';
+import { isNetworkFailure, runTool, toolResult } from './errors.js';
+import { productId } from './inputs.js';
+import { criteriaCounts } from './summarize.js';
+
+/** How many entries the read names; past this an entry keeps its backlogItemId only. */
+const NAMED_ENTRIES = 25;
+
+type Row = Record<string, unknown>;
+
+const MOVE_ASIDE =
+  'or move it down (taiga_queue_backlog_item with afterId) or off the line (taiga_move_backlog_item) to let the rest pass.';
+
+/**
+ * What lifts a halt, in the tools that do it. Read from the halt registry in
+ * @taiga/types (how each cause clears, and whether a person may lift it), so
+ * the advice cannot drift from what the API accepts; plan review is the one
+ * cause a tool answers directly.
+ */
+function haltNextStep(cause: string | null): string {
+  if (cause === 'awaiting_plan_review') {
+    return 'Read the plan with taiga_get_plan, then approve it (taiga_approve_plan) or send it back (taiga_reject_plan).';
+  }
+  const spec = cause ? (HALT_CAUSES as Record<string, { clearedWhen: string } | undefined>)[cause] : undefined;
+  if (!cause || !spec) return `Read the initiative with taiga_get_backlog_item to see why, ${MOVE_ASIDE}`;
+  const known = cause as HaltCause;
+  if (canResumeHalt(known)) return `taiga_resume_backlog_item lifts it, ${MOVE_ASIDE}`;
+  if (haltClearsItself(known)) return `It clears when ${spec.clearedWhen}; ${MOVE_ASIDE}`;
+  return `Only taking it off the line clears it (taiga_move_backlog_item): ${spec.clearedWhen}.`;
+}
+
+/**
+ * The entry the line waits on, by the queue's two kinds of blocker
+ * (@taiga/types): an active entry holds every other one wherever it sits, so
+ * it answers first; without one, the first halted entry holds the entries
+ * behind it. -1 when neither is there.
+ */
+function blockingIndex<T>(entries: T[], stateOf: (entry: T) => unknown): number {
+  const active = entries.findIndex((entry) => stateOf(entry) === 'active');
+  return active >= 0 ? active : entries.findIndex((entry) => stateOf(entry) === 'halted');
+}
+
+/** The one sentence a person needs: what the line is doing, or what it is waiting on. */
+function waitingOn(rows: Row[]): string | null {
+  const at = blockingIndex(rows, (row) => row.entryState);
+  if (at < 0) {
+    return rows.length > 0
+      ? 'Nothing in the queue is running; the first queued initiative starts when the line is free.'
+      : null;
+  }
+  const head = rows[at]!;
+  const name = typeof head.title === 'string' ? `"${head.title}"` : `Initiative ${String(head.backlogItemId)}`;
+  if (head.entryState === 'halted') {
+    const halt = head.halt as { reason: string; nextStep: string };
+    const ahead = at > 0 ? ' Entries ahead of it are not held by it.' : '';
+    return `${name} halted the queue, holding the entries behind it: ${halt.reason} ${halt.nextStep}${ahead}`;
+  }
+  const lifecycle = head.lifecycle as { turn?: unknown; stage?: unknown; cta?: unknown } | undefined;
+  const held = 'every other queued initiative waits until its pull request merges.';
+  if (!lifecycle) return `${name} is the active entry; ${held}`;
+  const pr = typeof head.prUrl === 'string' ? ` (${head.prUrl})` : '';
+  // An active entry with a landed plan is past its review gate (a closed
+  // gate halts it instead): it waits for the Build slot, not for anyone.
+  if (lifecycle.cta === 'start_build') return `${name} has its plan and waits for the Build slot; ${held}`;
+  if (lifecycle.turn === 'you') {
+    return `${name} is waiting on a person (${String(lifecycle.cta ?? lifecycle.stage)})${pr}; ${held}`;
+  }
+  return `${name} is ${String(lifecycle.stage)}${pr}; ${held}`;
+}
+
+/**
+ * The product's queue as a person reads it: each live entry in order with its
+ * initiative's title and where that initiative is, a halted entry with why and
+ * what lifts it, and one sentence saying what the line is waiting on. The
+ * route carries item ids only; each is named by one item read (when the key
+ * may read the backlog), and a read the API fails leaves that entry unnamed
+ * rather than failing the queue.
+ */
+export async function queueView(
+  client: TaigaClient,
+  product: string,
+  options: { name: 'all' | 'blocking' } = { name: 'all' }
+) {
+  const entries = ((await client.listQueue(product)).data as Row[]).filter((entry) => entry.state !== 'settled');
+  const canName = client.hasCapability('backlog:read');
+  // 'blocking' names only the entry the line waits on: a caller after one
+  // position and waitingOn need no more reads than that.
+  const blocking = blockingIndex(entries, (entry) => entry.state);
+  const toName = !canName
+    ? []
+    : options.name === 'all'
+      ? entries.slice(0, NAMED_ENTRIES).map((_, index) => index)
+      : blocking >= 0
+        ? [blocking]
+        : [];
+  const settled = await Promise.allSettled(
+    toName.map((index) => client.getBacklogItem(String(entries[index]!.backlogItemId)))
+  );
+  const reads = new Map(toName.map((index, at) => [index, settled[at]!]));
+  let unnamed = options.name === 'all' ? entries.length - toName.length : 0;
+  const rows = entries.map((entry, index) => {
+    const read = reads.get(index);
+    if (read?.status === 'rejected') {
+      // Only the API failing leaves an entry unnamed; a bug here surfaces.
+      if (!(read.reason instanceof TaigaApiError || isNetworkFailure(read.reason))) throw read.reason;
+      unnamed += 1;
+    }
+    const item = read?.status === 'fulfilled' ? (read.value.data as Row) : null;
+    const lifecycle = item?.lifecycle as Row | undefined;
+    const latestBuild = lifecycle?.latestBuild as Row | null | undefined;
+    const row: Row = { position: index + 1, backlogItemId: entry.backlogItemId, entryState: entry.state };
+    if (item) {
+      Object.assign(row, {
+        title: item.title,
+        state: item.state,
+        planningStatus: item.planningStatus,
+        needsHumanCause: item.needsHumanCause,
+        criteria: criteriaCounts(item),
+        lifecycle: lifecycle ? { turn: lifecycle.turn, stage: lifecycle.stage, cta: lifecycle.cta } : null,
+        ...(latestBuild ? { buildId: latestBuild.id, prUrl: latestBuild.prUrl ?? null } : {}),
+      });
+    }
+    if (entry.state === 'halted') {
+      const cause = typeof entry.haltCause === 'string' ? entry.haltCause : null;
+      // The registry renders the sentence; the stored prose answers for a
+      // cause this build does not know yet.
+      const rendered = cause ? renderHalt({ cause, params: entry.haltParams ?? {} } as Halt) : '';
+      row.halt = {
+        cause,
+        reason: rendered || (typeof entry.haltReason === 'string' ? entry.haltReason : 'The queue stopped here.'),
+        nextStep: haltNextStep(cause),
+      };
+    }
+    return row;
+  });
+  const note =
+    unnamed === 0
+      ? null
+      : !canName
+        ? 'Entries carry backlogItemId only: naming them needs backlog:read, which this key lacks.'
+        : entries.length > NAMED_ENTRIES
+          ? `Only the first ${NAMED_ENTRIES} entries are named; the rest carry backlogItemId only.`
+          : 'An entry whose initiative could not be read carries backlogItemId only; taiga_get_backlog_item reads it.';
+  return { entries: rows, waitingOn: waitingOn(rows), ...(note ? { note } : {}) };
+}
+
+export function registerQueueTools(server: McpServer, client: TaigaClient) {
+  if (!client.hasCapability('products:read')) return;
+
+  server.registerTool(
+    'taiga_get_queue',
+    {
+      title: 'Get the product queue',
+      description:
+        "Read a product's queue, the line the coding agent works one initiative at a time: each entry in order " +
+        'with its title, where it is (planning, building, in review) and whose turn it is, a halted entry with why ' +
+        'it stopped and what lifts it, and waitingOn, one sentence saying what the line is waiting for. The ' +
+        "line advances only when the active entry's pull request merges, so an entry waiting on a review holds " +
+        'everything behind it. Use this when a queued initiative is not moving.',
+      inputSchema: { productId },
+      annotations: READ_ONLY,
+    },
+    (params) => runTool(async () => toolResult(await queueView(client, params.productId)))
+  );
+}

package/src/tools/sections.test.ts

@@ -1,5 +1,13 @@
 import { describe, it, expect } from 'vitest';
-import { applySectionEdit, instructionsText, sectionContent, sectionsOf, stripProvenance } from './sections.js';
+import {
+  applySectionEdit,
+  budgetSections,
+  instructionsText,
+  pickSections,
+  sectionContent,
+  sectionsOf,
+  stripProvenance,
+} from './sections.js';
 
 describe('sectionsOf', () => {
   it('returns the sections map of a section-shaped document', () => {
@@ -106,3 +114,30 @@ describe('stripProvenance', () => {
     expect(stripProvenance(doc)).toEqual(doc);
   });
 });
+
+describe('budgetSections and pickSections', () => {
+  // Parsed, as the API's JSON arrives: an own "__proto__" key, not a prototype.
+  const doc = JSON.parse(
+    '{"data":{"sections":{"__proto__":{"content":"aaaa"},"constructor":{"content":"bbbb"},"toString":{"content":"cccc"}}}}'
+  ) as Record<string, unknown>;
+
+  it('keeps a section named like an Object.prototype member as an ordinary section', () => {
+    const cut = budgetSections(doc, 8)!;
+    const kept = (cut.doc.data as { sections: Record<string, unknown> }).sections;
+
+    expect(Object.keys(kept)).toEqual(['__proto__', 'constructor']);
+    expect(Object.getPrototypeOf(kept)).toBe(Object.prototype);
+    expect(cut.omittedSections).toEqual([{ id: 'toString', characters: 4 }]);
+  });
+
+  it('lists every section not picked, including one named like a prototype member', () => {
+    const cut = pickSections(doc, new Set(['toString']))!;
+
+    expect(cut.omittedSections.map((s) => s.id)).toEqual(['__proto__', 'constructor']);
+  });
+
+  it('answers null for a document that is not made of sections', () => {
+    expect(budgetSections({ data: { legacy: 'x' } }, 10)).toBeNull();
+    expect(pickSections({ data: { legacy: 'x' } }, new Set(['a']))).toBeNull();
+  });
+});

package/src/tools/sections.ts

@@ -75,3 +75,53 @@ export function instructionsText(sections: Sections): string | null {
   const text = parts.join('\n\n').trim();
   return text || null;
 }
+
+/** A document cut to some of its sections, and the ones left out with their sizes. */
+export interface SectionCut {
+  doc: Record<string, unknown>;
+  omittedSections: { id: string; characters: number }[];
+}
+
+function cutTo(doc: Record<string, unknown>, sections: Sections, kept: Sections): SectionCut {
+  const omittedSections = Object.keys(sections)
+    .filter((id) => !Object.hasOwn(kept, id))
+    .map((id) => ({ id, characters: sectionContent(sections, id)?.length ?? 0 }));
+  return { doc: { ...doc, data: { ...(doc.data as Record<string, unknown>), sections: kept } }, omittedSections };
+}
+
+/**
+ * The named sections of a section-shaped document, in the order the API
+ * returns them (a jsonb column: shorter ids first, then by bytes, not the
+ * order a person wrote them);
+ * every other section is listed with its size so the reader knows what else
+ * there is. Null when the document is not made of sections.
+ */
+export function pickSections(doc: Record<string, unknown>, ids: ReadonlySet<string>): SectionCut | null {
+  const sections = isRecord(doc.data) ? sectionsOf(doc.data) : null;
+  if (!sections) return null;
+  return cutTo(doc, sections, Object.fromEntries(Object.entries(sections).filter(([id]) => ids.has(id))));
+}
+
+/**
+ * As many whole sections as fit `budget` characters of text, the rest listed
+ * with their sizes so the reader can ask for them by id. Whole, never cut: a
+ * section's text is one argument, and half of it reads as all of it. Not "the
+ * opening": the document's own order is not in the data (a jsonb column
+ * hands back shorter ids first), so a section that does not fit is skipped
+ * and a later, smaller one may still be carried. Null when the document is
+ * not made of sections.
+ */
+export function budgetSections(doc: Record<string, unknown>, budget: number): SectionCut | null {
+  const sections = isRecord(doc.data) ? sectionsOf(doc.data) : null;
+  if (!sections) return null;
+  // Entries, not assignment: a section id is text, and `kept["__proto__"] = x` would set a prototype.
+  const kept: [string, unknown][] = [];
+  let used = 0;
+  for (const id of Object.keys(sections)) {
+    const length = sectionContent(sections, id)?.length ?? 0;
+    if (used + length > budget) continue;
+    kept.push([id, sections[id]]);
+    used += length;
+  }
+  return cutTo(doc, sections, Object.fromEntries(kept));
+}

package/src/tools/summarize.ts

@@ -20,3 +20,26 @@ export function pickFields<T extends Record<string, unknown>>(
 export function page<T>(data: T[], nextCursor: string | null | undefined): { data: T[]; nextCursor: string | null } {
   return { data, nextCursor: nextCursor ?? null };
 }
+
+/**
+ * How many of an initiative's acceptance criteria are met: one pair a row can
+ * carry, so "done with two unmet" shows in a list without reading the item.
+ * Null while it has none (an unplanned initiative).
+ */
+export function criteriaCounts(item: Record<string, unknown>): { met: number; total: number } | null {
+  const criteria = item.acceptanceCriteria;
+  if (!Array.isArray(criteria) || criteria.length === 0) return null;
+  const met = criteria.filter((c) => typeof c === 'object' && c !== null && (c as { met?: unknown }).met === true);
+  return { met: met.length, total: criteria.length };
+}
+
+/**
+ * Initiative rows cut to `fields`, each with its criteria counts. A row that
+ * does not carry `acceptanceCriteria` at all gets no count rather than a
+ * null that would read as "has none".
+ */
+export function itemRows(items: Record<string, unknown>[], fields: readonly string[]): Record<string, unknown>[] {
+  return pickFields(items, fields).map((row, index) =>
+    'acceptanceCriteria' in items[index]! ? { ...row, criteria: criteriaCounts(items[index]!) } : row
+  );
+}