@taiga-ai/mcp-server 0.4.0 → 0.5.0-rc.389

package/src/server.integration.test.ts

@@ -13,6 +13,7 @@ import { registerAllTools } from './tools/index.js';
 const ALL_CAPABILITIES = [
   'products:read',
   'factories:read',
+  'factories:documents:write',
   'tenant:documents:read',
   'tenant:documents:write',
   'backlog:read',
@@ -31,10 +32,42 @@ const ALL_TOOL_NAMES = [
   'taiga_list_factory_documents',
   'taiga_list_product_documents',
   'taiga_list_products',
+  'taiga_publish_document',
+  'taiga_publish_factory_document',
   'taiga_update_document',
   'taiga_update_factory_document',
 ];
 
+const FACTORY_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b';
+
+/** A policy as the API returns it: sections carry metadata beside their text. */
+function policyDocument(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'doc-1',
+    type: 'policy_security',
+    name: 'Security Policy',
+    version: 3,
+    isDraft: false,
+    data: {
+      version: '1.0.0',
+      sections: {
+        summary: { source: 'template', priority: 'core', content: 'Old summary' },
+        scope: { source: 'template', priority: 'core', content: 'Applies to everything' },
+      },
+    },
+    ...overrides,
+  };
+}
+
+/** The JSON body the fetch mock received for the one request matching `method` and `pathPart`. */
+function sentBody(fetchSpy: ReturnType<typeof vi.fn>, method: string, pathPart: string) {
+  const call = fetchSpy.mock.calls.find(
+    (c: unknown[]) => (c[1] as RequestInit)?.method === method && (c[0] as string).includes(pathPart)
+  );
+  expect(call, `${method} ${pathPart} was not sent`).toBeDefined();
+  return JSON.parse((call![1] as RequestInit).body as string);
+}
+
 function makeFetchRouter(routes: Record<string, unknown>) {
   return vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
     const path = new URL(url).pathname;
@@ -50,11 +83,13 @@ function makeFetchRouter(routes: Record<string, unknown>) {
         text: () => Promise.resolve(JSON.stringify(body)),
       };
     }
+    // Same envelope as the API's own 404 (shared/middleware/error-handler.ts).
+    const notFound = { error: 'Not Found', code: 'NOT_FOUND', message: 'The requested resource does not exist' };
     return {
       ok: false,
       status: 404,
-      json: () => Promise.resolve({ error: 'Not found' }),
-      text: () => Promise.resolve('Not found'),
+      json: () => Promise.resolve(notFound),
+      text: () => Promise.resolve(JSON.stringify(notFound)),
     };
   });
 }
@@ -110,7 +145,7 @@ function toolNames(tools: { name: string }[]) {
 /** Extract parsed JSON from the first text content block of a tool call result. */
 function parseToolResult(result: Record<string, unknown>) {
   const content = result.content as { type: string; text: string }[];
-  return JSON.parse(content[0].text);
+  return JSON.parse(content[0]!.text);
 }
 
 // ---------------------------------------------------------------------------
@@ -170,6 +205,14 @@ describe('MCP server integration', () => {
       expect(names).not.toContain('taiga_update_document');
     });
 
+    it('should not expose company document writes to a write-only key', async () => {
+      // The edit reads the draft and the published version first, and those
+      // routes need tenant:documents:read.
+      const { client } = await bootMcpPair({ capabilities: ['tenant:documents:write'] });
+
+      await expect(client.listTools()).rejects.toThrow(/Method not found/);
+    });
+
     it('should expose write tools when documents:write is also granted', async () => {
       const { client } = await bootMcpPair({
         capabilities: ['tenant:documents:read', 'tenant:documents:write'],
@@ -181,18 +224,33 @@ describe('MCP server integration', () => {
       expect(names).toContain('taiga_update_document');
     });
 
-    it('should expose factory document write when both teams:read and documents:write are granted', async () => {
+    it('should expose factory document writes when factories:read and factories:documents:write are granted', async () => {
       const { client } = await bootMcpPair({
-        capabilities: ['factories:read', 'tenant:documents:write'],
+        capabilities: ['factories:read', 'factories:documents:write'],
       });
 
       const { tools } = await client.listTools();
       const names = toolNames(tools);
 
       expect(names).toContain('taiga_update_factory_document');
+      expect(names).toContain('taiga_publish_factory_document');
       expect(names).toContain('taiga_list_factories');
     });
 
+    it('should not let tenant:documents:write stand in for factories:documents:write', async () => {
+      // The API's factory document write routes require factories:documents:write;
+      // a tool registered on the company-policy capability would only 403.
+      const { client } = await bootMcpPair({
+        capabilities: ['factories:read', 'tenant:documents:write'],
+      });
+
+      const { tools } = await client.listTools();
+      const names = toolNames(tools);
+
+      expect(names).not.toContain('taiga_update_factory_document');
+      expect(names).not.toContain('taiga_publish_factory_document');
+    });
+
     it('should combine capabilities additively', async () => {
       const { client } = await bootMcpPair({
         capabilities: ['factories:read', 'tenant:documents:read'],
@@ -210,15 +268,22 @@ describe('MCP server integration', () => {
       expect(names).not.toContain('taiga_update_document');
     });
 
-    it('should provide a description and input schema for every tool', async () => {
+    it('should provide a title, description, annotations and input schema for every tool', async () => {
       const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
 
       const { tools } = await client.listTools();
 
       for (const tool of tools) {
+        expect(tool.title, `${tool.name} missing title`).toBeTruthy();
         expect(tool.description, `${tool.name} missing description`).toBeTruthy();
         expect(tool.inputSchema, `${tool.name} missing inputSchema`).toBeDefined();
         expect(tool.inputSchema.type).toBe('object');
+        expect(tool.annotations, `${tool.name} missing annotations`).toMatchObject({
+          readOnlyHint: expect.any(Boolean),
+          destructiveHint: expect.any(Boolean),
+          idempotentHint: expect.any(Boolean),
+          openWorldHint: expect.any(Boolean),
+        });
       }
     });
   });
@@ -234,12 +299,15 @@ describe('MCP server integration', () => {
       'products:read': ['taiga_list_products', 'taiga_list_product_documents', 'taiga_get_product_document'],
       'factories:read': ['taiga_list_factories', 'taiga_list_factory_documents', 'taiga_get_factory_document'],
       'tenant:documents:read': ['taiga_list_documents', 'taiga_get_document'],
-      'tenant:documents:write': ['taiga_update_document'],
+    };
+    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'],
     };
 
-    for (const [capability, expectedTools] of Object.entries(CONTRACT)) {
+    for (const [capability, expectedTools] of [...Object.entries(CONTRACT), ...Object.entries(PAIRED_CONTRACT)]) {
       it(`${capability} should gate: ${expectedTools.join(', ')}`, async () => {
-        const { client } = await bootMcpPair({ capabilities: [capability] });
+        const { client } = await bootMcpPair({ capabilities: capability.split(' ') });
 
         const { tools } = await client.listTools();
         const names = toolNames(tools);
@@ -288,45 +356,349 @@ describe('MCP server integration', () => {
       expect(parseToolResult(result)).toEqual(docs);
     });
 
-    it('should send PUT when updating a document draft', async () => {
-      const docType = 'security_policy';
-      const updated = { type: docType, title: 'Updated Policy' };
+    it('should replace one section of the existing draft and keep the rest', async () => {
+      const draft = policyDocument({ id: 'draft-1', version: null, isDraft: true });
+      const saved = policyDocument({ id: 'draft-1', version: null, isDraft: true });
+      (saved.data.sections as Record<string, { content: string }>).summary!.content = 'New summary';
 
       const { client, fetchSpy } = await bootMcpPair({
         capabilities: ALL_CAPABILITIES,
-        routes: { [`PUT /v1/tenants/current/documents/${docType}/draft`]: { data: updated } },
+        routes: {
+          'GET /v1/tenants/current/documents/policy_security/draft': { data: draft },
+          'PUT /v1/tenants/current/documents/policy_security/draft': { data: saved },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_update_document',
+        arguments: { type: 'policy_security', sectionId: 'summary', content: 'New summary' },
+      });
+
+      // The whole data payload goes back: the untouched section, the version
+      // field, and the edited section's metadata beside its new text.
+      expect(sentBody(fetchSpy, 'PUT', '/documents/policy_security/draft')).toEqual({
+        data: {
+          version: '1.0.0',
+          sections: {
+            summary: { source: 'template', priority: 'core', content: 'New summary' },
+            scope: { source: 'template', priority: 'core', content: 'Applies to everything' },
+          },
+        },
+      });
+      expect(result.isError).toBeFalsy();
+      expect(parseToolResult(result)).toMatchObject({
+        id: 'draft-1',
+        isDraft: true,
+        sections: ['summary', 'scope'],
+        section: { id: 'summary', content: 'New summary' },
+      });
+      expect(parseToolResult(result)).not.toHaveProperty('data');
+    });
+
+    it('should seed the edit from the published version when no draft exists', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          'GET /v1/tenants/current/documents/policy_security/draft': { data: null },
+          'GET /v1/tenants/current/documents/policy_security': { data: policyDocument() },
+          'PUT /v1/tenants/current/documents/policy_security/draft': { data: policyDocument({ isDraft: true }) },
+        },
       });
 
       await client.callTool({
         name: 'taiga_update_document',
-        arguments: { type: docType, data: { title: 'Updated' } },
+        arguments: { type: 'policy_security', sectionId: 'retention', content: 'Keep logs 90 days' },
+      });
+
+      const body = sentBody(fetchSpy, 'PUT', '/documents/policy_security/draft');
+      expect(body.data.sections.summary).toEqual({ source: 'template', priority: 'core', content: 'Old summary' });
+      expect(body.data.sections.retention).toEqual({ content: 'Keep logs 90 days' });
+    });
+
+    it('should start from an empty section map when nothing is drafted or published yet', async () => {
+      // Organization instructions begin empty and unpublished (PRO-502): the
+      // published GET is a 404, and the API seeds the draft on the first save.
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          'GET /v1/tenants/current/documents/tenant_instructions/draft': { data: null },
+          'PUT /v1/tenants/current/documents/tenant_instructions/draft': {
+            data: policyDocument({ type: 'tenant_instructions', isDraft: true }),
+          },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_update_document',
+        arguments: { type: 'tenant_instructions', sectionId: 'instructions', content: 'Prefer pnpm.' },
       });
 
-      const putCall = fetchSpy.mock.calls.find((c: unknown[]) => (c[1] as RequestInit)?.method === 'PUT');
-      expect(putCall).toBeDefined();
-      expect(putCall![0]).toContain(`/v1/tenants/current/documents/${docType}/draft`);
+      expect(result.isError).toBeFalsy();
+      expect(sentBody(fetchSpy, 'PUT', '/documents/tenant_instructions/draft')).toEqual({
+        data: { sections: { instructions: { content: 'Prefer pnpm.' } } },
+      });
     });
 
-    it('should send PUT when updating a factory document draft', async () => {
-      const factoryId = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b';
-      const docType = 'domain_context';
-      const updated = { type: docType, name: 'Domain Context' };
+    it('should refuse to section-edit a document that is not made of sections', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          'GET /v1/tenants/current/documents/brand_standards/draft': { data: null },
+          'GET /v1/tenants/current/documents/brand_standards': {
+            data: policyDocument({ type: 'brand_standards', data: { components: {} } }),
+          },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_update_document',
+        arguments: { type: 'brand_standards', sectionId: 'summary', content: 'x' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).error).toBe('UNSUPPORTED_DOCUMENT');
+      expect(fetchSpy.mock.calls.some((c: unknown[]) => (c[1] as RequestInit)?.method === 'PUT')).toBe(false);
+    });
 
+    it('should publish the draft and return the new version without its content', async () => {
       const { client, fetchSpy } = await bootMcpPair({
         capabilities: ALL_CAPABILITIES,
-        routes: { [`PUT /v1/factories/${factoryId}/documents/${docType}/draft`]: { data: updated } },
+        routes: {
+          'POST /v1/tenants/current/documents/policy_security/publish': { data: policyDocument({ version: 4 }) },
+        },
       });
 
-      await client.callTool({
+      const result = await client.callTool({ name: 'taiga_publish_document', arguments: { type: 'policy_security' } });
+
+      const post = fetchSpy.mock.calls.find((c: unknown[]) => (c[1] as RequestInit)?.method === 'POST');
+      expect(post).toBeDefined();
+      // Bodiless, and without a JSON content type: Fastify answers 400 to the pair.
+      expect((post![1] as RequestInit).body).toBeNull();
+      expect((post![1] as RequestInit).headers).not.toHaveProperty('Content-Type');
+      expect(result.isError).toBeFalsy();
+      expect(parseToolResult(result)).toMatchObject({ version: 4, isDraft: false, sections: ['summary', 'scope'] });
+      expect(parseToolResult(result)).not.toHaveProperty('data');
+    });
+
+    it('should pass the API refusal on when there is no draft to publish', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: {} });
+
+      const result = await client.callTool({ name: 'taiga_publish_document', arguments: { type: 'policy_security' } });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toEqual({ error: 'NOT_FOUND', message: 'The requested resource does not exist' });
+    });
+
+    it('should refuse a document type shaped like a path before any request is made', async () => {
+      // `type` is interpolated into the route; a traversal-shaped value would
+      // otherwise reach a product document's draft through the company tool.
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+      const traversal = `../../products/${FACTORY_ID}/documents/specification`;
+
+      const calls = [
+        client.callTool({
+          name: 'taiga_update_document',
+          arguments: { type: traversal, sectionId: 's', content: 'x' },
+        }),
+        client.callTool({ name: 'taiga_publish_document', arguments: { type: traversal } }),
+        client.callTool({ name: 'taiga_get_document', arguments: { type: traversal } }),
+        client.callTool({
+          name: 'taiga_update_factory_document',
+          arguments: { factoryId: FACTORY_ID, type: traversal, content: 'x' },
+        }),
+        client.callTool({
+          name: 'taiga_publish_factory_document',
+          arguments: { factoryId: FACTORY_ID, type: traversal },
+        }),
+        client.callTool({ name: 'taiga_get_factory_document', arguments: { factoryId: FACTORY_ID, type: traversal } }),
+        client.callTool({ name: 'taiga_get_product_document', arguments: { productId: FACTORY_ID, type: traversal } }),
+      ];
+      for (const result of await Promise.all(calls)) {
+        expect(result.isError).toBe(true);
+        // The refusal names the type input, not some other failure.
+        expect((result.content as { text: string }[])[0]!.text).toMatch(/type/);
+      }
+      expect(fetchSpy.mock.calls.filter((c: unknown[]) => !(c[0] as string).endsWith('/auth/introspect'))).toEqual([]);
+    });
+
+    it('should mark publishing destructive and the edit not', async () => {
+      // Publishing replaces the governing version with no unpublish; a host
+      // that confirms destructive tools must ask before it.
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+
+      const { tools } = await client.listTools();
+      const byName = Object.fromEntries(tools.map((t) => [t.name, t.annotations]));
+
+      expect(byName.taiga_publish_document).toMatchObject({ destructiveHint: true, idempotentHint: false });
+      expect(byName.taiga_publish_factory_document).toMatchObject({ destructiveHint: true, idempotentHint: false });
+      expect(byName.taiga_update_document).toMatchObject({ destructiveHint: false, idempotentHint: true });
+    });
+
+    it('should hand the model the API message when the publish gate refuses the draft', async () => {
+      const refusal = {
+        error: 'Bad Request',
+        code: 'VALIDATION_ERROR',
+        message: 'Draft contains template residue in section "scope": "Edit this table to reflect"',
+      };
+      const fetchSpy = vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
+        const path = new URL(url).pathname;
+        if (path === '/v1/auth/introspect') {
+          return {
+            ok: true,
+            status: 200,
+            json: async () => introspectionResponse(ALL_CAPABILITIES),
+            text: async () => '',
+          };
+        }
+        if (init?.method === 'POST') {
+          return { ok: false, status: 400, json: async () => refusal, text: async () => JSON.stringify(refusal) };
+        }
+        const draft = { data: policyDocument({ isDraft: true }) };
+        return { ok: true, status: 200, json: async () => draft, text: async () => JSON.stringify(draft) };
+      });
+      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 result = await client.callTool({ name: 'taiga_publish_document', arguments: { type: 'policy_security' } });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toEqual({ error: 'VALIDATION_ERROR', message: refusal.message });
+    });
+
+    it('should name the invalid field when route validation refuses the input', async () => {
+      const refusal = {
+        error: 'ValidationError',
+        code: 'VALIDATION_ERROR',
+        message: 'Request validation failed',
+        details: [{ instancePath: '/type', message: 'Invalid enum value' }],
+      };
+      const fetchSpy = vi.fn().mockImplementation(async (url: string) => {
+        const path = new URL(url).pathname;
+        if (path === '/v1/auth/introspect') {
+          return {
+            ok: true,
+            status: 200,
+            json: async () => introspectionResponse(ALL_CAPABILITIES),
+            text: async () => '',
+          };
+        }
+        return { ok: false, status: 400, json: async () => refusal, text: async () => JSON.stringify(refusal) };
+      });
+      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 result = await client.callTool({
+        name: 'taiga_update_document',
+        arguments: { type: 'policy_nope', sectionId: 'summary', content: 'x' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toEqual({
+        error: 'VALIDATION_ERROR',
+        message: 'Request validation failed: /type Invalid enum value',
+      });
+    });
+
+    it('should report an unreachable API as a structured error', async () => {
+      const fetchSpy = vi.fn().mockImplementation(async (url: string) => {
+        const path = new URL(url).pathname;
+        if (path === '/v1/auth/introspect') {
+          return {
+            ok: true,
+            status: 200,
+            json: async () => introspectionResponse(ALL_CAPABILITIES),
+            text: async () => '',
+          };
+        }
+        throw new TypeError('fetch failed');
+      });
+      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 result = await client.callTool({ name: 'taiga_list_factories', arguments: {} });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toMatchObject({ error: 'NETWORK_ERROR' });
+    });
+
+    it('should edit the instructions section of factory instructions by default', async () => {
+      const instructions = {
+        id: 'fd-1',
+        type: 'factory_instructions',
+        name: 'Factory Instructions',
+        version: 1,
+        isDraft: false,
+        data: { sections: { instructions: { content: 'Use pnpm.' } } },
+      };
+
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions/draft`]: { data: null },
+          [`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions`]: { data: instructions },
+          [`PUT /v1/factories/${FACTORY_ID}/documents/factory_instructions/draft`]: {
+            data: { ...instructions, isDraft: true },
+          },
+        },
+      });
+
+      const result = await client.callTool({
         name: 'taiga_update_factory_document',
-        arguments: { factoryId, type: docType, data: { sections: { overview: 'Updated' } } },
+        arguments: { factoryId: FACTORY_ID, type: 'factory_instructions', content: 'Use pnpm. Node 22.' },
+      });
+
+      expect(result.isError).toBeFalsy();
+      expect(sentBody(fetchSpy, 'PUT', `/factories/${FACTORY_ID}/documents/factory_instructions/draft`)).toEqual({
+        data: { sections: { instructions: { content: 'Use pnpm. Node 22.' } } },
+      });
+    });
+
+    it('should publish factory instructions through the factory publish route', async () => {
+      const published = {
+        id: 'fd-1',
+        type: 'factory_instructions',
+        name: 'Factory Instructions',
+        version: 2,
+        isDraft: false,
+        data: { sections: {} },
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions/draft`]: {
+            data: { ...published, isDraft: true },
+          },
+          [`POST /v1/factories/${FACTORY_ID}/documents/factory_instructions/publish`]: { data: published },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_publish_factory_document',
+        arguments: { factoryId: FACTORY_ID, type: 'factory_instructions' },
       });
 
-      const putCall = fetchSpy.mock.calls.find(
-        (c: unknown[]) => (c[1] as RequestInit)?.method === 'PUT' && (c[0] as string).includes('/factories/')
-      );
-      expect(putCall).toBeDefined();
-      expect(putCall![0]).toContain(`/v1/factories/${factoryId}/documents/${docType}/draft`);
+      expect(result.isError).toBeFalsy();
+      const post = fetchSpy.mock.calls.find((c: unknown[]) => (c[1] as RequestInit)?.method === 'POST');
+      expect(post![0]).toContain(`/v1/factories/${FACTORY_ID}/documents/factory_instructions/publish`);
+      expect(parseToolResult(result)).toMatchObject({ version: 2, isDraft: false });
     });
 
     it('should return factories through MCP protocol', async () => {
@@ -349,7 +721,7 @@ describe('MCP server integration', () => {
   // -------------------------------------------------------------------------
 
   describe('error handling', () => {
-    it('should surface API errors as MCP error content', async () => {
+    it('should surface API errors as structured MCP error content', async () => {
       // Introspect succeeds, but all other endpoints fail
       const fetchSpy = vi.fn().mockImplementation(async (url: string) => {
         const path = new URL(url).pathname;
@@ -382,8 +754,9 @@ describe('MCP server integration', () => {
       // Act
       const result = await mcpClient.callTool({ name: 'taiga_list_products', arguments: {} });
 
-      // Assert -- the MCP SDK marks tool errors with isError
+      // Assert -- a stable code the model can branch on, and the API's status
       expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toEqual({ error: 'API_ERROR', message: 'Taiga API answered 500.' });
     });
 
     it('should reject tool calls with invalid parameters', async () => {
@@ -392,10 +765,10 @@ describe('MCP server integration', () => {
         routes: {},
       });
 
-      // taiga_get_product requires a UUID, not a plain string
+      // productId must be a UUID, not a plain string
       const result = await client.callTool({
-        name: 'taiga_get_product',
-        arguments: { id: 'not-a-uuid' },
+        name: 'taiga_get_product_document',
+        arguments: { productId: 'not-a-uuid', type: 'specification' },
       });
 
       expect(result.isError).toBe(true);