@taiga-ai/mcp-server 0.6.0-rc.393 → 0.7.0-dev.395

package/src/tools/products.ts

@@ -1,15 +1,43 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import type { TaigaClient } from '../client.js';
+import { TaigaApiError, type TaigaClient } from '../client.js';
 import { READ_ONLY } from './annotations.js';
+import {
+  ORIGIN_MEANING,
+  PRODUCT_DOCUMENT_ORIGINS,
+  PRODUCT_DOCUMENT_TYPES,
+  PRODUCT_STATUSES,
+  defaultOriginFor,
+  emptyOriginNote,
+  isImportedProduct,
+  productDocumentName,
+  type ProductDocumentOrigin,
+  type ProductSettingsView,
+} from './catalogue.js';
 import { runTool, toolError, toolResult } from './errors.js';
-import { documentType } from './inputs.js';
 import { parseRemote } from './remote.js';
-import { pickFields, summarizeList } from './summarize.js';
+import { stripProvenance } from './sections.js';
+import { 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;
 
+/**
+ * What a document row needs to say for the model to pick one and read it in
+ * full: which document, on which timeline, how current. Not the derived-from
+ * tree, the data key count or the reviewer's name.
+ */
+const DOCUMENT_SUMMARY_FIELDS = [
+  'type',
+  'origin',
+  'version',
+  'isDraft',
+  'hasDraft',
+  'stage',
+  'reviewedAt',
+  'updatedAt',
+] as const;
+
 /** The API's page ceiling (paginationSchema in apps/api). */
 const PAGE_SIZE = 100;
 
@@ -20,6 +48,20 @@ 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()
+  .describe(
+    `Which timeline. ${ORIGIN_MEANING.plan} ${ORIGIN_MEANING.reality} ` +
+      "Omit it to read the product's own timeline: reality for an imported product, plan for every other, " +
+      'and always plan for the documents a person writes (Look & Feel, Product Instructions).'
+  );
+
 /**
  * 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
@@ -37,6 +79,128 @@ async function linkedProducts(client: TaigaClient, repository: string, repositor
   return { products, truncated: true };
 }
 
+/** A document list row as the model sees it: the summary fields plus a display name and the staleness fact. */
+function documentSummaries(rows: unknown[]): Record<string, unknown>[] {
+  const typed = rows as Record<string, unknown>[];
+  return pickFields(typed, DOCUMENT_SUMMARY_FIELDS).map((picked, index) => {
+    // `outdated` on the wire is the list of sources that moved on; the model
+    // needs the fact, not the tree. Published plan rows carry it: null when
+    // current, a source list when not. A draft has nothing published to be
+    // outdated (the API stamps it null too) and reality rows carry no such
+    // field: no fact for either.
+    const outdated = typed[index]!.outdated as { sources?: unknown[] } | null | undefined;
+    const fact =
+      picked.isDraft !== false
+        ? undefined
+        : outdated === null
+          ? false
+          : Array.isArray(outdated?.sources)
+            ? outdated.sources.length > 0
+            : undefined;
+    return {
+      type: picked.type,
+      name: productDocumentName(String(picked.type)),
+      ...picked,
+      ...(fact === undefined ? {} : { outdated: fact }),
+    };
+  });
+}
+
+interface Timelines {
+  projectType: 'greenfield' | 'brownfield';
+  defaultOrigin: ProductDocumentOrigin;
+  /** The side's summaries, or null when the API could not list it (see `unlistable`). */
+  plan: Record<string, unknown>[] | null;
+  reality: Record<string, unknown>[] | null;
+  /** Why a null side is null, in the words the notes and a miss message use. */
+  unlistable: Partial<Record<ProductDocumentOrigin, string>>;
+  notes: string[];
+}
+
+/** The one sentence for a side the API would not list, with what it said. */
+function unlistableNote(origin: ProductDocumentOrigin, reason: unknown): string {
+  const said = reason instanceof TaigaApiError ? `${reason.status} ${reason.code ?? ''}`.trim() : 'the request failed';
+  return `The ${origin} side could not be listed (${said}).`;
+}
+
+/**
+ * Both timelines of a product's documents, each a list of summaries, with
+ * which one is the product's own and a note for an empty side. The product
+ * decides what an empty side means (imported or not, how far its import got),
+ * so a caller that already holds it passes it in.
+ */
+async function documentTimelines(client: TaigaClient, id: string, product?: ProductSettingsView): Promise<Timelines> {
+  const loaded = product ?? ((await client.getProduct(id)).data as ProductSettingsView);
+  // Each side on its own: one side the API cannot list is reported as
+  // unreadable, not as empty, and never hides the side that did answer.
+  // Both failing is the API failing, and that is an error like any other.
+  const settled = await Promise.allSettled(
+    PRODUCT_DOCUMENT_ORIGINS.map((o) => client.listProductDocuments(id, { origin: o, limit: PAGE_SIZE }))
+  );
+  if (settled.every((result) => result.status === 'rejected')) throw settled[0]!.reason;
+  const sides: Partial<Record<ProductDocumentOrigin, Record<string, unknown>[] | null>> = {};
+  const unlistable: Partial<Record<ProductDocumentOrigin, string>> = {};
+  PRODUCT_DOCUMENT_ORIGINS.forEach((o, index) => {
+    const result = settled[index]!;
+    if (result.status === 'fulfilled') sides[o] = documentSummaries(result.value.data);
+    else {
+      sides[o] = null;
+      unlistable[o] = unlistableNote(o, result.reason);
+    }
+  });
+  const notes = PRODUCT_DOCUMENT_ORIGINS.flatMap((o) => {
+    const side = sides[o];
+    if (!side) return [unlistable[o]!];
+    return side.length === 0 ? [emptyOriginNote(o, loaded)] : [];
+  });
+  return {
+    projectType: isImportedProduct(loaded) ? 'brownfield' : 'greenfield',
+    defaultOrigin: defaultOriginFor(loaded),
+    plan: sides.plan ?? null,
+    reality: sides.reality ?? null,
+    unlistable,
+    notes,
+  };
+}
+
+const isPublished = (row: Record<string, unknown>) => row.isDraft === false;
+
+/** `specification (v2), architecture (draft)` for one side. */
+function sideList(rows: Record<string, unknown>[]): string {
+  return rows
+    .map((row) => `${String(row.type)} (${isPublished(row) ? `v${String(row.version)}` : 'draft'})`)
+    .join(', ');
+}
+
+/** What a missed document read should say: where the type does live, and what each side holds. */
+function describeMiss(
+  type: string,
+  wanted: ProductDocumentOrigin,
+  timelines: Timelines,
+  product: ProductSettingsView
+): string {
+  const name = productDocumentName(type);
+  const other: ProductDocumentOrigin = wanted === 'plan' ? 'reality' : 'plan';
+  const parts = [`No published ${wanted} ${name} (${type}) for this product.`];
+  const rows = (side: ProductDocumentOrigin) => timelines[side] ?? [];
+  if (rows(other).some((row) => row.type === type && isPublished(row))) {
+    parts.push(`It is published on the ${other} side: call again with origin '${other}'.`);
+  } else {
+    for (const side of [wanted, other]) {
+      if (rows(side).some((row) => row.type === type && !isPublished(row))) {
+        parts.push(`A draft of it exists on the ${side} side, unpublished.`);
+      }
+    }
+  }
+  for (const o of PRODUCT_DOCUMENT_ORIGINS) {
+    const side = timelines[o];
+    const label = `${o[0]!.toUpperCase()}${o.slice(1)} documents`;
+    if (side === null) parts.push(timelines.unlistable[o]!);
+    else parts.push(side.length > 0 ? `${label}: ${sideList(side)}.` : emptyOriginNote(o, product));
+  }
+  return parts.join(' ');
+}
+
 export function registerProductTools(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('factories:read')) {
     server.registerTool(
@@ -67,9 +231,9 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       {
         title: 'List products',
         description:
-          'List products in the organization. Use this to find a product by name; inside a git checkout, ' +
-          'taiga_resolve_product finds it from the remote URL instead. ' +
-          'Can filter by factory; a status filter also exists but no longer distinguishes anything (see its description).',
+          'List products in the organization, as summaries (id, name, slug, status, factory, kind). ' +
+          'Use this to find a product by name; inside a git checkout, taiga_resolve_product finds it from ' +
+          'the remote URL instead. taiga_get_product reads one in full.',
         inputSchema: {
           factoryId: z
             .string()
@@ -77,12 +241,11 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
             .optional()
             .describe('Filter by factory ID -- get factory IDs from taiga_list_factories'),
           status: z
-            .enum(['draft', 'active', 'archived'])
+            .enum(PRODUCT_STATUSES)
             .optional()
             .describe(
-              'Filter by status. Taiga no longer surfaces product status in its UI (PRO-543), so every ' +
-                'product is currently "draft" and filtering by "active" or "archived" returns nothing. ' +
-                'Omit this unless you are working with data set through the API directly.'
+              '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)'),
         },
@@ -100,21 +263,37 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       {
         title: 'Get product',
         description:
-          'Get one product in full: name, slug, factory, what Taiga owns for it (application, infrastructure, ' +
-          'deployment) and its settings; the list and resolve tools carry summaries. Use taiga_list_product_documents for its specification and design, ' +
+          'Get one product in full, by ID or by slug: name, slug, factory, what Taiga owns for it ' +
+          '(application, infrastructure, deployment) and its settings; the list and resolve tools carry ' +
+          'summaries. Use taiga_list_product_documents for its specification and design, ' +
           'taiga_list_backlog_items for its work and taiga_list_builds for what the coding agent did.',
         inputSchema: {
-          productId: z
+          productId: productId.optional(),
+          slug: z
             .string()
-            .uuid()
-            .describe('Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products'),
+            .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'),
         },
         annotations: READ_ONLY,
       },
       (params) =>
         runTool(async () => {
-          const result = await client.getProduct(params.productId);
-          return toolResult(result.data);
+          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);
         })
     );
 
@@ -168,22 +347,20 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       {
         title: 'List product documents',
         description:
-          'List documents for a specific product (names and types only). ' +
-          'Product documents are generated during intake: specification (requirements), ' +
-          'architecture (system design), technology decisions, data flow, privacy assessment, ' +
-          'threat model (security risks), risk register, user flow, and service blueprint. ' +
-          'Use taiga_get_product_document to read the full content.',
-        inputSchema: {
-          productId: z.string().uuid().describe('Product ID -- get from taiga_list_products'),
-          limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
-        },
+          "List a product's documents on both timelines, as summaries (type, name, version, draft state, " +
+          "review and update times), and say which timeline is the product's own (defaultOrigin). " +
+          `Two timelines: ${ORIGIN_MEANING.plan} ${ORIGIN_MEANING.reality} ` +
+          'An empty side comes with a note saying why; a side the API could not list is null, with a note. ' +
+          'Use taiga_get_product_document with the type and origin to read one in full.',
+        inputSchema: { productId },
         annotations: READ_ONLY,
       },
       (params) =>
         runTool(async () => {
-          const result = await client.listProductDocuments(params.productId, { limit: params.limit });
-          const summaries = summarizeList(result.data as Record<string, unknown>[]);
-          return toolResult(summaries);
+          // `unlistable` is how a miss message is built; the list says the
+          // same in its notes and a null side.
+          const { unlistable: _unlistable, ...timelines } = await documentTimelines(client, params.productId);
+          return toolResult(timelines);
         })
     );
 
@@ -192,26 +369,40 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       {
         title: 'Get product document',
         description:
-          'Get the full content of a specific product document. ' +
-          'Use this when you need to understand what to build (specification), ' +
-          'how the system is designed (architecture), what security risks exist (threat model), ' +
-          'or what technology choices were made (technology_decisions). ' +
-          'Types: specification, architecture, technology_decisions, data_flow, ' +
-          'privacy_assessment, threat_model, risk_register, user_flow, service_blueprint, ' +
-          "ui_direction, codebase_snapshot, and product_instructions (the product's standing instructions).",
+          'Get the full content of one product document from one timeline. ' +
+          'Read the plan to learn what to build: specification (requirements), architecture (design), ' +
+          'threat_model (security risks), technology_decisions. Read reality, when the product has it, to ' +
+          "learn what the code actually does before changing it. Omit origin for the product's own timeline. " +
+          'A read that finds nothing says which documents and timelines the product does have.',
         inputSchema: {
-          productId: z.string().uuid().describe('Product ID -- get from taiga_list_products'),
-          type: documentType.describe(
-            'Document type -- get available types from taiga_list_product_documents. ' +
-              'Common: specification, architecture, threat_model, technology_decisions'
-          ),
+          productId,
+          type: z
+            .enum(PRODUCT_DOCUMENT_TYPES)
+            .describe('Document type -- taiga_list_product_documents shows which ones the product has'),
+          origin: originInput,
         },
         annotations: READ_ONLY,
       },
       (params) =>
         runTool(async () => {
-          const result = await client.getProductDocument(params.productId, params.type);
-          return toolResult(result.data);
+          // The product's own timeline when none is asked for; the API's
+          // default is plan, which is the wrong side of an imported product.
+          let product: ProductSettingsView | undefined;
+          if (!params.origin) product = (await client.getProduct(params.productId)).data as ProductSettingsView;
+          const origin = params.origin ?? defaultOriginFor(product, params.type);
+          try {
+            const result = await client.getProductDocument(params.productId, params.type, origin);
+            return toolResult(stripProvenance(result.data as Record<string, unknown>));
+          } catch (error) {
+            if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
+            // A product the key cannot see is a product miss, not a document
+            // miss, so the product read propagates. The lists after it are
+            // best effort per side (documentTimelines); only both failing
+            // propagates, as the API failing.
+            product ??= (await client.getProduct(params.productId)).data as ProductSettingsView;
+            const timelines = await documentTimelines(client, params.productId, product);
+            return toolError('NOT_FOUND', describeMiss(params.type, origin, timelines, product));
+          }
         })
     );
   }

package/src/tools/sections.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { applySectionEdit, sectionContent, sectionsOf } from './sections.js';
+import { applySectionEdit, sectionContent, sectionsOf, stripProvenance } from './sections.js';
 
 describe('sectionsOf', () => {
   it('returns the sections map of a section-shaped document', () => {
@@ -56,3 +56,36 @@ describe('applySectionEdit', () => {
     expect(sections.summary.content).toBe('old');
   });
 });
+
+describe('stripProvenance', () => {
+  it('drops the derived-from tree and outdated sources at the top and in every section', () => {
+    const doc = {
+      id: 'd1',
+      type: 'policy_security',
+      derivedFrom: { sources: [{ type: 'business_goals', version: 2 }] },
+      outdated: { sources: [] },
+      data: {
+        version: '1.0.0',
+        sections: {
+          summary: { source: 'template', priority: 'core', content: 'x', derivedFrom: ['business_goals'] },
+          legacy: 'bare text',
+        },
+      },
+    };
+
+    expect(stripProvenance(doc)).toEqual({
+      id: 'd1',
+      type: 'policy_security',
+      data: {
+        version: '1.0.0',
+        sections: { summary: { source: 'template', priority: 'core', content: 'x' }, legacy: 'bare text' },
+      },
+    });
+  });
+
+  it('leaves a document that is not made of sections alone', () => {
+    const doc = { id: 'd2', type: 'ui_direction', data: { picks: { palette: 'ocean' } } };
+
+    expect(stripProvenance(doc)).toEqual(doc);
+  });
+});

package/src/tools/sections.ts

@@ -14,7 +14,7 @@
 /** A section as stored: an object with `content` and metadata, or (older rows) a bare string. */
 export type Sections = Record<string, unknown>;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
+export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
@@ -36,3 +36,25 @@ export function applySectionEdit(sections: Sections, sectionId: string, content:
   const prior = sections[sectionId];
   return { ...sections, [sectionId]: isRecord(prior) ? { ...prior, content } : { content } };
 }
+
+/**
+ * A document for reading, without its provenance: the top-level `derivedFrom`
+ * tree and `outdated` source list (PRO-2359), and each section's own
+ * `derivedFrom` (PRO-2158). They say which documents shaped this one, which
+ * the editor needs and a reader does not; `source` and `priority` stay, the
+ * server instructions explain them.
+ */
+export function stripProvenance(doc: Record<string, unknown>): Record<string, unknown> {
+  const { derivedFrom: _derivedFrom, outdated: _outdated, ...rest } = doc;
+  if (!isRecord(rest.data)) return rest;
+  const sections = sectionsOf(rest.data);
+  if (!sections) return rest;
+  const stripped = Object.fromEntries(
+    Object.entries(sections).map(([id, section]) => {
+      if (!isRecord(section)) return [id, section];
+      const { derivedFrom: _sectionDerivedFrom, ...keep } = section;
+      return [id, keep];
+    })
+  );
+  return { ...rest, data: { ...rest.data, sections: stripped } };
+}

package/src/tools/summarize.ts

@@ -1,38 +1,7 @@
 /**
- * Strip heavy content from list responses to avoid context window bloat.
- *
- * List endpoints return summaries (id, name, description, metadata).
- * Get endpoints return the full content.
- *
- * This keeps list calls cheap (~100 tokens per item) and lets the AI
- * selectively load full content only for the items it needs.
- */
-
-/** Fields to strip from list responses -- these contain the bulk content. */
-const HEAVY_FIELDS = ['content', 'data', 'sections'];
-
-/**
- * Remove heavy content fields from each item in an array.
- * Preserves all metadata (id, name, description, type, dates, etc).
- */
-export function summarizeList<T extends Record<string, unknown>>(
-  items: T[]
-): Omit<T, 'content' | 'data' | 'sections'>[] {
-  return items.map((item) => {
-    const summary = { ...item };
-    for (const field of HEAVY_FIELDS) {
-      if (field in summary) {
-        delete summary[field];
-      }
-    }
-    return summary;
-  });
-}
-
-/**
- * Keep only the named fields of each item. For lists whose rows carry prose
- * (a backlog item's description, a run's metrics) that `summarizeList`'s
- * fixed field names would not catch.
+ * Keep only the named fields of each item. List tools return summaries (the
+ * fields a model needs to pick an item) and get tools return everything;
+ * this is how a list drops the prose and the provenance trees.
  */
 export function pickFields<T extends Record<string, unknown>>(
   items: T[],

package/src/tools/inputs.test.ts

@@ -1,19 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { FACTORY_DOCUMENT_TYPES, PRODUCT_DOCUMENT_TYPES, TENANT_DOCUMENT_TYPES } from '@taiga/types';
-import { documentType } from './inputs.js';
-
-describe('documentType', () => {
-  it('accepts every document type the shared types package names', () => {
-    // The identifier shape is a wall against path-shaped input, not a copy of
-    // the enums; this is what keeps it from silently rejecting a real type.
-    for (const type of [...TENANT_DOCUMENT_TYPES, ...FACTORY_DOCUMENT_TYPES, ...PRODUCT_DOCUMENT_TYPES]) {
-      expect(documentType.safeParse(type).success, type).toBe(true);
-    }
-  });
-
-  it('rejects anything that could reach another route', () => {
-    for (const value of ['../x', 'a/b', '.', '..', '', 'policy security', 'Policy', 'a?x=1', 'a#b']) {
-      expect(documentType.safeParse(value).success, JSON.stringify(value)).toBe(false);
-    }
-  });
-});

package/src/tools/inputs.ts

@@ -1,13 +0,0 @@
-import { z } from 'zod';
-
-/**
- * A document type as the API names one: policy_security, factory_instructions,
- * specification. An identifier, never a path: the value is interpolated into
- * the route, and a type that carried a slash would reach a different
- * document's route than the tool's description promises. The API's own enum
- * stays the source of truth for which identifiers exist (it answers 400 with
- * the valid list); this only rules out what could not be a type at all.
- */
-export const documentType = z
-  .string()
-  .regex(/^[a-z][a-z0-9_]{0,63}$/, 'A document type is a lowercase identifier such as policy_security');