@taiga-ai/mcp-server 0.18.0-rc.445 → 0.19.0-dev.451

package/src/tools/inbox.ts

@@ -1,8 +1,8 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import type { TaigaClient } from '../client.js';
+import { TaigaApiError, type TaigaClient } from '../client.js';
 import { OPERATE, READ_ONLY } from './annotations.js';
-import { runTool, toolError, toolResult } from './errors.js';
+import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { idInput, pagination, productId } from './inputs.js';
 import { page, pickFields } from './summarize.js';
 
@@ -16,6 +16,11 @@ import { page, pickFields } from './summarize.js';
 
 type Row = Record<string, unknown>;
 
+/**
+ * An item as a row: what it is, whose product, how long it has waited. Not
+ * its metadata by default: a document decision carried its whole text there,
+ * and fifty rows came to 57 KB (PRO-2800); full: true brings it.
+ */
 const ITEM_FIELDS = [
   'id',
   'productId',
@@ -29,11 +34,54 @@ const ITEM_FIELDS = [
   'status',
   'blocking',
   'snoozedUntil',
-  'metadata',
   'createdAt',
   'resolvedAt',
 ] as const;
 
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** When an item stopped waiting: its resolution, or now while it is open. */
+function waitedUntil(resolvedAt: unknown, now: number): number {
+  const at = typeof resolvedAt === 'string' ? Date.parse(resolvedAt) : NaN;
+  return Number.isNaN(at) ? now : at;
+}
+
+/** A row as an agent reads it: the pull request to open when there is one, and how many days it has waited. */
+function itemRow(row: Row, now: number, full: boolean): Row {
+  const picked = pickFields([row], ITEM_FIELDS)[0]!;
+  const { snoozedUntil, resolvedAt, ...rest } = picked;
+  const metadata = (row['metadata'] ?? {}) as Row;
+  const created = typeof row['createdAt'] === 'string' ? Date.parse(row['createdAt']) : NaN;
+  return {
+    ...rest,
+    ...(snoozedUntil ? { snoozedUntil } : {}),
+    ...(resolvedAt ? { resolvedAt } : {}),
+    ...(typeof metadata['prUrl'] === 'string' ? { prUrl: metadata['prUrl'] } : {}),
+    // A resolved item waited until it was resolved, not until now.
+    ...(Number.isNaN(created) ? {} : { waitingDays: Math.floor((waitedUntil(resolvedAt, now) - created) / DAY_MS) }),
+    ...(full ? { metadata: row['metadata'] } : {}),
+  };
+}
+
+/** What is open, counted by product and kind: the answer to "what needs attention" without reading every row. */
+function summaryOf(rows: Row[]): Row[] {
+  const byProduct = new Map<
+    string,
+    { productId: string; product: unknown; open: number; byKind: Record<string, number> }
+  >();
+  for (const row of rows) {
+    const key = String(row['productId']);
+    const entry = byProduct.get(key) ?? { productId: key, product: row['productName'] ?? key, open: 0, byKind: {} };
+    entry.open += 1;
+    entry.byKind[String(row['kind'])] = (entry.byKind[String(row['kind'])] ?? 0) + 1;
+    byProduct.set(key, entry);
+  }
+  return [...byProduct.values()].sort((a, b) => b.open - a.open);
+}
+
+/** Pages read for the summary; past this it says it counted only those. */
+const SUMMARY_PAGE = 100;
+
 const SETUP_TASK_FIELDS = [
   'id',
   'productId',
@@ -56,6 +104,48 @@ function totalOf(result: { totalCount?: unknown }): { totalCount?: number } {
   return typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {};
 }
 
+/**
+ * One row per variable: tasks filed before the API merged a key's categories
+ * (PRO-2782) still list JWT_SECRET once as a secret and once as an env_var.
+ * The oldest row stays, and names the others under alsoFiledAs, so the
+ * duplicates read as one thing to set with several records, not several things.
+ */
+export function sameKeyOnce(rows: Row[]): Row[] {
+  const first = new Map<string, Row>();
+  const out: Row[] = [];
+  const isOpen = (row: Row) => row['inboxItemStatus'] !== 'done' && row['inboxItemStatus'] !== 'dismissed';
+  for (const row of rows) {
+    if (typeof row['key'] !== 'string' || !row['key']) {
+      out.push(row);
+      continue;
+    }
+    const key = `${String(row['productId'])}:${row['key']}`;
+    const kept = first.get(key);
+    if (!kept) {
+      const copy = { ...row };
+      first.set(key, copy);
+      out.push(copy);
+      continue;
+    }
+    const also = (kept['alsoFiledAs'] as Row[] | undefined) ?? [];
+    const record = (from: Row) => ({
+      id: from['id'],
+      category: from['category'],
+      title: from['title'],
+      inboxItemStatus: from['inboxItemStatus'],
+    });
+    if (!isOpen(kept) && isOpen(row)) {
+      // An open record of the variable leads: a done one must not make it read as done.
+      const { alsoFiledAs: _also, ...was } = kept;
+      for (const field of Object.keys(kept)) delete kept[field];
+      Object.assign(kept, row, { alsoFiledAs: [...also, record(was)] });
+    } else {
+      kept['alsoFiledAs'] = [...also, record(row)];
+    }
+  }
+  return out;
+}
+
 export function registerInboxTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
 
@@ -64,19 +154,24 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
     {
       title: 'List what needs a person',
       description:
-        'Read Action Required, where work comes back to a person: things to review (a plan, a set of ' +
-        'initiatives, a document, a pull request, maintenance findings, new policy violations), each a decision ' +
-        'an agent handed back rather than made, and things to set up that only a person can (a secret, an ' +
-        'environment variable, an account, a package registry, a cloud permission). Across every product the key ' +
-        'can open (each row names its product), or one product. category gate is the reviews, setup the setup items; resolved: true reads the ' +
-        "archive of done and dismissed ones. The inbox is shared: it is the team's, not one person's. " +
-        'An item snoozed until later is left out until then, as the page leaves it out (snoozedHidden counts ' +
-        'them). The first page says how many there are on every page (totalCount, snoozed ones included). ' +
-        'taiga_list_setup_tasks has the setup tasks with what exactly to set.',
+        'Read Action Required, where work comes back to a person, shared by the team: things to review (a plan, ' +
+        'a set of initiatives, a document decision, a pull request, maintenance findings, new policy violations) ' +
+        'and things to set up that only a person can (a secret, an environment variable, an account, a package ' +
+        'registry, a cloud permission). Across every product the key can open, or one product. The first page ' +
+        'opens with summary: what is open, counted by product and kind, so "what needs attention" is one call, ' +
+        'and totalCount. Each row says how many days it has waited (waitingDays) and, for a pull request review, ' +
+        'the prUrl; an old item is still open, not stale. category gate is the reviews, setup the setup items; ' +
+        'resolved: true reads the archive. An item snoozed until later is left out until then (snoozedHidden ' +
+        "counts them). full: true adds each item's metadata. Unlike taiga_list_setup_tasks, which lists the setup " +
+        'items with exactly what to set and where.',
       inputSchema: z.object({
         productId: productId.optional(),
         category: z.enum(['gate', 'setup']).optional().describe('gate: things to review; setup: things to set up'),
         resolved: z.boolean().optional().describe('Read the resolved archive (done and dismissed) instead'),
+        full: z
+          .boolean()
+          .optional()
+          .describe("Carry each item's metadata, such as a document decision's whole text (default false)"),
         ...pagination,
       }),
       annotations: READ_ONLY,
@@ -85,24 +180,47 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
       runTool(async () => {
         // The route coerces any value to a boolean, so "false" would read the
         // archive: send resolved only when it is asked for.
-        const { resolved, ...rest } = params;
-        const result = await client.listInbox({
-          ...rest,
-          ...(resolved ? { resolved: true } : {}),
-          ...(params.cursor === undefined ? { withTotal: true } : {}),
-        });
+        const { resolved, full, ...rest } = params;
+        const query = { ...rest, ...(resolved ? { resolved: true } : {}) };
+        const first = params.cursor === undefined;
+        const result = await client.listInbox({ ...query, ...(first ? { withTotal: true } : {}) });
+        // The summary counts what is open across products, on the first page:
+        // from the page itself when it holds everything, else from one read
+        // of up to SUMMARY_PAGE items. Best effort: a failed read leaves the
+        // summary out, not the page the agent asked for.
+        const overview =
+          !first || resolved
+            ? null
+            : !result.nextCursor
+              ? result
+              : await client.listInbox({ ...query, limit: SUMMARY_PAGE, cursor: undefined }).catch((error: unknown) => {
+                  if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
+                  throw error;
+                });
         // The API returns snoozed items, as they are not done; the page hides
         // one until its snooze ends, and so does this, so an agent does not
         // act on what the team put off.
         const now = Date.now();
+        const isDue = (row: Row) =>
+          !(
+            row['status'] === 'snoozed' &&
+            typeof row['snoozedUntil'] === 'string' &&
+            Date.parse(row['snoozedUntil']) > now
+          );
         const rows = result.data as Row[];
-        const due = rows.filter(
-          (row) =>
-            !(row.status === 'snoozed' && typeof row.snoozedUntil === 'string' && Date.parse(row.snoozedUntil) > now)
-        );
+        const due = rows.filter(isDue);
         const hidden = rows.length - due.length;
         return toolResult({
-          ...page(pickFields(due, ITEM_FIELDS), result.nextCursor),
+          ...(overview
+            ? {
+                summary: summaryOf((overview.data as Row[]).filter(isDue)),
+                ...(overview.nextCursor ? { summaryNote: `The summary counts the first ${SUMMARY_PAGE} items.` } : {}),
+              }
+            : {}),
+          ...page(
+            due.map((row) => itemRow(row, now, full === true)),
+            result.nextCursor
+          ),
           ...totalOf(result),
           ...(hidden > 0 ? { snoozedHidden: hidden } : {}),
         });
@@ -122,7 +240,10 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'A build does not wait for any of them. Across every product the key can open (each row names its ' +
         'product), or one. The tasks still to do, oldest first, the order they depend on each other; ' +
         'includeDone: true adds the done and dismissed ones. The first page says how many there are on every ' +
-        'page (totalCount).',
+        'page (totalCount). One row per variable: a variable filed twice (as a secret and as an environment ' +
+        'variable) lists the other records under alsoFiledAs, an open one first; within a page, and totalCount ' +
+        'counts every record. Unlike taiga_list_action_required, whose setup ' +
+        'items are the same work as rows to resolve, this says exactly what to set and where.',
       inputSchema: z.object({
         productId: productId.optional(),
         includeDone: z.boolean().optional().describe('Also the tasks already done or dismissed (default false)'),
@@ -139,7 +260,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
           ...(params.cursor === undefined ? { withTotal: true } : {}),
         });
         return toolResult({
-          ...page(pickFields(result.data as Row[], SETUP_TASK_FIELDS), result.nextCursor),
+          ...page(sameKeyOnce(pickFields(result.data as Row[], SETUP_TASK_FIELDS)), result.nextCursor),
           ...totalOf(result),
         });
       })
@@ -161,7 +282,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'document was reviewed, and setting it back to in_progress withdraws that; do it only when the person ' +
         'says they read them. Ask the person before clearing what they have not dealt with.',
       inputSchema: z.object({
-        itemId: idInput('Action Required item', 'taiga_list_action_required gives it'),
+        actionId: idInput('Action Required item', 'taiga_list_action_required gives it'),
         status: z.enum(['in_progress', 'done', 'dismissed']).optional().describe('What became of it'),
         snoozedUntil: z
           .string()
@@ -177,11 +298,11 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         if (params.status === undefined && params.snoozedUntil === undefined) {
           return toolError('VALIDATION_ERROR', 'Say what became of the item (status) or until when to snooze it.');
         }
-        const result = await client.updateInboxItem(params.itemId, {
+        const result = await client.updateInboxItem(params.actionId, {
           ...(params.status !== undefined ? { status: params.status } : {}),
           ...(params.snoozedUntil !== undefined ? { snoozedUntil: params.snoozedUntil } : {}),
         });
-        return toolResult(pickFields([result.data as Row], ITEM_FIELDS)[0]);
+        return toolResult(pickFields([result.data], ITEM_FIELDS)[0]);
       })
   );
 }

package/src/tools/index.ts

@@ -46,7 +46,11 @@ function withStrictInputs(server: McpServer): McpServer {
     const handler = callback as (args: unknown, ctx: unknown) => unknown;
     const withHint = (args: unknown, ctx: unknown) =>
       notFoundHints.run(notFoundHint(name, args), () => handler(args, ctx));
-    const described = { ...config, description: `${writeNotice(name, config.annotations)}${config.description ?? ''}` };
+    const described = {
+      ...config,
+      description: `${writeNotice(name, config.annotations)}${config.description ?? ''}`,
+      ...(ALWAYS_LOAD.has(name) ? { _meta: { 'anthropic/alwaysLoad': true } } : {}),
+    };
     return register(name, schema ? { ...described, inputSchema: schema.strict() } : described, withHint);
   }) as unknown as McpServer['registerTool'];
   return server;
@@ -54,6 +58,16 @@ function withStrictInputs(server: McpServer): McpServer {
 
 type ToolAnnotations = { readOnlyHint?: boolean; destructiveHint?: boolean };
 
+/**
+ * The entry points, loaded with their descriptions at session start
+ * (PRO-2800). Claude Code defers every other MCP tool behind tool search and
+ * shows the model only its name until it searches, so an agent meeting Taiga
+ * sees these three in full: where a product stands, which products there
+ * are, and what waits on a person. Three, because each one loaded upfront
+ * costs every session its description.
+ */
+export const ALWAYS_LOAD = new Set(['taiga_get_product_context', 'taiga_list_products', 'taiga_list_action_required']);
+
 /**
  * What a tool's annotations say, in its description's first words (PRO-2778).
  * Annotations are for the client: Claude Code does not show them to the

package/src/tools/instructions.ts

@@ -1,158 +1,36 @@
-import {
-  OTHER_TENANT_DOCUMENT_TYPES,
-  ORIGIN_MEANING,
-  POLICY_TYPES,
-  PRODUCT_DOCUMENT_NAMES,
-  named,
-} from './catalogue.js';
-
 /**
- * What the server tells a client at connect time: where to start, when to ask
- * before writing, the words, then the knowledge base, the two document
- * timelines, what section metadata means. Kept as data so a test can hold it
- * to the catalogue the same way it holds the tool descriptions.
- *
- * The order is the point. Clients cut long instructions (Claude Code shows
- * about the first 2,000 characters), so what an agent needs before its first
- * call -- start with the context read, ask before paid or shared writes, what
- * a refusal means, which word means what -- comes first, under
- * INSTRUCTIONS_HEAD_LIMIT, and the reference material after it.
+ * What the server tells a client at connect time. Claude Code loads only the
+ * tool NAMES and these instructions until the model searches for a tool, and
+ * cuts each server's instructions at 2,048 characters (code.claude.com, MCP
+ * tool search), so this is the whole introduction an agent gets: what Taiga
+ * holds, when to search these tools, where to start, the words, when to ask,
+ * and what only the web does. Everything else lives in the tool descriptions,
+ * which load with the tool. The earlier instructions ran to about 8,000
+ * characters, and everything past the first 2,000 never reached the model
+ * (PRO-2800).
  */
-export const INSTRUCTIONS_HEAD = [
-  "You have access to Taiga, a policy-aware software development platform: the organization's",
-  'engineering knowledge base, its products, their backlog and what the coding agent has built.',
-  '',
-  '**Start here.** Call taiga_get_product_context first, naming the product by its git remote URL inside a',
-  'checkout (git remote get-url origin), else by slug or ID (taiga_list_products finds one by name with',
-  'query). It returns the product (and, while it is in setup, nextStep: what it waits for), its factory',
-  'instructions, the outline of its specification and architecture, every policy as its section ids, the',
-  'open initiatives, the repositories and the latest runs. Then read only what you need: sections by id with',
-  "taiga_get_document or taiga_get_product_document (sections: [] is any document's outline), an",
-  'initiative with taiga_get_backlog_item. Check Action Required (taiga_list_action_required) for what',
-  'waits on a person.',
-  '',
-  '**Before you write.** Tell the person what you are about to do and wait for their yes before a tool that',
-  'starts paid agent work (queueing, approving, resuming, requesting, importing, generating), interrupts it',
-  '(stopping, pausing) or changes what others read (publishing, resolving, settings, repositories). Such a',
-  'tool says so first in its description; a client that prompts on destructive tools does part of it.',
-  '',
-  '**Answers.** A refusal carries the API reason: say it as it is. NOT_FOUND names the tool that lists the',
-  'right IDs; an ID is a UUID, never a name. An empty result says why when it has a reason.',
-  '',
-  '**Words.** A backlog item is an initiative; a build is a run, the record of one attempt at it; Action',
-  'Required is the inbox; the line is the queue; a factory is the group that owns a set of products.',
-].join('\n');
-
-/** The most the head may take: under what a client shows before it cuts. */
-export const INSTRUCTIONS_HEAD_LIMIT = 1900;
-
 export const SERVER_INSTRUCTIONS = [
-  INSTRUCTIONS_HEAD,
-  '',
-  '**Company documents** (taiga_list_documents / taiga_get_document):',
-  `The ${POLICY_TYPES.length} policies (${named(POLICY_TYPES)}) carry the security, data, SDLC, operations and`,
-  `architecture rules that apply to all code. The other documents (${named(OTHER_TENANT_DOCUMENT_TYPES)})`,
-  'carry the business goals, design and brand standards, tone of voice and standing instructions.',
-  'Read the relevant policy BEFORE writing code that touches security, data handling or infrastructure.',
-  '',
-  '**Factory instructions** (taiga_list_factory_documents / taiga_get_factory_document):',
-  "A factory's standing guidance: domain context (ubiquitous language, entities, business rules),",
-  'tech preferences (approved stack, patterns) and conventions. Read these to understand HOW this factory',
-  'builds software. A factory that has not written any yet has none; that is normal.',
-  '',
-  '**Product documents** (taiga_list_product_documents / taiga_get_product_document):',
-  `${Object.entries(PRODUCT_DOCUMENT_NAMES)
-    .map(([type, name]) => `${name} (${type})`)
-    .join(', ')}.`,
-  'A product has two timelines of these, and the list shows both:',
-  `- ${ORIGIN_MEANING.plan}`,
-  `- ${ORIGIN_MEANING.reality}`,
-  'An imported (brownfield) product has no generated discovery chain: its derived documents are on the',
-  'reality side, while the documents a person writes (Look & Feel, Product Instructions) are on the plan',
-  'side of every product. Omit origin on a read and the server picks the right side (the list reports the',
-  "product's own as defaultOrigin). To understand",
-  'what to build, read the plan where there is one; to understand the code you are changing, read reality',
-  'when it exists, the ground truth for architecture, data flow and threats as built.',
-  '',
-  '**Backlog and runs** (taiga_list_backlog_items / taiga_get_backlog_item / taiga_list_builds / taiga_get_build):',
-  "The product's initiatives with their acceptance criteria, and what Taiga's coding agent already built",
-  'for them: runs, steps, commits and pull requests. taiga_list_builds without a product lists the runs of',
-  'every product the key can see, and active: true the ones executing now.',
-  '',
-  '**Operating the line** works the way Taiga is meant to be used. New work is described, not written:',
-  'taiga_request_initiatives asks an agent, which reads the product and its repository, expands the request',
-  'into initiatives in the Backlog (or says why it added none: already covered, not work, out of scope, or a',
-  'policy that does not allow it) -- follow it with taiga_wait_for_job. The queue is the only way to start',
-  'work (taiga_queue_backlog_item): Taiga plans and builds one initiative at a time, in queue order, and starts',
-  'the next when the pull request merges. Whether a landed plan waits for a review is the review gate',
-  '(taiga_set_auto_build, or autoBuild on the queue); read it with taiga_get_plan and answer with',
-  'taiga_approve_plan or taiga_reject_plan. Decisions about the work are made on the initiative: stop work by',
-  'moving it out of Build (taiga_move_backlog_item), carry it on with taiga_resume_backlog_item, ask for a new',
-  'plan with taiga_plan_again; a run is the record of an attempt. taiga_pause_line pauses the whole line.',
-  'taiga_stop_build is the emergency brake for a run whose initiative cannot be moved. Queueing, approving,',
-  'resuming and requesting start paid agent work; stopping and pausing interrupt it. Tell the person what you',
-  'are about to start or stop and wait for their yes; a client that prompts on destructive tools does that',
-  'for you. A refusal (CONFLICT) carries the API reason: say it as it is.',
-  '',
-  '**Watching the line** (taiga_get_queue / taiga_wait_for_backlog_item / taiga_wait_for_build /',
-  'taiga_get_job / taiga_wait_for_job): the queue read says what the line is waiting on (a paused line, a plan',
-  'to review, a pull request to merge, a halt and what lifts it). Planning takes minutes and a build up to an',
-  'hour: wait with the wait tools rather than reading the same item again and again; each returns when the',
-  'point is reached, when only a person can move it on, or at its timeout (call again to keep waiting).',
-  '',
-  '**Action Required** (taiga_list_action_required / taiga_list_setup_tasks / taiga_resolve_action): where work',
-  'comes back to a person, shared by the team. Check it first. Resolving an item clears it for everybody; a',
-  'setup task is marked done only by the person who did the setup.',
-  '',
-  '**Maintaining** (taiga_get_maintenance / taiga_list_findings / taiga_get_finding / taiga_ignore_finding /',
-  'taiga_fix_finding / taiga_get_policy_standing / taiga_fix_policy_violation): what the sweeps found and where',
-  'the product stands against its own policies. Sweeps run on their own; check when the last one ran before',
-  'trusting a quiet list. A finding is ignored with a reason or fixed; a fix raises an initiative at the end of',
-  'the queue. Nothing is marked fixed by hand: the next sweep or assessment decides.',
-  '',
-  '**Deployments and monitoring** (taiga_get_deployments / taiga_get_delivery_metrics / taiga_get_monitoring /',
-  'taiga_define_environment / taiga_update_environment): what runs where, how delivery is going, and how each',
-  'environment is doing. Taiga observes deployments and never performs them. An environment needs only its App',
-  'URL for monitoring to start.',
-  '',
-  '**Knowledge** (taiga_list_knowledge / taiga_get_knowledge / taiga_add_knowledge / taiga_retry_knowledge /',
-  'taiga_delete_knowledge): reference material agents search when work calls for it, at the organization, a',
-  'factory or a product. A rule that applies every time belongs in instructions instead.',
-  '',
-  '**Setting a product up** (taiga_create_factory / taiga_create_product / taiga_update_product /',
-  'taiga_list_linkable_repositories / taiga_link_repository / taiga_start_import / taiga_finish_discovery /',
-  'taiga_reopen_discovery / taiga_move_product): a product starts from scratch (Discovery is a conversation,',
-  'held in the web) or by importing a repository, chosen when it is created. An import links the repository,',
-  'starts the import and runs by itself; finishing Discovery locks the documents and opens the rest of the',
-  'product. Linking a repository and creating or moving factories are for owners and admins. GitHub is',
-  'connected once, in the web; members and deleting stay there too.',
-  '',
-  '**Product documents and autonomy** (taiga_update_product_document / taiga_publish_product_document /',
-  'taiga_regenerate_product_document / taiga_generate_product_documents / taiga_stop_generating_documents /',
-  'taiga_mark_product_document_reviewed /',
-  'taiga_set_product_autonomy / taiga_set_auto_merge): edit a product document in its draft and publish it;',
-  'documents built from it are marked outdated and regenerated, not rewritten. Set whether plans wait for a',
-  'review and pull requests for a person to merge. Organization-wide settings, members, roles and connections',
-  "are administrators' work in the web.",
-  '',
-  '**Sections.** Policies and instructions are maps of sections. Each section carries its text and two',
-  'provenance fields you can read past: `source` says where the text originally came from (template:',
-  "Taiga's standard text; overlay-<id>: a jurisdiction or industry overlay; cloud-preset:<providers>:",
-  "rendered for the organization's cloud providers; any other tag names the derivation that wrote the",
-  'text; a hand edit keeps the source it had) and',
-  '`priority: core` marks the sections every organization keeps. Neither changes what the section',
-  'requires of you.',
-  '',
-  'Without taiga_get_product_context, use taiga_list_factories and taiga_list_products, then read the',
-  "factory instructions, the product's specification and architecture, and the initiative you are working",
-  'on. A document read that finds nothing tells you what does exist and which tool reads or writes it.',
-  '',
-  'The same documents are resources (taiga://documents/{type}, taiga://products/{productId}/documents/{type},',
-  'taiga://factories/{factoryId}/instructions, taiga://backlog/{itemId}) for clients that attach them, and three',
-  'prompts open a session: taiga_start_session, taiga_implement_backlog_item, taiga_review_against_policies.',
-  '',
-  'When you notice a policy or factory instructions are outdated, fix the section with',
-  'taiga_update_document or taiga_update_factory_document. That saves a draft nobody follows yet;',
-  'publish it with taiga_publish_document or taiga_publish_factory_document only when the person asks.',
-  'This keeps the knowledge base accurate for everyone.',
+  "Taiga is a policy-aware software delivery platform: an organization's policies and knowledge, its factories",
+  "and products, each product's initiatives (its backlog), the line that plans and builds them one at a time, the",
+  "coding agent's runs and pull requests, maintenance findings, and Action Required, where work waits on a person.",
+  'Search these tools whenever the person asks about a Taiga product, an initiative, a run or pull request, policy',
+  'or compliance, findings, deployments or monitoring, or setting a product up.',
+  '',
+  '**Start here.** taiga_get_product_context (the product by git remote URL, slug or ID) gives its state in one',
+  'call: what it still needs while in setup, its documents as outlines, policies as section ids, open initiatives,',
+  'recent runs with their outcome, and what waits on a person. Then read only what you need. Across products,',
+  'taiga_list_products and taiga_list_action_required.',
+  '',
+  '**Words.** An initiative is a unit of work in the backlog; a run is one attempt by the coding agent to build it;',
+  "the line is the product's queue; a factory owns a set of products. IDs are UUIDs, never names; a NOT_FOUND names",
+  'the tool that lists the right ones. A refusal carries the reason: say it as it is.',
+  '',
+  '**Before you write.** A tool that writes says so first: "Writes." or "Acts on paid or shared work: ask the',
+  'person first." Ask before the second kind: it starts paid agent work, interrupts it, or changes what others see.',
+  '',
+  '**Only in the web:** connecting GitHub, members and roles, the Discovery conversation of a product started from',
+  'scratch, stamping checks, starting a run over, and deleting anything.',
 ].join('\n');
+
+/** The most the instructions may take: Claude Code cuts each server's at 2,048 characters. */
+export const SERVER_INSTRUCTIONS_LIMIT = 2048;

package/src/tools/jobs.ts

@@ -1,8 +1,9 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { createdInitiativeIdsOf, createdInitiativesOf, isBacklogGenerationEmptyResult } from '@taiga/types';
 import { z } from 'zod';
+import type { AgentJob } from '@taiga/types';
 import { idInput } from './inputs.js';
-import type { TaigaClient } from '../client.js';
+import type { TaigaClient, WithoutTenant } from '../client.js';
 import { READ_ONLY } from './annotations.js';
 import { runTool, toolResult } from './errors.js';
 import { pickFields } from './summarize.js';
@@ -13,7 +14,7 @@ import { pickFields } from './summarize.js';
  * it is, and what came of it.
  */
 
-type Row = Record<string, unknown>;
+type Job = WithoutTenant<AgentJob>;
 
 /** What a job says about itself: its kind, how far it got, and why it failed. */
 const JOB_FIELDS = [
@@ -43,7 +44,7 @@ export const SETTLED_JOB_STATUSES: ReadonlySet<string> = new Set(['completed', '
  * own words and the way to decide otherwise). Null while the job runs, and
  * for a job that is not an initiative request.
  */
-function requestOutcome(job: Row): Row | null {
+function requestOutcome(job: Job) {
   if (job.type !== 'generate_backlog' || job.status !== 'completed') return null;
   const created = createdInitiativesOf(job.result);
   if (created) return { outcome: 'created', initiatives: created };
@@ -63,7 +64,7 @@ function requestOutcome(job: Row): Row | null {
 }
 
 /** A job as the tools hand it over: its own fields, and for an initiative request, what came of it. */
-export function jobReport(job: Row): Row {
+export function jobReport(job: Job) {
   const outcome = requestOutcome(job);
   return { ...pickFields([job], JOB_FIELDS)[0], ...(outcome ? { outcome } : {}) };
 }
@@ -85,6 +86,6 @@ export function registerJobTools(server: McpServer, client: TaigaClient) {
       inputSchema: z.object({ jobId: idInput('job', 'the tool that started the job returned it') }),
       annotations: READ_ONLY,
     },
-    (params) => runTool(async () => toolResult(jobReport((await client.getAgentJob(params.jobId)).data as Row)))
+    (params) => runTool(async () => toolResult(jobReport((await client.getAgentJob(params.jobId)).data)))
   );
 }

package/src/tools/knowledge.ts

@@ -15,8 +15,6 @@ import { page, pickFields } from './summarize.js';
  * admin, which the API enforces.
  */
 
-type Row = Record<string, unknown>;
-
 const KNOWLEDGE_FIELDS = [
   'id',
   'factoryId',
@@ -123,7 +121,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
             ? { factoryId: params.factoryId, productId: null }
             : { factoryId: null, productId: null };
         const result = await client.listKnowledge({ ...scope, limit: params.limit, cursor: params.cursor });
-        return toolResult(page(pickFields(result.data as Row[], KNOWLEDGE_FIELDS), result.nextCursor));
+        return toolResult(page(pickFields(result.data, KNOWLEDGE_FIELDS), result.nextCursor));
       })
   );
 
@@ -143,7 +141,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const file = await client.getKnowledge(params.knowledgeId);
-        const row = pickFields([file.data as Row], KNOWLEDGE_FIELDS)[0]!;
+        const row = pickFields([file.data], KNOWLEDGE_FIELDS)[0]!;
         if (row.status !== 'ready') {
           return toolResult({
             ...row,
@@ -213,7 +211,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
         // there: the flag says so, so that file is not taken for a new one
         // (and deleted as one in a clean-up).
         return toolResult({
-          ...pickFields([result.data as Row], KNOWLEDGE_FIELDS)[0],
+          ...pickFields([result.data], KNOWLEDGE_FIELDS)[0],
           deduplicated: result.deduplicated === true,
         });
       })
@@ -231,7 +229,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () =>
-        toolResult(pickFields([(await client.retryKnowledge(params.knowledgeId)).data as Row], KNOWLEDGE_FIELDS)[0])
+        toolResult(pickFields([(await client.retryKnowledge(params.knowledgeId)).data], KNOWLEDGE_FIELDS)[0])
       )
   );