@taiga-ai/mcp-server 0.25.0-rc.474 → 0.26.0-dev.481

package/src/tools/context.ts

@@ -1,513 +0,0 @@
-import type { McpServer, CallToolResult } from '@modelcontextprotocol/server';
-import { isSettledOrArchived } from '@taiga/types';
-import type { BacklogItem, Product } from '@taiga/types';
-import { z } from 'zod';
-import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
-import { READ_ONLY } from './annotations.js';
-import { situatedRows } from './backlogs.js';
-import { POLICY_TYPES, defaultOriginFor, isImportedProduct } from './catalogue.js';
-import {
-  apiFailureText,
-  inProductWords,
-  isNetworkFailure,
-  networkFailureDetail,
-  runTool,
-  toolError,
-  toolResult,
-} from './errors.js';
-import { productId, remoteUrl, slug } from './inputs.js';
-import { PRODUCT_SUMMARY_FIELDS, resolveProductRef } from './products.js';
-import {
-  budgetSections,
-  instructionsText,
-  isRecord,
-  sectionContent,
-  sectionsOf,
-  stripProvenance,
-  type DocumentData,
-  type StoredDocument,
-} from './sections.js';
-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
- * otherwise collect in eight, fanned out here. Each part stands on its own
- * (Promise.allSettled): a part the API refuses or fails is named under
- * `unavailable` with what the API said, a part the key's capabilities do not
- * cover is named under `notGranted`, and neither is ever shown as empty. A
- * failure that is not the API's (a bug in this code) is not downgraded; it
- * fails the call so it surfaces.
- */
-
-/** The two documents a coding session starts from; the rest are a read away. */
-const CONTEXT_DOCUMENT_TYPES = ['specification', 'architecture'] as const;
-
-const REPOSITORY_SUMMARY_FIELDS = [
-  'id',
-  'provider',
-  'repositoryName',
-  'repositoryUrl',
-  'effectiveBranch',
-  'isManaged',
-] as const;
-
-/** How many of the latest runs to carry; taiga_list_runs pages the rest. */
-const BUILDS_IN_CONTEXT = 5;
-
-/** A run as the bundle carries it: enough to say what was built and where; taiga_get_run has the rest. */
-const CONTEXT_BUILD_FIELDS = [
-  'id',
-  'runNumber',
-  'backlogItemId',
-  'targetTitle',
-  'status',
-  'failedReason',
-  'completedSteps',
-  'totalSteps',
-  'baseBranch',
-  'prNumber',
-  'prUrl',
-  'prState',
-  'prMerged',
-  'prDraft',
-  'reviewEscalation',
-  'error',
-  // Read for hardeningNote; the compact row drops it.
-  'hardeningResult',
-  'createdAt',
-] as const;
-
-/**
- * Characters of section text each of the two documents may bring by default.
- * Two of them plus the rest of the bundle stay well inside the 25k-token
- * tool result Claude Code accepts (a 67k-character bundle was refused); a
- * larger product's documents come cut, with the sections left out named.
- */
-export const DOCUMENT_BUDGET = 12_000;
-
-/**
- * The document without each section's citations: on a reality document they
- * are the code evidence behind every claim and as long as the text itself,
- * which a session's opening read does not need. The full read keeps them.
- * Says whether any were dropped, so the bundle can tell the reader.
- */
-function withoutCitations(doc: StoredDocument): { doc: StoredDocument; dropped: boolean } {
-  const sections = isRecord(doc.data) ? sectionsOf(doc.data) : null;
-  if (!sections) return { doc, dropped: false };
-  let dropped = false;
-  const kept = Object.fromEntries(
-    Object.entries(sections).map(([id, section]) => {
-      if (!isRecord(section) || !('citations' in section)) return [id, section];
-      dropped = true;
-      const { citations: _citations, ...rest } = section;
-      return [id, rest];
-    })
-  );
-  return { doc: { ...doc, data: { ...(doc.data as DocumentData), sections: kept } }, dropped };
-}
-
-/**
- * How much of the two documents the bundle carries. The outline by default
- * (PRO-2778): the whole sections that fit a budget made the opening read run
- * to 43k characters for an active product, most of it prose a "where does it
- * stand" question never reads.
- */
-export const DOCUMENT_DEPTHS = ['outline', 'budget', 'full'] as const;
-export type DocumentDepth = (typeof DOCUMENT_DEPTHS)[number];
-
-/** Pages of 100 the backlog part follows before it stops and says so. */
-const BACKLOG_PAGE_LIMIT = 10;
-
-/**
- * Open items the bundle carries, the newest of those read; past this it says truncated and
- * taiga_list_initiatives pages the rest. Keeps a product with hundreds of
- * open initiatives inside the tool result the document budget is sized for.
- */
-const BACKLOG_IN_CONTEXT = 50;
-
-const PARTS = {
-  factory: 'factories:read',
-  documents: 'products:read',
-  policies: 'tenant:documents:read',
-  initiatives: 'backlog:read',
-  repositories: 'products:read',
-  runs: 'products:read',
-  actionRequired: 'products:read',
-  maintenance: 'products:read',
-  policyStanding: 'products:read',
-} as const;
-type Part = keyof typeof PARTS;
-
-/** What the API said when a part failed, in the words the bundle reports. */
-function unavailableReason(reason: unknown): string {
-  if (reason instanceof TaigaApiError) return apiFailureText(reason);
-  return `the API could not be reached: ${networkFailureDetail(reason as TypeError)}`;
-}
-
-/** Whether a failed part is the API's doing; anything else is ours and propagates. */
-function isApiFailure(reason: unknown): boolean {
-  return reason instanceof TaigaApiError || isNetworkFailure(reason);
-}
-
-function isNotFound(reason: unknown): boolean {
-  return reason instanceof TaigaApiError && reason.status === 404;
-}
-
-/** The factory's standing guidance in full; null, with a note, when none is published or it is not section-shaped. */
-async function factoryPart(client: TaigaClient, factoryId: string) {
-  const factory = (await client.getFactory(factoryId)).data;
-  const base = { id: factory.id, name: factory.name, slug: factory.slug };
-  try {
-    const doc = (await client.getFactoryDocument(factoryId, 'factory_instructions')).data;
-    const sections = sectionsOf(doc.data);
-    if (!sections) {
-      return {
-        ...base,
-        instructions: null,
-        instructionsVersion: doc.version,
-        note: 'The published instructions are not made of sections; read them with taiga_get_factory_document.',
-      };
-    }
-    // Every section, as the API injects them into the agents; a factory
-    // whose instructions grew a second section is not cut to the first.
-    return { ...base, instructions: instructionsText(sections), instructionsVersion: doc.version };
-  } catch (error) {
-    if (!isNotFound(error)) throw error;
-    return {
-      ...base,
-      instructions: null,
-      instructionsVersion: null,
-      note: 'This factory has not published instructions yet.',
-    };
-  }
-}
-
-/**
- * The specification and architecture from the product's own timeline: their
- * outline by default, the whole sections up to a budget or in full when
- * asked. Null, with a note, where unpublished.
- */
-async function documentsPart(client: TaigaClient, product: WithoutTenant<Product>, depth: DocumentDepth) {
-  const productId = product.id;
-  const origin = defaultOriginFor(product);
-  const reads = await Promise.allSettled(
-    CONTEXT_DOCUMENT_TYPES.map((type) => client.getProductDocument(productId, type, origin))
-  );
-  const out: Record<string, unknown> = { origin };
-  const notes: string[] = [];
-  CONTEXT_DOCUMENT_TYPES.forEach((type, index) => {
-    const read = reads[index]!;
-    if (read.status === 'fulfilled') {
-      const doc = stripProvenance(read.value.data);
-      if (depth === 'full') out[type] = doc;
-      else if (depth === 'budget') {
-        const lean = withoutCitations(doc);
-        if (lean.dropped) {
-          notes.push(
-            `The ${origin} ${type} leaves out each section's citations (its code evidence); taiga_get_product_document carries them.`
-          );
-        }
-        const cut = budgetSections(lean.doc, DOCUMENT_BUDGET);
-        if (!cut) {
-          // Not made of sections: whole when small, else pointed at.
-          const small = JSON.stringify(lean.doc).length <= DOCUMENT_BUDGET;
-          out[type] = small ? lean.doc : { version: doc.version, sections: null };
-          if (!small)
-            notes.push(`The ${origin} ${type} is not made of sections; read it with taiga_get_product_document.`);
-        } else if (cut.omittedSections.length > 0) {
-          out[type] = { ...cut.doc, omittedSections: cut.omittedSections };
-          notes.push(
-            `The ${origin} ${type} carries the whole sections that fit; read the ones under omittedSections with ` +
-              'taiga_get_product_document, naming them in sections.'
-          );
-        } else out[type] = cut.doc;
-      } else {
-        const sections = sectionsOf(doc.data ?? {});
-        if (sections) {
-          // Each id with the length of its text, so the next read is sized before it is
-          // made (a reality section's citations come on top).
-          const outline = Object.keys(sections).map((id) => ({
-            id,
-            characters: sectionContent(sections, id)?.length ?? 0,
-          }));
-          out[type] = { version: doc.version, sections: outline };
-        } else {
-          out[type] = { version: doc.version, sections: null };
-          notes.push(`The ${origin} ${type} is not made of sections; read it with taiga_get_product_document.`);
-        }
-      }
-    } else if (isNotFound(read.reason)) {
-      out[type] = null;
-      notes.push(`No published ${origin} ${type}; taiga_get_product_document without type shows what the product has.`);
-    } else throw read.reason;
-  });
-  return { ...out, notes };
-}
-
-/** Every published policy with its section count, so the model knows which one to read with taiga_get_document. */
-async function policiesPart(client: TaigaClient) {
-  const rows = (await client.listTenantDocuments({ limit: 100 })).data as Record<string, unknown>[];
-  // Each policy with how many sections it has, not their ids: the same for every product, and about a fifth of
-  // the bundle (PRO-2800). taiga_get_document with sections: [] lists them, and a control id reads its section.
-  return rows
-    .filter((row) => (POLICY_TYPES as readonly string[]).includes(String(row['type'])) && row['isDraft'] === false)
-    .map((row) => ({
-      type: row['type'],
-      name: row['name'],
-      version: row['version'],
-      sections: Object.keys(sectionsOf((row['data'] as Record<string, unknown>) ?? {}) ?? {}).length,
-    }));
-}
-
-/** The statuses an item is open in; the API's filter takes one at a time. */
-const OPEN_BACKLOG_STATUSES = ['backlog', 'in_progress'] as const;
-
-/**
- * The items still open: one status-filtered read per open status (the API
- * leaves archived items out), each paged in full up to a cap the result
- * reports. The list is oldest first and the open items are the newest, so a
- * single page would miss exactly the ones that matter. Rows carrying a
- * retired status (readable for a rolling deploy) match neither filter;
- * the settled check below keeps the shape honest for whatever comes back.
- */
-async function backlogPart(client: TaigaClient, productId: string) {
-  // Keyed by id: an item that moves from backlog to in_progress between the
-  // two reads would otherwise appear twice.
-  const open = new Map<string, WithoutTenant<BacklogItem>>();
-  let truncated = false;
-  let pageCapped = false;
-  for (const status of OPEN_BACKLOG_STATUSES) {
-    let cursor: string | undefined;
-    for (let pageIndex = 0; ; pageIndex += 1) {
-      if (pageIndex === BACKLOG_PAGE_LIMIT) {
-        truncated = true;
-        pageCapped = true;
-        break;
-      }
-      const result = await client.listBacklogItems(productId, { status, limit: 100, cursor });
-      for (const row of result.data) {
-        if (!isSettledOrArchived({ status: String(row.status), archivedAt: row.archivedAt ?? null })) {
-          open.set(String(row.id), row);
-        }
-      }
-      if (!result.nextCursor) break;
-      cursor = result.nextCursor;
-    }
-  }
-  // One read per status, so the rows arrive grouped by status, not by age.
-  // Ids are UUIDv7, time-ordered: sorted by id, the newest are the last.
-  const rows = [...open.values()].sort((a, b) =>
-    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
-    // page cap was read only up to its oldest items: these are the newest of
-    // what was read, not of the backlog.
-    ...(pageCapped
-      ? {
-          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 and byColumn counts only those read; taiga_list_initiatives pages the rest.',
-        }
-      : {}),
-  };
-}
-
-/**
- * The linked repositories. The route serves one page of 100 and takes no
- * cursor, so past that the bundle says the list is cut rather than complete.
- */
-async function repositoriesPart(links: () => ReturnType<TaigaClient['listProductRepositories']>) {
-  const result = await links();
-  return {
-    items: pickFields(result.data, REPOSITORY_SUMMARY_FIELDS),
-    truncated: result.nextCursor !== null,
-  };
-}
-
-async function buildsPart(client: TaigaClient, productId: string) {
-  const rows = (await client.listBuildRuns(productId, { limit: BUILDS_IN_CONTEXT })).data as Record<string, unknown>[];
-  const states = await initiativeStates(client, rows);
-  // The fields the outcome is made from are read, then the row is cut to what the bundle says: each run with its
-  // two-sentence outcome and every PR field was half the context, repeated by taiga_list_runs (PRO-2800).
-  return pickFields(rows, CONTEXT_BUILD_FIELDS)
-    .map(readableRow)
-    .map((row) => withInitiativeState(row, states))
-    .map((row) => pickFields([row], CONTEXT_RUN_SAID)[0]!);
-}
-
-/** A run in the bundle: which one, for what, how it ended, and its pull request. taiga_get_run has the rest. */
-const CONTEXT_RUN_SAID = [
-  'id',
-  'runNumber',
-  'backlogItemId',
-  'targetTitle',
-  'disposition',
-  'outcome',
-  // Rare and short, and what the outcome sentence does not say.
-  'failedReasonMeans',
-  'hardeningNote',
-  'prUrl',
-  'createdAt',
-] as const;
-
-/**
- * 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 });
-  const counts = await attentionCounts(client, result.data as Record<string, unknown>[]);
-  return {
-    ...counts,
-    ...(result.nextCursor
-      ? { note: 'These count the first 100 items; taiga_list_action_required pages the rest.' }
-      : {}),
-  };
-}
-
-/** The latest sweep and what it left open, as counts; taiga_list_findings lists them. */
-async function maintenancePart(client: TaigaClient, productId: string) {
-  const summary = (await client.getMaintenanceSummary(productId)).data as Record<string, unknown>;
-  const last = summary['lastRun'] as Record<string, unknown> | null | undefined;
-  return {
-    openFindings: summary['openFindings'],
-    bySeverity: summary['severityCounts'],
-    lastSweep: last ? { status: last['status'], completedAt: last['completedAt'] } : null,
-    ...(last ? {} : { note: 'Never swept: no findings is not an all-clear.' }),
-  };
-}
-
-/** Where the product stands against the policies, as counts; taiga_get_policy_standing has each violation. */
-async function standingPart(client: TaigaClient, productId: string) {
-  const standing = (await client.getPolicyStanding(productId)).data;
-  const summary = standingSummary(standing);
-  // No violations from an assessment that never ran, or failed, is no all-clear (PRO-2800).
-  const state = (standing.assessment as { state?: unknown } | null | undefined)?.state;
-  return {
-    openViolations: summary.violations,
-    bySeverity: summary.bySeverity,
-    controlsViolated: summary.controls,
-    ...(state === 'never' || state === 'failed'
-      ? {
-          note: `The assessment ${state === 'never' ? 'has never run' : 'failed'}: no violations here is not an all-clear.`,
-        }
-      : {}),
-  };
-}
-
-export async function productContext(
-  client: TaigaClient,
-  product: WithoutTenant<Product>,
-  options: { documents: DocumentDepth }
-): Promise<CallToolResult> {
-  const productId = product.id;
-  const granted = (part: Part) => client.hasCapability(PARTS[part]);
-  const notGranted = (Object.keys(PARTS) as Part[]).filter((part) => !granted(part));
-
-  // One read of the links serves the repositories part and the setup readiness.
-  let linksRead: ReturnType<TaigaClient['listProductRepositories']> | undefined;
-  const links = () => (linksRead ??= client.listProductRepositories(productId));
-  const fetchers: Record<Part, () => Promise<unknown>> = {
-    factory: () => factoryPart(client, String(product.factoryId)),
-    documents: () => documentsPart(client, product, options.documents),
-    policies: () => policiesPart(client),
-    initiatives: () => backlogPart(client, productId),
-    repositories: () => repositoriesPart(links),
-    runs: () => buildsPart(client, productId),
-    actionRequired: () => attentionPart(client, productId),
-    maintenance: () => maintenancePart(client, productId),
-    policyStanding: () => standingPart(client, productId),
-  };
-  const parts = (Object.keys(fetchers) as Part[]).filter(granted);
-  const [settled, readiness] = await Promise.all([
-    Promise.allSettled(parts.map((part) => fetchers[part]())),
-    setupReadiness(client, product, links),
-  ]);
-
-  const bundle: Record<string, unknown> = {
-    product: {
-      ...pickFields([product], PRODUCT_SUMMARY_FIELDS)[0],
-      projectType: isImportedProduct(product) ? 'brownfield' : 'greenfield',
-      defaultOrigin: defaultOriginFor(product),
-      // A product in setup says what it still needs: nothing else in the bundle does.
-      ...(readiness ? { readiness } : {}),
-    },
-  };
-  const unavailable: Record<string, string> = {};
-  parts.forEach((part, index) => {
-    const result = settled[index]!;
-    if (result.status === 'fulfilled') bundle[part] = result.value;
-    else if (isApiFailure(result.reason)) unavailable[part] = unavailableReason(result.reason);
-    else throw result.reason;
-  });
-  const result = {
-    ...bundle,
-    notGranted: notGranted.map((part) => `${part} (needs ${PARTS[part]})`),
-    unavailable,
-    readNext:
-      'Read a policy with taiga_get_document (sections: [] for its outline, or a control id such as SEC-5.1), the ' +
-      "specification's or architecture's sections or another product document with taiga_get_product_document, " +
-      'an initiative with taiga_get_initiative (taiga_list_initiatives pages a truncated backlog) and a run ' +
-      'with taiga_get_run.',
-  };
-  // Its own size, so a model can judge what one more read would cost: counted
-  // with the field in place, until the count no longer changes its own length.
-  // Measured as sent: toolResult renames keys into the product's words.
-  let characters = JSON.stringify(inProductWords(result), null, 2).length;
-  for (let measured = -1; measured !== characters;) {
-    measured = characters;
-    characters = JSON.stringify(inProductWords({ ...result, characters: measured }), null, 2).length;
-  }
-  return toolResult({ ...result, characters });
-}
-
-export function registerContextTools(server: McpServer, client: TaigaClient) {
-  if (!client.hasCapability('products:read')) return;
-
-  server.registerTool(
-    'taiga_get_product_context',
-    {
-      title: 'Get product context',
-      description:
-        '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 with a count per board column (byColumn; taiga_list_initiatives status: 'all' has the done " +
-        'and canceled), repositories, the latest five runs (taiga_list_runs has more), 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.',
-      inputSchema: z.object({
-        productId: productId.optional(),
-        slug: slug.optional(),
-        remoteUrl: remoteUrl.optional(),
-        documents: z
-          .enum(DOCUMENT_DEPTHS)
-          .optional()
-          .describe(
-            'The specification and architecture as outline (section ids and sizes, the default), budget (the whole sections that fit) or full'
-          ),
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const resolved = await resolveProductRef(client, params, ['productId', 'slug', 'remoteUrl']);
-        if ('refusal' in resolved) return toolError(resolved.refusal.code, resolved.refusal.message);
-        return productContext(client, resolved.product, { documents: params.documents ?? 'outline' });
-      })
-  );
-}