@taiga-ai/mcp-server 0.25.0-rc.474 → 0.26.0-dev.481

package/src/tools/observe.ts

@@ -1,311 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { ENVIRONMENT_TYPES } from '@taiga/types';
-import { z } from 'zod';
-import type { Deployment, Environment } from '@taiga/types';
-import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
-import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
-import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
-import { withNotFoundHint } from './hints.js';
-import { idInput, pagination, productId } from './inputs.js';
-import { page, pickFields } from './summarize.js';
-
-/**
- * What runs where and how it is doing (docs.tai.ga, Deliver: Deployments;
- * Operate: Monitoring). Taiga observes deployments, it does not perform them:
- * the history is mirrored from the provider, so these tools read and never
- * deploy, approve or cancel. Importing history reaches into the connected
- * provider and is an administrator's action in the web.
- */
-
-/** A deployment as a line of history: what shipped where, how it ended, and who shipped it. */
-const DEPLOYMENT_FIELDS = [
-  'id',
-  'environmentId',
-  'status',
-  'commitSha',
-  'commitSubject',
-  'version',
-  'tag',
-  'ref',
-  'prNumber',
-  'buildRunId',
-  'actorLogin',
-  'error',
-  'runUrl',
-  'createdAt',
-  'completedAt',
-] as const;
-
-const ENVIRONMENT_FIELDS = ['id', 'name', 'slug', 'type', 'ordinal', 'status', 'isProtected', 'url'] as const;
-
-/**
- * Deployments as lines, each naming the repository that deployed it: every
- * repository runs its own deployment in an environment, so two running in
- * production are two repositories, not a contradiction (PRO-2528).
- */
-function deploymentLines(rows: WithoutTenant<Deployment>[]) {
-  return rows.map((row) => {
-    // `metadata` is an untyped jsonb column until PRO-2515 types it.
-    const repository = row.metadata?.['repositoryFullName'];
-    return {
-      ...pickFields([row], DEPLOYMENT_FIELDS)[0],
-      repository: typeof repository === 'string' ? repository : null,
-    };
-  });
-}
-
-const environmentId = idInput('environment', 'taiga_list_environments lists them; a product ID is not one');
-/** The windows the pages offer, as the schema's own values rather than a number checked afterwards. */
-const windowDays = z.literal([30, 60, 90]).optional().describe('Days to look back: 30, 60 or 90 (default 30)');
-
-/** Whether a failure is the API's (refused, missing, unreachable) rather than a bug here. */
-const isApiFailure = (error: unknown) => error instanceof TaigaApiError || isNetworkFailure(error);
-
-/** A part that may fail on its own without failing the read: null and the reason, or the value. */
-async function part<T>(read: () => Promise<T>): Promise<{ value: T } | { unavailable: string }> {
-  try {
-    return { value: await read() };
-  } catch (error) {
-    if (!isApiFailure(error)) throw error;
-    return {
-      unavailable: error instanceof TaigaApiError ? `${error.status}: ${error.apiMessage ?? ''}`.trim() : 'unreachable',
-    };
-  }
-}
-
-/** Environment pages read for one answer; a product has a handful, so this is a guard, not a page size. */
-const ENVIRONMENT_PAGES = 5;
-
-/** Every environment of a product, page by page, and whether any were left past the guard. */
-async function allEnvironments(
-  client: TaigaClient,
-  product: string
-): Promise<{ rows: WithoutTenant<Environment>[]; more: boolean }> {
-  const rows: WithoutTenant<Environment>[] = [];
-  let cursor: string | undefined;
-  for (let pageNo = 0; pageNo < ENVIRONMENT_PAGES; pageNo++) {
-    const result = await client.listEnvironments(product, { limit: 100, cursor });
-    rows.push(...result.data);
-    if (!result.nextCursor) return { rows, more: false };
-    cursor = result.nextCursor;
-  }
-  return { rows, more: true };
-}
-
-export function registerObserveTools(server: McpServer, client: TaigaClient) {
-  if (!client.hasCapability('products:read')) return;
-
-  server.registerTool(
-    'taiga_get_deployments',
-    {
-      title: 'Get what runs where',
-      description:
-        "Read what runs in each of a product's environments and its recent deployments, newest first: commit, " +
-        "pull request, status, deployer and, on failure, the provider's error. What runs is the latest " +
-        'successful deployment, so a newer failure shows beside it. History is mirrored from the provider, ' +
-        'including deployments made outside Taiga; syncStatus says when it last synced. environmentId narrows to ' +
-        'one environment. Taiga never deploys.',
-      inputSchema: z.object({ productId, environmentId: environmentId.optional(), ...pagination }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const [environments, current, history, sync] = await Promise.all([
-          allEnvironments(client, params.productId),
-          client.getCurrentDeployments(params.productId),
-          client.listDeployments(params.productId, {
-            environmentId: params.environmentId,
-            limit: params.limit ?? 10,
-            cursor: params.cursor,
-          }),
-          part(() => client.getDeploymentSyncStatus(params.productId)),
-        ]);
-        const now = current.data;
-        // An empty answer says why, as the maintenance read does: no
-        // environment, or none deployed to yet, is not "nothing is wrong".
-        const note =
-          environments.rows.length === 0
-            ? 'This product has no environments yet: an environment is defined with taiga_create_environment, ' +
-              'and its deployments are mirrored from the provider once it is.'
-            : history.data.length === 0 && !params.cursor
-              ? 'No deployments recorded yet: none was mirrored from the provider (syncStatus says when it last ' +
-                'synced), or nothing has been deployed.'
-              : null;
-        return toolResult({
-          environments: pickFields(environments.rows, ENVIRONMENT_FIELDS),
-          ...(environments.more ? { moreEnvironments: true } : {}),
-          running: deploymentLines(now.current ?? []),
-          deploying: deploymentLines(now.deploying ?? []),
-          history: page(deploymentLines(history.data), history.nextCursor),
-          ...('value' in sync
-            ? { syncStatus: sync.value.data }
-            : { syncStatus: null, syncUnavailable: sync.unavailable }),
-          ...(note ? { note } : {}),
-        });
-      })
-  );
-
-  server.registerTool(
-    'taiga_list_environments',
-    {
-      title: "List a product's environments",
-      description:
-        "List a product's environments with ID, type, order and App URL. These are the environment IDs " +
-        'taiga_get_delivery_metrics, taiga_get_monitoring and taiga_update_environment take. ' +
-        'taiga_get_deployments lists them too, with what runs where.',
-      inputSchema: z.object({ productId }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const { rows, more } = await allEnvironments(client, params.productId);
-        return toolResult({
-          data: pickFields(rows, ENVIRONMENT_FIELDS),
-          ...(more ? { more: 'More environments than this answer reads; the rest were left out.' } : {}),
-          ...(rows.length === 0 ? { note: 'No environment is defined yet; taiga_create_environment adds one.' } : {}),
-        });
-      })
-  );
-
-  server.registerTool(
-    'taiga_get_delivery_metrics',
-    {
-      title: 'Get delivery metrics',
-      description:
-        "Read DORA's five delivery metrics for one environment (the page shows production) over 30, 60 or 90 " +
-        'days: deployment frequency, lead time, failed deployment recovery time, change-failure rate and rework ' +
-        'rate, each with its trend against the window before and a performance band (none for rework rate). ' +
-        'Computed from deployments, not incidents; previews and checks do not count. Under ten deployments a ' +
-        'trend is approximate; a metric with no data says so instead of a number.',
-      inputSchema: z.object({ productId, environmentId, windowDays }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const days = params.windowDays ?? 30;
-        return toolResult((await client.getDeliveryMetrics(params.productId, params.environmentId, days)).data);
-      })
-  );
-
-  server.registerTool(
-    'taiga_get_monitoring',
-    {
-      title: "Get a product's monitoring",
-      description:
-        "How a product's environments are doing: each one's health from Taiga's checks of its App URL, uptime " +
-        'and last check (not checked when unverifiable now, baseline learning when new). With environmentId: ' +
-        'uptime over 30, 60 or 90 days and the beacon signals (Core Web Vitals, JavaScript errors, API health); ' +
-        "not set up means no data. Setting up the beacon raises an initiative from the environment's settings in " +
-        'the web.',
-      inputSchema: z.object({
-        productId,
-        environmentId: environmentId.optional(),
-        windowDays,
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const health = await client.getMonitoringHealth(params.productId);
-        if (!params.environmentId) {
-          return toolResult({
-            health: health.data,
-            ...(health.data.length === 0
-              ? {
-                  note:
-                    'No environment is monitored: monitoring starts when an environment has its App URL ' +
-                    '(taiga_create_environment, taiga_update_environment). No health is not good health.',
-                }
-              : {}),
-          });
-        }
-        const days = params.windowDays ?? 30;
-        const env = params.environmentId;
-        const [uptime, experience, clientHealth] = await Promise.all([
-          part(() => client.getMonitoringSignal(params.productId, 'uptime', env, days)),
-          part(() => client.getMonitoringSignal(params.productId, 'rum', env, days)),
-          part(() => client.getMonitoringSignal(params.productId, 'client-health', env, days)),
-        ]);
-        // The API refuses an environment that is not the product's with 404
-        // on every signal: that is a wrong ID, not three signals missing.
-        if (
-          'unavailable' in uptime &&
-          [uptime, experience, clientHealth].every((p) => 'unavailable' in p && p.unavailable.startsWith('404'))
-        ) {
-          // The API's own word, with the environmentId hint, as runTool gives any 404.
-          const said = uptime.unavailable.replace(/^404:\s*/, '') || 'Environment not found';
-          return toolError('NOT_FOUND', withNotFoundHint(said));
-        }
-        const value = (p: { value: { data: unknown } } | { unavailable: string }) =>
-          'value' in p ? p.value.data : { unavailable: p.unavailable };
-        const envHealth = health.data.filter((row) => row.environmentId === env);
-        return toolResult({
-          health: envHealth,
-          ...(envHealth.length === 0
-            ? {
-                note:
-                  'No health for this environment: it has no App URL to check yet (taiga_update_environment ' +
-                  'sets one). No health is not good health.',
-              }
-            : {}),
-          windowDays: days,
-          uptime: value(uptime),
-          realUserExperience: value(experience),
-          clientHealth: value(clientHealth),
-        });
-      })
-  );
-
-  if (!client.hasCapability('products:write')) return;
-
-  server.registerTool(
-    'taiga_create_environment',
-    {
-      title: 'Create an environment',
-      description:
-        "Add an environment a product's software runs in (development, staging, production or its own). " +
-        'Deployments, monitoring and plans are tracked per environment. Taiga gets no access to it: the pipeline ' +
-        'deploys and Taiga learns what happened from source control. Members can do this. Then set its App URL ' +
-        "with taiga_update_environment so monitoring starts. Changes the product's setup for everybody.",
-      inputSchema: z.object({
-        productId,
-        name: z.string().trim().min(1).max(100).describe('What the team calls it, e.g. staging'),
-        type: z.enum(ENVIRONMENT_TYPES).describe('Its kind; production is the one delivery metrics report on'),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        const created = (await client.createEnvironment(params.productId, { name: params.name, type: params.type }))
-          .data;
-        return toolResult(pickFields([created], ENVIRONMENT_FIELDS)[0]);
-      })
-  );
-
-  server.registerTool(
-    'taiga_update_environment',
-    {
-      title: 'Update an environment',
-      description:
-        'Rename an environment, change its kind, or set its public App URL (null clears it). Once an App URL is ' +
-        'saved, Taiga checks availability every few minutes. Marking one production makes it the one delivery ' +
-        "metrics report on. Changes the product's setup for everybody.",
-      inputSchema: z.object({
-        environmentId,
-        name: z.string().trim().min(1).max(100).optional().describe('A new name'),
-        type: z.enum(ENVIRONMENT_TYPES).optional().describe('A new kind'),
-        url: z.string().trim().max(500).url().nullable().optional().describe('The public App URL; null clears it'),
-      }),
-      annotations: OPERATE_SETTING,
-    },
-    (params) =>
-      runTool(async () => {
-        const { environmentId: id, ...changes } = params;
-        if (Object.values(changes).every((value) => value === undefined)) {
-          return toolError('VALIDATION_ERROR', 'Change at least one of name, type or url.');
-        }
-        const updated = (await client.updateEnvironment(id, changes)).data;
-        return toolResult(pickFields([updated], ENVIRONMENT_FIELDS)[0]);
-      })
-  );
-}

package/src/tools/product-documents.ts

@@ -1,184 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-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 } 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.
- */
-
-/** 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_get_product_document without type 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: () => client.getProductDocument(product, type, 'plan'),
-    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 one section's text in a plan-timeline product document's draft; other sections stay. Agents " +
-          'read the published version until taiga_publish_product_document. Refused once Discovery is finished and ' +
-          'the set is locked (reopen it with taiga_reopen_discovery or in the web). Reality documents come from ' +
-          'the code and are not edited.',
-        inputSchema: z.object({
-          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 marked outdated, not rewritten; regenerate them with taiga_regenerate_product_document, or ' +
-        'taiga_generate_product_documents for every outdated and missing one.',
-      inputSchema: z.object({ 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. Once every published " +
-        "document is reviewed, the product's review item in Action Required resolves. Only when the person says " +
-        'they read it; your own reading is not a review.',
-      inputSchema: z.object({ productId, type: reviewableType }),
-      annotations: OPERATE,
-    },
-    (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:
-          'Regenerate one product document from the documents it derives from, when it is outdated or needs ' +
-          'another pass, and return the job. The result is published and documents derived from it are marked ' +
-          'outdated. The Specification (from the Discovery conversation) and the Look & Feel (from its concepts) ' +
-          'are made in the web. Documents Discovery requires regenerate only while Discovery is open; the optional ' +
-          'Service Blueprint any time. taiga_wait_for_job says when it is done.',
-        inputSchema: z.object({ 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;
-          return toolResult(jobReport(job));
-        })
-    );
-  }
-
-  server.registerTool(
-    'taiga_generate_product_documents',
-    {
-      title: 'Generate the remaining product documents',
-      description:
-        'Generate every missing or outdated product document (Generate remaining in the web), one after another ' +
-        'in the order they build on each other; on an imported product, every unpublished one. Returns the jobs ' +
-        'it started (jobIds). Refused (CONFLICT) while a document is already being generated. ' +
-        'taiga_stop_generating_documents stops it.',
-      inputSchema: z.object({ 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 (taiga_generate_product_documents): documents still being generated are ' +
-        'cancelled and nothing after them starts; published ones stay. An empty list means none was running.',
-      inputSchema: z.object({ productId }),
-      annotations: OPERATE,
-    },
-    (params) => runTool(async () => toolResult((await client.stopGeneratingDocuments(params.productId)).data))
-  );
-}