@taiga-ai/mcp-server 0.5.0-rc.389 → 0.6.0-dev.391

package/src/client.ts

@@ -137,12 +137,18 @@ export class TaigaClient {
   async listProducts(opts?: {
     factoryId?: string | undefined;
     status?: string | undefined;
+    repository?: string | undefined;
+    repositoryHost?: string | undefined;
     limit?: number | undefined;
+    cursor?: string | undefined;
   }) {
     const params = new URLSearchParams();
     if (opts?.factoryId) params.set('factoryId', opts.factoryId);
     if (opts?.status) params.set('status', opts.status);
+    if (opts?.repository) params.set('repository', opts.repository);
+    if (opts?.repositoryHost) params.set('repositoryHost', opts.repositoryHost);
     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', `/products${qs ? `?${qs}` : ''}`);
   }
@@ -242,83 +248,26 @@ export class TaigaClient {
   // Factory Documents
   // ---------------------------------------------------------------------------
 
-  /**
-   * Fetch the full context for a product in parallel: product metadata,
-   * its factory's instructions and the product documents.
-   * Returns a structured bundle optimized for coding agent consumption.
-   */
-  async getProductContext(productId: string): Promise<Record<string, unknown>> {
-    // First fetch the product to get its factory
-    const product = await this.request<{ data: Record<string, unknown> }>('GET', `/products/${seg(productId)}`);
-    const factoryId = product.data.factoryId as string | undefined;
-
-    // Fetch the document lists in parallel.
-    const [productDocs, factoryDocs] = await Promise.all([
-      this.listProductDocuments(productId, { limit: 20 }).catch(() => ({ data: [] })),
-      factoryId
-        ? this.listFactoryDocuments(factoryId, { limit: 20 }).catch(() => ({ data: [] }))
-        : Promise.resolve({ data: [] }),
-    ]);
-
-    // Fetch full content for key documents (in parallel)
-    const keyProductDocTypes = ['specification', 'architecture', 'technology_decisions'];
-    // The factory instructions document.
-    const keyFactoryDocTypes = ['factory_instructions'];
-
-    const docFetches: Promise<{ type: string; scope: string; data: unknown }>[] = [];
-
-    for (const docType of keyProductDocTypes) {
-      const exists = (productDocs.data as Record<string, unknown>[]).some((d) => d.type === docType && !d.isDraft);
-      if (exists) {
-        docFetches.push(
-          this.getProductDocument(productId, docType)
-            .then((r) => ({ type: docType, scope: 'product', data: r.data }))
-            .catch(() => ({ type: docType, scope: 'product', data: null }))
-        );
-      }
-    }
-
-    if (factoryId) {
-      for (const docType of keyFactoryDocTypes) {
-        const exists = (factoryDocs.data as Record<string, unknown>[]).some((d) => d.type === docType && !d.isDraft);
-        if (exists) {
-          docFetches.push(
-            this.getFactoryDocument(factoryId, docType)
-              .then((r) => ({ type: docType, scope: 'factory', data: r.data }))
-              .catch(() => ({ type: docType, scope: 'factory', data: null }))
-          );
-        }
-      }
-    }
-
-    const fetchedDocs = await Promise.all(docFetches);
-    const summarize = (docs: Record<string, unknown>[]) =>
-      docs.map((d) => ({ type: d.type, name: d.name, version: d.version, isDraft: d.isDraft }));
-
-    // Assemble context bundle
-    return {
-      product: product.data,
-      documents: {
-        product: Object.fromEntries(
-          fetchedDocs.filter((d) => d.scope === 'product' && d.data).map((d) => [d.type, d.data])
-        ),
-        factory: Object.fromEntries(
-          fetchedDocs.filter((d) => d.scope === 'factory' && d.data).map((d) => [d.type, d.data])
-        ),
-      },
-      available_documents: {
-        product: summarize(productDocs.data as Record<string, unknown>[]),
-        factory: summarize(factoryDocs.data as Record<string, unknown>[]),
-      },
-    };
-  }
-
   // ---------------------------------------------------------------------------
   // Backlog
   // ---------------------------------------------------------------------------
 
-  async listBacklogItems(productId: string, opts?: { limit?: number | undefined }) {
+  async listBacklogItems(
+    productId: string,
+    opts?: {
+      status?: string | undefined;
+      planningStatus?: string | undefined;
+      category?: string | undefined;
+      includeArchived?: boolean | undefined;
+      limit?: number | undefined;
+    }
+  ) {
     const params = new URLSearchParams();
+    if (opts?.status) params.set('status', opts.status);
+    if (opts?.planningStatus) params.set('planningStatus', opts.planningStatus);
+    if (opts?.category) params.set('category', opts.category);
+    // 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));
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>(
@@ -332,11 +281,26 @@ export class TaigaClient {
   }
 
   // ---------------------------------------------------------------------------
-  // Environments
+  // Build runs
   // ---------------------------------------------------------------------------
 
-  async listEnvironments(productId: string) {
-    return this.request<{ data: unknown[] }>('GET', `/products/${seg(productId)}/environments`);
+  async listBuildRuns(productId: string, opts?: { backlogItemId?: string | undefined; limit?: number | undefined }) {
+    const params = new URLSearchParams();
+    if (opts?.backlogItemId) params.set('backlogItemId', opts.backlogItemId);
+    if (opts?.limit) params.set('limit', String(opts.limit));
+    const qs = params.toString();
+    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+      'GET',
+      `/products/${seg(productId)}/builds${qs ? `?${qs}` : ''}`
+    );
+  }
+
+  async getBuildRun(id: string) {
+    return this.request<{ data: unknown }>('GET', `/builds/${seg(id)}`);
+  }
+
+  async listBuildRunSteps(id: string) {
+    return this.request<{ data: unknown[] }>('GET', `/builds/${seg(id)}/steps`);
   }
 
   // ---------------------------------------------------------------------------

package/src/index.ts

@@ -48,9 +48,13 @@ async function main() {
         "Specification (what to build), architecture (how it's designed), threat model (security risks),",
         'technology decisions, and data flow. Read these to understand the specific product.',
         '',
-        'Workflow: Start with taiga_list_factories to find your factory, then read its instructions.',
-        'For product-specific work, use taiga_list_products to find the product,',
-        'then read its specification and architecture.',
+        '**Backlog and runs** (taiga_list_backlog_items / taiga_get_backlog_item / taiga_list_builds / taiga_get_build):',
+        "The product's initiatives with their acceptance criteria, and what Taiga's coding agent already built",
+        'for them: runs, steps, commits and pull requests.',
+        '',
+        'Workflow: Inside a git checkout, start with taiga_resolve_product on the remote URL to find the product.',
+        'Otherwise use taiga_list_factories and taiga_list_products. Then read the factory instructions,',
+        "the product's specification and architecture, and the backlog item you are working on.",
         '',
         'When you notice a policy or factory instructions are outdated, fix the section with',
         'taiga_update_document or taiga_update_factory_document. That saves a draft nobody follows yet;',

package/src/server.integration.test.ts

@@ -24,9 +24,14 @@ const ALL_CAPABILITIES = [
  * sorted for deterministic comparison.
  */
 const ALL_TOOL_NAMES = [
+  'taiga_get_backlog_item',
+  'taiga_get_build',
   'taiga_get_document',
   'taiga_get_factory_document',
+  'taiga_get_product',
   'taiga_get_product_document',
+  'taiga_list_backlog_items',
+  'taiga_list_builds',
   'taiga_list_documents',
   'taiga_list_factories',
   'taiga_list_factory_documents',
@@ -34,10 +39,23 @@ const ALL_TOOL_NAMES = [
   'taiga_list_products',
   'taiga_publish_document',
   'taiga_publish_factory_document',
+  'taiga_resolve_product',
   'taiga_update_document',
   'taiga_update_factory_document',
 ];
 
+const PRODUCT_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c';
+const PRODUCT_ID_2 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5f';
+const ITEM_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d';
+const BUILD_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e';
+
+/** The URL the fetch mock received for the one request whose path contains `pathPart`. */
+function sentUrl(fetchSpy: ReturnType<typeof vi.fn>, pathPart: string) {
+  const call = fetchSpy.mock.calls.find((c: unknown[]) => (c[0] as string).includes(pathPart));
+  expect(call, `${pathPart} was not requested`).toBeDefined();
+  return new URL(call![0] as string);
+}
+
 const FACTORY_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b';
 
 /** A policy as the API returns it: sections carry metadata beside their text. */
@@ -296,7 +314,16 @@ describe('MCP server integration', () => {
 
   describe('capability-tool contract', () => {
     const CONTRACT: Record<string, string[]> = {
-      'products:read': ['taiga_list_products', 'taiga_list_product_documents', 'taiga_get_product_document'],
+      'products:read': [
+        'taiga_list_products',
+        'taiga_get_product',
+        'taiga_resolve_product',
+        'taiga_list_product_documents',
+        'taiga_get_product_document',
+        'taiga_list_builds',
+        'taiga_get_build',
+      ],
+      'backlog:read': ['taiga_list_backlog_items', 'taiga_get_backlog_item'],
       'factories:read': ['taiga_list_factories', 'taiga_list_factory_documents', 'taiga_get_factory_document'],
       'tenant:documents:read': ['taiga_list_documents', 'taiga_get_document'],
     };
@@ -720,6 +747,299 @@ describe('MCP server integration', () => {
   // clear error, not a silent success or cryptic crash.
   // -------------------------------------------------------------------------
 
+  // -------------------------------------------------------------------------
+  // Developer-in-a-checkout tools (PRO-2564): resolve the product from the
+  // remote, then read its backlog and the coding agent's runs.
+  // -------------------------------------------------------------------------
+
+  describe('backlog and build reads', () => {
+    const product = { id: PRODUCT_ID, name: 'Web', slug: 'web', factoryId: FACTORY_ID, settings: { big: true } };
+    const productSummary = { id: PRODUCT_ID, name: 'Web', slug: 'web', factoryId: FACTORY_ID };
+    const item = {
+      id: ITEM_ID,
+      productId: PRODUCT_ID,
+      title: 'Add login',
+      description: 'A long description the list must not carry',
+      category: 'feature',
+      status: 'in_progress',
+      state: 'build',
+      planningStatus: 'planned',
+      priority: 1,
+      estimate: 3,
+      origin: 'user',
+      needsHumanCause: null,
+      acceptanceCriteria: [{ criterion: 'Users can log in', met: false }],
+      technicalContext: { patterns: ['hexagonal'], constraints: [], references: [] },
+    };
+    const run = {
+      id: BUILD_ID,
+      runNumber: 2,
+      backlogItemId: ITEM_ID,
+      status: 'completed',
+      failedReason: null,
+      branch: 'taiga/add-login',
+      prUrl: 'https://github.com/acme/web/pull/7',
+      prState: 'open',
+      completedSteps: 3,
+      totalSteps: 3,
+      targetTitle: 'Add login',
+      error: 'a long agent error the list must not carry',
+      metrics: { tokens: 12345 },
+      hardeningResult: { findings: [] },
+    };
+    const step = { id: 'step-1', runId: BUILD_ID, stepOrder: 1, title: 'Add the route', status: 'completed' };
+
+    it('should resolve the product from a git remote through the repository filter', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { '/v1/products': { data: [product], nextCursor: null } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_resolve_product',
+        arguments: { remoteUrl: 'git@github.com:Acme/Web.git' },
+      });
+
+      expect(result.isError).toBeFalsy();
+      expect(parseToolResult(result)).toEqual({
+        repository: 'Acme/Web',
+        host: 'https://github.com',
+        products: [productSummary],
+        truncated: false,
+      });
+      const url = sentUrl(fetchSpy, '/v1/products');
+      expect(url.searchParams.get('repository')).toBe('Acme/Web');
+      expect(url.searchParams.get('repositoryHost')).toBe('https://github.com');
+      expect(url.searchParams.get('limit')).toBe('100');
+    });
+
+    /**
+     * The fetch router keys on the path, so product pages are served here by
+     * cursor instead; every other path still goes to the router.
+     */
+    function serveProductPages(fetchSpy: ReturnType<typeof vi.fn>, page: (cursor: string | null) => unknown) {
+      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 !== '/v1/products') return router(url, init);
+        const body = page(parsed.searchParams.get('cursor'));
+        return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+    }
+
+    const productPageCursors = (fetchSpy: ReturnType<typeof vi.fn>) =>
+      fetchSpy.mock.calls
+        .map((c: unknown[]) => new URL(c[0] as string))
+        .filter((u: URL) => u.pathname === '/v1/products')
+        .map((u: URL) => u.searchParams.get('cursor'));
+
+    it('should follow the pages of a shared repository rather than stop at the first', async () => {
+      const second = { ...product, id: PRODUCT_ID_2, name: 'Web Admin' };
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      serveProductPages(fetchSpy, (cursor) =>
+        cursor === null ? { data: [product], nextCursor: 'page-2' } : { data: [second], nextCursor: null }
+      );
+
+      const result = await client.callTool({
+        name: 'taiga_resolve_product',
+        arguments: { remoteUrl: 'git@github.com:acme/web.git' },
+      });
+
+      const parsed = parseToolResult(result);
+      expect(parsed.products.map((p: { id: string }) => p.id)).toEqual([PRODUCT_ID, PRODUCT_ID_2]);
+      expect(parsed.truncated).toBe(false);
+      expect(productPageCursors(fetchSpy)).toEqual([null, 'page-2']);
+    });
+
+    it('should stop after ten pages and say the list is truncated', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      serveProductPages(fetchSpy, () => ({ data: [product], nextCursor: 'more' }));
+
+      const result = await client.callTool({
+        name: 'taiga_resolve_product',
+        arguments: { remoteUrl: 'git@github.com:acme/web.git' },
+      });
+
+      const parsed = parseToolResult(result);
+      expect(parsed.products).toHaveLength(10);
+      expect(parsed.truncated).toBe(true);
+      expect(productPageCursors(fetchSpy)).toHaveLength(10);
+    });
+
+    it('should fail the whole resolution when a later page fails, not hand back a partial list', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      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 !== '/v1/products') return router(url, init);
+        if (parsed.searchParams.get('cursor') === null) {
+          const body = { data: [product], nextCursor: 'page-2' };
+          return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+        }
+        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 result = await client.callTool({
+        name: 'taiga_resolve_product',
+        arguments: { remoteUrl: 'git@github.com:acme/web.git' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toEqual({ error: 'RATE_LIMITED', message: 'Slow down' });
+    });
+
+    it('should say NOT_FOUND when no visible product is linked to the remote', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { '/v1/products': { data: [], nextCursor: null } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_resolve_product',
+        arguments: { remoteUrl: 'https://github.com/acme/web.git' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toMatchObject({
+        error: 'NOT_FOUND',
+        message: expect.stringContaining('acme/web'),
+      });
+    });
+
+    it('should refuse a remote it cannot read before any request is made', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      const before = fetchSpy.mock.calls.length;
+
+      const result = await client.callTool({
+        name: 'taiga_resolve_product',
+        arguments: { remoteUrl: '/Users/dev/web' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).error).toBe('INVALID_REMOTE');
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it('should list products as summaries now that taiga_get_product carries the rest', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { '/v1/products': { data: [product], nextCursor: null } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_products', arguments: {} });
+
+      expect(parseToolResult(result)).toEqual([productSummary]);
+    });
+
+    it('should return one product in full', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`/v1/products/${PRODUCT_ID}`]: { data: product } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_product', arguments: { productId: PRODUCT_ID } });
+
+      expect(parseToolResult(result)).toEqual(product);
+    });
+
+    it('should list backlog items as summaries and pass the filters through', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/products/${PRODUCT_ID}/backlog`]: { data: [item], nextCursor: null } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_list_backlog_items',
+        arguments: { productId: PRODUCT_ID, status: 'in_progress', category: 'feature', includeArchived: true },
+      });
+
+      const [row] = parseToolResult(result);
+      expect(row).toMatchObject({ id: ITEM_ID, title: 'Add login', state: 'build', planningStatus: 'planned' });
+      expect(row).not.toHaveProperty('description');
+      expect(row).not.toHaveProperty('acceptanceCriteria');
+      const url = sentUrl(fetchSpy, '/backlog');
+      expect(url.searchParams.get('status')).toBe('in_progress');
+      expect(url.searchParams.get('category')).toBe('feature');
+      expect(url.searchParams.get('includeArchived')).toBe('true');
+    });
+
+    it('should return a backlog item in full, acceptance criteria included', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: { data: item } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_backlog_item', arguments: { itemId: ITEM_ID } });
+
+      expect(parseToolResult(result)).toEqual(item);
+    });
+
+    it('should list runs as summaries, filtered to one backlog item', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`/v1/products/${PRODUCT_ID}/builds`]: { data: [run], nextCursor: null } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_list_builds',
+        arguments: { productId: PRODUCT_ID, backlogItemId: ITEM_ID },
+      });
+
+      const [row] = parseToolResult(result);
+      expect(row).toMatchObject({
+        id: BUILD_ID,
+        runNumber: 2,
+        status: 'completed',
+        prUrl: run.prUrl,
+        targetTitle: 'Add login',
+      });
+      expect(row).not.toHaveProperty('error');
+      expect(row).not.toHaveProperty('metrics');
+      expect(row).not.toHaveProperty('hardeningResult');
+      expect(sentUrl(fetchSpy, '/builds').searchParams.get('backlogItemId')).toBe(ITEM_ID);
+    });
+
+    it('should return a run with its steps from two routes', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/builds/${BUILD_ID}`]: { data: run },
+          [`/v1/builds/${BUILD_ID}/steps`]: { data: [step] },
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_build', arguments: { buildId: BUILD_ID } });
+
+      expect(result.isError).toBeFalsy();
+      expect(parseToolResult(result)).toEqual({ ...run, steps: [step] });
+    });
+
+    it('should refuse a fractional limit before any request, as the API would after one', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['backlog:read', 'products:read'] });
+      const before = fetchSpy.mock.calls.length;
+
+      for (const [name, args] of [
+        ['taiga_list_backlog_items', { productId: PRODUCT_ID, limit: 2.5 }],
+        ['taiga_list_builds', { productId: PRODUCT_ID, limit: 2.5 }],
+        ['taiga_list_products', { limit: 2.5 }],
+      ] as const) {
+        const result = await client.callTool({ name, arguments: { ...args } });
+        expect(result.isError, name).toBe(true);
+      }
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it('should not expose backlog reads to a products:read-only key', async () => {
+      const { client } = await bootMcpPair({ capabilities: ['products:read'] });
+
+      const names = toolNames((await client.listTools()).tools);
+
+      expect(names).toContain('taiga_list_builds');
+      expect(names).not.toContain('taiga_list_backlog_items');
+    });
+  });
+
   describe('error handling', () => {
     it('should surface API errors as structured MCP error content', async () => {
       // Introspect succeeds, but all other endpoints fail

package/src/tools/annotations.ts

@@ -0,0 +1,10 @@
+/**
+ * Tool annotations shared by every read tool. Hints for the client, not a
+ * control: the API enforces what a key may do.
+ */
+export const READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;

package/src/tools/backlogs.ts

@@ -1,10 +1,82 @@
-// Backlog tools are reserved for post-beta.
-// The beta MCP server focuses on the knowledge base (policies, factory instructions).
-
 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 { runTool, toolResult } from './errors.js';
+import { 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 = [
+  'id',
+  'title',
+  'category',
+  'status',
+  'state',
+  'planningStatus',
+  'priority',
+  'estimate',
+  'origin',
+  'needsHumanCause',
+  'archivedAt',
+  'createdAt',
+  'updatedAt',
+] as const;
+
+export function registerBacklogTools(server: McpServer, client: TaigaClient) {
+  if (!client.hasCapability('backlog:read')) return;
+
+  server.registerTool(
+    'taiga_list_backlog_items',
+    {
+      title: 'List backlog items',
+      description:
+        "List a product's backlog items (initiatives): titles, category, status and where each one is on the " +
+        'line (backlog, todo, queue, plan, build, done). Use this to find the item you are working on, then ' +
+        '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'),
+        status: z
+          .enum(['backlog', 'in_progress', 'done', 'canceled'])
+          .optional()
+          .describe('Only items with this status; in_progress covers everything between backlog and done'),
+        planningStatus: z
+          .enum(['unplanned', 'planning', 'planned', 'failed'])
+          .optional()
+          .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)'),
+      },
+      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));
+      })
+  );
 
-export function registerBacklogTools(_server: McpServer, _client: TaigaClient) {
-  // No backlog tools in beta -- will be added when the MCP server
-  // expands beyond the knowledge base use case.
+  server.registerTool(
+    'taiga_get_backlog_item',
+    {
+      title: 'Get backlog item',
+      description:
+        'Get one backlog item in full: description, acceptance criteria (and which are met), technical ' +
+        'context (patterns, constraints, references), dependencies and source documents. Read this before ' +
+        'implementing an item, and read its runs with taiga_list_builds to see what the coding agent already did.',
+      inputSchema: {
+        itemId: z.string().uuid().describe('Backlog item ID -- get from taiga_list_backlog_items'),
+      },
+      annotations: READ_ONLY,
+    },
+    (params) =>
+      runTool(async () => {
+        const result = await client.getBacklogItem(params.itemId);
+        return toolResult(result.data);
+      })
+  );
 }