@taiga-ai/mcp-server 0.4.0-rc.345 → 0.5.0-dev.388

package/src/tools/documents.ts

@@ -1,148 +1,296 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import type { TaigaClient } from '../client.js';
+import { TaigaApiError, type TaigaClient, type TaigaDocument } from '../client.js';
+import { runTool, toolError, toolResult } from './errors.js';
+import { applySectionEdit, sectionContent, sectionsOf } from './sections.js';
+import { documentType } from './inputs.js';
 import { summarizeList } from './summarize.js';
 
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } as const;
+const DRAFT_WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+// Publishing replaces the version every agent and person reads, and there is
+// no unpublish: destructive so a host that confirms destructive tools asks
+// first. Not idempotent: a second call publishes the same draft once more.
+const PUBLISH = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false } as const;
+
+const sectionId = z
+  .string()
+  .min(1)
+  .describe(
+    'Section id -- the keys of `data.sections` in taiga_get_document, e.g. summary, scope, apiDesign. ' +
+      'An id that does not exist yet adds a section.'
+  );
+const sectionContentInput = z.string().describe('The full new Markdown text of the section; it replaces the old text');
+const tenantDocumentType = documentType.describe(
+  'Document type (e.g. policy_security, policy_sdlc) -- see taiga_list_documents'
+);
+
+/**
+ * The read, save and publish calls for one document scope. The tools are the
+ * same for a company policy and for factory instructions; only the routes and
+ * the capability gate differ.
+ */
+interface DocumentScope {
+  getDraft(): Promise<{ data: TaigaDocument | null }>;
+  getPublished(): Promise<{ data: TaigaDocument }>;
+  saveDraft(data: Record<string, unknown>): Promise<{ data: TaigaDocument }>;
+  publish(): Promise<{ data: TaigaDocument }>;
+}
+
+/** Everything the model needs back from a write, without the content it already holds. */
+function documentSummary(doc: TaigaDocument) {
+  const { data, ...rest } = doc;
+  return { ...rest, sections: Object.keys(sectionsOf(data) ?? {}) };
+}
+
+/**
+ * The document a section edit starts from: the draft when one exists, else
+ * the published version, else (instructions documents start empty and
+ * unpublished, PRO-502) an empty section map. The API seeds the draft the
+ * same way on the first save, so the merge happens on what it would hold.
+ */
+async function editBase(scope: DocumentScope): Promise<Record<string, unknown>> {
+  const draft = (await scope.getDraft()).data;
+  if (draft) return draft.data;
+  try {
+    return (await scope.getPublished()).data.data;
+  } catch (error) {
+    if (error instanceof TaigaApiError && error.status === 404) return { sections: {} };
+    throw error;
+  }
+}
+
+/**
+ * Edit one section of a document's draft; the edit keeps every other section
+ * and the section's own metadata, see sections.ts.
+ */
+async function updateSection(scope: DocumentScope, type: string, id: string, content: string) {
+  const base = await editBase(scope);
+  const sections = sectionsOf(base);
+  if (!sections) {
+    return toolError(
+      'UNSUPPORTED_DOCUMENT',
+      `Document ${type} is not made of sections and cannot be edited section by section. Edit it in the Taiga app.`
+    );
+  }
+  const saved = await scope.saveDraft({ ...base, sections: applySectionEdit(sections, id, content) });
+  return toolResult({
+    ...documentSummary(saved.data),
+    section: { id, content: sectionContent(sectionsOf(saved.data.data) ?? {}, id) },
+  });
+}
+
+/** Publish the draft; the API answers 404 when there is none and 400 when the residue gate refuses it. */
+async function publishDraft(scope: DocumentScope) {
+  const published = await scope.publish();
+  return toolResult(documentSummary(published.data));
+}
+
 export function registerDocumentTools(server: McpServer, client: TaigaClient) {
   // ── Company-level policy documents ──────────────────────────────────
 
   if (client.hasCapability('tenant:documents:read')) {
-    server.tool(
+    server.registerTool(
       'taiga_list_documents',
-      'List company-level policy documents (names and types only). ' +
-        'Policies define security, data privacy, SDLC, operations, architecture, and compliance rules ' +
-        'that apply across all factories and products. ' +
-        'Use taiga_get_document with the document type to read the full policy content.',
       {
-        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+        title: 'List company documents',
+        description:
+          'List company-level policy documents (names and types only). ' +
+          'Policies define security, data privacy, SDLC, operations, architecture, and compliance rules ' +
+          'that apply across all factories and products. ' +
+          'Use taiga_get_document with the document type to read the full policy content.',
+        inputSchema: {
+          limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+        },
+        annotations: READ_ONLY,
       },
-      { readOnlyHint: true, openWorldHint: false },
-      async (params) => {
-        const result = await client.listTenantDocuments(params);
-        const summaries = summarizeList(result.data as Record<string, unknown>[]);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(summaries, null, 2) }],
-        };
-      }
+      (params) =>
+        runTool(async () => {
+          const result = await client.listTenantDocuments(params);
+          const summaries = summarizeList(result.data as Record<string, unknown>[]);
+          return toolResult(summaries);
+        })
     );
 
-    server.tool(
+    server.registerTool(
       'taiga_get_document',
-      'Get the full content of a company policy document. ' +
-        'Use this when you need to understand security requirements, data handling rules, ' +
-        'architecture standards, or compliance controls that apply to your code. ' +
-        'Types: policy_security, policy_data, policy_sdlc, policy_ops, policy_tic, ' +
-        'policy_risk, policy_architecture, policy_supply_chain, policy_cloud_governance, policy_acceptable_use, policy_ip.',
       {
-        type: z
-          .string()
-          .describe(
+        title: 'Get company document',
+        description:
+          'Get the full content of a company policy document. ' +
+          'Use this when you need to understand security requirements, data handling rules, ' +
+          'architecture standards, or compliance controls that apply to your code. ' +
+          'Types: policy_security, policy_data, policy_sdlc, policy_ops, policy_tic, ' +
+          'policy_risk, policy_architecture, policy_supply_chain, policy_cloud_governance, policy_acceptable_use, policy_ip.',
+        inputSchema: {
+          type: documentType.describe(
             'Document type -- get available types from taiga_list_documents. ' +
               'Common: policy_security, policy_data, policy_sdlc, policy_architecture'
           ),
+        },
+        annotations: READ_ONLY,
       },
-      { readOnlyHint: true, openWorldHint: false },
-      async (params) => {
-        const result = await client.getTenantDocument(params.type);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
-        };
-      }
+      (params) =>
+        runTool(async () => {
+          const result = await client.getTenantDocument(params.type);
+          return toolResult(result.data);
+        })
     );
   }
 
-  if (client.hasCapability('tenant:documents:write')) {
-    server.tool(
+  // The edit reads the draft and the published version before it writes,
+  // and those routes need tenant:documents:read; a write-only scoped key
+  // would get a tool that 403s on every call.
+  if (client.hasCapability('tenant:documents:read') && client.hasCapability('tenant:documents:write')) {
+    const tenantScope = (type: string): DocumentScope => ({
+      getDraft: () => client.getTenantDocumentDraft(type),
+      getPublished: () => client.getTenantDocument(type),
+      saveDraft: (data) => client.saveTenantDocumentDraft(type, { data }),
+      publish: () => client.publishTenantDocument(type),
+    });
+
+    server.registerTool(
       'taiga_update_document',
-      'Update the draft content of a company policy document. ' +
-        'Only updates the draft -- does not publish. Use this when you notice a policy ' +
-        'is outdated or needs corrections while reviewing code.',
       {
-        type: z.string().describe('Document type (e.g. policy_security, policy_sdlc)'),
-        data: z.record(z.string(), z.unknown()).describe('Document content to save as JSON'),
+        title: 'Update a section of a company document draft',
+        description:
+          'Replace the text of one section of a company policy document, in its draft. ' +
+          'Every other section stays as it is. Does not publish: people and agents keep reading the ' +
+          'published version until taiga_publish_document is called. Read the document with ' +
+          'taiga_get_document first to see its sections and their current text. ' +
+          'Use this when you notice a policy is outdated or needs corrections while reviewing code.',
+        inputSchema: {
+          type: tenantDocumentType,
+          sectionId,
+          content: sectionContentInput,
+        },
+        annotations: DRAFT_WRITE,
       },
-      { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-      async (params) => {
-        const { type, ...body } = params;
-        const result = await client.saveTenantDocumentDraft(type, body as { data: Record<string, unknown> });
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
-        };
-      }
+      (params) => runTool(() => updateSection(tenantScope(params.type), params.type, params.sectionId, params.content))
+    );
+
+    server.registerTool(
+      'taiga_publish_document',
+      {
+        title: 'Publish a company document draft',
+        description:
+          "Publish a company policy document's draft as its next version, the one every agent and person " +
+          'reads from then on. Only publish when the person asked for it; save edits with ' +
+          'taiga_update_document first. A refused publish names what to fix in the draft.',
+        inputSchema: {
+          type: tenantDocumentType,
+        },
+        annotations: PUBLISH,
+      },
+      (params) => runTool(() => publishDraft(tenantScope(params.type)))
     );
   }
 
   // ── Factory instructions ────────────────────────────────────────────
 
   if (client.hasCapability('factories:read')) {
-    server.tool(
+    server.registerTool(
       'taiga_list_factory_documents',
-      'List documents for a specific factory (names and types only). ' +
-        "A factory has one document: its instructions, the factory's free-form standing guidance " +
-        '(domain context, tech preferences, conventions) that applies to every product it owns. ' +
-        'Use taiga_get_factory_document to read the full content.',
       {
-        factoryId: z.string().uuid().describe('Factory ID -- get from taiga_list_factories'),
-        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+        title: 'List factory documents',
+        description:
+          'List documents for a specific factory (names and types only). ' +
+          "A factory has one document: its instructions, the factory's free-form standing guidance " +
+          '(domain context, tech preferences, conventions) that applies to every product it owns. ' +
+          '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().min(1).max(100).optional().describe('Max results (default 25)'),
+        },
+        annotations: READ_ONLY,
       },
-      { readOnlyHint: true, openWorldHint: false },
-      async (params) => {
-        const result = await client.listFactoryDocuments(params.factoryId, { limit: params.limit });
-        const summaries = summarizeList(result.data as Record<string, unknown>[]);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(summaries, null, 2) }],
-        };
-      }
+      (params) =>
+        runTool(async () => {
+          const result = await client.listFactoryDocuments(params.factoryId, { limit: params.limit });
+          const summaries = summarizeList(result.data as Record<string, unknown>[]);
+          return toolResult(summaries);
+        })
     );
 
-    server.tool(
+    server.registerTool(
       'taiga_get_factory_document',
-      "Get the full content of a factory's instructions. " +
-        'Use this when you need the domain context, tech preferences, or conventions ' +
-        'the factory expects every product it owns to follow.',
       {
-        factoryId: z.string().uuid().describe('Factory ID -- get from taiga_list_factories'),
-        type: z
-          .string()
-          .describe(
+        title: 'Get factory instructions',
+        description:
+          "Get the full content of a factory's instructions. " +
+          'Use this when you need the domain context, tech preferences, or conventions ' +
+          'the factory expects every product it owns to follow.',
+        inputSchema: {
+          factoryId: z.string().uuid().describe('Factory ID -- get from taiga_list_factories'),
+          type: documentType.describe(
             'Document type -- get available types from taiga_list_factory_documents. ' +
               'The factory instructions document is `factory_instructions`.'
           ),
+        },
+        annotations: READ_ONLY,
       },
-      { readOnlyHint: true, openWorldHint: false },
-      async (params) => {
-        const result = await client.getFactoryDocument(params.factoryId, params.type);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
-        };
-      }
+      (params) =>
+        runTool(async () => {
+          const result = await client.getFactoryDocument(params.factoryId, params.type);
+          return toolResult(result.data);
+        })
     );
   }
 
-  // Factory document write requires both teams:read (to find the factory) and tenant:documents:write
-  if (client.hasCapability('factories:read') && client.hasCapability('tenant:documents:write')) {
-    server.tool(
+  // Writing factory instructions needs factories:read (to find the factory) and
+  // factories:documents:write, which is what the API routes require: members
+  // hold it for their own factories, and tenant:documents:write (company
+  // policies) does not stand in for it.
+  if (client.hasCapability('factories:read') && client.hasCapability('factories:documents:write')) {
+    const factoryScope = (factoryId: string, type: string): DocumentScope => ({
+      getDraft: () => client.getFactoryDocumentDraft(factoryId, type),
+      getPublished: () => client.getFactoryDocument(factoryId, type),
+      saveDraft: (data) => client.saveFactoryDocumentDraft(factoryId, type, { data }),
+      publish: () => client.publishFactoryDocument(factoryId, type),
+    });
+    const factoryId = z.string().uuid().describe('Factory ID -- get from taiga_list_factories');
+    const factoryDocumentType = documentType.describe('Document type (`factory_instructions`)');
+
+    server.registerTool(
       'taiga_update_factory_document',
-      "Update the draft of a factory's instructions. " +
-        'Only updates the draft -- does not publish. Use this when you notice the factory conventions, ' +
-        'domain context, or tech preferences need updating while working on the codebase.',
       {
-        factoryId: z.string().uuid().describe('Factory ID -- get from taiga_list_factories'),
-        type: z.string().describe('Document type (`factory_instructions`)'),
-        data: z.record(z.string(), z.unknown()).describe('Document content to save as JSON'),
-      },
-      { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-      async (params) => {
-        const { factoryId, type, ...body } = params;
-        const result = await client.saveFactoryDocumentDraft(
+        title: 'Update a section of factory instructions',
+        description:
+          "Replace the text of one section of a factory's instructions, in its draft. The instructions " +
+          'document has one section, `instructions`. Does not publish: products keep following the ' +
+          'published version until taiga_publish_factory_document is called. Read the current text with ' +
+          'taiga_get_factory_document first. Use this when the factory conventions, domain context or tech ' +
+          'preferences need updating while working on the codebase.',
+        inputSchema: {
           factoryId,
-          type,
-          body as { data: Record<string, unknown> }
-        );
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
-        };
-      }
+          type: factoryDocumentType,
+          sectionId: sectionId.default('instructions'),
+          content: sectionContentInput,
+        },
+        annotations: DRAFT_WRITE,
+      },
+      (params) =>
+        runTool(() =>
+          updateSection(factoryScope(params.factoryId, params.type), params.type, params.sectionId, params.content)
+        )
+    );
+
+    server.registerTool(
+      'taiga_publish_factory_document',
+      {
+        title: 'Publish factory instructions draft',
+        description:
+          "Publish a factory's instructions draft as the next version every product of the factory follows. " +
+          'Only publish when the person asked for it; save edits with taiga_update_factory_document first.',
+        inputSchema: { factoryId, type: factoryDocumentType },
+        annotations: PUBLISH,
+      },
+      (params) => runTool(() => publishDraft(factoryScope(params.factoryId, params.type)))
     );
   }
 }

package/src/tools/errors.ts

@@ -0,0 +1,48 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { TaigaApiError } from '../client.js';
+
+/** A successful tool result: one JSON text block the model reads. */
+export function toolResult(value: unknown): CallToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+/**
+ * A failed tool result the model can branch on: a stable code and a message
+ * that says what to do next. Returned, not thrown, so the client sees
+ * `isError` rather than a protocol error.
+ */
+export function toolError(error: string, message: string): CallToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify({ error, message }) }], isError: true };
+}
+
+const CODE_BY_STATUS: Record<number, string> = {
+  400: 'VALIDATION_FAILED',
+  401: 'UNAUTHENTICATED',
+  403: 'FORBIDDEN',
+  404: 'NOT_FOUND',
+  409: 'CONFLICT',
+  429: 'RATE_LIMITED',
+};
+
+/**
+ * Run a tool handler and turn a failure into a structured error. An API
+ * refusal keeps the API's own code when it sent one and its message whole:
+ * on a refused publish that names the section holding template residue,
+ * which is what the model needs to fix the draft. A failed connection is
+ * structured too, so every failure the model sees has the same shape.
+ */
+export async function runTool(handler: () => Promise<CallToolResult>): Promise<CallToolResult> {
+  try {
+    return await handler();
+  } catch (error) {
+    if (error instanceof TaigaApiError) {
+      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.`);
+    }
+    throw error;
+  }
+}

package/src/tools/inputs.test.ts

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,13 @@
+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');