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

package/src/tools/catalogue.test.ts

@@ -1,170 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { McpServer, InMemoryTransport } from '@modelcontextprotocol/server';
-import { Client } from '@modelcontextprotocol/client';
-import {
-  FACTORY_DOCUMENT_TYPES,
-  POLICY_TYPES,
-  PRODUCT_DOCUMENT_TYPES,
-  PRODUCT_STATUSES,
-  TENANT_DOCUMENT_TYPES,
-} from '@taiga/types';
-import { TaigaClient } from '../client.js';
-import { registerAllTools, writeNotice } from './index.js';
-import { SERVER_INSTRUCTIONS, SERVER_INSTRUCTIONS_LIMIT } from './instructions.js';
-import { PRODUCT_DOCUMENT_NAMES } from './catalogue.js';
-
-/**
- * What the model reads must match what exists. The walk-through that led to
- * this file found two policy types named in a description that no tenant
- * has; a model that follows a description into a type the API refuses learns
- * to stop asking.
- */
-
-const ALL_CAPABILITIES = [
-  'products:read',
-  'factories:read',
-  'factories:documents:write',
-  'tenant:documents:read',
-  'tenant:documents:write',
-  'backlog:read',
-  'backlog:write',
-  'products:write',
-  'customDocuments:read',
-  'customDocuments:write',
-  'customDocuments:delete',
-  'factories:write',
-  'vcs:read',
-  'vcs:manage',
-];
-
-async function connected() {
-  vi.stubGlobal(
-    'fetch',
-    vi.fn().mockResolvedValue({
-      ok: true,
-      status: 200,
-      json: async () => ({
-        data: { userId: 'u', tenantId: 't', email: 'e', role: 'owner', capabilities: ALL_CAPABILITIES },
-      }),
-      text: async () => '',
-    })
-  );
-  const taigaClient = new TaigaClient({ baseUrl: 'https://api.test.com', apiKey: 'k' });
-  await taigaClient.introspect();
-  const server = new McpServer({ name: 't', version: '0' });
-  registerAllTools(server, taigaClient);
-  const client = new Client({ name: 'c', version: '0' });
-  const [ct, st] = InMemoryTransport.createLinkedPair();
-  await Promise.all([server.connect(st), client.connect(ct)]);
-  return client;
-}
-
-async function allTools() {
-  return (await (await connected()).listTools()).tools;
-}
-
-/** Every description a client sees: tools, resource templates, prompts and their arguments. */
-async function everyDescription(): Promise<string> {
-  const client = await connected();
-  const [tools, templates, prompts] = await Promise.all([
-    client.listTools(),
-    client.listResourceTemplates(),
-    client.listPrompts(),
-  ]);
-  return JSON.stringify([tools.tools, templates.resourceTemplates, prompts.prompts]);
-}
-
-/** Every `policy_*` token in a text. */
-const policyTokens = (text: string) => [...new Set(text.match(/\bpolicy_[a-z_]+\b/g) ?? [])];
-
-describe('tool descriptions against the catalogue', () => {
-  beforeEach(() => vi.restoreAllMocks());
-
-  it('names no policy type the catalogue lacks, in any description, schema, template or prompt', async () => {
-    const text = (await everyDescription()) + SERVER_INSTRUCTIONS;
-
-    for (const token of policyTokens(text)) {
-      expect(TENANT_DOCUMENT_TYPES as readonly string[], token).toContain(token);
-    }
-  });
-
-  it('names no tool that is not registered, in any description, template, prompt or the instructions', async () => {
-    const client = await connected();
-    const registered = new Set((await client.listTools()).tools.map((t) => t.name));
-    const text = (await everyDescription()) + SERVER_INSTRUCTIONS;
-
-    for (const name of new Set(text.match(/\btaiga_[a-z_]+\b/g) ?? [])) {
-      // Prompts carry the same prefix; they are registered too.
-      const prompts = new Set((await client.listPrompts()).prompts.map((p) => p.name));
-      expect(registered.has(name) || prompts.has(name), name).toBe(true);
-    }
-  });
-
-  it('names every policy where the company documents are explained', async () => {
-    const tools = await allTools();
-    // One tool lists and reads the company documents.
-    const get = tools.find((t) => t.name === 'taiga_get_document')!;
-    const list = get;
-    const typeEnum = (get.inputSchema.properties as Record<string, { enum?: string[] }>)['type']!.enum;
-
-    for (const type of POLICY_TYPES) {
-      expect(list.description, type).toContain(type);
-    }
-    expect(typeEnum).toEqual([...TENANT_DOCUMENT_TYPES]);
-  });
-
-  it('offers exactly the product statuses, product document types and origins the API has', async () => {
-    const tools = await allTools();
-    const props = (name: string) =>
-      tools.find((t) => t.name === name)!.inputSchema.properties as Record<string, { enum?: string[] }>;
-
-    expect(props('taiga_list_products')['status']!.enum).toEqual([...PRODUCT_STATUSES]);
-    expect(props('taiga_get_product_document')['type']!.enum).toEqual([...PRODUCT_DOCUMENT_TYPES]);
-    expect(props('taiga_get_product_document')['origin']!.enum).toEqual(['plan', 'reality']);
-    expect(props('taiga_get_factory_document')['type']!.enum).toEqual([...FACTORY_DOCUMENT_TYPES]);
-  });
-
-  it('has a display name for every product document type, the one the web uses', () => {
-    expect(Object.keys(PRODUCT_DOCUMENT_NAMES).sort()).toEqual([...PRODUCT_DOCUMENT_TYPES].sort());
-    // apps/web/src/lib/documentTypes.ts: "Look & Feel", not "UI Direction".
-    expect(PRODUCT_DOCUMENT_NAMES.ui_direction).toBe('Look & Feel');
-  });
-
-  it('explains both timelines where a product document is read', async () => {
-    const tools = await allTools();
-    const origin = (
-      tools.find((t) => t.name === 'taiga_get_product_document')!.inputSchema.properties as Record<
-        string,
-        { description?: string }
-      >
-    )['origin']!.description;
-    expect(origin).toMatch(/plan: .*discovery/);
-    expect(origin).toMatch(/reality: .*merged pull request/);
-  });
-
-  it('fits the whole instructions inside what Claude Code keeps, and says where to start and when to ask', () => {
-    // Claude Code loads only tool names and the instructions until the model
-    // searches, and cuts the instructions at 2,048 characters (PRO-2800).
-    expect(SERVER_INSTRUCTIONS.length).toBeLessThanOrEqual(SERVER_INSTRUCTIONS_LIMIT);
-    for (const must of ['taiga_get_product_context', 'ask-first', 'NOT_FOUND', 'initiative', 'Only in the web']) {
-      expect(SERVER_INSTRUCTIONS).toContain(must);
-    }
-  });
-});
-
-// PRO-2778: the notice is what tells the model a tool writes, so a tool must say whether it does.
-describe('writeNotice', () => {
-  it('refuses a tool whose annotations do not say whether it is read-only', () => {
-    expect(() => writeNotice('taiga_x', undefined)).toThrow(/taiga_x: annotations must say/);
-    expect(() => writeNotice('taiga_x', {})).toThrow(/annotations must say/);
-  });
-
-  it('says nothing for a read, and what a write does otherwise', () => {
-    expect(writeNotice('r', { readOnlyHint: true })).toBe('');
-    expect(writeNotice('w', { readOnlyHint: false })).toBe('Writes. ');
-    expect(writeNotice('o', { readOnlyHint: false, destructiveHint: true })).toBe('Ask first (others see it). ');
-    expect(writeNotice('taiga_queue_initiative', { readOnlyHint: false, destructiveHint: true })).toBe(
-      'Ask first (paid agent work). '
-    );
-  });
-});

package/src/tools/catalogue.ts

@@ -1,223 +0,0 @@
-/**
- * What exists, from the one place that knows: the shared types package.
- *
- * Tool descriptions are what the model reads to decide what to call, and a
- * description that names a document type the catalogue lacks sends it down a
- * dead end (the walk-through that led here found `policy_acceptable_use` and
- * `policy_ip` named in a description and nowhere else). Every list of types,
- * origins and statuses a tool shows is derived from these constants, and a
- * test holds the descriptions to them.
- */
-import {
-  FACTORY_DOCUMENT_TYPES,
-  POLICY_TYPES,
-  PRODUCT_DOCUMENT_DISPLAY_NAMES,
-  PRODUCT_DOCUMENT_ORIGINS,
-  PRODUCT_DOCUMENT_TYPES,
-  PRODUCT_STATUSES,
-  REALITY_DERIVED_DOCUMENT_TYPES,
-  TENANT_DOCUMENT_TYPES,
-  type ProductDocumentOrigin,
-  type ProductDocumentType,
-  type TenantDocumentType,
-} from '@taiga/types';
-
-export {
-  FACTORY_DOCUMENT_TYPES,
-  POLICY_TYPES,
-  PRODUCT_DOCUMENT_ORIGINS,
-  PRODUCT_DOCUMENT_TYPES,
-  PRODUCT_STATUSES,
-  TENANT_DOCUMENT_TYPES,
-};
-export type { ProductDocumentOrigin, ProductDocumentType };
-
-/**
- * Display names for every product document type. The reviewable nine come
- * from the shared map the web uses; the three the web never asks a person to
- * review are named here, and the record type keeps the two sets complete.
- */
-export const PRODUCT_DOCUMENT_NAMES: Record<ProductDocumentType, string> = {
-  ...PRODUCT_DOCUMENT_DISPLAY_NAMES,
-  // "Look & Feel" is what the web calls it (apps/web/src/lib/documentTypes.ts);
-  // an agent and a person should name the same document the same way.
-  ui_direction: 'Look & Feel',
-  codebase_snapshot: 'Codebase Snapshot',
-  product_instructions: 'Product Instructions',
-};
-
-export function productDocumentName(type: string): string {
-  return (PRODUCT_DOCUMENT_NAMES as Record<string, string>)[type] ?? type;
-}
-
-/** The organization documents that are not policies: goals, standards, voice, instructions. */
-export const OTHER_TENANT_DOCUMENT_TYPES: readonly TenantDocumentType[] = TENANT_DOCUMENT_TYPES.filter(
-  (type) => !(POLICY_TYPES as readonly string[]).includes(type)
-);
-
-/** `a, b, c` for a description. */
-export function named(types: readonly string[]): string {
-  return types.join(', ');
-}
-
-/**
- * The two document timelines of a product (ADR-017), in the words the tools
- * and the server instructions use. One place, so the list tool, the read
- * tool and the instructions cannot explain them three different ways.
- */
-export const ORIGIN_MEANING: Record<ProductDocumentOrigin, string> = {
-  plan: 'plan: the discovery documents, what is meant to be built.',
-  reality:
-    'reality: derived from the code on the main branch, what is built; an imported product has them from ' +
-    'its import, any other once its first initiative is done (a merged pull request) or code is pushed.',
-};
-
-/**
- * Which timeline is a product's own (the API's documentOriginForSettings):
- * an imported product has no plan chain by design, so its documents are on
- * the reality side; everything else starts on the plan side. Derived from the
- * same settings key the API reads, so the two cannot disagree.
- */
-export function isImportedProduct(product: ProductSettingsView | null | undefined): boolean {
-  const settings = product?.settings;
-  return (
-    typeof settings === 'object' &&
-    settings !== null &&
-    (settings as { projectType?: unknown }).projectType === 'brownfield'
-  );
-}
-
-/**
- * The document types no derivation ever writes: a person records or writes
- * them, so they live on the plan side of every product, imported or not.
- */
-export const PLAN_ONLY_DOCUMENT_TYPES: readonly ProductDocumentType[] = PRODUCT_DOCUMENT_TYPES.filter(
-  (type) => !(REALITY_DERIVED_DOCUMENT_TYPES as readonly string[]).includes(type)
-);
-
-/**
- * The timeline a read should default to: the plan side for a type only a
- * person writes, else the product's own side (reality for an imported
- * product, plan for every other).
- */
-export function defaultOriginFor(
-  product: ProductSettingsView | null | undefined,
-  type?: ProductDocumentType
-): ProductDocumentOrigin {
-  if (type !== undefined && PLAN_ONLY_DOCUMENT_TYPES.includes(type)) return 'plan';
-  return isImportedProduct(product) ? 'reality' : 'plan';
-}
-
-/** The product settings the notes read: the import marker and where the import got to. */
-export interface ProductSettingsView {
-  settings?: unknown;
-}
-
-/**
- * Where an imported product's import got to (`settings.importStatus`, written
- * by the API: pending, analyzing, complete, cancelled, failed). Unknown values
- * read as "not known", never as a promise.
- */
-function importStatusOf(product: ProductSettingsView | null | undefined): string | null {
-  const settings = product?.settings;
-  if (typeof settings !== 'object' || settings === null) return null;
-  const status = (settings as { importStatus?: unknown }).importStatus;
-  return typeof status === 'string' ? status : null;
-}
-
-/** Why a side of the timeline is empty, for a list or a miss that shows one. */
-export function emptyOriginNote(
-  origin: ProductDocumentOrigin,
-  product: ProductSettingsView | null | undefined
-): string {
-  const imported = isImportedProduct(product);
-  if (origin === 'plan') {
-    return imported
-      ? 'This product was imported, so no discovery chain was generated for it: its derived documents are on ' +
-          `the reality side. Only the documents a person writes (${PLAN_ONLY_DOCUMENT_TYPES.map(productDocumentName).join(', ')}) ` +
-          'would appear here.'
-      : 'No plan documents are published yet: they are written during discovery in Taiga.';
-  }
-  if (!imported) {
-    return (
-      'No reality documents yet: they are derived from the code once the first initiative is done (a merged ' +
-      'pull request marks it done) or the repository is pushed to. Until then read the plan side.'
-    );
-  }
-  switch (importStatusOf(product)) {
-    case 'pending':
-      return 'No reality documents yet: the import has not started. Link the repository, then taiga_start_import.';
-    // generating_docs is the retired name for the same in-flight state
-    // (PRO-1161); rows that predate it can still carry it.
-    case 'analyzing':
-    case 'generating_docs':
-      return 'No reality documents yet: the import is running and will derive them from the code.';
-    case 'cancelled':
-      return 'No reality documents: the import was cancelled before it derived any. taiga_start_import runs it again.';
-    case 'failed':
-      return 'No reality documents: the import failed before it derived any. taiga_start_import runs it again.';
-    default:
-      return 'No reality documents: the import derives them from the code, and none have been published.';
-  }
-}
-
-/**
- * What a product in setup waits for, as the next call to make. Nothing on a
- * draft product says it otherwise: discoveryStep names the step and
- * importStatus the import, and the way on from each lives in tool
- * descriptions an agent reads only when it already knows which. Null once the
- * product is active.
- */
-export function setupNextStep(
-  product: (ProductSettingsView & { status?: unknown; discoveryStep?: unknown }) | null | undefined
-): string | null {
-  if (product?.status !== 'draft') return null;
-  if (isImportedProduct(product)) {
-    switch (importStatusOf(product)) {
-      case 'analyzing':
-      case 'generating_docs':
-        return (
-          'The import is running and derives the documents from the code (taiga_wait_for_job follows its job). ' +
-          'Then review them, and taiga_finish_discovery opens the product.'
-        );
-      case 'complete':
-        return (
-          'The import is done: review the reality documents (taiga_get_product_document without type), then ' +
-          'taiga_finish_discovery opens the product.'
-        );
-      case 'failed':
-      case 'cancelled':
-        return 'The last import did not finish: taiga_start_import runs it again.';
-      default:
-        return (
-          'Link its repository if it has none (taiga_list_linkable_repositories, taiga_link_repository), then ' +
-          'taiga_start_import: the import derives the documents from the code and runs by itself.'
-        );
-    }
-  }
-  // Unknown is not "not started": a write's answer leaves the step out, and
-  // the default below would send a product at its documents back to the
-  // conversation.
-  if (product.discoveryStep === undefined) return null;
-  switch (product.discoveryStep) {
-    case 'documents':
-      return (
-        'The specification is done; the other documents are generated from it ' +
-        '(taiga_generate_product_documents starts the ones still missing). Once every required one is ' +
-        'published, taiga_finish_discovery opens the product.'
-      );
-    case 'checks':
-      return 'The documents are published; the checks are stamped in the web, then taiga_finish_discovery opens the product.';
-    default:
-      return (
-        'Discovery is a conversation held in the web: the person describes the product there and the ' +
-        'specification comes out of it. The other documents follow, then taiga_finish_discovery opens the product.'
-      );
-  }
-}
-
-/** What discoveryStep says, for a description that shows it. */
-export const DISCOVERY_STEP_MEANING =
-  'discoveryStep is where a product in setup is: context (not started), conversation or import (the ' +
-  'specification being written or derived from code), documents (generated and reviewed), checks (stamped in ' +
-  'the web); null once it is active.';