@taiga-ai/mcp-server 0.13.0-rc.424 → 0.14.0-dev.425

package/src/server.integration.test.ts

@@ -19,6 +19,9 @@ const ALL_CAPABILITIES = [
   'backlog:read',
   'backlog:write',
   'products:write',
+  'customDocuments:read',
+  'customDocuments:write',
+  'customDocuments:delete',
 ];
 
 /**
@@ -26,38 +29,66 @@ const ALL_CAPABILITIES = [
  * sorted for deterministic comparison.
  */
 const ALL_TOOL_NAMES = [
+  'taiga_add_knowledge',
   'taiga_approve_plan',
+  'taiga_define_environment',
+  'taiga_delete_knowledge',
+  'taiga_fix_finding',
+  'taiga_fix_policy_violation',
+  'taiga_generate_product_documents',
   'taiga_get_backlog_item',
   'taiga_get_build',
+  'taiga_get_delivery_metrics',
+  'taiga_get_deployments',
   'taiga_get_document',
   'taiga_get_factory_document',
+  'taiga_get_finding',
   'taiga_get_job',
+  'taiga_get_knowledge',
+  'taiga_get_maintenance',
+  'taiga_get_monitoring',
   'taiga_get_plan',
+  'taiga_get_policy_standing',
   'taiga_get_product',
   'taiga_get_product_context',
   'taiga_get_product_document',
   'taiga_get_queue',
+  'taiga_ignore_finding',
+  'taiga_list_action_required',
   'taiga_list_backlog_items',
   'taiga_list_builds',
   'taiga_list_documents',
   'taiga_list_factories',
   'taiga_list_factory_documents',
+  'taiga_list_findings',
+  'taiga_list_knowledge',
   'taiga_list_product_documents',
   'taiga_list_products',
+  'taiga_list_setup_tasks',
+  'taiga_mark_product_document_reviewed',
   'taiga_move_backlog_item',
   'taiga_pause_line',
   'taiga_plan_again',
   'taiga_publish_document',
   'taiga_publish_factory_document',
+  'taiga_publish_product_document',
   'taiga_queue_backlog_item',
+  'taiga_regenerate_product_document',
   'taiga_reject_plan',
   'taiga_request_initiatives',
+  'taiga_resolve_action',
   'taiga_resolve_product',
   'taiga_resume_backlog_item',
+  'taiga_retry_knowledge',
   'taiga_set_auto_build',
+  'taiga_set_auto_merge',
+  'taiga_set_product_autonomy',
   'taiga_stop_build',
+  'taiga_stop_generating_documents',
   'taiga_update_document',
+  'taiga_update_environment',
   'taiga_update_factory_document',
+  'taiga_update_product_document',
   'taiga_wait_for_backlog_item',
   'taiga_wait_for_build',
   'taiga_wait_for_job',
@@ -370,6 +401,15 @@ describe('MCP server integration', () => {
         'taiga_wait_for_build',
         'taiga_get_job',
         'taiga_wait_for_job',
+        'taiga_get_maintenance',
+        'taiga_list_findings',
+        'taiga_get_finding',
+        'taiga_get_policy_standing',
+        'taiga_list_action_required',
+        'taiga_list_setup_tasks',
+        'taiga_get_deployments',
+        'taiga_get_delivery_metrics',
+        'taiga_get_monitoring',
       ],
       'backlog:read': [
         'taiga_list_backlog_items',
@@ -379,16 +419,39 @@ describe('MCP server integration', () => {
       ],
       'factories:read': ['taiga_list_factories', 'taiga_list_factory_documents', 'taiga_get_factory_document'],
       'tenant:documents:read': ['taiga_list_documents', 'taiga_get_document'],
+      'customDocuments:read': ['taiga_list_knowledge', 'taiga_get_knowledge'],
     };
     const PAIRED_CONTRACT: Record<string, string[]> = {
       'tenant:documents:read tenant:documents:write': ['taiga_update_document', 'taiga_publish_document'],
       'factories:read factories:documents:write': ['taiga_update_factory_document', 'taiga_publish_factory_document'],
-      'backlog:write': ['taiga_move_backlog_item'],
+      'backlog:write': ['taiga_move_backlog_item', 'taiga_set_auto_merge'],
       'backlog:write products:write': ['taiga_queue_backlog_item'],
-      'products:write': ['taiga_resume_backlog_item', 'taiga_set_auto_build', 'taiga_request_initiatives'],
+      'products:write': [
+        'taiga_resume_backlog_item',
+        'taiga_set_auto_build',
+        'taiga_request_initiatives',
+        'taiga_set_product_autonomy',
+        'taiga_publish_product_document',
+        'taiga_mark_product_document_reviewed',
+        'taiga_generate_product_documents',
+        'taiga_stop_generating_documents',
+      ],
       'backlog:read products:write': ['taiga_approve_plan', 'taiga_reject_plan'],
       'backlog:read backlog:write products:write': ['taiga_plan_again'],
-      'products:read products:write': ['taiga_stop_build', 'taiga_pause_line'],
+      'products:read products:write': [
+        'taiga_stop_build',
+        'taiga_pause_line',
+        'taiga_ignore_finding',
+        'taiga_fix_finding',
+        'taiga_fix_policy_violation',
+        'taiga_resolve_action',
+        'taiga_define_environment',
+        'taiga_update_environment',
+        'taiga_update_product_document',
+        'taiga_regenerate_product_document',
+      ],
+      'customDocuments:read customDocuments:write': ['taiga_add_knowledge', 'taiga_retry_knowledge'],
+      'customDocuments:read customDocuments:write customDocuments:delete': ['taiga_delete_knowledge'],
     };
 
     for (const [capability, expectedTools] of [...Object.entries(CONTRACT), ...Object.entries(PAIRED_CONTRACT)]) {
@@ -2766,13 +2829,29 @@ describe('MCP server integration', () => {
         'taiga_stop_build',
         'taiga_request_initiatives',
         'taiga_plan_again',
+        'taiga_define_environment',
+        'taiga_add_knowledge',
+        'taiga_retry_knowledge',
       ]) {
         expect(byName[name], name).toMatchObject({ readOnlyHint: false, destructiveHint: true, idempotentHint: false });
       }
       // Settings: the same call twice leaves things as one call does.
-      for (const name of ['taiga_set_auto_build', 'taiga_pause_line']) {
+      for (const name of [
+        'taiga_set_auto_build',
+        'taiga_pause_line',
+        'taiga_update_environment',
+        'taiga_set_product_autonomy',
+        'taiga_set_auto_merge',
+      ]) {
         expect(byName[name], name).toMatchObject({ readOnlyHint: false, destructiveHint: true, idempotentHint: true });
       }
+      // A section id points at the read tool of its own scope, which lists the valid ids.
+      const sectionHelp = (name: string) =>
+        (tools.find((t) => t.name === name)!.inputSchema.properties as Record<string, { description?: string }>)
+          .sectionId!.description;
+      expect(sectionHelp('taiga_update_document')).toContain('taiga_get_document,');
+      expect(sectionHelp('taiga_update_factory_document')).toContain('taiga_get_factory_document');
+      expect(sectionHelp('taiga_update_product_document')).toContain('taiga_get_product_document');
       for (const name of ['taiga_get_plan', 'taiga_get_job', 'taiga_wait_for_job']) {
         expect(byName[name], name).toMatchObject({ readOnlyHint: true });
       }
@@ -2996,13 +3075,21 @@ describe('MCP server integration', () => {
       const backlogOnly = await bootMcpPair({ capabilities: ['backlog:write'] });
       const operatorOnly = await bootMcpPair({ capabilities: ['products:write'] });
 
-      expect(toolNames((await backlogOnly.client.listTools()).tools)).toEqual(['taiga_move_backlog_item']);
+      expect(toolNames((await backlogOnly.client.listTools()).tools)).toEqual([
+        'taiga_move_backlog_item',
+        'taiga_set_auto_merge',
+      ]);
       // A request, the resume and the review gate take a product or an item ID a request or a queue hands
       // back, so they need no backlog read; the verdicts and Plan again act on what only a read shows.
       expect(toolNames((await operatorOnly.client.listTools()).tools)).toEqual([
+        'taiga_generate_product_documents',
+        'taiga_mark_product_document_reviewed',
+        'taiga_publish_product_document',
         'taiga_request_initiatives',
         'taiga_resume_backlog_item',
         'taiga_set_auto_build',
+        'taiga_set_product_autonomy',
+        'taiga_stop_generating_documents',
       ]);
     });
 
@@ -4659,6 +4746,813 @@ describe('MCP server integration', () => {
     });
   });
 
+  describe('operating the whole product', () => {
+    const FINDING_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b01';
+    const ENV_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b02';
+    const ENV_ID_2 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b0b';
+    const KNOWLEDGE_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b03';
+    const INBOX_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b04';
+    const VIOLATION_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b05';
+    const finding = {
+      id: FINDING_ID,
+      productId: PRODUCT_ID,
+      kind: 'vulnerable_dependency',
+      severity: 'high',
+      tier: 'urgent',
+      status: 'open',
+      title: 'lodash 4.17.20: prototype pollution',
+      ecosystem: 'npm',
+      packageName: 'lodash',
+      currentVersion: '4.17.20',
+      recommendedVersion: '4.17.21',
+      advisoryId: 'GHSA-xxxx',
+      fingerprint: 'noise the row must not carry',
+      summary: 'a long advisory summary the row must not carry',
+      remediableBy: 'coding_agent',
+    };
+    const callsTo = (fetchSpy: ReturnType<typeof vi.fn>, method: string) =>
+      fetchSpy.mock.calls
+        .filter((c: unknown[]) => ((c[1] as RequestInit | undefined)?.method ?? 'GET') === method)
+        .map((c: unknown[]) => new URL(c[0] as string));
+
+    it("should read a product's maintenance standing with its latest sweeps, and say when it was never swept", async () => {
+      const summary = {
+        productId: PRODUCT_ID,
+        openFindings: 2,
+        severityCounts: { high: 2 },
+        kindCounts: {},
+        topFindings: [],
+      };
+      const swept = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/maintenance/summary`]: { data: summary },
+          [`/v1/products/${PRODUCT_ID}/maintenance/runs`]: {
+            data: [
+              { id: 'run-1', trigger: 'event', status: 'completed', scanners: { deps: 'passed' }, agentJobId: 'x' },
+            ],
+            nextCursor: null,
+          },
+        },
+      });
+      const standing = parseToolResult(
+        await swept.client.callTool({ name: 'taiga_get_maintenance', arguments: { productId: PRODUCT_ID } })
+      );
+      expect(standing).toMatchObject({ openFindings: 2, latestSweeps: [{ id: 'run-1', status: 'completed' }] });
+      expect(standing.latestSweeps[0]).not.toHaveProperty('agentJobId');
+      expect(standing).not.toHaveProperty('note');
+      expect(sentUrl(swept.fetchSpy, '/maintenance/runs').searchParams.get('limit')).toBe('3');
+
+      const never = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/maintenance/summary`]: { data: { ...summary, openFindings: 0 } },
+          [`/v1/products/${PRODUCT_ID}/maintenance/runs`]: { data: [], nextCursor: null },
+        },
+      });
+      const quiet = parseToolResult(
+        await never.client.callTool({ name: 'taiga_get_maintenance', arguments: { productId: PRODUCT_ID } })
+      );
+      expect(quiet.note).toMatch(/never been swept/);
+    });
+
+    it('should list findings as rows with the filters passed through', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/maintenance/findings`]: { data: [finding], nextCursor: null, totalCount: 1 },
+        },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({
+          name: 'taiga_list_findings',
+          arguments: { productId: PRODUCT_ID, kind: 'vulnerable_dependency', severity: 'high' },
+        })
+      );
+
+      expect(result).toMatchObject({ totalCount: 1, nextCursor: null, data: [{ id: FINDING_ID, tier: 'urgent' }] });
+      expect(result.data[0]).not.toHaveProperty('fingerprint');
+      expect(result.data[0]).not.toHaveProperty('summary');
+      const url = sentUrl(fetchSpy, '/maintenance/findings');
+      expect(url.searchParams.get('kind')).toBe('vulnerable_dependency');
+      expect(url.searchParams.get('severity')).toBe('high');
+      expect(url.searchParams.has('status')).toBe(false);
+    });
+
+    it('should ignore a finding with its reason, note and expiry, and reopen one', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: { [`PATCH /v1/maintenance/findings/${FINDING_ID}`]: { data: { ...finding, status: 'ignored' } } },
+      });
+
+      await client.callTool({
+        name: 'taiga_ignore_finding',
+        arguments: {
+          findingId: FINDING_ID,
+          ignored: true,
+          reason: 'not_reachable',
+          note: 'The vulnerable function is never called.',
+          expiresAt: '2099-01-01T00:00:00Z',
+        },
+      });
+      expect(sentBody(fetchSpy, 'PATCH', '/maintenance/findings/')).toEqual({
+        status: 'ignored',
+        ignoreReason: 'not_reachable',
+        ignoreNote: 'The vulnerable function is never called.',
+        ignoreExpiresAt: '2099-01-01T00:00:00Z',
+      });
+
+      fetchSpy.mockClear();
+      vi.stubGlobal('fetch', fetchSpy);
+      await client.callTool({ name: 'taiga_ignore_finding', arguments: { findingId: FINDING_ID, ignored: false } });
+      expect(sentBody(fetchSpy, 'PATCH', '/maintenance/findings/')).toEqual({ status: 'open' });
+
+      // An ignore says why: without a reason it is refused before any request, as the API would.
+      fetchSpy.mockClear();
+      const unexplained = await client.callTool({
+        name: 'taiga_ignore_finding',
+        arguments: { findingId: FINDING_ID, ignored: true },
+      });
+      expect(unexplained.isError).toBe(true);
+      expect(callsTo(fetchSpy, 'PATCH')).toHaveLength(0);
+    });
+
+    it("should fix a finding, or its whole group with the finding's own package, version and repository", async () => {
+      const repoId = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b06';
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`POST /v1/products/${PRODUCT_ID}/maintenance/findings/${FINDING_ID}/remediate`]: {
+            data: { finding: { ...finding, status: 'remediating' }, backlogItemId: ITEM_ID },
+          },
+          [`GET /v1/maintenance/findings/${FINDING_ID}`]: { data: { ...finding, productRepositoryId: repoId } },
+          [`POST /v1/products/${PRODUCT_ID}/maintenance/packages/remediate`]: {
+            data: { backlogItemId: ITEM_ID, findingIds: [FINDING_ID] },
+          },
+        },
+      });
+
+      const one = parseToolResult(
+        await client.callTool({
+          name: 'taiga_fix_finding',
+          arguments: { productId: PRODUCT_ID, findingId: FINDING_ID },
+        })
+      );
+      expect(one).toMatchObject({ backlogItemId: ITEM_ID, finding: { id: FINDING_ID, status: 'remediating' } });
+      expect(one.finding).not.toHaveProperty('fingerprint');
+
+      const group = parseToolResult(
+        await client.callTool({
+          name: 'taiga_fix_finding',
+          arguments: { productId: PRODUCT_ID, findingId: FINDING_ID, wholeGroup: true },
+        })
+      );
+      // The route matches the group exactly: package, installed version and repository, all from the finding.
+      expect(sentBody(fetchSpy, 'POST', '/packages/remediate')).toEqual({
+        ecosystem: 'npm',
+        packageName: 'lodash',
+        currentVersion: '4.17.20',
+        productRepositoryId: repoId,
+      });
+      expect(group).toEqual({ backlogItemId: ITEM_ID, findingIds: [FINDING_ID] });
+
+      // A finding of another product is not fixed as a group of this one.
+      const before = callsTo(fetchSpy, 'POST').length;
+      const elsewhere = await client.callTool({
+        name: 'taiga_fix_finding',
+        arguments: { productId: PRODUCT_ID_2, findingId: FINDING_ID, wholeGroup: true },
+      });
+      expect(elsewhere.isError).toBe(true);
+      expect(parseToolResult(elsewhere).error).toBe('NOT_FOUND');
+      expect(callsTo(fetchSpy, 'POST')).toHaveLength(before);
+    });
+
+    it('should report the controls something is recorded against, and the violations without their evidence unless asked', async () => {
+      const standing = {
+        productId: PRODUCT_ID,
+        hasPolicies: true,
+        canAssess: true,
+        controls: [
+          {
+            controlId: 'SEC-3.4',
+            policyType: 'policy_security',
+            text: 'Encrypt at rest',
+            state: 'diverged',
+            findingCount: 0,
+            divergenceCount: 1,
+            plannedCount: 0,
+            workItems: [],
+          },
+          {
+            controlId: 'ARC-1.1',
+            policyType: 'policy_architecture',
+            text: 'Quiet',
+            state: 'no_evidence',
+            findingCount: 0,
+            divergenceCount: 0,
+            plannedCount: 0,
+            workItems: [],
+          },
+        ],
+        divergences: [
+          {
+            id: VIOLATION_ID,
+            controlId: 'SEC-3.4',
+            severity: 'high',
+            status: 'open',
+            title: 'Plaintext',
+            summary: 's',
+            evidence: 'long evidence',
+            policyExcerpt: 'excerpt',
+            work: null,
+          },
+        ],
+        resolvedDivergences: [{ id: 'r1' }, { id: 'r2' }],
+        assessment: { state: 'complete' },
+        documents: { commit: 'abc' },
+      };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`/v1/products/${PRODUCT_ID}/maintenance/policies`]: { data: standing } },
+      });
+
+      const summary = parseToolResult(
+        await client.callTool({ name: 'taiga_get_policy_standing', arguments: { productId: PRODUCT_ID } })
+      );
+      const full = parseToolResult(
+        await client.callTool({ name: 'taiga_get_policy_standing', arguments: { productId: PRODUCT_ID, full: true } })
+      );
+
+      expect(summary.controls.map((c: { controlId: string }) => c.controlId)).toEqual(['SEC-3.4']);
+      expect(summary.violations[0]).toMatchObject({ id: VIOLATION_ID, title: 'Plaintext' });
+      expect(summary.violations[0]).not.toHaveProperty('evidence');
+      expect(summary.resolvedViolations).toBe(2);
+      expect(full.divergences[0].evidence).toBe('long evidence');
+    });
+
+    it('should fix a control or one violation through its own route', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`POST /v1/products/${PRODUCT_ID}/maintenance/policies/controls/SEC-3.4/remediate`]: {
+            data: { backlogItemId: ITEM_ID, divergenceIds: [VIOLATION_ID], created: true },
+          },
+          [`POST /v1/products/${PRODUCT_ID}/maintenance/policies/divergences/${VIOLATION_ID}/remediate`]: {
+            data: { backlogItemId: ITEM_ID, divergenceIds: [VIOLATION_ID], created: true },
+          },
+        },
+      });
+
+      const control = parseToolResult(
+        await client.callTool({
+          name: 'taiga_fix_policy_violation',
+          arguments: { productId: PRODUCT_ID, controlId: 'SEC-3.4' },
+        })
+      );
+      await client.callTool({
+        name: 'taiga_fix_policy_violation',
+        arguments: { productId: PRODUCT_ID, violationId: VIOLATION_ID },
+      });
+      const both = await client.callTool({
+        name: 'taiga_fix_policy_violation',
+        arguments: { productId: PRODUCT_ID, controlId: 'SEC-3.4', violationId: VIOLATION_ID },
+      });
+
+      expect(control).toEqual({ backlogItemId: ITEM_ID, divergenceIds: [VIOLATION_ID], created: true });
+      expect(callsTo(fetchSpy, 'POST').map((u) => u.pathname)).toEqual([
+        `/v1/products/${PRODUCT_ID}/maintenance/policies/controls/SEC-3.4/remediate`,
+        `/v1/products/${PRODUCT_ID}/maintenance/policies/divergences/${VIOLATION_ID}/remediate`,
+      ]);
+      expect(both.isError).toBe(true);
+    });
+
+    it('should read Action Required across products or for one, and resolve or snooze an item', async () => {
+      const inboxItem = {
+        id: INBOX_ID,
+        productId: PRODUCT_ID,
+        category: 'gate',
+        kind: 'review_pr',
+        title: 'Review PR #25',
+        status: 'open',
+        createdBy: 'u',
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          '/v1/inbox': { data: [inboxItem], nextCursor: null },
+          [`/v1/products/${PRODUCT_ID}/inbox`]: {
+            data: [
+              inboxItem,
+              { ...inboxItem, id: 'later', status: 'snoozed', snoozedUntil: '2999-01-01T00:00:00.000Z' },
+              { ...inboxItem, id: 'woken', status: 'snoozed', snoozedUntil: '2020-01-01T00:00:00.000Z' },
+            ],
+            nextCursor: null,
+          },
+          [`PATCH /v1/inbox/${INBOX_ID}`]: { data: { ...inboxItem, status: 'done' } },
+        },
+      });
+
+      const all = parseToolResult(
+        await client.callTool({ name: 'taiga_list_action_required', arguments: { category: 'gate', resolved: true } })
+      );
+      expect(all.data[0]).toMatchObject({ id: INBOX_ID, kind: 'review_pr' });
+      expect(all.data[0]).not.toHaveProperty('createdBy');
+      const across = sentUrl(fetchSpy, '/v1/inbox');
+      expect(across.searchParams.get('category')).toBe('gate');
+      expect(across.searchParams.get('resolved')).toBe('true');
+
+      const open = parseToolResult(
+        await client.callTool({
+          name: 'taiga_list_action_required',
+          arguments: { productId: PRODUCT_ID, resolved: false },
+        })
+      );
+      // Snoozed until later is left out until then, as the page leaves it out; a lapsed snooze is due again.
+      expect(open.data.map((item: { id: string }) => item.id)).toEqual([INBOX_ID, 'woken']);
+      expect(open.snoozedHidden).toBe(1);
+      expect(all).not.toHaveProperty('snoozedHidden');
+      const product = callsTo(fetchSpy, 'GET').find((u) => u.pathname === `/v1/products/${PRODUCT_ID}/inbox`)!;
+      // The route coerces any value to true, so false is not sent at all.
+      expect(product.searchParams.has('resolved')).toBe(false);
+
+      const done = parseToolResult(
+        await client.callTool({ name: 'taiga_resolve_action', arguments: { itemId: INBOX_ID, status: 'done' } })
+      );
+      expect(done.status).toBe('done');
+      expect(sentBody(fetchSpy, 'PATCH', '/inbox/')).toEqual({ status: 'done' });
+
+      fetchSpy.mockClear();
+      vi.stubGlobal('fetch', fetchSpy);
+      await client.callTool({ name: 'taiga_resolve_action', arguments: { itemId: INBOX_ID, snoozedUntil: null } });
+      expect(sentBody(fetchSpy, 'PATCH', '/inbox/')).toEqual({ snoozedUntil: null });
+
+      const nothing = await client.callTool({ name: 'taiga_resolve_action', arguments: { itemId: INBOX_ID } });
+      expect(nothing.isError).toBe(true);
+    });
+
+    it('should read what runs where, and keep the answer when only the sync status cannot be read', async () => {
+      const deployment = {
+        id: 'd1',
+        environmentId: ENV_ID,
+        status: 'active',
+        commitSha: 'abc',
+        commitSubject: 'Merge #1',
+        artifacts: {},
+        metadata: { big: true },
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          // Two pages: every environment is read, not the first page's.
+          [`/v1/products/${PRODUCT_ID}/environments`]: (url: string) =>
+            new Response(
+              JSON.stringify(
+                new URL(url).searchParams.get('cursor') === 'p2'
+                  ? { data: [{ id: ENV_ID_2, name: 'staging', slug: 'staging', type: 'staging' }], nextCursor: null }
+                  : {
+                      data: [
+                        {
+                          id: ENV_ID,
+                          name: 'production',
+                          slug: 'prod',
+                          type: 'production',
+                          deployConfig: {},
+                          url: 'https://app.example.com',
+                        },
+                      ],
+                      nextCursor: 'p2',
+                    }
+              )
+            ),
+          [`/v1/products/${PRODUCT_ID}/deployments/current`]: { data: { current: [deployment], deploying: [] } },
+          [`/v1/products/${PRODUCT_ID}/deployments`]: { data: [deployment], nextCursor: 'more' },
+          [`/v1/products/${PRODUCT_ID}/deployments/sync-status`]: refusal(500, 'INTERNAL', 'boom'),
+        },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_get_deployments', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(result.environments[0]).toEqual({
+        id: ENV_ID,
+        name: 'production',
+        slug: 'prod',
+        type: 'production',
+        url: 'https://app.example.com',
+      });
+      expect(result.environments.map((e: { id: string }) => e.id)).toEqual([ENV_ID, ENV_ID_2]);
+      expect(result).not.toHaveProperty('moreEnvironments');
+      expect(result.running[0]).toMatchObject({ id: 'd1', commitSubject: 'Merge #1' });
+      expect(result.running[0]).not.toHaveProperty('metadata');
+      expect(result.history).toMatchObject({ nextCursor: 'more' });
+      expect(result.syncStatus).toBeNull();
+      expect(result.syncUnavailable).toContain('500');
+      expect(sentUrl(fetchSpy, `/products/${PRODUCT_ID}/deployments?`).searchParams.get('limit')).toBe('10');
+    });
+
+    it('should read delivery metrics for a window the page offers, and refuse any other', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/deployments/insights`]: { data: { deploymentFrequency: { band: 'high' } } },
+        },
+      });
+
+      const metrics = parseToolResult(
+        await client.callTool({
+          name: 'taiga_get_delivery_metrics',
+          arguments: { productId: PRODUCT_ID, environmentId: ENV_ID, windowDays: 60 },
+        })
+      );
+      const odd = await client.callTool({
+        name: 'taiga_get_delivery_metrics',
+        arguments: { productId: PRODUCT_ID, environmentId: ENV_ID, windowDays: 45 },
+      });
+
+      expect(metrics).toEqual({ deploymentFrequency: { band: 'high' } });
+      const url = sentUrl(fetchSpy, '/deployments/insights');
+      expect(url.searchParams.get('environmentId')).toBe(ENV_ID);
+      expect(url.searchParams.get('windowDays')).toBe('60');
+      expect(odd.isError).toBe(true);
+    });
+
+    it("should read health for every environment, and one environment's signals with a missing one named", async () => {
+      const health = [
+        { environmentId: ENV_ID, environmentName: 'prod', overallState: 'operational' },
+        { environmentId: 'other', environmentName: 'dev', overallState: 'down' },
+      ];
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/monitoring/health`]: { data: health },
+          [`/v1/products/${PRODUCT_ID}/monitoring/uptime`]: { data: { uptimePercent: 99.9 } },
+          [`/v1/products/${PRODUCT_ID}/monitoring/rum`]: { data: { score: null } },
+          [`/v1/products/${PRODUCT_ID}/monitoring/client-health`]: refusal(503, 'UNAVAILABLE', 'Later'),
+        },
+      });
+
+      const all = parseToolResult(
+        await client.callTool({ name: 'taiga_get_monitoring', arguments: { productId: PRODUCT_ID } })
+      );
+      const one = parseToolResult(
+        await client.callTool({
+          name: 'taiga_get_monitoring',
+          arguments: { productId: PRODUCT_ID, environmentId: ENV_ID },
+        })
+      );
+
+      expect(all.health).toHaveLength(2);
+      const odd = await client.callTool({
+        name: 'taiga_get_monitoring',
+        arguments: { productId: PRODUCT_ID, environmentId: ENV_ID, windowDays: 7 },
+      });
+      expect(odd.isError).toBe(true);
+      expect(one).toMatchObject({
+        health: [{ environmentId: ENV_ID }],
+        windowDays: 30,
+        uptime: { uptimePercent: 99.9 },
+        realUserExperience: { score: null },
+        clientHealth: { unavailable: expect.stringContaining('503') },
+      });
+    });
+
+    it('should define an environment and set its App URL, refusing an update that changes nothing', async () => {
+      const env = { id: ENV_ID, name: 'staging', slug: 'staging', type: 'staging', url: null, deployConfig: {} };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`POST /v1/products/${PRODUCT_ID}/environments`]: { data: env },
+          [`PATCH /v1/environments/${ENV_ID}`]: { data: { ...env, url: 'https://staging.example.com' } },
+        },
+      });
+
+      await client.callTool({
+        name: 'taiga_define_environment',
+        arguments: { productId: PRODUCT_ID, name: 'staging', type: 'staging' },
+      });
+      expect(sentBody(fetchSpy, 'POST', '/environments')).toEqual({ name: 'staging', type: 'staging' });
+
+      const updated = parseToolResult(
+        await client.callTool({
+          name: 'taiga_update_environment',
+          arguments: { environmentId: ENV_ID, url: 'https://staging.example.com' },
+        })
+      );
+      expect(sentBody(fetchSpy, 'PATCH', '/environments/')).toEqual({ url: 'https://staging.example.com' });
+      expect(updated).not.toHaveProperty('deployConfig');
+
+      const nothing = await client.callTool({ name: 'taiga_update_environment', arguments: { environmentId: ENV_ID } });
+      expect(nothing.isError).toBe(true);
+    });
+
+    it('should list knowledge one level at a time, as the route reads null', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['customDocuments:read'],
+        routes: { '/v1/custom-documents': { data: [], nextCursor: null } },
+      });
+
+      for (const args of [{}, { factoryId: FACTORY_ID }, { productId: PRODUCT_ID }]) {
+        await client.callTool({ name: 'taiga_list_knowledge', arguments: args });
+      }
+      const two = await client.callTool({
+        name: 'taiga_list_knowledge',
+        arguments: { factoryId: FACTORY_ID, productId: PRODUCT_ID },
+      });
+      expect(two.isError).toBe(true);
+
+      const scopes = callsTo(fetchSpy, 'GET')
+        .filter((u) => u.pathname === '/v1/custom-documents')
+        .map((u) => [u.searchParams.get('factoryId'), u.searchParams.get('productId')]);
+      expect(scopes).toEqual([
+        ['null', 'null'],
+        [FACTORY_ID, 'null'],
+        [null, PRODUCT_ID],
+      ]);
+    });
+
+    it('should add a Markdown file as knowledge with a multipart upload at the scope named', async () => {
+      const filed = {
+        id: KNOWLEDGE_ID,
+        factoryId: FACTORY_ID,
+        productId: PRODUCT_ID,
+        fileName: 'contract.md',
+        mime: 'text/markdown',
+        status: 'pending',
+        sha256: 'x',
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['customDocuments:read', 'customDocuments:write'],
+        routes: { 'POST /v1/custom-documents': { data: filed, deduplicated: true } },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({
+          name: 'taiga_add_knowledge',
+          arguments: { productId: PRODUCT_ID, fileName: 'contract.md', content: '# Orders API\n' },
+        })
+      );
+      const twoLevels = await client.callTool({
+        name: 'taiga_add_knowledge',
+        arguments: { factoryId: FACTORY_ID, productId: PRODUCT_ID, fileName: 'contract.md', content: 'x' },
+      });
+
+      const call = fetchSpy.mock.calls.find((c: unknown[]) => (c[1] as RequestInit)?.method === 'POST')!;
+      const init = call[1] as RequestInit;
+      const form = init.body as FormData;
+      // A form sets its own multipart type with its boundary.
+      expect((init.headers as Record<string, string>)['Content-Type']).toBeUndefined();
+      // A product's own: the route resolves its factory, so none is sent to mismatch it.
+      expect(form.get('factoryId')).toBeNull();
+      expect(form.get('productId')).toBe(PRODUCT_ID);
+      const file = form.get('file') as File;
+      expect(file.name).toBe('contract.md');
+      expect(file.type).toBe('text/markdown');
+      expect(await file.text()).toBe('# Orders API\n');
+      expect(result).toMatchObject({ id: KNOWLEDGE_ID, status: 'pending' });
+      // The file already there: said so, so it is not taken for a new one.
+      expect(result.deduplicated).toBe(true);
+      expect(result).not.toHaveProperty('sha256');
+      expect(twoLevels.isError).toBe(true);
+    });
+
+    it('should read a text file’s content through its download URL, bounded, and delete a file', async () => {
+      const text = { id: KNOWLEDGE_ID, fileName: 'contract.md', mime: 'text/markdown', status: 'ready' };
+      const PDF_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b07';
+      const BIG_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b08';
+      const GONE_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b09';
+      const FAILED_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4b0a';
+      const download = (name: string) => ({ data: { url: `https://storage.example.com/${name}?sig=1` } });
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['customDocuments:read', 'customDocuments:write', 'customDocuments:delete'],
+        routes: {
+          [`GET /v1/custom-documents/${KNOWLEDGE_ID}`]: { data: text },
+          [`/v1/custom-documents/${KNOWLEDGE_ID}/download`]: download('contract.md'),
+          [`GET /v1/custom-documents/${PDF_ID}`]: { data: { ...text, id: PDF_ID, mime: 'application/pdf' } },
+          [`/v1/custom-documents/${PDF_ID}/download`]: download('guide.pdf'),
+          [`GET /v1/custom-documents/${BIG_ID}`]: { data: { ...text, id: BIG_ID } },
+          [`/v1/custom-documents/${BIG_ID}/download`]: download('big.md'),
+          [`GET /v1/custom-documents/${GONE_ID}`]: { data: { ...text, id: GONE_ID } },
+          [`/v1/custom-documents/${GONE_ID}/download`]: download('gone.md'),
+          [`GET /v1/custom-documents/${FAILED_ID}`]: { data: { ...text, id: FAILED_ID, status: 'failed' } },
+          '/contract.md': () => new Response('# Orders API\n'),
+          '/big.md': () => new Response('x'.repeat(400_000)),
+          '/gone.md': () => new Response('expired', { status: 403 }),
+          [`DELETE /v1/custom-documents/${KNOWLEDGE_ID}`]: () => new Response(null, { status: 204 }),
+        },
+      });
+      const read = async (knowledgeId: string) =>
+        parseToolResult(await client.callTool({ name: 'taiga_get_knowledge', arguments: { knowledgeId } }));
+
+      expect(await read(KNOWLEDGE_ID)).toMatchObject({ id: KNOWLEDGE_ID, content: '# Orders API\n' });
+      // The storage URL gets no Taiga credentials, follows no redirect and has a deadline.
+      const storage = fetchSpy.mock.calls.find((c: unknown[]) => (c[0] as string).includes('/contract.md'))!;
+      const init = storage[1] as RequestInit;
+      expect(init.headers).toBeUndefined();
+      expect(init.redirect).toBe('error');
+      expect(init.signal).toBeInstanceOf(AbortSignal);
+
+      const pdf = await read(PDF_ID);
+      expect(pdf).not.toHaveProperty('content');
+      expect(pdf.downloadUrl).toBe('https://storage.example.com/guide.pdf?sig=1');
+      expect(fetchSpy.mock.calls.some((c: unknown[]) => (c[0] as string).includes('/guide.pdf'))).toBe(false);
+
+      const big = await read(BIG_ID);
+      expect(big.content).toMatch(/^x{20000}\n\n\[Cut at 20000 characters\.\]$/);
+      expect(big.downloadUrl).toContain('/big.md');
+
+      const gone = await read(GONE_ID);
+      expect(gone).not.toHaveProperty('content');
+      expect(gone.note).toBe('Storage answered 403.');
+
+      // A file that failed processing is read by nothing until it is retried, this tool included.
+      const failed = await read(FAILED_ID);
+      expect(failed).toMatchObject({ id: FAILED_ID, status: 'failed' });
+      expect(failed).not.toHaveProperty('content');
+      expect(failed).not.toHaveProperty('downloadUrl');
+      expect(failed.note).toMatch(/taiga_retry_knowledge/);
+      expect(fetchSpy.mock.calls.some((c: unknown[]) => (c[0] as string).includes(`${FAILED_ID}/download`))).toBe(
+        false
+      );
+
+      const deleted = parseToolResult(
+        await client.callTool({ name: 'taiga_delete_knowledge', arguments: { knowledgeId: KNOWLEDGE_ID } })
+      );
+      expect(deleted).toEqual({ id: KNOWLEDGE_ID, deleted: true });
+    });
+
+    it("should set a product's autonomy defaults, writing null where the page writes it, and an initiative's merge switch", async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:write', 'backlog:write'],
+        routes: {
+          [`PATCH /v1/products/${PRODUCT_ID}`]: {
+            data: { id: PRODUCT_ID, name: 'Web', autoBuild: false, autoMerge: null, settings: {} },
+          },
+          [`PATCH /v1/backlog/${ITEM_ID}`]: {
+            data: { id: ITEM_ID, title: 'Add login', autoMerge: false, description: 'long' },
+          },
+        },
+      });
+
+      const product = parseToolResult(
+        await client.callTool({
+          name: 'taiga_set_product_autonomy',
+          arguments: { productId: PRODUCT_ID, autoBuild: false, autoMerge: true },
+        })
+      );
+      expect(sentBody(fetchSpy, 'PATCH', `/products/${PRODUCT_ID}`)).toEqual({ autoBuild: false, autoMerge: null });
+      expect(product).not.toHaveProperty('settings');
+
+      const item = parseToolResult(
+        await client.callTool({ name: 'taiga_set_auto_merge', arguments: { itemId: ITEM_ID, autoMerge: false } })
+      );
+      expect(sentBody(fetchSpy, 'PATCH', `/backlog/${ITEM_ID}`)).toEqual({ autoMerge: false });
+      expect(item).not.toHaveProperty('description');
+
+      const nothing = await client.callTool({
+        name: 'taiga_set_product_autonomy',
+        arguments: { productId: PRODUCT_ID },
+      });
+      expect(nothing.isError).toBe(true);
+    });
+
+    it('should edit a product document section in its draft, publish it, and ask agents to generate', async () => {
+      const published = {
+        id: 'doc-1',
+        type: 'specification',
+        version: 2,
+        isDraft: false,
+        data: { sections: { vision: { content: 'Old', source: 'ai' }, scope: { content: 'Keep' } } },
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`GET /v1/products/${PRODUCT_ID}/documents/specification/draft`]: { data: null },
+          [`GET /v1/products/${PRODUCT_ID}/documents/specification?origin=plan`]: { data: published },
+          [`PUT /v1/products/${PRODUCT_ID}/documents/specification/draft`]: () => {
+            const body = {
+              data: {
+                ...published,
+                isDraft: true,
+                data: JSON.parse((fetchSpy.mock.calls.at(-1)![1] as RequestInit).body as string).data,
+              },
+            };
+            return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+          },
+          [`POST /v1/products/${PRODUCT_ID}/documents/specification/publish`]: {
+            data: { ...published, version: 3 },
+            warnings: { unknownPolicyCitations: ['SEC-99.9'] },
+          },
+          [`POST /v1/products/${PRODUCT_ID}/documents/specification/review`]: { data: { reviewed: true } },
+          'POST /v1/agent-jobs': {
+            data: { id: 'job-9', type: 'generate_document', documentType: 'architecture', status: 'pending' },
+          },
+          [`POST /v1/products/${PRODUCT_ID}/documents/generate-all`]: { data: { jobIds: ['job-10'] } },
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: { id: PRODUCT_ID, status: 'draft' } },
+        },
+      });
+
+      const edited = parseToolResult(
+        await client.callTool({
+          name: 'taiga_update_product_document',
+          arguments: { productId: PRODUCT_ID, type: 'specification', sectionId: 'vision', content: 'New' },
+        })
+      );
+      expect(sentBody(fetchSpy, 'PUT', '/documents/specification/draft')).toEqual({
+        data: { sections: { vision: { content: 'New', source: 'ai' }, scope: { content: 'Keep' } } },
+      });
+      expect(edited.section).toEqual({ id: 'vision', content: 'New' });
+
+      const out = parseToolResult(
+        await client.callTool({
+          name: 'taiga_publish_product_document',
+          arguments: { productId: PRODUCT_ID, type: 'specification' },
+        })
+      );
+      expect(out.version).toBe(3);
+      // A publish that cites a control no policy has says so: the publisher hears of it only here.
+      expect(out.warnings).toEqual({ unknownPolicyCitations: ['SEC-99.9'] });
+
+      await client.callTool({
+        name: 'taiga_mark_product_document_reviewed',
+        arguments: { productId: PRODUCT_ID, type: 'specification' },
+      });
+      const regen = parseToolResult(
+        await client.callTool({
+          name: 'taiga_regenerate_product_document',
+          arguments: { productId: PRODUCT_ID, type: 'architecture' },
+        })
+      );
+      expect(sentBody(fetchSpy, 'POST', '/agent-jobs')).toEqual({
+        scope: 'product',
+        type: 'generate_document',
+        targetId: PRODUCT_ID,
+        documentType: 'architecture',
+      });
+      expect(regen).toMatchObject({ id: 'job-9', status: 'pending' });
+
+      const all = parseToolResult(
+        await client.callTool({ name: 'taiga_generate_product_documents', arguments: { productId: PRODUCT_ID } })
+      );
+      expect(all).toEqual({ jobIds: ['job-10'] });
+      expect(callsTo(fetchSpy, 'POST').map((u) => u.pathname)).toContain(
+        `/v1/products/${PRODUCT_ID}/documents/specification/review`
+      );
+
+      // Each tool takes the types its route serves: the specification is not regenerated from other
+      // documents, and the codebase snapshot is not a document a person reviews.
+      const posts = callsTo(fetchSpy, 'POST').length;
+      const spec = await client.callTool({
+        name: 'taiga_regenerate_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'specification' },
+      });
+      const snapshot = await client.callTool({
+        name: 'taiga_mark_product_document_reviewed',
+        arguments: { productId: PRODUCT_ID, type: 'codebase_snapshot' },
+      });
+      const snapshotEdit = await client.callTool({
+        name: 'taiga_update_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'codebase_snapshot', sectionId: 'vision', content: 'x' },
+      });
+      expect(spec.isError).toBe(true);
+      expect(snapshot.isError).toBe(true);
+      expect(snapshotEdit.isError).toBe(true);
+      expect(callsTo(fetchSpy, 'POST')).toHaveLength(posts);
+    });
+  });
+
+  describe('the Discovery lock on regenerating', () => {
+    it('should refuse to regenerate a document once Discovery is finished, before any job is asked for', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: { id: PRODUCT_ID, status: 'active' } },
+          'POST /v1/agent-jobs': {
+            data: { id: 'job-11', type: 'generate_document', documentType: 'service_blueprint', status: 'pending' },
+          },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_regenerate_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).message).toMatch(/Discovery is finished/);
+      expect(fetchSpy.mock.calls.some((c: unknown[]) => (c[0] as string).includes('/agent-jobs'))).toBe(false);
+
+      // The optional Service Blueprint is not one setup locks, so it is still generated after it.
+      const blueprint = await client.callTool({
+        name: 'taiga_regenerate_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'service_blueprint' },
+      });
+      expect(blueprint.isError).toBeFalsy();
+      expect(sentBody(fetchSpy, 'POST', '/agent-jobs')).toMatchObject({ documentType: 'service_blueprint' });
+    });
+  });
+
   describe('error handling', () => {
     it('should surface API errors as structured MCP error content', async () => {
       // Introspect succeeds, but all other endpoints fail