@taiga-ai/mcp-server 0.13.0-dev.423 → 0.14.0-dev.425

package/src/tools/product-documents.ts

@@ -0,0 +1,193 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  DOCUMENT_INPUTS,
+  type GeneratedDocumentType,
+  PRODUCT_DOCUMENT_TYPES,
+  type ProductDocumentType,
+  REVIEWABLE_PRODUCT_DOCUMENT_TYPES,
+  SETUP_REQUIRED_DOCUMENT_TYPES,
+} from '@taiga/types';
+import { z } from 'zod';
+import type { TaigaClient, TaigaDocument } from '../client.js';
+import { OPERATE, WRITE } from './annotations.js';
+import { type DocumentScope, publishDraft, sectionContentInput, sectionIdFrom, updateSection } from './documents.js';
+import { runTool, toolError, toolResult } from './errors.js';
+import { productId } from './inputs.js';
+import { jobReport } from './jobs.js';
+
+/**
+ * A product's own documents (docs.tai.ga, Learn: Product documents): drafts,
+ * versions and publishing on the plan timeline, the side people and the
+ * discovery agents write. A draft changes nothing downstream until it is
+ * published; documents generated from one that changed are marked outdated
+ * and regenerated, never rewritten in place; and finishing Discovery locks
+ * the set, which the API enforces. The reality timeline is derived from the
+ * code and is not edited.
+ */
+
+type Row = Record<string, unknown>;
+
+/** The plan-side documents people edit; the codebase snapshot is derived from the code, never written. */
+type EditableType = Exclude<ProductDocumentType, 'codebase_snapshot'>;
+const EDITABLE_TYPES = PRODUCT_DOCUMENT_TYPES.filter((type): type is EditableType => type !== 'codebase_snapshot') as [
+  EditableType,
+  ...EditableType[],
+];
+
+const documentType = z
+  .enum(EDITABLE_TYPES)
+  .describe('Document type -- taiga_list_product_documents shows which ones the product has');
+
+/** The documents a person reviews: the discovery chain, not the snapshot or the product's own instructions. */
+const reviewableType = z
+  .enum(REVIEWABLE_PRODUCT_DOCUMENT_TYPES)
+  .describe('Document type -- one of the discovery documents a person reviews');
+
+/** The documents an agent writes from other documents; the same table the worker reads its inputs from. */
+const generatedType = z
+  .enum(Object.keys(DOCUMENT_INPUTS) as [GeneratedDocumentType, ...GeneratedDocumentType[]])
+  .describe('Document type -- one generated from the documents above it');
+
+export function registerProductDocumentWrites(server: McpServer, client: TaigaClient) {
+  if (!client.hasCapability('products:write')) return;
+  // The section edit reads the draft and the published version, and the
+  // regenerate reads the product's Discovery state, before they write.
+  const canRead = client.hasCapability('products:read');
+
+  const productScope = (product: string, type: string): DocumentScope => ({
+    getDraft: () => client.getProductDocumentDraft(product, type),
+    getPublished: async () => (await client.getProductDocument(product, type, 'plan')) as { data: TaigaDocument },
+    saveDraft: (data) => client.saveProductDocumentDraft(product, type, { data }),
+    publish: () => client.publishProductDocument(product, type),
+  });
+
+  if (canRead) {
+    server.registerTool(
+      'taiga_update_product_document',
+      {
+        title: 'Update a section of a product document draft',
+        description:
+          'Replace the text of one section of a product document on its plan timeline, in the draft. Every other ' +
+          'section stays as it is. A draft changes nothing downstream: agents keep reading the published version ' +
+          'until the draft is published (taiga_publish_product_document). Refused once Discovery is finished and ' +
+          'the set is locked: reopening Discovery is done in the web. Reality documents are derived from the code ' +
+          'and not edited.',
+        inputSchema: {
+          productId,
+          type: documentType,
+          sectionId: sectionIdFrom('taiga_get_product_document (the plan timeline)'),
+          content: sectionContentInput,
+        },
+        annotations: WRITE,
+      },
+      (params) =>
+        runTool(() =>
+          updateSection(productScope(params.productId, params.type), params.type, params.sectionId, params.content)
+        )
+    );
+  }
+
+  server.registerTool(
+    'taiga_publish_product_document',
+    {
+      title: 'Publish a product document draft',
+      description:
+        "Publish a product document's draft as its new version, the one agents work from. Documents generated " +
+        'from it are not rewritten: each is marked outdated, and is regenerated when someone chooses to ' +
+        '(taiga_regenerate_product_document, or taiga_generate_product_documents for every outdated and missing ' +
+        'one). Ask the person before publishing.',
+      inputSchema: { productId, type: documentType },
+      annotations: OPERATE,
+    },
+    (params) => runTool(() => publishDraft(productScope(params.productId, params.type)))
+  );
+
+  server.registerTool(
+    'taiga_mark_product_document_reviewed',
+    {
+      title: 'Mark a product document reviewed',
+      description:
+        "Record that a person reviewed a product document's latest published version, as the Documents page " +
+        "shows it beside each version; once every published document is reviewed, the product's review item in " +
+        'Action Required resolves. The mark says a human read it, so make it only when the person tells you they ' +
+        'have: reading it yourself is not a review.',
+      inputSchema: { productId, type: reviewableType },
+      annotations: WRITE,
+    },
+    (params) =>
+      runTool(async () => toolResult((await client.markProductDocumentReviewed(params.productId, params.type)).data))
+  );
+
+  if (canRead) {
+    server.registerTool(
+      'taiga_regenerate_product_document',
+      {
+        title: 'Regenerate a product document',
+        description:
+          'Ask an agent to generate one product document again from the documents it is derived from, for one ' +
+          'marked outdated or one that needs another pass. The Specification comes from the Discovery ' +
+          'conversation and the Look & Feel from its concepts, both in the web. The documents Discovery requires ' +
+          'are regenerated while it is open only: a finished Discovery locks them, and reopening it is done in ' +
+          'the web. The optional Service Blueprint can be generated whenever someone wants one. The result is published as the new version, and ' +
+          'the documents generated from it are marked outdated in turn. Runs an agent in the background: this ' +
+          'returns the job; taiga_wait_for_job says when it is done. Ask the person first.',
+        inputSchema: { productId, type: generatedType },
+        annotations: OPERATE,
+      },
+      (params) =>
+        runTool(async () => {
+          // The lock guards the draft and publish routes; a generated document
+          // is published by the worker directly, so the check is made here.
+          // It holds the documents setup requires, as the API's lock does; the
+          // optional blueprint stays open after setup.
+          const locked = (SETUP_REQUIRED_DOCUMENT_TYPES as readonly string[]).includes(params.type);
+          const product = locked ? ((await client.getProduct(params.productId)).data as { status?: unknown }) : null;
+          if (product && product.status !== 'draft') {
+            return toolError(
+              'CONFLICT',
+              'Discovery is finished for this product, so its documents are locked. Reopen Discovery in the web to regenerate one.'
+            );
+          }
+          const job = (
+            await client.createAgentJob({
+              scope: 'product',
+              type: 'generate_document',
+              targetId: params.productId,
+              documentType: params.type,
+            })
+          ).data as Row;
+          return toolResult(jobReport(job));
+        })
+    );
+  }
+
+  server.registerTool(
+    'taiga_generate_product_documents',
+    {
+      title: 'Generate the remaining product documents',
+      description:
+        'Generate remaining: every document the product still needs, and every one marked outdated, in the ' +
+        'order they build on each other, one after another (each next one starts when the one before it is ' +
+        'published). Refused (CONFLICT) while a document is already being generated. On an imported product, ' +
+        'it queues every unpublished document. Runs agents in the background: this returns the jobs it started ' +
+        '(jobIds); taiga_stop_generating_documents stops the run. Ask the person first.',
+      inputSchema: { productId },
+      annotations: OPERATE,
+    },
+    (params) => runTool(async () => toolResult((await client.generateRemainingDocuments(params.productId)).data))
+  );
+
+  server.registerTool(
+    'taiga_stop_generating_documents',
+    {
+      title: 'Stop generating product documents',
+      description:
+        'Stop a Generate remaining run: every document of it still being generated is cancelled and nothing ' +
+        'after them starts; published documents stay. An empty list means no run was going. Interrupts agent ' +
+        'work; ask the person first.',
+      inputSchema: { productId },
+      annotations: OPERATE,
+    },
+    (params) => runTool(async () => toolResult((await client.stopGeneratingDocuments(params.productId)).data))
+  );
+}