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

package/src/tools/products.ts

@@ -1,7 +1,9 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { TaigaApiError, type TaigaClient } from '../client.js';
 import { READ_ONLY } from './annotations.js';
+import { pagination, productId, remoteUrl, slug } from './inputs.js';
 import {
   ORIGIN_MEANING,
   PRODUCT_DOCUMENT_ORIGINS,
@@ -17,10 +19,10 @@ import {
 import { runTool, toolError, toolResult } from './errors.js';
 import { parseRemote } from './remote.js';
 import { stripProvenance } from './sections.js';
-import { pickFields } from './summarize.js';
+import { page, pickFields } from './summarize.js';
 
 /** What a product row needs to say for the model to pick one and read it in full. */
-const PRODUCT_SUMMARY_FIELDS = ['id', 'name', 'slug', 'status', 'factoryId', 'kind', 'discoveryStep'] as const;
+export const PRODUCT_SUMMARY_FIELDS = ['id', 'name', 'slug', 'status', 'factoryId', 'kind', 'discoveryStep'] as const;
 
 /**
  * What a document row needs to say for the model to pick one and read it in
@@ -48,11 +50,6 @@ const PAGE_SIZE = 100;
  */
 const RESOLVE_PAGE_LIMIT = 10;
 
-const productId = z
-  .string()
-  .uuid()
-  .describe('Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products');
-
 const originInput = z
   .enum(PRODUCT_DOCUMENT_ORIGINS)
   .optional()
@@ -64,8 +61,9 @@ const originInput = z
 
 /**
  * Every product linked to the repository, page by page, until the API runs
- * out or the cap is hit. A page that fails fails the call, like every other
- * tool: a partial list marked truncated would read as a complete one.
+ * out or the cap is hit, in which case the list says it is truncated. A page
+ * that FAILS is different: it fails the call, like every other tool, rather
+ * than being folded into a truncated list that would read as a complete one.
  */
 async function linkedProducts(client: TaigaClient, repository: string, repositoryHost: string) {
   const products: Record<string, unknown>[] = [];
@@ -201,6 +199,75 @@ function describeMiss(
   return parts.join(' ');
 }
 
+/**
+ * One product from whichever name the caller has: its ID, its slug (through
+ * the list's slug filter) or the git remote of a checkout (through the
+ * repository filter). Exactly one of the three; a remote linked to several
+ * products is ambiguous and says so.
+ */
+export async function resolveProductRef(
+  client: TaigaClient,
+  ref: { productId?: string | undefined; slug?: string | undefined; remoteUrl?: string | undefined },
+  /** The names the calling tool accepts, for the message when none or several were given. */
+  accepted: readonly string[]
+): Promise<{ product: Record<string, unknown> } | { error: CallToolResult }> {
+  const given = [ref.productId, ref.slug, ref.remoteUrl].filter((v) => v !== undefined).length;
+  if (given !== 1) {
+    return {
+      error: toolError(
+        'VALIDATION_FAILED',
+        `Name the product exactly once: ${accepted.join(' or ')}. Two names could mean two products.`
+      ),
+    };
+  }
+  if (ref.productId) return { product: (await client.getProduct(ref.productId)).data as Record<string, unknown> };
+  if (ref.slug) {
+    const [product] = (await client.listProducts({ slug: ref.slug, limit: 1 })).data as Record<string, unknown>[];
+    if (!product) {
+      return {
+        error: toolError(
+          'NOT_FOUND',
+          `No product you can see has the slug "${ref.slug}". taiga_list_products shows the ones you can.`
+        ),
+      };
+    }
+    return { product };
+  }
+  const remote = parseRemote(ref.remoteUrl!);
+  if (!remote) {
+    return {
+      error: toolError(
+        'INVALID_REMOTE',
+        `"${ref.remoteUrl}" is not a remote of the form host/owner/repo. Pass the URL git remote get-url origin prints.`
+      ),
+    };
+  }
+  // `truncated` is dropped on purpose: past the cap the answer is AMBIGUOUS anyway.
+  const { products } = await linkedProducts(client, remote.repository, remote.host);
+  if (products.length === 0) {
+    return {
+      error: toolError(
+        'NOT_FOUND',
+        `No product you can see is linked to ${remote.repository} on ${remote.host}. ` +
+          'Link the repository to its product in Taiga, or find the product with taiga_list_products.'
+      ),
+    };
+  }
+  if (products.length > 1) {
+    const names = pickFields(products, PRODUCT_SUMMARY_FIELDS)
+      .map((p) => `${String(p.name)} (${String(p.id)})`)
+      .join(', ');
+    return {
+      error: toolError(
+        'AMBIGUOUS',
+        `${remote.repository} is linked to several products: ${names}. Call again with the productId of the one you mean.`
+      ),
+    };
+  }
+  // The list route returns full product rows, the same shape the single read does.
+  return { product: products[0]! };
+}
+
 export function registerProductTools(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('factories:read')) {
     server.registerTool(
@@ -213,14 +280,14 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           "Factory instructions carry the factory's standing guidance: domain context, tech preferences, " +
           'and the conventions its products follow.',
         inputSchema: {
-          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.listFactories(params);
-          return toolResult(result.data);
+          return toolResult(page(result.data, result.nextCursor));
         })
     );
   }
@@ -247,14 +314,16 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
               'Filter by status: draft until the product finishes setup in Taiga, active after that, ' +
                 'archived when retired.'
             ),
-          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.listProducts(params);
-          return toolResult(pickFields(result.data as Record<string, unknown>[], PRODUCT_SUMMARY_FIELDS));
+          return toolResult(
+            page(pickFields(result.data as Record<string, unknown>[], PRODUCT_SUMMARY_FIELDS), result.nextCursor)
+          );
         })
     );
 
@@ -269,31 +338,14 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           'taiga_list_backlog_items for its work and taiga_list_builds for what the coding agent did.',
         inputSchema: {
           productId: productId.optional(),
-          slug: z
-            .string()
-            .max(63)
-            .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'A slug is lowercase words joined by hyphens')
-            .optional()
-            .describe('Product slug, as it appears in Taiga URLs -- an alternative to productId'),
+          slug: slug.optional(),
         },
         annotations: READ_ONLY,
       },
       (params) =>
         runTool(async () => {
-          if (params.productId && params.slug) {
-            return toolError('VALIDATION_FAILED', 'Pass productId or slug, not both: they could name two products.');
-          }
-          if (params.productId) return toolResult((await client.getProduct(params.productId)).data);
-          if (!params.slug) return toolError('VALIDATION_FAILED', 'Pass productId or slug.');
-          const result = await client.listProducts({ slug: params.slug, limit: 1 });
-          const [product] = result.data;
-          if (!product) {
-            return toolError(
-              'NOT_FOUND',
-              `No product you can see has the slug "${params.slug}". taiga_list_products shows the ones you can.`
-            );
-          }
-          return toolResult(product);
+          const resolved = await resolveProductRef(client, params, ['productId', 'slug']);
+          return 'error' in resolved ? resolved.error : toolResult(resolved.product);
         })
     );
 
@@ -303,16 +355,12 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
         title: 'Resolve product from git remote',
         description:
           'Find the Taiga product a git checkout belongs to from its remote URL (the output of ' +
-          '`git remote get-url origin`). Call this first when working inside a repository, then use the ' +
-          'product ID with every other tool. Returns every product the repository is linked to (several ' +
+          '`git remote get-url origin`). taiga_get_product_context takes the same URL and returns the whole ' +
+          'context at once; use this when you only need the ID. Returns every product the repository is linked to (several ' +
           `when the organization shares repositories; \`truncated\` is true past ${PAGE_SIZE * RESOLVE_PAGE_LIMIT}); ` +
           'NOT_FOUND means nobody linked it, or the key cannot see the product.',
         inputSchema: {
-          remoteUrl: z
-            .string()
-            .min(1)
-            .max(2048)
-            .describe('The remote URL: https://github.com/owner/repo.git, git@github.com:owner/repo.git or ssh://...'),
+          remoteUrl,
         },
         annotations: READ_ONLY,
       },

package/src/tools/sections.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { applySectionEdit, sectionContent, sectionsOf, stripProvenance } from './sections.js';
+import { applySectionEdit, instructionsText, sectionContent, sectionsOf, stripProvenance } from './sections.js';
 
 describe('sectionsOf', () => {
   it('returns the sections map of a section-shaped document', () => {
@@ -57,6 +57,23 @@ describe('applySectionEdit', () => {
   });
 });
 
+describe('instructionsText', () => {
+  it('joins every non-empty object section and skips bare strings, as the API extractor does', () => {
+    expect(
+      instructionsText({
+        instructions: { content: ' Use pnpm. ' },
+        legacy: 'bare text the agents never receive',
+        empty: { content: '   ' },
+        deploys: { content: 'Deploy on Tuesdays.' },
+      })
+    ).toBe('Use pnpm.\n\nDeploy on Tuesdays.');
+  });
+
+  it('is null when nothing is readable', () => {
+    expect(instructionsText({ empty: { content: '' }, legacy: 'x' })).toBeNull();
+  });
+});
+
 describe('stripProvenance', () => {
   it('drops the derived-from tree and outdated sources at the top and in every section', () => {
     const doc = {

package/src/tools/sections.ts

@@ -58,3 +58,20 @@ export function stripProvenance(doc: Record<string, unknown>): Record<string, un
   );
   return { ...rest, data: { ...rest.data, sections: stripped } };
 }
+
+/**
+ * The free-form text of an instructions document, the way the API hands it
+ * to the agents (factory-instructions.ts: every non-empty section, in order,
+ * joined by a blank line). Null when there is nothing to read.
+ */
+export function instructionsText(sections: Sections): string | null {
+  const parts: string[] = [];
+  for (const section of Object.values(sections)) {
+    // Object sections only, as the API's extractor reads them: a bare-string
+    // row the agents never receive is not handed to the model here either.
+    const content = isRecord(section) ? section.content : undefined;
+    if (typeof content === 'string' && content.trim()) parts.push(content.trim());
+  }
+  const text = parts.join('\n\n').trim();
+  return text || null;
+}

package/src/tools/summarize.ts

@@ -15,3 +15,8 @@ export function pickFields<T extends Record<string, unknown>>(
     return picked;
   });
 }
+
+/** The page a list tool returns: the rows the model asked for and where the next page starts. */
+export function page<T>(data: T[], nextCursor: string | null | undefined): { data: T[]; nextCursor: string | null } {
+  return { data, nextCursor: nextCursor ?? null };
+}