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

package/src/tools/setup.ts

@@ -1,455 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { DEPLOYMENT_NOTES_MAX_LENGTH, REALITY_DERIVED_DOCUMENT_TYPES } from '@taiga/types';
-import { z } from 'zod';
-import type { Product } from '@taiga/types';
-import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
-import { OPERATE, OPERATE_SETTING, READ_ONLY, WRITE } from './annotations.js';
-import { isImportedProduct } from './catalogue.js';
-import { runTool, toolError, toolResult } from './errors.js';
-import { setupReadiness } from './readiness.js';
-import { withStop } from './hints.js';
-import { idInput, productId } from './inputs.js';
-import { pickFields } from './summarize.js';
-
-/**
- * Setting a product up (docs.tai.ga, Start: Your first product, Learn: Import
- * an existing codebase, Organizations, factories and products): factories to
- * put products in, a product started from scratch or from an imported
- * codebase, what Taiga builds for it, the import, and finishing or reopening
- * Discovery. Who may reach a factory (its members) and deleting a factory or
- * a product stay in the web.
- */
-
-const PRODUCT_FIELDS = [
-  'id',
-  'name',
-  'slug',
-  'status',
-  'factoryId',
-  'ownsInfrastructure',
-  'ownsDeployment',
-  'deploymentNotes',
-  'emitDesignStandards',
-  'settings',
-] as const;
-
-const FACTORY_FIELDS = ['id', 'name', 'slug', 'isDefault'] as const;
-
-const factoryId = idInput('factory', 'taiga_list_factories (query finds one by name) gives it');
-
-const buildScope = {
-  ownsInfrastructure: z
-    .boolean()
-    .nullable()
-    .optional()
-    .describe('Whether Taiga writes the infrastructure code; null follows the organization'),
-  ownsDeployment: z
-    .boolean()
-    .nullable()
-    .optional()
-    .describe('Whether Taiga writes the CI/CD pipelines; null follows the organization'),
-};
-
-const deploymentNotes = z
-  .string()
-  .trim()
-  .min(1)
-  .max(DEPLOYMENT_NOTES_MAX_LENGTH)
-  .describe('When a half is off: a sentence on how it is done today, which Taiga designs and plans against');
-
-/** How a missing required document comes to exist, said with a documents_incomplete refusal. */
-const MISSING_DOCUMENTS_HOW =
-  'An imported product gets them from its import (taiga_start_import); a product started from scratch gets the ' +
-  'specification from the Discovery conversation in the web and the rest from taiga_generate_product_documents. ' +
-  'A draft is published with taiga_publish_product_document.';
-
-type ProductRow = WithoutTenant<Product>;
-
-/**
- * Refuse a name already taken (PRO-2800): the API appends -2 to the slug and
- * creates a second one, so a retried call or two agents at once left
- * duplicates nobody asked for. The API checks it in the create's transaction
- * (PRO-2808), so names past any page and two creates at once are caught too.
- * allowDuplicateName says the person means it.
- */
-const allowDuplicateName = z
-  .boolean()
-  .optional()
-  .describe('Create it even when one with the same name exists (default false: refused, naming the existing one)');
-
-/**
- * The API's refusal of a taken name, as the tool's: it names the one that
- * exists when the caller may read it, and leaves the choice to the person.
- * Another session may have made it, so "use it" would hand the agent someone
- * else's work (PRO-2800, review 6). Anything else is not this refusal.
- */
-function duplicateName(kind: 'factory' | 'product', error: unknown, where: string) {
-  if (!(error instanceof TaigaApiError) || error.status !== 409 || error.details?.['reason'] !== 'duplicate_name') {
-    return null;
-  }
-  const said = (key: string) => (typeof error.details?.[key] === 'string' ? (error.details[key] as string) : undefined);
-  const [existingId, existingSlug, name, createdAt] = [
-    said('existingId'),
-    said('existingSlug'),
-    said('existingName'),
-    said('existingCreatedAt'),
-  ];
-  const which = name ? `A ${kind} named "${name}"` : `A ${kind} with this name`;
-  const ids = existingId ? ` (${existingId}${createdAt ? `, created ${createdAt}` : ''})` : '';
-  // Without the holder's id the caller cannot read it, so "that one" is not a choice they have.
-  const choices = existingId
-    ? "It may not be this person's: ask whether they meant that one, want another name, or want a second"
-    : 'The caller cannot read it: ask whether they want another name or a second';
-  return toolError('DUPLICATE_NAME', `${which} already exists ${where}${ids}. ${choices} (allowDuplicateName: true).`, {
-    ...(existingId ? { existingId } : {}),
-    ...(existingSlug ? { existingSlug } : {}),
-  });
-}
-
-/** A product row the model can act on: how it started, and while in setup what it still needs. */
-async function productRow(client: TaigaClient, product: ProductRow) {
-  const { settings: _settings, ...rest } = pickFields([product], PRODUCT_FIELDS)[0]!;
-  const readiness = await setupReadiness(client, product);
-  return {
-    ...rest,
-    projectType: isImportedProduct(product) ? 'brownfield' : 'greenfield',
-    ...(readiness ? { readiness } : {}),
-  };
-}
-
-/**
- * A half turned off with nothing said about how it is done today. Allowed (the
- * web asks for the sentence but does not insist), so a warning rather than a
- * refusal: plans then design against a gap.
- */
-function missingNotesWarning(product: ProductRow): string[] {
-  const off = product.ownsInfrastructure === false || product.ownsDeployment === false;
-  const notes = typeof product.deploymentNotes === 'string' ? product.deploymentNotes.trim() : '';
-  return off && !notes
-    ? [
-        'A half Taiga does not build has no deploymentNotes: plans cannot design against how it is done today. ' +
-          'Ask the person for a sentence and set it.',
-      ]
-    : [];
-}
-
-/**
- * The sentence is for a half Taiga does not build; the web asks for it only
- * then. When both halves are decided on here, a sentence has nothing to say.
- */
-function notesWithNothingToDescribe(params: {
-  ownsInfrastructure?: boolean | null | undefined;
-  ownsDeployment?: boolean | null | undefined;
-  deploymentNotes?: string | null | undefined;
-}) {
-  return typeof params.deploymentNotes === 'string' &&
-    params.ownsInfrastructure === true &&
-    params.ownsDeployment === true
-    ? toolError(
-        'VALIDATION_ERROR',
-        'deploymentNotes describes a half Taiga does not build; both are on, so leave it out.'
-      )
-    : null;
-}
-
-export function registerSetupTools(server: McpServer, client: TaigaClient) {
-  if (client.hasCapability('factories:write')) {
-    server.registerTool(
-      'taiga_create_factory',
-      {
-        title: 'Create a factory',
-        description:
-          'Create a factory: a group of products sharing knowledge, one instructions document and members. Owners ' +
-          'and admins only; members are added in the web. Then add products with taiga_create_product or ' +
-          'taiga_move_product.',
-        inputSchema: z.object({
-          name: z.string().trim().min(1).max(255).describe('The factory name'),
-          allowDuplicateName: allowDuplicateName,
-        }),
-        annotations: WRITE,
-      },
-      (params) =>
-        runTool(async () => {
-          try {
-            const made = await client.createFactory({
-              name: params.name,
-              refuseDuplicateName: !params.allowDuplicateName,
-            });
-            return toolResult(pickFields([made.data], FACTORY_FIELDS)[0]);
-          } catch (error) {
-            const refused = duplicateName('factory', error, 'in this organization');
-            if (refused) return refused;
-            throw error;
-          }
-        })
-    );
-
-    server.registerTool(
-      'taiga_rename_factory',
-      {
-        title: 'Rename a factory',
-        description:
-          'Rename a factory. Its slug follows the new name, so links to it change; products, members, knowledge ' +
-          'and instructions stay as they are.',
-        inputSchema: z.object({ factoryId, name: z.string().trim().min(1).max(255).describe('The new name') }),
-        annotations: OPERATE_SETTING,
-      },
-      (params) =>
-        runTool(async () =>
-          toolResult(
-            pickFields([(await client.updateFactory(params.factoryId, { name: params.name })).data], FACTORY_FIELDS)[0]
-          )
-        )
-    );
-
-    server.registerTool(
-      'taiga_preview_product_move',
-      {
-        title: 'Preview moving a product to another factory',
-        description:
-          "Show who gains and who loses access if a product moves to another factory: the source factory's members " +
-          "lose it, the target's gain it; people in both, the product's own members, and owners and admins keep " +
-          'it, named with why. Show it to the person before taiga_move_product.',
-        inputSchema: z.object({ productId, factoryId: factoryId.describe('The factory to move it to') }),
-        annotations: READ_ONLY,
-      },
-      (params) =>
-        runTool(async () => toolResult((await client.previewProductMove(params.productId, params.factoryId)).data))
-    );
-
-    server.registerTool(
-      'taiga_move_product',
-      {
-        title: 'Move a product to another factory',
-        description:
-          'Move a product to another factory. Access follows the factory, so this changes who can reach it ' +
-          "(taiga_preview_product_move says who). The product's own knowledge moves with it; factory knowledge and " +
-          'instructions stay. Refused (WORK_IN_FLIGHT) while a plan or run is in flight; then ask the person: ' +
-          'stopLine: true stops the line first, interrupting that work.',
-        inputSchema: z.object({
-          productId,
-          factoryId: factoryId.describe('The factory to move it to'),
-          stopLine: z
-            .boolean()
-            .optional()
-            .describe('Stop the line first, interrupting the plan or build in flight; only when the person says so'),
-        }),
-        annotations: OPERATE,
-      },
-      (params) =>
-        runTool(async () => {
-          let moved;
-          try {
-            moved = await client.moveProduct(params.productId, {
-              factoryId: params.factoryId,
-              ...(params.stopLine ? { stopLine: true } : {}),
-            });
-          } catch (error) {
-            // The API's own words say "Stop the line, then move the product",
-            // which reads as an instruction to the agent; whether to interrupt
-            // the work is the person's call (PRO-2800).
-            if (error instanceof TaigaApiError && error.code === 'WORK_IN_FLIGHT') {
-              return toolError(
-                'WORK_IN_FLIGHT',
-                // The API's first sentence says what is in flight; its second ("Stop the line, then move the product")
-                // is the instruction this replaces.
-                `${withStop((error.apiMessage ?? 'Work is in flight on this product').split(/(?<=[.!?])\s/)[0]!)} Moving it now means stopping ` +
-                  'the line, which interrupts that work: ask the person, and pass stopLine: true only if they say so.',
-                error.details
-              );
-            }
-            throw error;
-          }
-          return toolResult({
-            product: await productRow(client, moved.data),
-            changed: moved.changed,
-            previousFactoryId: moved.previousFactoryId,
-            lineStopped: moved.lineStopped,
-            failedDocuments: moved.failedDocuments,
-          });
-        })
-    );
-  }
-
-  if (!client.hasCapability('products:write')) return;
-
-  server.registerTool(
-    'taiga_create_product',
-    {
-      title: 'Create a product',
-      description:
-        'Create a product in a factory and return it with readiness (what it needs next). start cannot change ' +
-        'later. import (brownfield): Taiga drafts the documents from existing code; link it with ' +
-        'taiga_link_repository (owners and admins only), then taiga_start_import. scratch (greenfield): Discovery ' +
-        'is a conversation in the web that writes the specification. Infrastructure code and CI/CD ' +
-        'pipelines follow the organization unless set here; when one is off, deploymentNotes says how that half ' +
-        'is done today. Add source material first with taiga_add_knowledge (productId): Discovery writes from it.',
-      inputSchema: z.object({
-        factoryId,
-        name: z.string().trim().min(1).max(255).describe('The product name'),
-        start: z.enum(['scratch', 'import']).describe('scratch: describe it in Discovery; import: from a repository'),
-        ...buildScope,
-        deploymentNotes: deploymentNotes.optional(),
-        allowDuplicateName: allowDuplicateName,
-      }),
-      annotations: WRITE,
-    },
-    (params) =>
-      runTool(async () => {
-        const contradiction = notesWithNothingToDescribe(params);
-        if (contradiction) return contradiction;
-        let product: ProductRow;
-        try {
-          product = (
-            await client.createProduct({
-              name: params.name,
-              factoryId: params.factoryId,
-              ...(params.start === 'import' ? { projectType: 'brownfield' as const } : {}),
-              ...(params.ownsInfrastructure !== undefined ? { ownsInfrastructure: params.ownsInfrastructure } : {}),
-              ...(params.ownsDeployment !== undefined ? { ownsDeployment: params.ownsDeployment } : {}),
-              ...(params.deploymentNotes !== undefined ? { deploymentNotes: params.deploymentNotes } : {}),
-              // Within the factory it goes into: the same name in another factory is a different product.
-              refuseDuplicateName: !params.allowDuplicateName,
-            })
-          ).data;
-        } catch (error) {
-          const refused = duplicateName('product', error, 'in this factory');
-          if (refused) return refused;
-          throw error;
-        }
-        return toolResult(await productRow(client, product));
-      })
-  );
-
-  server.registerTool(
-    'taiga_update_product',
-    {
-      title: "Change a product's settings",
-      description:
-        "Change a product's name or what Taiga builds for it. A new name changes the slug, so links change. " +
-        'Infrastructure code and CI/CD pipelines: null returns one to the organization default; deploymentNotes ' +
-        'says how a half Taiga does not build is done; emitDesignStandards: null follows the default for how the ' +
-        'product started. Later plans read the change; planned work is not redone. Autonomy is ' +
-        'taiga_set_product_autonomy.',
-      inputSchema: z.object({
-        productId,
-        name: z.string().trim().min(1).max(255).optional().describe('A new name'),
-        ...buildScope,
-        deploymentNotes: deploymentNotes.nullable().optional(),
-        emitDesignStandards: z
-          .boolean()
-          .nullable()
-          .optional()
-          .describe("Inherit the organization's design standards; null follows the default"),
-      }),
-      annotations: OPERATE_SETTING,
-    },
-    (params) =>
-      runTool(async () => {
-        const { productId: id, ...changes } = params;
-        if (Object.values(changes).every((value) => value === undefined)) {
-          return toolError('VALIDATION_ERROR', 'Change at least one setting.');
-        }
-        const contradiction = notesWithNothingToDescribe(params);
-        if (contradiction) return contradiction;
-        const updated = (await client.updateProduct(id, changes)).data;
-        const warnings = missingNotesWarning(updated);
-        return toolResult({ ...(await productRow(client, updated)), ...(warnings.length > 0 ? { warnings } : {}) });
-      })
-  );
-
-  server.registerTool(
-    'taiga_refresh_reality_documents',
-    {
-      title: "Refresh a product's documents from its code",
-      description:
-        'Derive the reality documents again from the code on the branch Taiga works on (effectiveBranch): all, ' +
-        'or the ones named. For a document the import misread, refresh it instead of importing again; unchanged ' +
-        'sections are not republished. Returns the job; taiga_wait_for_job says when it is done.',
-      inputSchema: z.object({
-        productId,
-        docTypes: z
-          .array(z.enum(REALITY_DERIVED_DOCUMENT_TYPES))
-          .min(1)
-          .max(REALITY_DERIVED_DOCUMENT_TYPES.length)
-          .optional()
-          .describe('The documents to refresh; omit for all'),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => toolResult((await client.refreshRealityDocuments(params.productId, params.docTypes)).data))
-  );
-
-  server.registerTool(
-    'taiga_finish_discovery',
-    {
-      title: 'Finish Discovery',
-      description:
-        "Finish a product's Discovery: it locks the documents and opens the rest of the product; for an imported " +
-        'product the first initiatives are planned. Refused (CONFLICT) with details.reason: documents_incomplete ' +
-        '(details.missingDocuments lists them and how they are made), not_in_setup (already finished), or a ' +
-        'required check not yet stamped (stamped in the web). A locked document changes only after ' +
-        'taiga_reopen_discovery. The person decides the documents are right: ask first.',
-      inputSchema: z.object({ productId }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        try {
-          return toolResult(await productRow(client, (await client.completeSetup(params.productId)).data));
-        } catch (error) {
-          // The refusal names what is missing; it does not say how a missing
-          // document comes to exist, which is what the agent asks next.
-          if (!(error instanceof TaigaApiError) || error.details?.['reason'] !== 'documents_incomplete') throw error;
-          return toolError(
-            error.code ?? 'CONFLICT',
-            `${withStop(error.apiMessage ?? 'Required documents are not published yet')} ${MISSING_DOCUMENTS_HOW}`,
-            error.details
-          );
-        }
-      })
-  );
-
-  server.registerTool(
-    'taiga_reopen_discovery',
-    {
-      title: 'Reopen Discovery',
-      description:
-        "Reopen a finished product's Discovery so its documents can be amended; finish it again afterwards. " +
-        'Nothing built from them is undone.',
-      inputSchema: z.object({ productId }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => toolResult(await productRow(client, (await client.reopenSetup(params.productId)).data)))
-  );
-
-  if (!client.hasCapability('products:read')) return;
-
-  server.registerTool(
-    'taiga_start_import',
-    {
-      title: 'Import a codebase into a product',
-      description:
-        'Start importing a product created for import, and return the job. Taiga reads the linked repository and ' +
-        'derives the full document set from the code, citing the files. Then the scanners sweep it, the ' +
-        'documents are assessed against policies, and the first initiatives are planned when Discovery finishes. ' +
-        'Refused for a scratch product, without a linked repository, or while an import runs. taiga_wait_for_job ' +
-        'says when it is done (it takes a while).',
-      inputSchema: z.object({ productId }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        const product = (await client.getProduct(params.productId)).data;
-        if (!isImportedProduct(product)) {
-          return toolError(
-            'CONFLICT',
-            'This product was started from scratch, so it has no import: the choice is made when a product is created.'
-          );
-        }
-        return toolResult((await client.startImport(params.productId)).data);
-      })
-  );
-}

package/src/tools/summarize.test.ts

@@ -1,20 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { pickFields } from './summarize.js';
-
-describe('pickFields', () => {
-  const rows: { id: string; name?: string; content?: string }[] = [
-    { id: 'a', name: 'A', content: 'the prose a list leaves out' },
-    { id: 'b' },
-  ];
-
-  it('keeps the named fields and leaves out one an item does not carry', () => {
-    expect(pickFields(rows, ['id', 'name'])).toEqual([{ id: 'a', name: 'A' }, { id: 'b' }]);
-  });
-
-  it('refuses a field the row type does not have', () => {
-    // The *_FIELDS lists are checked against their rows, so a misspelled field
-    // fails to compile instead of silently picking nothing (tsc covers tests).
-    // @ts-expect-error -- 'nmae' is not a field of the row.
-    expect(pickFields([{ id: 'a', name: 'A' }], ['id', 'nmae'])).toEqual([{ id: 'a' }]);
-  });
-});

package/src/tools/summarize.ts

@@ -1,96 +0,0 @@
-/**
- * Keep only the named fields of each item. List tools return summaries (the
- * fields a model needs to pick an item) and get tools return everything;
- * this is how a list drops the prose and the provenance trees.
- */
-export function pickFields<T extends object, K extends keyof T>(
-  items: readonly T[],
-  fields: readonly K[]
-): Partial<Pick<T, K>>[] {
-  return items.map((item) => {
-    // Partial: a field the item does not carry is left out, not set to undefined.
-    const picked: Partial<Pick<T, K>> = {};
-    for (const field of fields) {
-      if (field in item) picked[field] = item[field];
-    }
-    return picked;
-  });
-}
-
-/** The page a list tool returns: the rows the model asked for and where the next page starts. */
-export function page<T>(data: T[], nextCursor: string | null | undefined): { data: T[]; nextCursor: string | null } {
-  return { data, nextCursor: nextCursor ?? null };
-}
-
-/**
- * How many of an initiative's acceptance criteria are met: one pair a row can
- * carry, so "done with two unmet" shows in a list without reading the item.
- * Null while it has none (an unplanned initiative).
- */
-export function criteriaCounts(item: { acceptanceCriteria?: unknown }): { met: number; total: number } | null {
-  const criteria = item.acceptanceCriteria;
-  if (!Array.isArray(criteria) || criteria.length === 0) return null;
-  const met = criteria.filter((c) => typeof c === 'object' && c !== null && (c as { met?: unknown }).met === true);
-  return { met: met.length, total: criteria.length };
-}
-
-/**
- * Initiative rows cut to `fields`, each with its criteria counts. A row that
- * does not carry `acceptanceCriteria` at all gets no count rather than a
- * null that would read as "has none".
- */
-export function itemRows<T extends { acceptanceCriteria?: unknown }, K extends keyof T>(
-  items: readonly T[],
-  fields: readonly K[]
-): (Partial<Pick<T, K>> & { criteria?: { met: number; total: number } | null })[] {
-  return pickFields(items, fields).map((row, index) =>
-    'acceptanceCriteria' in items[index]! ? { ...row, criteria: criteriaCounts(items[index]!) } : row
-  );
-}
-
-/** Pages a name search reads before it stops and says so: 1,000 rows at the API's page ceiling. */
-const SEARCH_PAGE_LIMIT = 10;
-
-/**
- * Rows whose text contains `query`, ignoring case, read page by page until
- * `limit` match or the rows run out. The API has no name search, and a model
- * told the person's word for a thing ("the Sandbox factory") otherwise pages
- * the whole list to find its ID. `more` is true when it stopped before the end.
- */
-export async function searchPages<T>(
-  fetchPage: (cursor: string | undefined) => Promise<{ data: T[]; nextCursor: string | null }>,
-  query: string,
-  text: (row: T) => unknown[],
-  limit: number,
-  /** A further condition a row must meet, besides the query. */
-  keep: (row: T) => boolean = () => true
-): Promise<{ rows: T[]; more: boolean }> {
-  const needle = query.toLowerCase();
-  const rows: T[] = [];
-  let cursor: string | undefined;
-  for (let index = 0; index < SEARCH_PAGE_LIMIT; index += 1) {
-    const result = await fetchPage(cursor);
-    const page = result.data;
-    for (const [at, row] of page.entries()) {
-      if (!keep(row)) continue;
-      if (!text(row).some((value) => typeof value === 'string' && value.toLowerCase().includes(needle))) continue;
-      rows.push(row);
-      // Full: stop reading. \`more\` then means "there may be more", not
-      // that a further match was seen; reading on to find out cost up to ten
-      // sequential pages for one bit.
-      if (rows.length === limit) return { rows, more: at < page.length - 1 || result.nextCursor !== null };
-    }
-    if (!result.nextCursor) return { rows, more: false };
-    cursor = result.nextCursor;
-  }
-  return { rows, more: true };
-}
-
-/** The page size a search reads at: the API's ceiling. */
-export const SEARCH_PAGE_SIZE = 100;
-
-/** A search reads its own pages, so a cursor from a plain page has nothing to continue. */
-export const SEARCH_WITH_CURSOR = 'A search answers one page; narrow the query instead of paging it.';
-
-/** What a search says when it stopped before reading every row. */
-export const SEARCH_NOTE = 'There may be more matches than the limit carries; narrow the query or raise the limit.';