@taiga-ai/mcp-server 0.7.0-dev.395 → 0.8.0-dev.397

package/src/client.ts

@@ -159,13 +159,21 @@ export class TaigaClient {
     return this.request<{ data: unknown }>('GET', `/products/${seg(id)}`);
   }
 
+  async listProductRepositories(productId: string) {
+    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+      'GET',
+      `/products/${seg(productId)}/repositories`
+    );
+  }
+
   // ---------------------------------------------------------------------------
   // Documents (tenant-level policies)
   // ---------------------------------------------------------------------------
 
-  async listTenantDocuments(opts?: { limit?: number | undefined }) {
+  async listTenantDocuments(opts?: { limit?: number | undefined; cursor?: string | undefined }) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set('limit', String(opts.limit));
+    if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>(
       'GET',
@@ -194,9 +202,10 @@ export class TaigaClient {
   // Factory Documents
   // ---------------------------------------------------------------------------
 
-  async listFactoryDocuments(factoryId: string, opts?: { limit?: number | undefined }) {
+  async listFactoryDocuments(factoryId: string, opts?: { limit?: number | undefined; cursor?: string | undefined }) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set('limit', String(opts.limit));
+    if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>(
       'GET',
@@ -264,6 +273,7 @@ export class TaigaClient {
       category?: string | undefined;
       includeArchived?: boolean | undefined;
       limit?: number | undefined;
+      cursor?: string | undefined;
     }
   ) {
     const params = new URLSearchParams();
@@ -273,6 +283,7 @@ export class TaigaClient {
     // The route reads the literal strings 'true' and 'false'.
     if (opts?.includeArchived) params.set('includeArchived', 'true');
     if (opts?.limit) params.set('limit', String(opts.limit));
+    if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>(
       'GET',
@@ -288,10 +299,14 @@ export class TaigaClient {
   // Build runs
   // ---------------------------------------------------------------------------
 
-  async listBuildRuns(productId: string, opts?: { backlogItemId?: string | undefined; limit?: number | undefined }) {
+  async listBuildRuns(
+    productId: string,
+    opts?: { backlogItemId?: string | undefined; limit?: number | undefined; cursor?: string | undefined }
+  ) {
     const params = new URLSearchParams();
     if (opts?.backlogItemId) params.set('backlogItemId', opts.backlogItemId);
     if (opts?.limit) params.set('limit', String(opts.limit));
+    if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>(
       'GET',
@@ -315,9 +330,10 @@ export class TaigaClient {
     return this.request<{ data: unknown }>('GET', `/factories/${seg(id)}`);
   }
 
-  async listFactories(opts?: { limit?: number | undefined }) {
+  async listFactories(opts?: { limit?: number | undefined; cursor?: string | undefined }) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set('limit', String(opts.limit));
+    if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>('GET', `/factories${qs ? `?${qs}` : ''}`);
   }

package/src/server.integration.test.ts

@@ -29,6 +29,7 @@ const ALL_TOOL_NAMES = [
   'taiga_get_document',
   'taiga_get_factory_document',
   'taiga_get_product',
+  'taiga_get_product_context',
   'taiga_get_product_document',
   'taiga_list_backlog_items',
   'taiga_list_builds',
@@ -317,6 +318,7 @@ describe('MCP server integration', () => {
       'products:read': [
         'taiga_list_products',
         'taiga_get_product',
+        'taiga_get_product_context',
         'taiga_resolve_product',
         'taiga_list_product_documents',
         'taiga_get_product_document',
@@ -367,7 +369,7 @@ describe('MCP server integration', () => {
       const result = await client.callTool({ name: 'taiga_list_factories', arguments: {} });
 
       expect(result.content).toHaveLength(1);
-      expect(parseToolResult(result)).toEqual(factories);
+      expect(parseToolResult(result)).toEqual({ data: factories, nextCursor: null });
     });
 
     it('should list company documents as summaries without content or authorship', async () => {
@@ -386,7 +388,7 @@ describe('MCP server integration', () => {
 
       const result = await client.callTool({ name: 'taiga_list_documents', arguments: {} });
 
-      expect(parseToolResult(result)).toEqual([
+      expect(parseToolResult(result).data).toEqual([
         {
           type: 'policy_security',
           name: 'Security Policy',
@@ -665,7 +667,8 @@ describe('MCP server integration', () => {
             text: async () => '',
           };
         }
-        throw new TypeError('fetch failed');
+        // What undici throws: a TypeError whose cause is the socket error.
+        throw new TypeError('fetch failed', { cause: new Error('ECONNREFUSED') });
       });
       vi.stubGlobal('fetch', fetchSpy);
       const taigaClient = new TaigaClient({ baseUrl: 'https://api.test.com', apiKey: 'taiga_sk_live_test' });
@@ -679,7 +682,10 @@ describe('MCP server integration', () => {
       const result = await client.callTool({ name: 'taiga_list_factories', arguments: {} });
 
       expect(result.isError).toBe(true);
-      expect(parseToolResult(result)).toMatchObject({ error: 'NETWORK_ERROR' });
+      expect(parseToolResult(result)).toMatchObject({
+        error: 'NETWORK_ERROR',
+        message: expect.stringContaining('fetch failed (ECONNREFUSED)'),
+      });
     });
 
     it('should edit the instructions section of factory instructions by default', async () => {
@@ -754,7 +760,7 @@ describe('MCP server integration', () => {
 
       const result = await client.callTool({ name: 'taiga_list_factories', arguments: {} });
 
-      expect(parseToolResult(result)).toEqual(factories);
+      expect(parseToolResult(result)).toEqual({ data: factories, nextCursor: null });
     });
   });
 
@@ -945,7 +951,7 @@ describe('MCP server integration', () => {
 
       const result = await client.callTool({ name: 'taiga_list_products', arguments: {} });
 
-      expect(parseToolResult(result)).toEqual([productSummary]);
+      expect(parseToolResult(result)).toEqual({ data: [productSummary], nextCursor: null });
     });
 
     it('should return one product in full', async () => {
@@ -970,7 +976,7 @@ describe('MCP server integration', () => {
         arguments: { productId: PRODUCT_ID, status: 'in_progress', category: 'feature', includeArchived: true },
       });
 
-      const [row] = parseToolResult(result);
+      const [row] = parseToolResult(result).data;
       expect(row).toMatchObject({ id: ITEM_ID, title: 'Add login', state: 'build', planningStatus: 'planned' });
       expect(row).not.toHaveProperty('description');
       expect(row).not.toHaveProperty('acceptanceCriteria');
@@ -1002,7 +1008,7 @@ describe('MCP server integration', () => {
         arguments: { productId: PRODUCT_ID, backlogItemId: ITEM_ID },
       });
 
-      const [row] = parseToolResult(result);
+      const [row] = parseToolResult(result).data;
       expect(row).toMatchObject({
         id: BUILD_ID,
         runNumber: 2,
@@ -1658,7 +1664,7 @@ describe('MCP server integration', () => {
       expect(result.isError).toBe(true);
       expect(parseToolResult(result)).toMatchObject({
         error: 'VALIDATION_FAILED',
-        message: expect.stringContaining('not both'),
+        message: expect.stringContaining('exactly once'),
       });
       expect(fetchSpy.mock.calls.length).toBe(before);
     });
@@ -1675,6 +1681,439 @@ describe('MCP server integration', () => {
     });
   });
 
+  // -------------------------------------------------------------------------
+  // The composite (PRO-2572): one call, every part on its own footing.
+  // -------------------------------------------------------------------------
+
+  describe('product context', () => {
+    const product = {
+      id: PRODUCT_ID,
+      name: 'Web',
+      slug: 'web',
+      status: 'active',
+      factoryId: FACTORY_ID,
+      kind: 'application',
+      settings: { autoMerge: true },
+    };
+    const factory = { id: FACTORY_ID, name: 'Platform', slug: 'platform', isDefault: true };
+    const instructions = {
+      id: 'fd-1',
+      type: 'factory_instructions',
+      version: 2,
+      isDraft: false,
+      data: {
+        sections: {
+          instructions: { content: 'Use pnpm. Ship behind flags.' },
+          deploys: { content: '  Deploy on Tuesdays.  ' },
+          empty: { content: '   ' },
+        },
+      },
+    };
+    const spec = {
+      id: 'doc-spec',
+      type: 'specification',
+      version: 3,
+      isDraft: false,
+      origin: 'plan',
+      derivedFrom: { sources: [] },
+      data: { sections: { vision: { content: 'A web app', derivedFrom: ['x'] } } },
+    };
+    const policy = policyDocument();
+    const draftPolicy = policyDocument({ type: 'policy_ops', isDraft: true, version: null });
+    const item = {
+      id: ITEM_ID,
+      title: 'Add login',
+      status: 'in_progress',
+      state: 'build',
+      archivedAt: null,
+      description: 'long',
+    };
+    const settled = { ...item, id: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a60', title: 'Old', status: 'done' };
+    const repo = {
+      id: 'r1',
+      provider: 'github',
+      repositoryName: 'acme/web',
+      repositoryUrl: 'https://github.com/acme/web',
+      effectiveBranch: 'main',
+      isManaged: false,
+      languages: { TypeScript: 1 },
+    };
+    const run = { id: BUILD_ID, runNumber: 1, status: 'completed', metrics: { tokens: 1 }, targetTitle: 'Add login' };
+    const allRoutes = {
+      [`GET /v1/products/${PRODUCT_ID}`]: { data: product },
+      [`GET /v1/factories/${FACTORY_ID}`]: { data: factory },
+      [`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions`]: { data: instructions },
+      [`GET /v1/products/${PRODUCT_ID}/documents/specification?origin=plan`]: { data: spec },
+      'GET /v1/tenants/current/documents': { data: [policy, draftPolicy], nextCursor: null },
+      [`GET /v1/products/${PRODUCT_ID}/backlog?status=backlog&limit=100`]: { data: [], nextCursor: null },
+      // `settled` could not come back from a status=in_progress read; it is here
+      // so the client-side check is seen to hold whatever the API returns.
+      [`GET /v1/products/${PRODUCT_ID}/backlog?status=in_progress&limit=100`]: {
+        data: [item, settled],
+        nextCursor: null,
+      },
+      [`GET /v1/products/${PRODUCT_ID}/repositories`]: { data: [repo], nextCursor: null },
+      [`GET /v1/products/${PRODUCT_ID}/builds?limit=10`]: { data: [run], nextCursor: null },
+    };
+
+    it('should assemble every part in one call and name the one document that is not published', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+
+      const result = await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } });
+
+      expect(result.isError).toBeFalsy();
+      const bundle = parseToolResult(result);
+      expect(bundle.product).toEqual({
+        id: PRODUCT_ID,
+        name: 'Web',
+        slug: 'web',
+        status: 'active',
+        factoryId: FACTORY_ID,
+        kind: 'application',
+        projectType: 'greenfield',
+        defaultOrigin: 'plan',
+      });
+      expect(bundle.factory).toEqual({
+        id: FACTORY_ID,
+        name: 'Platform',
+        slug: 'platform',
+        instructions: 'Use pnpm. Ship behind flags.\n\nDeploy on Tuesdays.',
+        instructionsVersion: 2,
+      });
+      expect(bundle.documents.origin).toBe('plan');
+      expect(bundle.documents.specification.data.sections.vision).toEqual({ content: 'A web app' });
+      expect(bundle.documents.specification).not.toHaveProperty('derivedFrom');
+      expect(bundle.documents.architecture).toBeNull();
+      expect(bundle.documents.notes).toEqual([
+        'No published plan architecture; taiga_list_product_documents shows what the product has.',
+      ]);
+      expect(bundle.policies).toEqual([
+        { type: 'policy_security', name: 'Security Policy', version: 3, sections: ['summary', 'scope'] },
+      ]);
+      expect(bundle.backlog.items.map((row: { id: string }) => row.id)).toEqual([ITEM_ID]);
+      expect(bundle.backlog.items[0]).not.toHaveProperty('description');
+      expect(bundle.backlog.truncated).toBe(false);
+      expect(bundle.repositories).toEqual({
+        items: [
+          {
+            id: 'r1',
+            provider: 'github',
+            repositoryName: 'acme/web',
+            repositoryUrl: 'https://github.com/acme/web',
+            effectiveBranch: 'main',
+            isManaged: false,
+          },
+        ],
+        truncated: false,
+      });
+      expect(bundle.builds).toEqual([{ id: BUILD_ID, runNumber: 1, status: 'completed', targetTitle: 'Add login' }]);
+      expect(bundle.notGranted).toEqual([]);
+      expect(bundle.unavailable).toEqual({});
+    });
+
+    it('should name the parts the key cannot read instead of showing them empty', async () => {
+      const { client } = await bootMcpPair({ capabilities: ['products:read'], routes: allRoutes });
+
+      const bundle = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(bundle.notGranted).toEqual([
+        'factory (needs factories:read)',
+        'policies (needs tenant:documents:read)',
+        'backlog (needs backlog:read)',
+      ]);
+      expect(bundle).not.toHaveProperty('factory');
+      expect(bundle).not.toHaveProperty('policies');
+      expect(bundle.repositories.items).toHaveLength(1);
+    });
+
+    it('should name a part the API failed, with what it said, and keep the rest', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        if (!new URL(url).pathname.endsWith('/backlog')) return router(url, init);
+        const body = { error: 'Too Many Requests', code: 'RATE_LIMITED', message: 'Slow down' };
+        return { ok: false, status: 429, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+
+      const bundle = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(bundle.unavailable).toEqual({ backlog: '429 RATE_LIMITED: Slow down' });
+      expect(bundle).not.toHaveProperty('backlog');
+      expect(bundle.builds).toHaveLength(1);
+    });
+
+    it('should read every backlog page, since the open items are the newest and the list is oldest first', async () => {
+      const newest = { ...item, id: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a62', title: 'Newest' };
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        const parsed = new URL(url);
+        if (!parsed.pathname.endsWith('/backlog')) return router(url, init);
+        const status = parsed.searchParams.get('status');
+        const body =
+          status === 'backlog'
+            ? { data: [], nextCursor: null }
+            : parsed.searchParams.get('cursor') === null
+              ? { data: [item], nextCursor: 'page-2' }
+              : { data: [newest], nextCursor: null };
+        return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+
+      const bundle = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(bundle.backlog.items.map((row: { title: string }) => row.title)).toEqual(['Add login', 'Newest']);
+    });
+
+    it('should list an item once when it moved between the two status reads', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        if (!new URL(url).pathname.endsWith('/backlog')) return router(url, init);
+        // The same item answers both status reads.
+        const body = { data: [item], nextCursor: null };
+        return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+
+      const bundle = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(bundle.backlog.items).toHaveLength(1);
+      expect(bundle.backlog.truncated).toBe(false);
+      const statuses = fetchSpy.mock.calls
+        .map((c: unknown[]) => new URL(c[0] as string))
+        .filter((u: URL) => u.pathname.endsWith('/backlog'))
+        .map((u: URL) => u.searchParams.get('status'));
+      expect(new Set(statuses)).toEqual(new Set(['backlog', 'in_progress']));
+    });
+
+    it('should stop after ten backlog pages and say the open list is truncated', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      let served = 0;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        if (!new URL(url).pathname.endsWith('/backlog')) return router(url, init);
+        // A distinct item per page, so the id-keyed set is not what caps the count.
+        served += 1;
+        const body = {
+          data: [{ ...item, id: `0199a1b2-c3d4-7e5f-8a9b-${String(served).padStart(12, '0')}` }],
+          nextCursor: 'more',
+        };
+        return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+
+      const bundle = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      );
+
+      // Ten pages per open status, two statuses.
+      expect(bundle.backlog.items).toHaveLength(20);
+      expect(bundle.backlog.truncated).toBe(true);
+    });
+
+    it('should carry the two documents as section ids only when asked for a small bundle', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+
+      const bundle = parseToolResult(
+        await client.callTool({
+          name: 'taiga_get_product_context',
+          arguments: { productId: PRODUCT_ID, fullDocuments: false },
+        })
+      );
+
+      expect(bundle.documents.specification).toEqual({ version: 3, sections: ['vision'] });
+      expect(bundle.documents.architecture).toBeNull();
+    });
+
+    it('should note a document that is not made of sections in a small bundle', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          ...allRoutes,
+          [`GET /v1/products/${PRODUCT_ID}/documents/specification?origin=plan`]: {
+            data: { ...spec, data: { legacy: 'free text' } },
+          },
+        },
+      });
+
+      const bundle = parseToolResult(
+        await client.callTool({
+          name: 'taiga_get_product_context',
+          arguments: { productId: PRODUCT_ID, fullDocuments: false },
+        })
+      );
+
+      expect(bundle.documents.specification).toEqual({ version: 3, sections: null });
+      expect(bundle.documents.notes).toEqual(
+        expect.arrayContaining([expect.stringContaining('taiga_get_product_document')])
+      );
+    });
+
+    it('should say when the published instructions are not made of sections', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          ...allRoutes,
+          [`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions`]: {
+            data: { ...instructions, data: { legacy: 'free text' } },
+          },
+        },
+      });
+
+      const bundle = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(bundle.factory).toMatchObject({
+        instructions: null,
+        instructionsVersion: 2,
+        note: expect.stringContaining('taiga_get_factory_document'),
+      });
+    });
+
+    it("should say when the repository list is cut at the route's one page", async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { ...allRoutes, [`GET /v1/products/${PRODUCT_ID}/repositories`]: { data: [repo], nextCursor: 'more' } },
+      });
+
+      const bundle = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(bundle.repositories.truncated).toBe(true);
+    });
+
+    it('should say when the factory has no instructions rather than fail the part', async () => {
+      const routes: Record<string, unknown> = { ...allRoutes };
+      delete routes[`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions`];
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes });
+
+      const bundle = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(bundle.factory).toMatchObject({
+        instructions: null,
+        note: 'This factory has not published instructions yet.',
+      });
+    });
+
+    it('should take the remote URL of a checkout and refuse an ambiguous one', async () => {
+      const second = { ...product, id: ITEM_ID, name: 'Web Admin' };
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { ...allRoutes, 'GET /v1/products': { data: [product], nextCursor: null } },
+      });
+
+      const one = await client.callTool({
+        name: 'taiga_get_product_context',
+        arguments: { remoteUrl: 'git@github.com:acme/web.git' },
+      });
+      expect(parseToolResult(one).product.id).toBe(PRODUCT_ID);
+
+      const { client: other } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { ...allRoutes, 'GET /v1/products': { data: [product, second], nextCursor: null } },
+      });
+      const two = await other.callTool({
+        name: 'taiga_get_product_context',
+        arguments: { remoteUrl: 'git@github.com:acme/web.git' },
+      });
+      expect(two.isError).toBe(true);
+      expect(parseToolResult(two)).toMatchObject({ error: 'AMBIGUOUS', message: expect.stringContaining('Web Admin') });
+    });
+
+    it('should take a slug, and say NOT_FOUND for one nobody visible has', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          ...allRoutes,
+          'GET /v1/products?slug=web&limit=1': { data: [product], nextCursor: null },
+          'GET /v1/products?slug=nope&limit=1': { data: [], nextCursor: null },
+        },
+      });
+
+      const hit = await client.callTool({ name: 'taiga_get_product_context', arguments: { slug: 'web' } });
+      const miss = await client.callTool({ name: 'taiga_get_product_context', arguments: { slug: 'nope' } });
+
+      expect(parseToolResult(hit).product.id).toBe(PRODUCT_ID);
+      expect(miss.isError).toBe(true);
+      expect(parseToolResult(miss)).toMatchObject({ error: 'NOT_FOUND', message: expect.stringContaining('"nope"') });
+    });
+
+    it('should let a bug in a part fail the call rather than blame the network', async () => {
+      // A TypeError with no cause is our code, not undici: it must surface.
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        if (!new URL(url).pathname.endsWith('/repositories')) return router(url, init);
+        throw new TypeError('bug');
+      });
+
+      // The SDK turns a thrown error into an error result carrying its
+      // message; what matters is that it is not dressed up as NETWORK_ERROR.
+      const result = await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } });
+
+      expect(result.isError).toBe(true);
+      const text = (result.content as { text: string }[])[0]!.text;
+      expect(text).toContain('bug');
+      expect(text).not.toContain('NETWORK_ERROR');
+    });
+
+    it('should refuse two names for the product at once, and none', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+      const before = fetchSpy.mock.calls.length;
+
+      for (const args of [{}, { productId: PRODUCT_ID, slug: 'web' }]) {
+        const result = await client.callTool({ name: 'taiga_get_product_context', arguments: args });
+        expect(result.isError).toBe(true);
+        expect(parseToolResult(result).error).toBe('VALIDATION_FAILED');
+      }
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Pagination (PRO-2565): every list tool pages, and says where the next
+  // page starts.
+  // -------------------------------------------------------------------------
+
+  describe('pagination', () => {
+    it.each([
+      ['taiga_list_factories', {}, '/v1/factories', ['factories:read']],
+      ['taiga_list_products', {}, '/v1/products', ['products:read']],
+      ['taiga_list_documents', {}, '/v1/tenants/current/documents', ['tenant:documents:read']],
+      [
+        'taiga_list_factory_documents',
+        { factoryId: FACTORY_ID },
+        `/v1/factories/${FACTORY_ID}/documents`,
+        ['factories:read'],
+      ],
+      ['taiga_list_backlog_items', { productId: PRODUCT_ID }, `/v1/products/${PRODUCT_ID}/backlog`, ['backlog:read']],
+      ['taiga_list_builds', { productId: PRODUCT_ID }, `/v1/products/${PRODUCT_ID}/builds`, ['products:read']],
+    ] as const)('%s passes the cursor on and returns where the next page starts', async (name, args, path, caps) => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: [...caps],
+        routes: { [path]: { data: [], nextCursor: 'page-3' } },
+      });
+
+      const result = await client.callTool({ name, arguments: { ...args, cursor: 'page-2', limit: 5 } });
+
+      expect(result.isError).toBeFalsy();
+      expect(parseToolResult(result)).toEqual({ data: [], nextCursor: 'page-3' });
+      const url = sentUrl(fetchSpy, path);
+      expect(url.searchParams.get('cursor')).toBe('page-2');
+      expect(url.searchParams.get('limit')).toBe('5');
+    });
+  });
+
   describe('error handling', () => {
     it('should surface API errors as structured MCP error content', async () => {
       // Introspect succeeds, but all other endpoints fail

package/src/tools/backlogs.ts

@@ -2,11 +2,12 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
 import { READ_ONLY } from './annotations.js';
+import { pagination, productId } from './inputs.js';
 import { runTool, toolResult } from './errors.js';
-import { pickFields } from './summarize.js';
+import { page, pickFields } from './summarize.js';
 
 /** What a list row needs to say for the model to pick an item to read in full. */
-const BACKLOG_SUMMARY_FIELDS = [
+export const BACKLOG_SUMMARY_FIELDS = [
   'id',
   'title',
   'category',
@@ -35,10 +36,7 @@ export function registerBacklogTools(server: McpServer, client: TaigaClient) {
         'read its acceptance criteria and technical context with taiga_get_backlog_item. ' +
         'Archived items are left out unless asked for.',
       inputSchema: {
-        productId: z
-          .string()
-          .uuid()
-          .describe('Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products'),
+        productId,
         status: z
           .enum(['backlog', 'in_progress', 'done', 'canceled'])
           .optional()
@@ -49,14 +47,16 @@ export function registerBacklogTools(server: McpServer, client: TaigaClient) {
           .describe('Only items whose plan is in this state'),
         category: z.enum(['feature', 'bug', 'tech_debt', 'improvement']).optional().describe('Only this category'),
         includeArchived: z.boolean().optional().describe('Include archived items (default false)'),
-        limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
+        ...pagination,
       },
       annotations: READ_ONLY,
     },
     (params) =>
       runTool(async () => {
         const result = await client.listBacklogItems(params.productId, params);
-        return toolResult(pickFields(result.data as Record<string, unknown>[], BACKLOG_SUMMARY_FIELDS));
+        return toolResult(
+          page(pickFields(result.data as Record<string, unknown>[], BACKLOG_SUMMARY_FIELDS), result.nextCursor)
+        );
       })
   );