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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.13.0-rc.424",
+  "version": "0.14.0-dev.425",
   "description": "MCP server for Taiga -- gives AI assistants access to documents and products",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.ts

@@ -1,4 +1,4 @@
-import type { ApiKeyIntrospection } from '@taiga/types';
+import type { AgentJobType, ApiKeyIntrospection } from '@taiga/types';
 import { SERVER_VERSION } from './version.js';
 
 /**
@@ -70,6 +70,20 @@ function seg(value: string): string {
   return encodeURIComponent(value);
 }
 
+/**
+ * A query string from the defined values only, prefixed with "?" when there
+ * is one. Every value goes through URLSearchParams, so nothing a tool passes
+ * can add a parameter of its own.
+ */
+function query(params: Record<string, string | number | boolean | null | undefined>): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== '') search.set(key, String(value));
+  }
+  const text = search.toString();
+  return text ? `?${text}` : '';
+}
+
 function parseErrorBody(body: string): { code?: string; message?: string } {
   try {
     const json = JSON.parse(body) as { code?: unknown; message?: unknown; details?: unknown };
@@ -133,13 +147,15 @@ export class TaigaClient {
       'User-Agent': `taiga-ai-mcp-server/${SERVER_VERSION}`,
     };
     // Only with a body: Fastify refuses an empty body under a JSON
-    // content type, which is what a bodiless POST (publish) would send.
-    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    // content type, which is what a bodiless POST (publish) would send. A
+    // form (a file upload) sets its own multipart type with its boundary.
+    const form = body instanceof FormData;
+    if (body !== undefined && !form) headers['Content-Type'] = 'application/json';
 
     const response = await fetch(url, {
       method,
       headers,
-      body: body === undefined ? null : JSON.stringify(body),
+      body: body === undefined ? null : form ? body : JSON.stringify(body),
       // A caller that must stop waiting (a wait's deadline, a cancelled call) ends the read too.
       ...(options.signal ? { signal: options.signal } : {}),
     });
@@ -149,6 +165,8 @@ export class TaigaClient {
       throw new TaigaApiError(method, path, response.status, text);
     }
 
+    // A delete answers 204 with no body: there is nothing to parse.
+    if (response.status === 204) return null as T;
     const parsed = (await response.json()) as T;
     return options.keepTenant ? parsed : withoutTenant(parsed);
   }
@@ -313,7 +331,7 @@ export class TaigaClient {
   /** Ask an agent for work: the job is queued and runs in the background. */
   async createAgentJob(body: {
     scope: 'product' | 'tenant';
-    type: string;
+    type: AgentJobType;
     targetId: string;
     documentType?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
@@ -325,6 +343,44 @@ export class TaigaClient {
     return this.request<{ data: unknown }>('GET', `/agent-jobs/${seg(id)}`, undefined, { signal });
   }
 
+  /** The plan-side draft of a product document, or `{ data: null }` when none exists. */
+  async getProductDocumentDraft(productId: string, type: string) {
+    return this.request<{ data: TaigaDocument | null }>(
+      'GET',
+      `/products/${seg(productId)}/documents/${seg(type)}/draft`
+    );
+  }
+
+  async saveProductDocumentDraft(productId: string, type: string, body: { data: Record<string, unknown> }) {
+    return this.request<{ data: TaigaDocument }>(
+      'PUT',
+      `/products/${seg(productId)}/documents/${seg(type)}/draft`,
+      body
+    );
+  }
+
+  async publishProductDocument(productId: string, type: string) {
+    return this.request<{ data: TaigaDocument; warnings?: { unknownPolicyCitations?: string[] } }>(
+      'POST',
+      `/products/${seg(productId)}/documents/${seg(type)}/publish`
+    );
+  }
+
+  /** Mark the published version reviewed by the caller, as the Documents page shows it. */
+  async markProductDocumentReviewed(productId: string, type: string) {
+    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/documents/${seg(type)}/review`);
+  }
+
+  /** Generate remaining: every missing and outdated document, in chain order. */
+  async generateRemainingDocuments(productId: string) {
+    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/documents/generate-all`);
+  }
+
+  /** Cancel a Generate remaining run still in flight. */
+  async stopGeneratingDocuments(productId: string) {
+    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/documents/generate-all/stop`);
+  }
+
   async getProductDocument(productId: string, type: string, origin?: string) {
     const qs = origin ? `?${new URLSearchParams({ origin })}` : '';
     return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/documents/${seg(type)}${qs}`);
@@ -454,6 +510,258 @@ export class TaigaClient {
     return this.request<{ data: unknown[] }>('GET', `/builds/${seg(id)}/steps`);
   }
 
+  // ---------------------------------------------------------------------------
+  // Maintaining
+  // ---------------------------------------------------------------------------
+
+  async getMaintenanceSummary(productId: string) {
+    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/maintenance/summary`);
+  }
+
+  async listMaintenanceSweeps(productId: string, opts?: { limit?: number | undefined }) {
+    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+      'GET',
+      `/products/${seg(productId)}/maintenance/runs${query({ limit: opts?.limit })}`
+    );
+  }
+
+  async listFindings(
+    productId: string,
+    opts?: {
+      status?: string | undefined;
+      severity?: string | undefined;
+      kind?: string | undefined;
+      limit?: number | undefined;
+      cursor?: string | undefined;
+    }
+  ) {
+    return this.request<{ data: unknown[]; nextCursor: string | null; totalCount?: number }>(
+      'GET',
+      `/products/${seg(productId)}/maintenance/findings${query({ ...opts })}`
+    );
+  }
+
+  async getFinding(id: string) {
+    return this.request<{ data: unknown }>('GET', `/maintenance/findings/${seg(id)}`);
+  }
+
+  async updateFinding(
+    id: string,
+    body: {
+      status: 'open' | 'ignored';
+      ignoreReason?: string | undefined;
+      ignoreNote?: string | null | undefined;
+      ignoreExpiresAt?: string | null | undefined;
+    }
+  ) {
+    return this.request<{ data: unknown }>('PATCH', `/maintenance/findings/${seg(id)}`, body);
+  }
+
+  async remediateFinding(productId: string, findingId: string) {
+    return this.request<{ data: unknown }>(
+      'POST',
+      `/products/${seg(productId)}/maintenance/findings/${seg(findingId)}/remediate`,
+      {}
+    );
+  }
+
+  async remediatePackage(
+    productId: string,
+    body: {
+      ecosystem: string;
+      packageName: string;
+      currentVersion?: string | null | undefined;
+      productRepositoryId?: string | null | undefined;
+    }
+  ) {
+    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/maintenance/packages/remediate`, body);
+  }
+
+  async getPolicyStanding(productId: string) {
+    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/maintenance/policies`);
+  }
+
+  async remediatePolicyControl(productId: string, controlId: string) {
+    return this.request<{ data: unknown }>(
+      'POST',
+      `/products/${seg(productId)}/maintenance/policies/controls/${seg(controlId)}/remediate`,
+      {}
+    );
+  }
+
+  async remediatePolicyViolation(productId: string, divergenceId: string) {
+    return this.request<{ data: unknown }>(
+      'POST',
+      `/products/${seg(productId)}/maintenance/policies/divergences/${seg(divergenceId)}/remediate`,
+      {}
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Action Required
+  // ---------------------------------------------------------------------------
+
+  async listInbox(opts: {
+    productId?: string | undefined;
+    category?: string | undefined;
+    resolved?: boolean | undefined;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+  }) {
+    const { productId, ...rest } = opts;
+    const path = productId ? `/products/${seg(productId)}/inbox` : '/inbox';
+    return this.request<{ data: unknown[]; nextCursor: string | null }>('GET', `${path}${query({ ...rest })}`);
+  }
+
+  async updateInboxItem(
+    id: string,
+    body: { status?: 'in_progress' | 'done' | 'dismissed' | undefined; snoozedUntil?: string | null | undefined }
+  ) {
+    return this.request<{ data: unknown }>('PATCH', `/inbox/${seg(id)}`, body);
+  }
+
+  async listSetupTasks(opts: {
+    productId?: string | undefined;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+  }) {
+    const { productId, ...rest } = opts;
+    const path = productId ? `/products/${seg(productId)}/setup-tasks` : '/setup-tasks';
+    return this.request<{ data: unknown[]; nextCursor: string | null }>('GET', `${path}${query({ ...rest })}`);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Deployments, environments and monitoring (observed, never driven)
+  // ---------------------------------------------------------------------------
+
+  async listEnvironments(productId: string, opts?: { limit?: number | undefined; cursor?: string | undefined }) {
+    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+      'GET',
+      `/products/${seg(productId)}/environments${query({ ...opts })}`
+    );
+  }
+
+  async createEnvironment(productId: string, body: { name: string; type: string }) {
+    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/environments`, body);
+  }
+
+  async updateEnvironment(
+    id: string,
+    body: { name?: string | undefined; type?: string | undefined; url?: string | null | undefined }
+  ) {
+    return this.request<{ data: unknown }>('PATCH', `/environments/${seg(id)}`, body);
+  }
+
+  async getCurrentDeployments(productId: string) {
+    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/deployments/current`);
+  }
+
+  async listDeployments(
+    productId: string,
+    opts?: { environmentId?: string | undefined; limit?: number | undefined; cursor?: string | undefined }
+  ) {
+    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+      'GET',
+      `/products/${seg(productId)}/deployments${query({ ...opts })}`
+    );
+  }
+
+  async getDeploymentSyncStatus(productId: string) {
+    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/deployments/sync-status`);
+  }
+
+  async getDeliveryMetrics(productId: string, environmentId: string, windowDays: number) {
+    return this.request<{ data: unknown }>(
+      'GET',
+      `/products/${seg(productId)}/deployments/insights${query({ environmentId, windowDays })}`
+    );
+  }
+
+  async getMonitoringHealth(productId: string) {
+    return this.request<{ data: unknown[] }>('GET', `/products/${seg(productId)}/monitoring/health`);
+  }
+
+  async getMonitoringSignal(
+    productId: string,
+    signal: 'uptime' | 'rum' | 'client-health' | 'history',
+    environmentId: string,
+    windowDays: number
+  ) {
+    return this.request<{ data: unknown }>(
+      'GET',
+      `/products/${seg(productId)}/monitoring/${signal}${query({ environmentId, windowDays })}`
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Knowledge
+  // ---------------------------------------------------------------------------
+
+  async listKnowledge(opts: {
+    factoryId?: string | null | undefined;
+    productId?: string | null | undefined;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+  }) {
+    // The route reads the literal 'null' as "this level only, not below it".
+    const scope = (value: string | null | undefined) => (value === null ? 'null' : value);
+    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+      'GET',
+      `/custom-documents${query({ ...opts, factoryId: scope(opts.factoryId), productId: scope(opts.productId) })}`
+    );
+  }
+
+  async getKnowledge(id: string) {
+    return this.request<{ data: unknown }>('GET', `/custom-documents/${seg(id)}`);
+  }
+
+  async getKnowledgeDownload(id: string) {
+    return this.request<{ data: { url?: unknown } & Record<string, unknown> }>(
+      'GET',
+      `/custom-documents/${seg(id)}/download`
+    );
+  }
+
+  /** A text file filed as knowledge at one level: the organization, a factory, or a product in its factory. */
+  async addKnowledge(file: {
+    fileName: string;
+    mime: 'text/markdown' | 'text/plain';
+    content: string;
+    factoryId?: string | undefined;
+    productId?: string | undefined;
+  }) {
+    const form = new FormData();
+    // Fields before the file: the route reads them in any order, but the
+    // order a person would read them in costs nothing.
+    if (file.factoryId) form.set('factoryId', file.factoryId);
+    if (file.productId) form.set('productId', file.productId);
+    form.set('file', new Blob([file.content], { type: file.mime }), file.fileName);
+    return this.request<{ data: unknown; deduplicated?: boolean }>('POST', '/custom-documents', form);
+  }
+
+  async retryKnowledge(id: string) {
+    return this.request<{ data: unknown }>('POST', `/custom-documents/${seg(id)}/retry`);
+  }
+
+  async deleteKnowledge(id: string) {
+    return this.request<{ data?: unknown } | null>('DELETE', `/custom-documents/${seg(id)}`);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Autonomy
+  // ---------------------------------------------------------------------------
+
+  async updateProduct(
+    productId: string,
+    body: { autoMerge?: boolean | null | undefined; autoBuild?: boolean | undefined }
+  ) {
+    return this.request<{ data: unknown }>('PATCH', `/products/${seg(productId)}`, body);
+  }
+
+  async updateBacklogItem(itemId: string, body: { autoMerge?: boolean | null | undefined }) {
+    return this.request<{ data: unknown }>('PATCH', `/backlog/${seg(itemId)}`, body);
+  }
+
   // ---------------------------------------------------------------------------
   // Factories
   // ---------------------------------------------------------------------------