@taiga-ai/mcp-server 0.14.0-dev.428 → 0.16.0-dev.430

package/src/server.integration.test.ts

@@ -1,9 +1,9 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { Client, InMemoryTransport } from '@modelcontextprotocol/client';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { TaigaClient } from './client.js';
-import { registerAllTools } from './tools/index.js';
+import { createServer } from './server.js';
+import type { WaitOptions } from './tools/wait.js';
 
 // ---------------------------------------------------------------------------
 // Helpers -- thin wrappers, not abstraction layers
@@ -22,6 +22,9 @@ const ALL_CAPABILITIES = [
   'customDocuments:read',
   'customDocuments:write',
   'customDocuments:delete',
+  'factories:write',
+  'vcs:read',
+  'vcs:manage',
 ];
 
 /**
@@ -31,8 +34,11 @@ const ALL_CAPABILITIES = [
 const ALL_TOOL_NAMES = [
   'taiga_add_knowledge',
   'taiga_approve_plan',
+  'taiga_create_factory',
+  'taiga_create_product',
   'taiga_define_environment',
   'taiga_delete_knowledge',
+  'taiga_finish_discovery',
   'taiga_fix_finding',
   'taiga_fix_policy_violation',
   'taiga_generate_product_documents',
@@ -54,6 +60,7 @@ const ALL_TOOL_NAMES = [
   'taiga_get_product_document',
   'taiga_get_queue',
   'taiga_ignore_finding',
+  'taiga_link_repository',
   'taiga_list_action_required',
   'taiga_list_backlog_items',
   'taiga_list_builds',
@@ -62,19 +69,27 @@ const ALL_TOOL_NAMES = [
   'taiga_list_factory_documents',
   'taiga_list_findings',
   'taiga_list_knowledge',
+  'taiga_list_linkable_repositories',
   'taiga_list_product_documents',
+  'taiga_list_product_repositories',
   'taiga_list_products',
+  'taiga_list_repository_branches',
   'taiga_list_setup_tasks',
   'taiga_mark_product_document_reviewed',
   'taiga_move_backlog_item',
+  'taiga_move_product',
   'taiga_pause_line',
   'taiga_plan_again',
+  'taiga_preview_product_move',
   'taiga_publish_document',
   'taiga_publish_factory_document',
   'taiga_publish_product_document',
   'taiga_queue_backlog_item',
+  'taiga_refresh_reality_documents',
   'taiga_regenerate_product_document',
   'taiga_reject_plan',
+  'taiga_rename_factory',
+  'taiga_reopen_discovery',
   'taiga_request_initiatives',
   'taiga_resolve_action',
   'taiga_resolve_product',
@@ -83,11 +98,15 @@ const ALL_TOOL_NAMES = [
   'taiga_set_auto_build',
   'taiga_set_auto_merge',
   'taiga_set_product_autonomy',
+  'taiga_set_repository_branch',
+  'taiga_start_import',
   'taiga_stop_build',
   'taiga_stop_generating_documents',
+  'taiga_unlink_repository',
   'taiga_update_document',
   'taiga_update_environment',
   'taiga_update_factory_document',
+  'taiga_update_product',
   'taiga_update_product_document',
   'taiga_wait_for_backlog_item',
   'taiga_wait_for_build',
@@ -139,14 +158,18 @@ function sentBody(fetchSpy: ReturnType<typeof vi.fn>, method: string, pathPart:
 /** What the API answers when it refuses: the status and the error envelope its error handler sends. */
 class Refusal {
   readonly status: number;
-  readonly body: { error: string; code: string; message: string };
+  readonly body: { error: string; code: string; message: string; details?: Record<string, unknown> };
 
-  constructor(status: number, body: { error: string; code: string; message: string }) {
+  constructor(
+    status: number,
+    body: { error: string; code: string; message: string; details?: Record<string, unknown> }
+  ) {
     this.status = status;
     this.body = body;
   }
 }
-const refusal = (status: number, code: string, message: string) => new Refusal(status, { error: code, code, message });
+const refusal = (status: number, code: string, message: string, details?: Record<string, unknown>) =>
+  new Refusal(status, { error: code, code, message, ...(details ? { details } : {}) });
 
 function makeFetchRouter(routes: Record<string, unknown>) {
   return vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
@@ -218,17 +241,25 @@ async function bootMcpPair(opts: { capabilities: string[]; routes?: Record<strin
   });
   await taigaClient.introspect();
 
-  const server = new McpServer({ name: 'taiga-test', version: '0.0.1' });
   // Waits poll every few milliseconds here, not every few seconds.
-  registerAllTools(server, taigaClient, { wait: { pollIntervalMs: 5 } });
-
-  const client = new Client({ name: 'test-client', version: '0.0.1' });
-  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-  await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+  const client = await connectServer(taigaClient, { pollIntervalMs: 5 });
 
   return { client, fetchSpy };
 }
 
+/**
+ * The server as the entry point serves it: createServer behind serveStdio,
+ * reached by a client opening with the 2025 initialize handshake, as Claude
+ * Code and Cursor do (modern.integration.test.ts covers 2026-07-28).
+ */
+async function connectServer(taigaClient: TaigaClient, wait?: WaitOptions) {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  serveStdio(() => createServer(taigaClient, wait ? { wait } : {}), { transport: serverTransport });
+  const client = new Client({ name: 'test-client', version: '0.0.1' });
+  await client.connect(clientTransport);
+  return client;
+}
+
 /** Extract sorted tool names from a listTools response. */
 function toolNames(tools: { name: string }[]) {
   return tools.map((t) => t.name).sort();
@@ -264,13 +295,20 @@ describe('MCP server integration', () => {
       expect(toolNames(tools)).toEqual(ALL_TOOL_NAMES);
     });
 
-    it('should reject tools/list when API key has no capabilities', async () => {
-      // When zero tools are registered, the MCP SDK doesn't advertise
-      // the tools capability at all -- the protocol-correct response
-      // is "Method not found".
+    it('should not advertise tools when the API key has no capabilities', async () => {
+      // With no tool registered the server leaves the tools capability out, as
+      // v1 did. A v2 client then answers listTools with an empty list itself,
+      // without asking, so the capability is what is asserted.
       const { client } = await bootMcpPair({ capabilities: [] });
 
-      await expect(client.listTools()).rejects.toThrow(/Method not found/);
+      expect(client.getServerCapabilities()?.tools).toBeUndefined();
+      expect((await client.listTools()).tools).toEqual([]);
+    });
+
+    it('should give the server instructions to a client on the 2025 handshake', async () => {
+      const { client } = await bootMcpPair({ capabilities: ['products:read'] });
+
+      expect(client.getInstructions()).toContain('Taiga');
     });
 
     it('should expose only factory tools for a teams:read-only key', async () => {
@@ -302,7 +340,7 @@ describe('MCP server integration', () => {
       // routes need tenant:documents:read.
       const { client } = await bootMcpPair({ capabilities: ['tenant:documents:write'] });
 
-      await expect(client.listTools()).rejects.toThrow(/Method not found/);
+      expect(client.getServerCapabilities()?.tools).toBeUndefined();
     });
 
     it('should expose write tools when documents:write is also granted', async () => {
@@ -410,7 +448,17 @@ describe('MCP server integration', () => {
         'taiga_get_deployments',
         'taiga_get_delivery_metrics',
         'taiga_get_monitoring',
+        'taiga_list_product_repositories',
+        'taiga_list_repository_branches',
+      ],
+      'vcs:read': ['taiga_list_linkable_repositories'],
+      'factories:write': [
+        'taiga_create_factory',
+        'taiga_rename_factory',
+        'taiga_preview_product_move',
+        'taiga_move_product',
       ],
+      'vcs:manage': ['taiga_link_repository', 'taiga_set_repository_branch', 'taiga_unlink_repository'],
       'backlog:read': [
         'taiga_list_backlog_items',
         'taiga_get_backlog_item',
@@ -435,10 +483,16 @@ describe('MCP server integration', () => {
         'taiga_mark_product_document_reviewed',
         'taiga_generate_product_documents',
         'taiga_stop_generating_documents',
+        'taiga_create_product',
+        'taiga_update_product',
+        'taiga_refresh_reality_documents',
+        'taiga_finish_discovery',
+        'taiga_reopen_discovery',
       ],
       'backlog:read products:write': ['taiga_approve_plan', 'taiga_reject_plan'],
       'backlog:read backlog:write products:write': ['taiga_plan_again'],
       'products:read products:write': [
+        'taiga_start_import',
         'taiga_stop_build',
         'taiga_pause_line',
         'taiga_ignore_finding',
@@ -724,11 +778,7 @@ describe('MCP server integration', () => {
       vi.stubGlobal('fetch', fetchSpy);
       const taigaClient = new TaigaClient({ baseUrl: 'https://api.test.com', apiKey: 'taiga_sk_live_test' });
       await taigaClient.introspect();
-      const server = new McpServer({ name: 'taiga-test', version: '0.0.1' });
-      registerAllTools(server, taigaClient);
-      const client = new Client({ name: 'test-client', version: '0.0.1' });
-      const [ct, st] = InMemoryTransport.createLinkedPair();
-      await Promise.all([server.connect(st), client.connect(ct)]);
+      const client = await connectServer(taigaClient);
 
       const result = await client.callTool({ name: 'taiga_publish_document', arguments: { type: 'policy_security' } });
 
@@ -758,11 +808,7 @@ describe('MCP server integration', () => {
       vi.stubGlobal('fetch', fetchSpy);
       const taigaClient = new TaigaClient({ baseUrl: 'https://api.test.com', apiKey: 'taiga_sk_live_test' });
       await taigaClient.introspect();
-      const server = new McpServer({ name: 'taiga-test', version: '0.0.1' });
-      registerAllTools(server, taigaClient);
-      const client = new Client({ name: 'test-client', version: '0.0.1' });
-      const [ct, st] = InMemoryTransport.createLinkedPair();
-      await Promise.all([server.connect(st), client.connect(ct)]);
+      const client = await connectServer(taigaClient);
 
       const result = await client.callTool({
         name: 'taiga_update_document',
@@ -793,11 +839,7 @@ describe('MCP server integration', () => {
       vi.stubGlobal('fetch', fetchSpy);
       const taigaClient = new TaigaClient({ baseUrl: 'https://api.test.com', apiKey: 'taiga_sk_live_test' });
       await taigaClient.introspect();
-      const server = new McpServer({ name: 'taiga-test', version: '0.0.1' });
-      registerAllTools(server, taigaClient);
-      const client = new Client({ name: 'test-client', version: '0.0.1' });
-      const [ct, st] = InMemoryTransport.createLinkedPair();
-      await Promise.all([server.connect(st), client.connect(ct)]);
+      const client = await connectServer(taigaClient);
 
       const result = await client.callTool({ name: 'taiga_list_factories', arguments: {} });
 
@@ -2437,7 +2479,7 @@ describe('MCP server integration', () => {
 
       expect(failure).toMatchObject({ code: -32602 });
       expect(String((failure as Error).message)).toBe(
-        'MCP error -32602: No published tone_of_voice the key can read (404 NOT_FOUND: The requested resource does not exist). ' +
+        'No published tone_of_voice the key can read (404 NOT_FOUND: The requested resource does not exist). ' +
           'Published documents: policy_security.'
       );
     });
@@ -2612,7 +2654,8 @@ describe('MCP server integration', () => {
         error: 'FORBIDDEN',
         message: expect.stringContaining('403 FORBIDDEN'),
       });
-      expect(String((prompt as Error).message)).toMatch(/^MCP error -32602: FORBIDDEN: /);
+      expect(prompt).toMatchObject({ code: -32602 });
+      expect(String((prompt as Error).message)).toMatch(/^FORBIDDEN: /);
     });
 
     it('should refuse a session on a product the key cannot see as invalid params', async () => {
@@ -2634,7 +2677,7 @@ describe('MCP server integration', () => {
       expect(failure).toMatchObject({ code: -32602 });
       // A slash command with no argument lands here; the message says how to pass one.
       expect(String((failure as Error).message)).toMatch(
-        /^MCP error -32602: VALIDATION_FAILED: Name the product exactly once: slug or productId or remoteUrl\. Pass the slug as the first argument \(\/taiga_start_session <slug>/
+        /^VALIDATION_FAILED: Name the product exactly once: slug or productId or remoteUrl\. Pass the slug as the first argument \(\/taiga_start_session <slug>/
       );
     });
 
@@ -3082,14 +3125,19 @@ describe('MCP server integration', () => {
       // 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_create_product',
+        'taiga_finish_discovery',
         'taiga_generate_product_documents',
         'taiga_mark_product_document_reviewed',
         'taiga_publish_product_document',
+        'taiga_refresh_reality_documents',
+        'taiga_reopen_discovery',
         'taiga_request_initiatives',
         'taiga_resume_backlog_item',
         'taiga_set_auto_build',
         'taiga_set_product_autonomy',
         'taiga_stop_generating_documents',
+        'taiga_update_product',
       ]);
     });
 
@@ -4202,7 +4250,6 @@ describe('MCP server integration', () => {
 
       const pending = client.callTool(
         { name: 'taiga_wait_for_backlog_item', arguments: { itemId: ITEM_ID, until: 'planned', timeoutSeconds: 60 } },
-        undefined,
         { signal: controller.signal }
       );
       await vi.waitFor(() => expect(hung).toBeDefined());
@@ -4427,7 +4474,6 @@ describe('MCP server integration', () => {
 
       const result = await client.callTool(
         { name: 'taiga_wait_for_backlog_item', arguments: { itemId: ITEM_ID, until: 'changed' } },
-        undefined,
         { onprogress }
       );
 
@@ -5522,6 +5568,532 @@ describe('MCP server integration', () => {
     });
   });
 
+  describe('setting a product up', () => {
+    const FACTORY_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c01';
+    const OTHER_FACTORY_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c02';
+    const JOB_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c03';
+    const LINK_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c04';
+    const GH_REPO_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c05';
+    const INSTALL_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c06';
+    const INSTALL_ID_2 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c07';
+    const product = (settings: Record<string, unknown> = {}) => ({
+      id: PRODUCT_ID,
+      name: 'Billing',
+      slug: 'billing',
+      status: 'draft',
+      factoryId: FACTORY_ID,
+      ownerId: 'u',
+      ownsInfrastructure: null,
+      ownsDeployment: false,
+      deploymentNotes: 'Platform team owns the pipelines',
+      emitDesignStandards: null,
+      autoBuild: true,
+      settings,
+    });
+    const link = {
+      id: LINK_ID,
+      provider: 'github',
+      repositoryName: 'acme/billing',
+      repositoryUrl: 'https://github.com/acme/billing',
+      repositoryDefaultBranch: 'main',
+      baseBranch: null,
+      effectiveBranch: 'main',
+      label: null,
+      languages: { TypeScript: 100 },
+      isManaged: false,
+      buildable: true,
+    };
+    const ghRepo = (id: string, fullName: string) => ({
+      id,
+      installationId: INSTALL_ID,
+      githubId: 1,
+      name: fullName.split('/')[1],
+      fullName,
+      private: true,
+      visibility: 'private',
+      archived: false,
+      description: null,
+      defaultBranch: 'main',
+      language: 'TypeScript',
+      topics: [],
+    });
+    const calls = (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 create a product from scratch or for an import, with what Taiga builds as the person decided', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:write'],
+        routes: {
+          'POST /v1/products': (_url: string, init: RequestInit) => {
+            const body = JSON.parse(init.body as string);
+            const created = { data: product(body.projectType ? { projectType: body.projectType } : {}) };
+            return { ok: true, status: 201, json: async () => created, text: async () => JSON.stringify(created) };
+          },
+        },
+      });
+
+      const scratch = parseToolResult(
+        await client.callTool({
+          name: 'taiga_create_product',
+          arguments: { factoryId: FACTORY_ID, name: 'Billing', start: 'scratch' },
+        })
+      );
+      const firstBody = sentBody(fetchSpy, 'POST', '/v1/products');
+      fetchSpy.mockClear();
+      const imported = parseToolResult(
+        await client.callTool({
+          name: 'taiga_create_product',
+          arguments: {
+            factoryId: FACTORY_ID,
+            name: 'Billing',
+            start: 'import',
+            ownsDeployment: false,
+            deploymentNotes: 'Platform team owns the pipelines',
+          },
+        })
+      );
+
+      // Following the organization is saying nothing, as the web's dialog does.
+      expect(firstBody).toEqual({ name: 'Billing', factoryId: FACTORY_ID });
+      expect(sentBody(fetchSpy, 'POST', '/v1/products')).toEqual({
+        name: 'Billing',
+        factoryId: FACTORY_ID,
+        projectType: 'brownfield',
+        ownsDeployment: false,
+        deploymentNotes: 'Platform team owns the pipelines',
+      });
+      expect(scratch).toMatchObject({ id: PRODUCT_ID, projectType: 'greenfield' });
+      expect(imported).toMatchObject({ projectType: 'brownfield', ownsDeployment: false });
+      expect(imported).not.toHaveProperty('settings');
+      expect(imported).not.toHaveProperty('ownerId');
+    });
+
+    it("should change a product's settings, returning a half to the organization with null, and refuse an empty change", async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:write'],
+        routes: { [`PATCH /v1/products/${PRODUCT_ID}`]: { data: product() } },
+      });
+
+      await client.callTool({
+        name: 'taiga_update_product',
+        arguments: { productId: PRODUCT_ID, ownsInfrastructure: null, emitDesignStandards: false, name: 'Billing 2' },
+      });
+      const nothing = await client.callTool({ name: 'taiga_update_product', arguments: { productId: PRODUCT_ID } });
+
+      expect(sentBody(fetchSpy, 'PATCH', `/v1/products/${PRODUCT_ID}`)).toEqual({
+        ownsInfrastructure: null,
+        emitDesignStandards: false,
+        name: 'Billing 2',
+      });
+      expect(nothing.isError).toBe(true);
+      expect(calls(fetchSpy, 'PATCH')).toHaveLength(1);
+    });
+
+    it('should create and rename a factory, preview a move and move a product, stopping the line only when asked', async () => {
+      const factory = {
+        id: OTHER_FACTORY_ID,
+        name: 'Payments',
+        slug: 'payments',
+        isDefault: false,
+        settings: {},
+        autoMerge: null,
+      };
+      const preview = {
+        sourceFactoryId: FACTORY_ID,
+        targetFactoryId: OTHER_FACTORY_ID,
+        loses: [],
+        gains: [],
+        kept: [],
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['factories:write'],
+        routes: {
+          'POST /v1/factories': { data: factory },
+          [`PATCH /v1/factories/${OTHER_FACTORY_ID}`]: { data: { ...factory, name: 'Payments EU' } },
+          [`GET /v1/products/${PRODUCT_ID}/factory/preview?factoryId=${OTHER_FACTORY_ID}`]: { data: preview },
+          [`PUT /v1/products/${PRODUCT_ID}/factory`]: {
+            data: { ...product(), factoryId: OTHER_FACTORY_ID },
+            changed: true,
+            previousFactoryId: FACTORY_ID,
+            lineStopped: false,
+            factoryStopped: false,
+            rescopedDocumentIds: [],
+            failedDocumentIds: [],
+            failedDocuments: [],
+          },
+        },
+      });
+
+      const created = parseToolResult(
+        await client.callTool({ name: 'taiga_create_factory', arguments: { name: 'Payments' } })
+      );
+      const renamed = parseToolResult(
+        await client.callTool({
+          name: 'taiga_rename_factory',
+          arguments: { factoryId: OTHER_FACTORY_ID, name: 'Payments EU' },
+        })
+      );
+      const seen = parseToolResult(
+        await client.callTool({
+          name: 'taiga_preview_product_move',
+          arguments: { productId: PRODUCT_ID, factoryId: OTHER_FACTORY_ID },
+        })
+      );
+      const moved = parseToolResult(
+        await client.callTool({
+          name: 'taiga_move_product',
+          arguments: { productId: PRODUCT_ID, factoryId: OTHER_FACTORY_ID },
+        })
+      );
+      const plainMove = sentBody(fetchSpy, 'PUT', '/factory');
+      const factoryBody = sentBody(fetchSpy, 'POST', '/v1/factories');
+      fetchSpy.mockClear();
+      await client.callTool({
+        name: 'taiga_move_product',
+        arguments: { productId: PRODUCT_ID, factoryId: OTHER_FACTORY_ID, stopLine: true },
+      });
+
+      expect(factoryBody).toEqual({ name: 'Payments' });
+      expect(created).toEqual({ id: OTHER_FACTORY_ID, name: 'Payments', slug: 'payments', isDefault: false });
+      expect(renamed.name).toBe('Payments EU');
+      expect(seen).toEqual(preview);
+      expect(plainMove).toEqual({ factoryId: OTHER_FACTORY_ID });
+      expect(sentBody(fetchSpy, 'PUT', '/factory')).toEqual({ factoryId: OTHER_FACTORY_ID, stopLine: true });
+      expect(moved).toMatchObject({
+        changed: true,
+        previousFactoryId: FACTORY_ID,
+        product: { factoryId: OTHER_FACTORY_ID },
+      });
+    });
+
+    it('should start an import only for a product created to import, and refresh, finish and reopen Discovery', async () => {
+      const SCRATCH_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c08';
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: product({ projectType: 'brownfield' }) },
+          [`GET /v1/products/${SCRATCH_ID}`]: { data: { ...product(), id: SCRATCH_ID } },
+          [`POST /v1/products/${PRODUCT_ID}/brownfield-import`]: { data: { jobId: JOB_ID } },
+          [`POST /v1/products/${PRODUCT_ID}/documents/refresh-reality`]: { data: { jobId: JOB_ID } },
+          [`POST /v1/products/${PRODUCT_ID}/setup/complete`]: { data: { ...product(), status: 'active' } },
+          [`POST /v1/products/${PRODUCT_ID}/setup/reopen`]: { data: product() },
+        },
+      });
+
+      const scratch = await client.callTool({ name: 'taiga_start_import', arguments: { productId: SCRATCH_ID } });
+      const started = parseToolResult(
+        await client.callTool({ name: 'taiga_start_import', arguments: { productId: PRODUCT_ID } })
+      );
+      await client.callTool({
+        name: 'taiga_refresh_reality_documents',
+        arguments: { productId: PRODUCT_ID, docTypes: ['architecture'] },
+      });
+      const finished = parseToolResult(
+        await client.callTool({ name: 'taiga_finish_discovery', arguments: { productId: PRODUCT_ID } })
+      );
+      const reopened = parseToolResult(
+        await client.callTool({ name: 'taiga_reopen_discovery', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(scratch.isError).toBe(true);
+      expect(parseToolResult(scratch).message).toMatch(/started from scratch/);
+      expect(calls(fetchSpy, 'POST').map((u) => u.pathname)).not.toContain(
+        `/v1/products/${SCRATCH_ID}/brownfield-import`
+      );
+      expect(started).toEqual({ jobId: JOB_ID });
+      expect(sentBody(fetchSpy, 'POST', '/refresh-reality')).toEqual({ docTypes: ['architecture'] });
+      expect(finished.status).toBe('active');
+      expect(reopened.status).toBe('draft');
+    });
+
+    it("should list a product's repositories and branches, and find, link, set and unlink one", async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'vcs:read', 'vcs:manage'],
+        routes: {
+          [`GET /v1/products/${PRODUCT_ID}/repositories`]: { data: [link], nextCursor: null },
+          [`GET /v1/products/${PRODUCT_ID}/repositories/${LINK_ID}/branches`]: {
+            data: [
+              { name: 'main', protected: true },
+              { name: 'develop', protected: false },
+            ],
+            truncated: false,
+          },
+          'GET /v1/github/installations': {
+            data: [
+              { id: INSTALL_ID, installationId: 1, accountLogin: 'acme', accountType: 'Organization', permissions: {} },
+            ],
+            nextCursor: null,
+          },
+          [`GET /v1/github/installations/${INSTALL_ID}/repositories`]: {
+            data: [ghRepo(GH_REPO_ID, 'acme/billing')],
+            nextCursor: 'next',
+          },
+          [`POST /v1/products/${PRODUCT_ID}/repositories`]: () => {
+            const created = { data: link };
+            return { ok: true, status: 201, json: async () => created, text: async () => JSON.stringify(created) };
+          },
+          [`PATCH /v1/products/${PRODUCT_ID}/repositories/${LINK_ID}`]: {
+            data: { ...link, baseBranch: 'develop', effectiveBranch: 'develop', baseBranchProtection: null },
+          },
+          [`DELETE /v1/products/${PRODUCT_ID}/repositories/${LINK_ID}`]: () => new Response(null, { status: 204 }),
+        },
+      });
+
+      const linked = parseToolResult(
+        await client.callTool({ name: 'taiga_list_product_repositories', arguments: { productId: PRODUCT_ID } })
+      );
+      const branches = parseToolResult(
+        await client.callTool({
+          name: 'taiga_list_repository_branches',
+          arguments: { productId: PRODUCT_ID, repositoryId: LINK_ID },
+        })
+      );
+      const found = parseToolResult(
+        await client.callTool({ name: 'taiga_list_linkable_repositories', arguments: { query: 'bill' } })
+      );
+      await client.callTool({
+        name: 'taiga_link_repository',
+        arguments: { productId: PRODUCT_ID, githubRepositoryId: GH_REPO_ID },
+      });
+      const set = parseToolResult(
+        await client.callTool({
+          name: 'taiga_set_repository_branch',
+          arguments: { productId: PRODUCT_ID, repositoryId: LINK_ID, baseBranch: 'develop' },
+        })
+      );
+      const nothing = await client.callTool({
+        name: 'taiga_set_repository_branch',
+        arguments: { productId: PRODUCT_ID, repositoryId: LINK_ID },
+      });
+      const unlinked = parseToolResult(
+        await client.callTool({
+          name: 'taiga_unlink_repository',
+          arguments: { productId: PRODUCT_ID, repositoryId: LINK_ID },
+        })
+      );
+
+      expect(linked).toEqual([
+        {
+          id: LINK_ID,
+          provider: 'github',
+          repositoryName: 'acme/billing',
+          repositoryUrl: 'https://github.com/acme/billing',
+          repositoryDefaultBranch: 'main',
+          baseBranch: null,
+          effectiveBranch: 'main',
+          label: null,
+          buildable: true,
+          isManaged: false,
+        },
+      ]);
+      expect(branches.branches).toHaveLength(2);
+      expect(found.accounts).toEqual([{ id: INSTALL_ID, accountLogin: 'acme', accountType: 'Organization' }]);
+      expect(found.repositories).toEqual({
+        data: [
+          {
+            id: GH_REPO_ID,
+            fullName: 'acme/billing',
+            private: true,
+            archived: false,
+            defaultBranch: 'main',
+            description: null,
+            language: 'TypeScript',
+          },
+        ],
+        nextCursor: 'next',
+      });
+      expect(sentUrl(fetchSpy, `/installations/${INSTALL_ID}/repositories`).searchParams.get('q')).toBe('bill');
+      // The web's picker sends the GitHub repository's id and nothing else; the API fills in the rest.
+      expect(sentBody(fetchSpy, 'POST', `/v1/products/${PRODUCT_ID}/repositories`)).toEqual({
+        githubRepositoryId: GH_REPO_ID,
+      });
+      expect(sentBody(fetchSpy, 'PATCH', `/repositories/${LINK_ID}`)).toEqual({ baseBranch: 'develop' });
+      expect(set).toMatchObject({ effectiveBranch: 'develop', baseBranchProtection: null });
+      expect(nothing.isError).toBe(true);
+      expect(calls(fetchSpy, 'PATCH')).toHaveLength(1);
+      expect(unlinked).toEqual({ repositoryId: LINK_ID, unlinked: true });
+    });
+
+    it('should say GitHub is not connected, and read every account once when several are', async () => {
+      const none = await bootMcpPair({
+        capabilities: ['vcs:read'],
+        routes: { 'GET /v1/github/installations': { data: [], nextCursor: null } },
+      });
+      const notConnected = await none.client.callTool({ name: 'taiga_list_linkable_repositories', arguments: {} });
+      expect(notConnected.isError).toBe(true);
+      expect(parseToolResult(notConnected).error).toBe('NOT_CONNECTED');
+
+      const two = await bootMcpPair({
+        capabilities: ['vcs:read'],
+        routes: {
+          'GET /v1/github/installations': {
+            data: [
+              { id: INSTALL_ID, accountLogin: 'acme', accountType: 'Organization' },
+              { id: INSTALL_ID_2, accountLogin: 'acme-labs', accountType: 'Organization' },
+            ],
+            nextCursor: null,
+          },
+          [`GET /v1/github/installations/${INSTALL_ID}/repositories`]: {
+            data: [ghRepo(GH_REPO_ID, 'acme/billing')],
+            nextCursor: null,
+          },
+          [`GET /v1/github/installations/${INSTALL_ID_2}/repositories`]: {
+            data: [ghRepo(LINK_ID, 'acme-labs/billing-poc')],
+            nextCursor: 'more',
+          },
+        },
+      });
+      const both = parseToolResult(
+        await two.client.callTool({ name: 'taiga_list_linkable_repositories', arguments: { query: 'billing' } })
+      );
+      expect(both.repositories.nextCursor).toBeNull();
+      const one = parseToolResult(
+        await two.client.callTool({
+          name: 'taiga_list_linkable_repositories',
+          arguments: { query: 'billing', limit: 1 },
+        })
+      );
+      // The limit holds across accounts, and the answer says it was cut.
+      expect(one.repositories.data).toHaveLength(1);
+      expect(one.more).toMatch(/installationId/);
+      expect(both.repositories.data.map((r: { fullName: string }) => r.fullName)).toEqual([
+        'acme/billing',
+        'acme-labs/billing-poc',
+      ]);
+      expect(both.more).toMatch(/installationId/);
+    });
+  });
+
+  describe('setting a product up when the API refuses', () => {
+    const FACTORY_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c01';
+    const INSTALL_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c06';
+    const INSTALL_ID_2 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c07';
+    const UNKNOWN_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c09';
+    const GH_REPO_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4c05';
+
+    it("should pass on the API's reason and what it found, so the model knows which documents to publish", async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:write', 'factories:write', 'vcs:manage'],
+        routes: {
+          [`POST /v1/products/${PRODUCT_ID}/setup/complete`]: refusal(
+            409,
+            'CONFLICT',
+            'Every required document must be published before setup can be completed',
+            { reason: 'documents_incomplete', missingDocuments: ['threat_model', 'risk_register'] }
+          ),
+          [`PUT /v1/products/${PRODUCT_ID}/factory`]: refusal(409, 'CONFLICT', 'A plan or build is in flight', {
+            reason: 'work_in_flight',
+          }),
+          [`POST /v1/products/${PRODUCT_ID}/repositories`]: refusal(
+            409,
+            'CONFLICT',
+            'acme/billing is already linked to this product.'
+          ),
+        },
+      });
+
+      const finish = await client.callTool({ name: 'taiga_finish_discovery', arguments: { productId: PRODUCT_ID } });
+      const move = await client.callTool({
+        name: 'taiga_move_product',
+        arguments: { productId: PRODUCT_ID, factoryId: FACTORY_ID },
+      });
+      const link = await client.callTool({
+        name: 'taiga_link_repository',
+        arguments: { productId: PRODUCT_ID, githubRepositoryId: GH_REPO_ID },
+      });
+
+      expect(finish.isError).toBe(true);
+      expect(parseToolResult(finish)).toEqual({
+        error: 'CONFLICT',
+        message: 'Every required document must be published before setup can be completed',
+        details: { reason: 'documents_incomplete', missingDocuments: ['threat_model', 'risk_register'] },
+      });
+      expect(parseToolResult(move)).toMatchObject({ error: 'CONFLICT', details: { reason: 'work_in_flight' } });
+      // A refusal without details carries none.
+      expect(parseToolResult(link)).toEqual({
+        error: 'CONFLICT',
+        message: 'acme/billing is already linked to this product.',
+      });
+    });
+
+    it('should refuse what it can tell is wrong before any request: an unknown account, a cursor without one, a sentence with nothing to describe', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:write', 'vcs:read'],
+        routes: {
+          'GET /v1/github/installations': {
+            data: [
+              { id: INSTALL_ID, accountLogin: 'acme', accountType: 'Organization' },
+              { id: INSTALL_ID_2, accountLogin: 'acme-labs', accountType: 'Organization' },
+            ],
+            nextCursor: null,
+          },
+        },
+      });
+
+      const unknown = await client.callTool({
+        name: 'taiga_list_linkable_repositories',
+        arguments: { installationId: UNKNOWN_ID },
+      });
+      const cursor = await client.callTool({ name: 'taiga_list_linkable_repositories', arguments: { cursor: 'abc' } });
+      const notes = await client.callTool({
+        name: 'taiga_create_product',
+        arguments: {
+          factoryId: FACTORY_ID,
+          name: 'Billing',
+          start: 'scratch',
+          ownsInfrastructure: true,
+          ownsDeployment: true,
+          deploymentNotes: 'Nothing to say',
+        },
+      });
+
+      expect(parseToolResult(unknown)).toMatchObject({ error: 'NOT_FOUND', details: { accounts: expect.any(Array) } });
+      expect(parseToolResult(cursor).error).toBe('VALIDATION_FAILED');
+      const pagedSearch = await client.callTool({
+        name: 'taiga_list_linkable_repositories',
+        arguments: { installationId: INSTALL_ID, query: 'bill', cursor: 'abc' },
+      });
+      expect(parseToolResult(pagedSearch).error).toBe('VALIDATION_FAILED');
+      expect(parseToolResult(notes).error).toBe('VALIDATION_FAILED');
+      const updateNotes = await client.callTool({
+        name: 'taiga_update_product',
+        arguments: { productId: PRODUCT_ID, ownsInfrastructure: true, ownsDeployment: true, deploymentNotes: 'x' },
+      });
+      expect(parseToolResult(updateNotes).error).toBe('VALIDATION_FAILED');
+      const asked = fetchSpy.mock.calls.map((c: unknown[]) => new URL(c[0] as string).pathname);
+      expect(asked.filter((p: string) => p.includes('/github/installations/'))).toEqual([]);
+      expect(asked).not.toContain('/v1/products');
+      expect(asked).not.toContain(`/v1/products/${PRODUCT_ID}`);
+    });
+
+    it('should find a GitHub account on a later page of connections', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['vcs:read'],
+        routes: {
+          'GET /v1/github/installations': (url: string) =>
+            new Response(
+              JSON.stringify(
+                new URL(url).searchParams.get('cursor') === 'p2'
+                  ? { data: [{ id: INSTALL_ID_2, accountLogin: 'acme-labs' }], nextCursor: null }
+                  : { data: [{ id: INSTALL_ID, accountLogin: 'acme' }], nextCursor: 'p2' }
+              )
+            ),
+          [`GET /v1/github/installations/${INSTALL_ID_2}/repositories`]: { data: [], nextCursor: null },
+        },
+      });
+
+      const found = parseToolResult(
+        await client.callTool({ name: 'taiga_list_linkable_repositories', arguments: { installationId: INSTALL_ID_2 } })
+      );
+
+      expect(found.accounts.map((a: { accountLogin: string }) => a.accountLogin)).toEqual(['acme', 'acme-labs']);
+      expect(found.repositories).toEqual({ data: [], nextCursor: null });
+      expect(sentUrl(fetchSpy, 'cursor=p2').searchParams.get('limit')).toBe('100');
+    });
+  });
+
   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({
@@ -5578,11 +6150,7 @@ describe('MCP server integration', () => {
       // Arrange
       const taigaClient = new TaigaClient({ baseUrl: 'https://api.test.com', apiKey: 'test' });
       await taigaClient.introspect();
-      const server = new McpServer({ name: 'test', version: '0.0.1' });
-      registerAllTools(server, taigaClient);
-      const mcpClient = new Client({ name: 'test-client', version: '0.0.1' });
-      const [ct, st] = InMemoryTransport.createLinkedPair();
-      await Promise.all([server.connect(st), mcpClient.connect(ct)]);
+      const mcpClient = await connectServer(taigaClient);
 
       // Act
       const result = await mcpClient.callTool({ name: 'taiga_list_products', arguments: {} });