@taiga-ai/mcp-server 0.25.0-rc.472 → 0.26.0-dev.479

package/src/tools/maintenance.ts

@@ -1,540 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import {
-  MAINTENANCE_FINDING_KINDS,
-  MAINTENANCE_FINDING_SEVERITIES,
-  MAINTENANCE_FINDING_STATUSES,
-  MAINTENANCE_IGNORE_REASONS,
-} from '@taiga/types';
-import { z } from 'zod';
-import { TaigaApiError, type TaigaClient } from '../client.js';
-import { OPERATE, READ_ONLY } from './annotations.js';
-import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
-import { idInput, pagination, productId } from './inputs.js';
-import { page, pickFields } from './summarize.js';
-
-/**
- * Maintaining (docs.tai.ga, Operate): what the sweeps found in a product's
- * repository and where it stands against the organization's own policies,
- * and the two things a person does with a finding, Ignore and Fix. Sweeps run
- * themselves and nothing is marked fixed by hand: a finding resolves when the
- * next sweep no longer detects it, so there is no tool for either.
- */
-
-/** A finding as a list row: enough to decide whether to open, fix or ignore it. */
-const FINDING_ROW_FIELDS = [
-  'id',
-  'kind',
-  'severity',
-  'tier',
-  'status',
-  'title',
-  'ecosystem',
-  'packageName',
-  'currentVersion',
-  'recommendedVersion',
-  'advisoryId',
-  'location',
-  'sourcePaths',
-  'productRepositoryId',
-  'ownership',
-  'remediableBy',
-  'controls',
-  'backlogItemId',
-  'detectedAt',
-  'ignoreReason',
-  'ignoreExpiresAt',
-] as const;
-
-/**
- * Whether taiga_fix_finding would take a finding, said on the row (PRO-2800): three reviews found a dependency
- * marked remediableBy coding_agent with no fixed version, which the API refuses to fix. The API's own refusals,
- * read off the row; remediableBy stays as the sweep recorded it.
- */
-function withFixability(row: Row): Row {
-  const dependency = row['kind'] === 'vulnerable_dependency' || row['kind'] === 'outdated_dependency';
-  if (dependency && !row['recommendedVersion'] && row['remediableBy'] === 'coding_agent') {
-    return {
-      ...row,
-      fixable: false,
-      fixNote: 'No fixed version is known yet: taiga_fix_finding refuses it until one is published.',
-    };
-  }
-  return row;
-}
-
-/** The parts of an advisory record an agent reads; the rest (every affected range, every reference) is full: true. */
-const ADVISORY_KEPT = ['id', 'aliases', 'summary', 'details', 'severity', 'published'];
-const ADVISORY_TEXT_LIMIT = 1_500;
-
-function leanAdvisory(data: unknown): unknown {
-  if (typeof data !== 'object' || data === null || !('affected' in data || 'references' in data)) return data;
-  const record = data as Row;
-  const kept = Object.fromEntries(ADVISORY_KEPT.filter((key) => key in record).map((key) => [key, record[key]]));
-  const details = kept['details'];
-  if (typeof details === 'string' && details.length > ADVISORY_TEXT_LIMIT) {
-    kept['details'] =
-      `${details.slice(0, ADVISORY_TEXT_LIMIT)}... [cut at ${ADVISORY_TEXT_LIMIT} of ${details.length} characters; full: true reads it whole]`;
-  }
-  const references = Array.isArray(record['references']) ? record['references'] : [];
-  return {
-    ...kept,
-    ...(references.length > 0
-      ? {
-          references: references.slice(0, 3),
-          ...(references.length > 3 ? { referencesNote: `3 of ${references.length}; full: true has every one.` } : {}),
-        }
-      : {}),
-  };
-}
-
-/** A sweep as the record of when the product was last checked, and whether that check held. */
-const SWEEP_FIELDS = [
-  'id',
-  'trigger',
-  'status',
-  'scanners',
-  'findingsCount',
-  'newFindingsCount',
-  'error',
-  'createdAt',
-  'completedAt',
-] as const;
-
-/** A policy violation in a list: what it is, how bad, and what is being done about it. */
-const VIOLATION_FIELDS = [
-  'id',
-  'controlId',
-  'policyType',
-  'severity',
-  'status',
-  'title',
-  'summary',
-  'work',
-  'unconfirmedSince',
-  'verifyRequestedAt',
-  'assessedAt',
-] as const;
-
-type Row = Record<string, unknown>;
-
-/** Characters of one text field the full standing carries; violationId reads one violation uncut. */
-const FULL_TEXT_LIMIT = 1_500;
-
-/** Resolved violations the full standing carries. */
-const FULL_RESOLVED = 20;
-
-/** A copy with every string longer than the limit cut and marked, at any depth. */
-function cutLongText(value: unknown): unknown {
-  if (typeof value === 'string') {
-    return value.length > FULL_TEXT_LIMIT
-      ? `${value.slice(0, FULL_TEXT_LIMIT)}... [cut at ${FULL_TEXT_LIMIT} of ${value.length} characters; violationId reads it whole]`
-      : value;
-  }
-  if (Array.isArray(value)) return value.map(cutLongText);
-  if (value === null || typeof value !== 'object') return value;
-  return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, cutLongText(inner)]));
-}
-
-/**
- * How bad a product's policy standing is, as counts: the controls something is
- * recorded against, the open violations by severity, the resolved ones. The
- * API's standing carries the lists only; this tool and the product context
- * both count them here.
- */
-export function standingSummary(standing: {
-  controls?: unknown;
-  divergences?: unknown;
-  resolvedDivergences?: unknown;
-}): {
-  controls: number;
-  controlsInPolicies: number;
-  controlsWithNothingRecorded: number;
-  violations: number;
-  bySeverity: Record<string, number>;
-  resolvedViolations: number;
-} {
-  const controls = Array.isArray(standing.controls) ? (standing.controls as Row[]) : [];
-  const violations = Array.isArray(standing.divergences) ? (standing.divergences as Row[]) : [];
-  const resolved = Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences.length : 0;
-  const listed = controls.filter((c) => Number(c['divergenceCount'] ?? 0) > 0 || Number(c['findingCount'] ?? 0) > 0);
-  const bySeverity: Record<string, number> = {};
-  for (const violation of violations) {
-    const severity = String(violation['severity'] ?? 'unknown');
-    bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
-  }
-  return {
-    controls: listed.length,
-    // Every control the product's policies hold, and those nothing is recorded against: the positive side of
-    // "how do we stand", which is no evidence against them, not proof they are met.
-    controlsInPolicies: controls.length,
-    controlsWithNothingRecorded: controls.length - listed.length,
-    violations: violations.length,
-    bySeverity,
-    resolvedViolations: resolved,
-  };
-}
-
-const findingId = idInput('finding', 'taiga_list_findings gives it');
-
-/** Open findings by severity and kind, and the latest sweeps, as the first page of findings carries them. */
-async function sweepOverview(client: TaigaClient, productId: string) {
-  const [summary, sweeps] = await Promise.all([
-    client.getMaintenanceSummary(productId),
-    client.listMaintenanceSweeps(productId, { limit: 3 }),
-  ]);
-  const latest = pickFields(sweeps.data, SWEEP_FIELDS);
-  // The summary's own run rows (one per repository) would repeat the sweeps with every column.
-  const {
-    lastRun: _lastRun,
-    lastRuns: _lastRuns,
-    topFindings: _top,
-    violatedControls: _controls,
-    ...counts
-  } = summary.data as Record<string, unknown>;
-  return {
-    ...counts,
-    latestSweeps: latest,
-    ...(latest.length === 0 ? { note: 'This product has never been swept: no findings is not an all-clear.' } : {}),
-  };
-}
-
-export function registerMaintenanceTools(server: McpServer, client: TaigaClient) {
-  if (!client.hasCapability('products:read')) return;
-
-  server.registerTool(
-    'taiga_list_findings',
-    {
-      title: 'List maintenance findings',
-      description:
-        "List what maintenance sweeps found in a product's repository: dependencies, secrets, insecure code " +
-        '(sast) and infrastructure. The first page opens with sweep (open counts, latest sweeps), so an old or ' +
-        'failed sweep is not read as an all-clear. Rows: severity, tier (act_now: known exploited; urgent: ' +
-        'likely and serious; elevated: one of the two; routine), location, remediableBy (coding_agent: a run here ' +
-        'can fix it; upstream_only: the code is in a submodule, so the fix belongs in its own repository), fixable: false ' +
-        'when no fixed version is known yet, breached controls and initiativeId of a fix under way. Omit status ' +
-        'for open findings. taiga_get_finding reads one.',
-      inputSchema: z.object({
-        productId,
-        status: z
-          .enum(MAINTENANCE_FINDING_STATUSES)
-          .optional()
-          .describe('Only findings in this status; omit for the ones needing action'),
-        severity: z.enum(MAINTENANCE_FINDING_SEVERITIES).optional().describe('Only this severity'),
-        kind: z.enum(MAINTENANCE_FINDING_KINDS).optional().describe('Only this kind of finding'),
-        ...pagination,
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const { productId: id, ...filters } = params;
-        // The sweep overview on the first page: when the product was last
-        // checked decides whether an empty list can be trusted.
-        const [result, sweep] = await Promise.all([
-          client.listFindings(id, filters),
-          // Best effort: the findings the agent asked for do not fail on the overview.
-          params.cursor === undefined
-            ? sweepOverview(client, id).catch((error: unknown) => {
-                if (error instanceof TaigaApiError || isNetworkFailure(error)) return 'unread' as const;
-                throw error;
-              })
-            : Promise.resolve(null),
-        ]);
-        return toolResult({
-          // An overview that could not be read says so: without it an empty list would read as an all-clear.
-          ...(sweep === 'unread'
-            ? {
-                sweep: null,
-                sweepNote: 'The sweep overview could not be read: an empty list here is not an all-clear.',
-              }
-            : sweep
-              ? { sweep }
-              : {}),
-          ...page(pickFields(result.data, FINDING_ROW_FIELDS).map(withFixability), result.nextCursor),
-          ...(typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {}),
-          // The default list has findings with a fix under way too; the sweep's count does not (31 against 33).
-          ...(params.status === undefined &&
-          params.severity === undefined &&
-          params.kind === undefined &&
-          typeof result.totalCount === 'number' &&
-          sweep &&
-          sweep !== 'unread' &&
-          typeof (sweep as Row)['openFindings'] === 'number' &&
-          (sweep as Row)['openFindings'] !== result.totalCount
-            ? {
-                totalNote:
-                  'totalCount includes findings with a fix under way (remediating) and ignored findings whose ' +
-                  'ignore has expired; ' +
-                  'sweep.openFindings counts open ones only.',
-              }
-            : {}),
-        });
-      })
-  );
-
-  server.registerTool(
-    'taiga_get_finding',
-    {
-      title: 'Get a maintenance finding',
-      description:
-        'Read one maintenance finding: exploit likelihood (EPSS, known-exploited list), the advisory summarized ' +
-        '(full: true for its whole record: every affected range and reference) and ' +
-        'fixed version, code location, breached policy controls, why it ranks where it does, history ' +
-        '(reintroduced, previously resolved) and the remediation under way. fixable: false with fixNote says ' +
-        "taiga_fix_finding would refuse it. A secret's value is never stored, only the rule and location.",
-      inputSchema: z.object({
-        findingId,
-        full: z
-          .boolean()
-          .optional()
-          .describe("Carry the advisory's whole record: every affected range and reference (default false)"),
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        // The finding's runId is the sweep that found it, not a coding run:
-        // in the product's words runId is what taiga_get_run takes (PRO-2800).
-        const { runId, ...raw } = (await client.getFinding(params.findingId)).data as Row;
-        const finding = withFixability(params.full ? raw : { ...raw, data: leanAdvisory(raw['data']) });
-        return toolResult(runId === undefined ? finding : { sweepId: runId, ...finding });
-      })
-  );
-
-  server.registerTool(
-    'taiga_get_policy_standing',
-    {
-      title: "Get a product's policy standing",
-      description:
-        "How a product stands against the organization's published policies: summary counts, when the documents " +
-        'were assessed, and each violated control with its violations (critical and high only, citing the policy ' +
-        'sentence and the contradicting passage) and the work on each. state: breached (open scanner findings ' +
-        'map to it, by findingsByTier; routine-only is not urgent) or diverged (the documents contradict it). ' +
-        "live: false means the violation's initiative ended without fixing it: it needs a person or a new fix. " +
-        "raisedFor: false means the link is the backlog planner's: it said an initiative a person asked it for " +
-        'would close the violation, which may be a dedicated fix or broader work; true means a fix was raised ' +
-        'for it (taiga_fix_policy_violation or the sweep). ' +
-        'An unlisted control is not "passing" (summary.controlsWithNothingRecorded counts them). full: true adds ' +
-        'evidence and resolved ones. Fix with taiga_fix_policy_violation.',
-      inputSchema: z.object({
-        productId,
-        full: z
-          .boolean()
-          .optional()
-          .describe(
-            "Carry each violation's evidence and policy excerpt, cut to about 1,500 characters each, and up to 20 resolved violations (default false)"
-          ),
-        violationId: idInput('violation', 'this tool lists them')
-          .optional()
-          .describe('Only this violation, in full and uncut: its evidence, policy excerpt and work'),
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const standing = (await client.getPolicyStanding(params.productId)).data;
-        const controls = Array.isArray(standing.controls) ? standing.controls : [];
-        const violations = Array.isArray(standing.divergences) ? standing.divergences : [];
-        const listed = controls.filter((c) => Number(c.divergenceCount ?? 0) > 0 || Number(c.findingCount ?? 0) > 0);
-        // The counts first, on both answers: the lists run to thousands of
-        // tokens, and "how bad is it" is the first question.
-        const summary = standingSummary(standing);
-        // Never assessed reads like a clean bill otherwise (PRO-2800).
-        const assessment = standing.assessment as { state?: unknown } | null | undefined;
-        const note =
-          assessment?.state === 'never'
-            ? 'Never assessed: the documents have not been checked against the policies yet, so nothing here is an ' +
-              'all-clear. An assessment runs when the reality documents are derived or refreshed ' +
-              '(taiga_refresh_reality_documents, paid work: ask first).'
-            : null;
-        // Each assessment refreshes a violation's evidence but rewords its title and summary only when it
-        // re-describes the gap, so the words can describe code the evidence says is gone (PRO-2810). Said once.
-        const resolvedAny = Array.isArray(standing.resolvedDivergences) && standing.resolvedDivergences.length > 0;
-        const wording =
-          violations.length > 0 || resolvedAny
-            ? {
-                wordingNote:
-                  "A violation's evidence is from its assessedAt; its title and summary may be from when it was " +
-                  'first recorded. Where they disagree, the evidence is current.',
-              }
-            : {};
-        if (params.violationId) {
-          const one = [
-            ...violations,
-            ...(Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences : []),
-          ].find((violation) => (violation as Row)['id'] === params.violationId);
-          if (!one) {
-            return toolError(
-              'NOT_FOUND',
-              'No violation with that ID on this product; this tool without violationId lists them.'
-            );
-          }
-          return toolResult({ ...(one as Row), ...wording });
-        }
-        // The full form ran to 228k characters on a product with eleven violations (PRO-2800): each text is
-        // cut and the resolved list bounded; violationId reads one whole.
-        if (params.full) {
-          const resolvedAll = Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences : [];
-          return toolResult({
-            summary,
-            ...(note ? { note } : {}),
-            ...wording,
-            ...standing,
-            // Only the controls something is recorded against, as the summary answer lists them.
-            controls: listed,
-            divergences: cutLongText(violations),
-            resolvedDivergences: cutLongText(resolvedAll.slice(0, FULL_RESOLVED)),
-            ...(resolvedAll.length > FULL_RESOLVED
-              ? { resolvedNote: `The first ${FULL_RESOLVED} of ${resolvedAll.length} resolved violations.` }
-              : {}),
-          });
-        }
-        return toolResult({
-          summary,
-          ...(note ? { note } : {}),
-          ...wording,
-          productId: standing.productId,
-          hasPolicies: standing.hasPolicies,
-          assessment: standing.assessment,
-          documents: standing.documents,
-          // Only the controls something is recorded against; every other
-          // control is simply not reported, as the page does.
-          controls: pickFields(listed, [
-            'controlId',
-            'policyType',
-            'text',
-            'state',
-            'divergenceCount',
-            'findingCount',
-            'findingsByTier',
-            'plannedCount',
-          ]),
-          violations: pickFields(violations, VIOLATION_FIELDS),
-        });
-      })
-  );
-
-  if (!client.hasCapability('products:write')) return;
-
-  server.registerTool(
-    'taiga_ignore_finding',
-    {
-      title: 'Ignore or reopen a finding',
-      description:
-        'Ignore a maintenance finding with a reason, or reopen one (ignored: false). Reasons: false_positive, ' +
-        'not_reachable, accepted_risk, wont_fix; plus an optional note and an expiry after which it resurfaces ' +
-        'if still present. There is no "mark fixed": a finding resolves when the next sweep stops detecting it. ' +
-        'For a secret only in history, rotate it outside Taiga, then ignore it. Ignoring can record the team ' +
-        "accepting a risk, which is the person's decision: ask first.",
-      inputSchema: z.object({
-        findingId,
-        ignored: z.boolean().describe('true ignores the finding, false reopens it'),
-        reason: z.enum(MAINTENANCE_IGNORE_REASONS).optional().describe('Why it is ignored; required when ignoring'),
-        note: z.string().trim().max(280).optional().describe('A short justification, kept for audit'),
-        expiresAt: z
-          .string()
-          .datetime({ offset: true })
-          // format: date-time says it; the leap-year pattern beside it ran to hundreds of characters (PRO-2800).
-          .meta({ pattern: undefined })
-          .optional()
-          .describe('When the ignore lapses and the finding resurfaces if it still exists (ISO 8601, in the future)'),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        if (params.ignored && params.reason === undefined) {
-          return toolError('VALIDATION_ERROR', 'Say why the finding is ignored (reason).');
-        }
-        const body = params.ignored
-          ? {
-              status: 'ignored' as const,
-              ignoreReason: params.reason,
-              ...(params.note !== undefined ? { ignoreNote: params.note } : {}),
-              ...(params.expiresAt !== undefined ? { ignoreExpiresAt: params.expiresAt } : {}),
-            }
-          : { status: 'open' as const };
-        const finding = (await client.updateFinding(params.findingId, body)).data;
-        return toolResult(pickFields([finding], [...FINDING_ROW_FIELDS, 'ignoreNote'])[0]);
-      })
-  );
-
-  server.registerTool(
-    'taiga_fix_finding',
-    {
-      title: 'Fix a finding',
-      description:
-        "Raise an initiative that fixes a maintenance finding, at the end of the product's line; it ends in a " +
-        "pull request a person merges, and the initiative's review gate applies. wholeGroup: true fixes the " +
-        'group in one initiative: every open advisory on that package version in one bump, or every location the ' +
-        'same rule flagged. Refused for a secret only in history, remediableBy upstream_only (code in a ' +
-        'submodule), and a dependency with no fixed version yet (fixable: false).',
-      inputSchema: z.object({
-        productId,
-        findingId,
-        wholeGroup: z
-          .boolean()
-          .optional()
-          .describe("Fix every finding in this finding's group (its package and version, or its rule) together"),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        if (!params.wholeGroup) {
-          const fixed = (await client.remediateFinding(params.productId, params.findingId)).data;
-          return toolResult({
-            backlogItemId: fixed.backlogItemId,
-            finding: fixed.finding ? pickFields([fixed.finding], FINDING_ROW_FIELDS)[0] : null,
-          });
-        }
-        // The group is the finding's own: the route matches the package (or
-        // rule), the installed version and the repository exactly, so they are
-        // taken from the finding rather than asked of the caller.
-        const finding = (await client.getFinding(params.findingId)).data;
-        // The finding is read by its own id, so it is held to the product the
-        // group fix is sent to, as the single-finding route holds it.
-        if (finding.productId !== params.productId) {
-          return toolError('NOT_FOUND', 'No such finding in this product.');
-        }
-        const result = await client.remediatePackage(params.productId, {
-          ecosystem: String(finding.ecosystem),
-          packageName: String(finding.packageName),
-          currentVersion: typeof finding.currentVersion === 'string' ? finding.currentVersion : null,
-          productRepositoryId: typeof finding.productRepositoryId === 'string' ? finding.productRepositoryId : null,
-        });
-        return toolResult(result.data);
-      })
-  );
-
-  server.registerTool(
-    'taiga_fix_policy_violation',
-    {
-      title: 'Fix policy violations',
-      description:
-        "Raise one initiative that fixes a product's policy violations and add it to the end of the line. Name a " +
-        'control to cover all its violations with no initiative yet, or one violationId when the control has ' +
-        'several. The violation stays listed until the next assessment no longer finds it, even while the fix is ' +
-        'under way.',
-      inputSchema: z.object({
-        productId,
-        controlId: z.string().min(1).max(40).optional().describe("The control's identifier, e.g. SEC-3.4"),
-        violationId: idInput('violation', 'taiga_get_policy_standing gives it').optional(),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        if ((params.controlId === undefined) === (params.violationId === undefined)) {
-          return toolError(
-            'VALIDATION_ERROR',
-            'Name either a control (controlId) or one violation (violationId), not both or neither.'
-          );
-        }
-        const result = params.controlId
-          ? await client.remediatePolicyControl(params.productId, params.controlId)
-          : await client.remediatePolicyViolation(params.productId, params.violationId!);
-        return toolResult(result.data);
-      })
-  );
-}