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

package/src/tools/builds.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 a run to read in full. */
-const BUILD_SUMMARY_FIELDS = [
+export const BUILD_SUMMARY_FIELDS = [
   'id',
   'runNumber',
   'backlogItemId',
@@ -42,23 +43,22 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         'progress. Use this to see what Taiga already built or is building, then read one run with ' +
         'taiga_get_build. Filter by backlog item to follow a single initiative.',
       inputSchema: {
-        productId: z
-          .string()
-          .uuid()
-          .describe('Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products'),
+        productId,
         backlogItemId: z
           .string()
           .uuid()
           .optional()
           .describe("Only this backlog item's runs -- get from taiga_list_backlog_items"),
-        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.listBuildRuns(params.productId, params);
-        return toolResult(pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS));
+        return toolResult(
+          page(pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS), result.nextCursor)
+        );
       })
   );
 

package/src/tools/context.ts

@@ -0,0 +1,280 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { isSettledOrArchived } from '@taiga/types';
+import { z } from 'zod';
+import { TaigaApiError, type TaigaClient } from '../client.js';
+import { READ_ONLY } from './annotations.js';
+import { BACKLOG_SUMMARY_FIELDS } from './backlogs.js';
+import { BUILD_SUMMARY_FIELDS } from './builds.js';
+import { POLICY_TYPES, defaultOriginFor, isImportedProduct, type ProductSettingsView } from './catalogue.js';
+import { isNetworkFailure, networkFailureDetail, runTool, toolResult } from './errors.js';
+import { productId, remoteUrl, slug } from './inputs.js';
+import { PRODUCT_SUMMARY_FIELDS, resolveProductRef } from './products.js';
+import { instructionsText, sectionsOf, stripProvenance } from './sections.js';
+import { pickFields } from './summarize.js';
+
+/**
+ * One call at the start of a coding session: everything the model would
+ * otherwise collect in eight, fanned out here. Each part stands on its own
+ * (Promise.allSettled): a part the API refuses or fails is named under
+ * `unavailable` with what the API said, a part the key's capabilities do not
+ * cover is named under `notGranted`, and neither is ever shown as empty. A
+ * failure that is not the API's (a bug in this code) is not downgraded; it
+ * fails the call so it surfaces.
+ */
+
+/** The two documents a coding session starts from; the rest are a read away. */
+const CONTEXT_DOCUMENT_TYPES = ['specification', 'architecture'] as const;
+
+const REPOSITORY_SUMMARY_FIELDS = [
+  'id',
+  'provider',
+  'repositoryName',
+  'repositoryUrl',
+  'effectiveBranch',
+  'isManaged',
+] as const;
+
+/** How many of the latest runs to carry; taiga_list_builds pages the rest. */
+const BUILDS_IN_CONTEXT = 10;
+
+/** Pages of 100 the backlog part follows before it stops and says so. */
+const BACKLOG_PAGE_LIMIT = 10;
+
+const PARTS = {
+  factory: 'factories:read',
+  documents: 'products:read',
+  policies: 'tenant:documents:read',
+  backlog: 'backlog:read',
+  repositories: 'products:read',
+  builds: 'products:read',
+} as const;
+type Part = keyof typeof PARTS;
+
+/** What the API said when a part failed, in the words the bundle reports. */
+function unavailableReason(reason: unknown): string {
+  if (reason instanceof TaigaApiError) {
+    return `${reason.status} ${reason.code ?? ''}`.trim() + (reason.apiMessage ? `: ${reason.apiMessage}` : '');
+  }
+  return `the API could not be reached: ${networkFailureDetail(reason as TypeError)}`;
+}
+
+/** Whether a failed part is the API's doing; anything else is ours and propagates. */
+function isApiFailure(reason: unknown): boolean {
+  return reason instanceof TaigaApiError || isNetworkFailure(reason);
+}
+
+function isNotFound(reason: unknown): boolean {
+  return reason instanceof TaigaApiError && reason.status === 404;
+}
+
+/** The factory's standing guidance in full; null, with a note, when none is published or it is not section-shaped. */
+async function factoryPart(client: TaigaClient, factoryId: string) {
+  const factory = (await client.getFactory(factoryId)).data as Record<string, unknown>;
+  const base = { id: factory.id, name: factory.name, slug: factory.slug };
+  try {
+    const doc = (await client.getFactoryDocument(factoryId, 'factory_instructions')).data;
+    const sections = sectionsOf(doc.data);
+    if (!sections) {
+      return {
+        ...base,
+        instructions: null,
+        instructionsVersion: doc.version,
+        note: 'The published instructions are not made of sections; read them with taiga_get_factory_document.',
+      };
+    }
+    // Every section, as the API injects them into the agents; a factory
+    // whose instructions grew a second section is not cut to the first.
+    return { ...base, instructions: instructionsText(sections), instructionsVersion: doc.version };
+  } catch (error) {
+    if (!isNotFound(error)) throw error;
+    return {
+      ...base,
+      instructions: null,
+      instructionsVersion: null,
+      note: 'This factory has not published instructions yet.',
+    };
+  }
+}
+
+/**
+ * The specification and architecture from the product's own timeline: in full
+ * by default, or as section ids when the caller wants a small bundle. Null,
+ * with a note, where unpublished.
+ */
+async function documentsPart(client: TaigaClient, product: Record<string, unknown>, full: boolean) {
+  const productId = String(product.id);
+  const origin = defaultOriginFor(product as ProductSettingsView);
+  const reads = await Promise.allSettled(
+    CONTEXT_DOCUMENT_TYPES.map((type) => client.getProductDocument(productId, type, origin))
+  );
+  const out: Record<string, unknown> = { origin };
+  const notes: string[] = [];
+  CONTEXT_DOCUMENT_TYPES.forEach((type, index) => {
+    const read = reads[index]!;
+    if (read.status === 'fulfilled') {
+      const doc = stripProvenance(read.value.data as Record<string, unknown>);
+      if (full) out[type] = doc;
+      else {
+        const sections = sectionsOf((doc.data as Record<string, unknown>) ?? {});
+        if (sections) out[type] = { version: doc.version, sections: Object.keys(sections) };
+        else {
+          out[type] = { version: doc.version, sections: null };
+          notes.push(`The ${origin} ${type} is not made of sections; read it with taiga_get_product_document.`);
+        }
+      }
+    } else if (isNotFound(read.reason)) {
+      out[type] = null;
+      notes.push(`No published ${origin} ${type}; taiga_list_product_documents shows what the product has.`);
+    } else throw read.reason;
+  });
+  return { ...out, notes };
+}
+
+/** Every published policy as its section ids, so the model knows which one to read with taiga_get_document. */
+async function policiesPart(client: TaigaClient) {
+  const rows = (await client.listTenantDocuments({ limit: 100 })).data as Record<string, unknown>[];
+  return rows
+    .filter((row) => (POLICY_TYPES as readonly string[]).includes(String(row.type)) && row.isDraft === false)
+    .map((row) => ({
+      type: row.type,
+      name: row.name,
+      version: row.version,
+      sections: Object.keys(sectionsOf((row.data as Record<string, unknown>) ?? {}) ?? {}),
+    }));
+}
+
+/** The statuses an item is open in; the API's filter takes one at a time. */
+const OPEN_BACKLOG_STATUSES = ['backlog', 'in_progress'] as const;
+
+/**
+ * The items still open: one status-filtered read per open status (the API
+ * leaves archived items out), each paged in full up to a cap the result
+ * reports. The list is oldest first and the open items are the newest, so a
+ * single page would miss exactly the ones that matter. Rows carrying a
+ * retired status (readable for a rolling deploy) match neither filter;
+ * the settled check below keeps the shape honest for whatever comes back.
+ */
+async function backlogPart(client: TaigaClient, productId: string) {
+  // Keyed by id: an item that moves from backlog to in_progress between the
+  // two reads would otherwise appear twice.
+  const open = new Map<string, Record<string, unknown>>();
+  let truncated = false;
+  for (const status of OPEN_BACKLOG_STATUSES) {
+    let cursor: string | undefined;
+    for (let pageIndex = 0; ; pageIndex += 1) {
+      if (pageIndex === BACKLOG_PAGE_LIMIT) {
+        truncated = true;
+        break;
+      }
+      const result = await client.listBacklogItems(productId, { status, limit: 100, cursor });
+      for (const row of result.data as Record<string, unknown>[]) {
+        if (
+          !isSettledOrArchived({ status: String(row.status), archivedAt: (row.archivedAt as string | null) ?? null })
+        ) {
+          open.set(String(row.id), row);
+        }
+      }
+      if (!result.nextCursor) break;
+      cursor = result.nextCursor;
+    }
+  }
+  return { items: pickFields([...open.values()], BACKLOG_SUMMARY_FIELDS), truncated };
+}
+
+/**
+ * The linked repositories. The route serves one page of 100 and takes no
+ * cursor, so past that the bundle says the list is cut rather than complete.
+ */
+async function repositoriesPart(client: TaigaClient, productId: string) {
+  const result = await client.listProductRepositories(productId);
+  return {
+    items: pickFields(result.data as Record<string, unknown>[], REPOSITORY_SUMMARY_FIELDS),
+    truncated: result.nextCursor !== null,
+  };
+}
+
+async function buildsPart(client: TaigaClient, productId: string) {
+  const rows = (await client.listBuildRuns(productId, { limit: BUILDS_IN_CONTEXT })).data as Record<string, unknown>[];
+  return pickFields(rows, BUILD_SUMMARY_FIELDS);
+}
+
+export async function productContext(
+  client: TaigaClient,
+  product: Record<string, unknown>,
+  options: { fullDocuments: boolean }
+): Promise<CallToolResult> {
+  const productId = String(product.id);
+  const granted = (part: Part) => client.hasCapability(PARTS[part]);
+  const notGranted = (Object.keys(PARTS) as Part[]).filter((part) => !granted(part));
+
+  const fetchers: Record<Part, () => Promise<unknown>> = {
+    factory: () => factoryPart(client, String(product.factoryId)),
+    documents: () => documentsPart(client, product, options.fullDocuments),
+    policies: () => policiesPart(client),
+    backlog: () => backlogPart(client, productId),
+    repositories: () => repositoriesPart(client, productId),
+    builds: () => buildsPart(client, productId),
+  };
+  const parts = (Object.keys(fetchers) as Part[]).filter(granted);
+  const settled = await Promise.allSettled(parts.map((part) => fetchers[part]()));
+
+  const bundle: Record<string, unknown> = {
+    product: {
+      ...pickFields([product], PRODUCT_SUMMARY_FIELDS)[0],
+      projectType: isImportedProduct(product as ProductSettingsView) ? 'brownfield' : 'greenfield',
+      defaultOrigin: defaultOriginFor(product as ProductSettingsView),
+    },
+  };
+  const unavailable: Record<string, string> = {};
+  parts.forEach((part, index) => {
+    const result = settled[index]!;
+    if (result.status === 'fulfilled') bundle[part] = result.value;
+    else if (isApiFailure(result.reason)) unavailable[part] = unavailableReason(result.reason);
+    else throw result.reason;
+  });
+  return toolResult({
+    ...bundle,
+    notGranted: notGranted.map((part) => `${part} (needs ${PARTS[part]})`),
+    unavailable,
+    readNext:
+      'Read a policy in full with taiga_get_document, another product document with taiga_get_product_document, ' +
+      'a backlog item with taiga_get_backlog_item and a run with taiga_get_build.',
+  });
+}
+
+export function registerContextTools(server: McpServer, client: TaigaClient) {
+  if (!client.hasCapability('products:read')) return;
+
+  server.registerTool(
+    'taiga_get_product_context',
+    {
+      title: 'Get product context',
+      description:
+        'Everything a coding session starts from, in one call: the product and which document timeline is its ' +
+        'own, its factory with the instructions in full, the specification and architecture from that timeline, ' +
+        'every published policy as its section ids, the open backlog items, the linked repositories and the ' +
+        'latest runs. Name the product by ID, slug or the git remote URL of the checkout. A part the API refused ' +
+        'or failed is named under unavailable with what it said; a part the key cannot read is named under ' +
+        'notGranted; neither is shown as empty. The two documents come in full, which on a large product is ' +
+        'several thousand tokens; pass fullDocuments: false for their section ids only. Call this first, then ' +
+        'read what you need in full.',
+      inputSchema: {
+        productId: productId.optional(),
+        slug: slug.optional(),
+        remoteUrl: remoteUrl.optional(),
+        fullDocuments: z
+          .boolean()
+          .default(true)
+          .describe('Carry the specification and architecture in full (default) or as section ids only'),
+      },
+      annotations: READ_ONLY,
+    },
+    (params) =>
+      runTool(async () => {
+        const resolved = await resolveProductRef(client, params, ['productId', 'slug', 'remoteUrl']);
+        if ('error' in resolved) return resolved.error;
+        return productContext(client, resolved.product, { fullDocuments: params.fullDocuments });
+      })
+  );
+}

package/src/tools/documents.ts

@@ -2,6 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { TaigaApiError, type TaigaClient, type TaigaDocument } from '../client.js';
 import { READ_ONLY } from './annotations.js';
+import { pagination } from './inputs.js';
 import {
   FACTORY_DOCUMENT_TYPES,
   OTHER_TENANT_DOCUMENT_TYPES,
@@ -11,7 +12,7 @@ import {
 } from './catalogue.js';
 import { runTool, toolError, toolResult } from './errors.js';
 import { applySectionEdit, sectionContent, sectionsOf, stripProvenance } from './sections.js';
-import { pickFields } from './summarize.js';
+import { page, pickFields } from './summarize.js';
 
 /**
  * What a document row needs to say for the model to pick one and read it in
@@ -136,14 +137,14 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           `documents (${named(OTHER_TENANT_DOCUMENT_TYPES)}) carry goals, standards, voice and standing ` +
           'instructions. Use taiga_get_document with the type to read one in full.',
         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.listTenantDocuments(params);
-          return toolResult(summaries(result.data));
+          return toolResult(page(summaries(result.data), result.nextCursor));
         })
     );
 
@@ -260,14 +261,14 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           'Use taiga_get_factory_document to read the full content.',
         inputSchema: {
           factoryId: z.string().uuid().describe('Factory ID -- get from taiga_list_factories'),
-          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.listFactoryDocuments(params.factoryId, { limit: params.limit });
-          return toolResult(summaries(result.data));
+          const result = await client.listFactoryDocuments(params.factoryId, params);
+          return toolResult(page(summaries(result.data), result.nextCursor));
         })
     );
 

package/src/tools/errors.ts

@@ -15,6 +15,21 @@ export function toolError(error: string, message: string): CallToolResult {
   return { content: [{ type: 'text', text: JSON.stringify({ error, message }) }], isError: true };
 }
 
+/**
+ * fetch rejects with a TypeError carrying a `cause` when the API cannot be
+ * reached; a TypeError from our own code carries none and is a bug to surface.
+ */
+export function isNetworkFailure(error: unknown): error is TypeError {
+  return error instanceof TypeError && 'cause' in error;
+}
+
+/** What went wrong on the wire: undici's message is the constant "fetch failed", the cause says why. */
+export function networkFailureDetail(error: TypeError): string {
+  const cause = error.cause as { code?: unknown; message?: unknown } | undefined;
+  const why = typeof cause?.code === 'string' ? cause.code : typeof cause?.message === 'string' ? cause.message : null;
+  return why ? `${error.message} (${why})` : error.message;
+}
+
 const CODE_BY_STATUS: Record<number, string> = {
   400: 'VALIDATION_FAILED',
   401: 'UNAUTHENTICATED',
@@ -39,9 +54,11 @@ export async function runTool(handler: () => Promise<CallToolResult>): Promise<C
       const code = error.code ?? CODE_BY_STATUS[error.status] ?? 'API_ERROR';
       return toolError(code, error.apiMessage ?? `Taiga API answered ${error.status}.`);
     }
-    // fetch rejects with a TypeError when the API cannot be reached.
-    if (error instanceof TypeError) {
-      return toolError('NETWORK_ERROR', `Could not reach the Taiga API: ${error.message}. Check TAIGA_API_URL.`);
+    if (isNetworkFailure(error)) {
+      return toolError(
+        'NETWORK_ERROR',
+        `Could not reach the Taiga API: ${networkFailureDetail(error)}. Check TAIGA_API_URL.`
+      );
     }
     throw error;
   }

package/src/tools/index.ts

@@ -4,6 +4,7 @@ import { registerProductTools } from './products.js';
 import { registerDocumentTools } from './documents.js';
 import { registerBacklogTools } from './backlogs.js';
 import { registerBuildTools } from './builds.js';
+import { registerContextTools } from './context.js';
 
 /**
  * Register all MCP tools based on the API key's effective capabilities.
@@ -15,4 +16,5 @@ export function registerAllTools(server: McpServer, client: TaigaClient): void {
   registerDocumentTools(server, client);
   registerBacklogTools(server, client);
   registerBuildTools(server, client);
+  registerContextTools(server, client);
 }

package/src/tools/inputs.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+/** The inputs several tools share, so a product or a page is named the same way everywhere. */
+
+export const productId = z
+  .string()
+  .uuid()
+  .describe('Product ID -- taiga_get_product_context, taiga_resolve_product or taiga_list_products give it');
+
+/** The page inputs every list tool takes; `nextCursor` of one page is the `cursor` of the next. */
+export const pagination = {
+  limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
+  cursor: z
+    .string()
+    .max(256)
+    .optional()
+    .describe('The nextCursor of the previous page, to read the next one; omit for the first page'),
+};
+
+export const slug = z
+  .string()
+  .max(63)
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'A slug is lowercase words joined by hyphens')
+  .describe('Product slug, as it appears in Taiga URLs');
+
+export const remoteUrl = z
+  .string()
+  .min(1)
+  .max(2048)
+  .describe(
+    'The git remote URL of a checkout (git remote get-url origin): https://, git@host:owner/repo.git or ssh://'
+  );

package/src/tools/instructions.ts

@@ -53,8 +53,12 @@ export const SERVER_INSTRUCTIONS = [
   '`priority: core` marks the sections every organization keeps. Neither changes what the section',
   'requires of you.',
   '',
-  '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,',
+  'Workflow: start with taiga_get_product_context, naming the product by its git remote URL inside a checkout',
+  '(git remote get-url origin), else by slug or ID from taiga_list_products. It returns the product, the',
+  'factory instructions, the specification and architecture, every policy as its section ids, the open backlog',
+  'items, the repositories and the latest runs in one call, and names any part it could not read. Then read',
+  'what you need in full: a policy with taiga_get_document, a backlog item with taiga_get_backlog_item.',
+  'Without it, 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. A document",
   'read that finds nothing tells you what does exist and which tool reads or writes it.',
   '',