@taiga-ai/mcp-server 0.17.0-dev.441 → 0.18.0-dev.443

package/src/tools/product-documents.ts

@@ -112,7 +112,7 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
         'Action Required resolves. The mark says a human read it, so make it only when the person tells you they ' +
         'have: reading it yourself is not a review.',
       inputSchema: z.object({ productId, type: reviewableType }),
-      annotations: WRITE,
+      annotations: OPERATE,
     },
     (params) =>
       runTool(async () => toolResult((await client.markProductDocumentReviewed(params.productId, params.type)).data))
@@ -130,7 +130,7 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
           'are regenerated while it is open only: a finished Discovery locks them, and reopening it is done in ' +
           'the web. The optional Service Blueprint can be generated whenever someone wants one. The result is published as the new version, and ' +
           'the documents generated from it are marked outdated in turn. Runs an agent in the background: this ' +
-          'returns the job; taiga_wait_for_job says when it is done. Ask the person first.',
+          'returns the job; taiga_wait_for_job says when it is done.',
         inputSchema: z.object({ productId, type: generatedType }),
         annotations: OPERATE,
       },
@@ -170,7 +170,7 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
         'order they build on each other, one after another (each next one starts when the one before it is ' +
         'published). Refused (CONFLICT) while a document is already being generated. On an imported product, ' +
         'it queues every unpublished document. Runs agents in the background: this returns the jobs it started ' +
-        '(jobIds); taiga_stop_generating_documents stops the run. Ask the person first.',
+        '(jobIds); taiga_stop_generating_documents stops the run.',
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },
@@ -183,8 +183,7 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
       title: 'Stop generating product documents',
       description:
         'Stop a Generate remaining run: every document of it still being generated is cancelled and nothing ' +
-        'after them starts; published documents stay. An empty list means no run was going. Interrupts agent ' +
-        'work; ask the person first.',
+        'after them starts; published documents stay. An empty list means no run was going. Interrupts agent work.',
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },

package/src/tools/products.ts

@@ -19,7 +19,7 @@ import {
 } from './catalogue.js';
 import { apiFailureCode, apiFailureText, isMissOrRefusal, runTool, toolError, toolResult } from './errors.js';
 import { parseRemote } from './remote.js';
-import { sectionReadResult, stripProvenance } from './sections.js';
+import { sectionReadResult, sectionsInput, stripProvenance } from './sections.js';
 import { SEARCH_NOTE, SEARCH_PAGE_SIZE, SEARCH_WITH_CURSOR, page, pickFields, searchPages } from './summarize.js';
 
 /** What a product row needs to say for the model to pick one and read it in full. */
@@ -441,7 +441,8 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           "review and update times), and say which timeline is the product's own (defaultOrigin). " +
           `Two timelines: ${ORIGIN_MEANING.plan} ${ORIGIN_MEANING.reality} ` +
           'An empty side comes with a note saying why; a side the API could not list is null, with a note. ' +
-          'Use taiga_get_product_document with the type and origin to read one in full.',
+          'Use taiga_get_product_document with the type and origin to read one in full, or with sections: [] ' +
+          'for its outline (section ids and sizes) first.',
         inputSchema: z.object({ productId }),
         annotations: READ_ONLY,
       },
@@ -463,9 +464,9 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           'Read the plan to learn what to build: specification (requirements), architecture (design), ' +
           'threat_model (security risks), technology_decisions. Read reality, when the product has it, to ' +
           "learn what the code actually does before changing it. Omit origin for the product's own timeline. " +
-          'A large document runs to tens of thousands of characters: name the sections you need (the ids ' +
-          'taiga_get_product_context lists) and the read carries only those, listing the rest with their sizes ' +
-          'and any id the document lacks (unknownSections). ' +
+          'A large document runs to tens of thousands of characters: sections: [] reads its outline (every ' +
+          'section id with its size, no text) on either timeline, then name the sections you need and the read ' +
+          'carries only those, listing the rest with their sizes and any id the document lacks (unknownSections). ' +
           'A read that finds nothing says which documents and timelines the product does have.',
         inputSchema: z.object({
           productId,
@@ -473,12 +474,7 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
             .enum(PRODUCT_DOCUMENT_TYPES)
             .describe('Document type -- taiga_list_product_documents shows which ones the product has'),
           origin: originInput,
-          sections: z
-            .array(z.string().min(1).max(200))
-            .min(1)
-            .max(50)
-            .optional()
-            .describe('Only these sections, by id; omit for the whole document'),
+          sections: sectionsInput,
         }),
         annotations: READ_ONLY,
       },

package/src/tools/repositories.ts

@@ -54,6 +54,16 @@ const repositoryId = idInput(
   'taiga_list_product_repositories gives it; a GitHub repository id is not one'
 );
 
+/** Round-robin over lists: the first of each, then the second of each, and so on. */
+export function interleave<T>(lists: T[][]): T[] {
+  const out: T[] = [];
+  const longest = Math.max(0, ...lists.map((list) => list.length));
+  for (let index = 0; index < longest; index++) {
+    for (const list of lists) if (index < list.length) out.push(list[index]!);
+  }
+  return out;
+}
+
 export function registerRepositoryTools(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('products:read')) {
     server.registerTool(
@@ -68,8 +78,12 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
       },
       (params) =>
         runTool(async () => {
+          // The route answers one page of 100 and takes no cursor: past that, the list says it is cut.
           const result = await client.listProductRepositories(params.productId);
-          return toolResult(pickFields(result.data as Row[], LINK_FIELDS));
+          return toolResult({
+            data: pickFields(result.data as Row[], LINK_FIELDS),
+            truncated: result.nextCursor !== null,
+          });
         })
     );
 
@@ -87,7 +101,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
       (params) =>
         runTool(async () => {
           const result = await client.listRepositoryBranches(params.productId, params.repositoryId);
-          return toolResult({ branches: result.data, truncated: result.truncated });
+          return toolResult({ data: result.data, truncated: result.truncated });
         })
     );
   }
@@ -99,11 +113,21 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         title: 'Find a repository to link',
         description:
           "The repositories the organization's GitHub connection can reach, to link one to a product " +
-          '(taiga_link_repository takes its id). Searches by name with query; without installationId it reads ' +
-          'every connected GitHub account. No connection means GitHub is not connected yet: that is done once, ' +
-          'in the web, by someone who can install the app.',
+          '(taiga_link_repository takes its id). Searches by name with query. Name the GitHub account (account: ' +
+          'its login, the owner in owner/repo, or installationId) to read only its repositories; without one it ' +
+          'reads every connected account and takes rows from each in turn, so one account cannot fill the page. No ' +
+          'connection means GitHub is not connected yet: that is done once, in the web, by someone who can ' +
+          'install the app.',
         inputSchema: z.object({
           query: z.string().trim().min(1).max(256).optional().describe('Part of the repository name'),
+          account: z
+            .string()
+            .trim()
+            .min(1)
+            // owner/repo: a 39-character login, the slash and a 100-character name.
+            .max(140)
+            .optional()
+            .describe('The GitHub account login (the owner in owner/repo), case-insensitive'),
           installationId: idInput('GitHub account', 'this tool lists them').optional(),
           ...pagination,
         }),
@@ -119,9 +143,13 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
               'GitHub is not connected for this organization. It is connected once, in the web; then link.'
             );
           }
-          const chosen = params.installationId
-            ? installations.filter((i) => i.id === params.installationId)
-            : installations;
+          // owner/repo names the owner too: the part before the slash is the account.
+          const login = params.account?.split('/')[0]!.toLowerCase();
+          const chosen = installations.filter(
+            (i) =>
+              (!params.installationId || i.id === params.installationId) &&
+              (!login || String(i.accountLogin ?? '').toLowerCase() === login)
+          );
           if (chosen.length === 0) {
             return toolError('NOT_FOUND', 'No such GitHub connection; these are the connected accounts.', { accounts });
           }
@@ -131,7 +159,9 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
             return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
           }
           if (chosen.length > 1 && params.cursor !== undefined) {
-            return toolError('VALIDATION_ERROR', 'A cursor pages one account: name its installationId.', { accounts });
+            return toolError('VALIDATION_ERROR', 'A cursor pages one account: name it (account or installationId).', {
+              accounts,
+            });
           }
           // `limit` is the most rows the answer carries, however many accounts
           // are read: a search answers its ranked matches whatever the page
@@ -158,14 +188,15 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
           const pages = await Promise.all(
             chosen.map((i) => client.listInstallationRepositories(String(i.id), { q: params.query, limit: max }))
           );
-          const found = pages.flatMap((p) => rows(p.data));
+          // In turn, one row from each account, so the first account's page
+          // cannot fill the answer and hide the others.
+          const perAccount = pages.map((p) => rows(p.data));
+          const found = interleave(perAccount);
           const cut = found.length > max || pages.some((p) => p.nextCursor);
           return toolResult({
             accounts,
             repositories: page(found.slice(0, max), null),
-            ...(cut
-              ? { more: 'More than the limit across accounts: name an installationId, or narrow the query.' }
-              : {}),
+            ...(cut ? { more: 'More than the limit across accounts: name an account, or narrow the query.' } : {}),
           });
         })
     );
@@ -182,7 +213,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         'product, or with replacesRepositoryId swap the one linked now for it in one step (naming the same ' +
         'repository there changes nothing; linking one already linked without it is refused). A link Taiga ' +
         'manages (isManaged) cannot be replaced or unlinked. Once linked, planning reads its code, runs open pull requests in it, ' +
-        'sweeps scan it, and its deployment history is imported in the background. Ask the person first.',
+        'sweeps scan it, and its deployment history is imported in the background.',
       inputSchema: z.object({
         productId,
         githubRepositoryId: idInput('GitHub repository', 'taiga_list_linkable_repositories gives it'),
@@ -208,7 +239,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         "Choose the branch of a product's repository that Taiga branches from and opens its pull requests " +
         "against (taiga_list_repository_branches lists them), or null to follow the repository's default " +
         'again. A protected branch is not refused, but Taiga may not be able to merge into it: the answer says ' +
-        'when it is protected. Optionally a label for the link. Ask the person first.',
+        'when it is protected. Optionally a label for the link.',
       inputSchema: z.object({
         productId,
         repositoryId,
@@ -250,7 +281,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         'Unlink a repository from a product. Without one, the product can still have documents and initiatives ' +
         'but no changes: nothing is planned against code, built or swept. The repository itself is untouched, ' +
         'and a repository Taiga created for the product cannot be unlinked. ' +
-        'To swap it for another, use taiga_link_repository with replacesRepositoryId instead. Ask the person first.',
+        'To swap it for another, use taiga_link_repository with replacesRepositoryId instead.',
       inputSchema: z.object({ productId, repositoryId }),
       annotations: OPERATE,
     },

package/src/tools/sections.ts

@@ -12,6 +12,7 @@
  */
 
 import type { CallToolResult } from '@modelcontextprotocol/server';
+import { z } from 'zod';
 import { toolError, toolResult } from './errors.js';
 
 /** A section as stored: an object with `content` and metadata, or (older rows) a bare string. */
@@ -129,20 +130,31 @@ export function budgetSections(doc: Record<string, unknown>, budget: number): Se
   return cutTo(doc, sections, Object.fromEntries(kept));
 }
 
+/**
+ * The `sections` input of a document read: some sections by id, none for the
+ * outline (every id with its size and no text), or omitted for the whole.
+ */
+export const sectionsInput = z
+  .array(z.string().min(1).max(200))
+  .max(50)
+  .optional()
+  .describe(
+    'Only these sections, by id; [] for the outline (every section id and its size, no text); omit for the whole document'
+  );
+
 /**
  * The answer to a read that names sections: the ones the document has, the
  * rest listed with their sizes, and the asked-for ids it lacks under
- * unknownSections. One wrong id does not throw away the right ones (the
- * model retries only the miss); none right is a miss that lists the real ids.
+ * unknownSections. One shape whatever matched (PRO-2778): a wrong id does not
+ * throw away the right ones, and an answer with none right still lists every
+ * real id with its size, so the retry needs nothing else. No ids is the
+ * outline.
  */
 export function sectionReadResult(doc: Record<string, unknown>, ids: readonly string[], label: string): CallToolResult {
   const cut = pickSections(doc, new Set(ids));
   if (!cut) return toolError('VALIDATION_ERROR', `The ${label} is not made of sections; read it without sections.`);
   const all = Object.keys(sectionsOf(doc.data as Record<string, unknown>) ?? {});
   const unknownSections = ids.filter((id) => !all.includes(id));
-  if (unknownSections.length === ids.length) {
-    return toolError('NOT_FOUND', `The ${label} has no section ${ids.join(', ')}; its sections are ${all.join(', ')}.`);
-  }
   return toolResult({
     ...cut.doc,
     omittedSections: cut.omittedSections,

package/src/tools/setup.ts

@@ -154,7 +154,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
         title: 'Rename a factory',
         description:
           'Rename a factory. Its products, members, knowledge and instructions stay as they are, but its slug ' +
-          'follows the new name, so links to the factory change. Ask the person first.',
+          'follows the new name, so links to the factory change.',
         inputSchema: z.object({ factoryId, name: z.string().trim().min(1).max(255).describe('The new name') }),
         annotations: OPERATE_SETTING,
       },
@@ -194,7 +194,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
           "product (taiga_preview_product_move says who); the product's own knowledge files are re-filed onto " +
           'the new factory, and factory knowledge and instructions stay with the factory that owns them. Refused ' +
           '(CONFLICT) while a plan or build is in flight: stopLine: true stops the line first and then moves, which ' +
-          'interrupts that work. Ask the person first.',
+          'interrupts that work.',
         inputSchema: z.object({
           productId,
           factoryId: factoryId.describe('The factory to move it to'),
@@ -230,8 +230,8 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       title: 'Create a product',
       description:
         'Create a product in a factory, the way New product does. It starts one of two ways, chosen now and not ' +
-        'later: scratch, where Discovery is a conversation that writes the specification (held in the web), or ' +
-        'import (projectType brownfield), where Taiga reads an existing repository and drafts the documents from ' +
+        'later: scratch (afterwards projectType greenfield), where Discovery is a conversation that writes the ' +
+        'specification (held in the web), or import (projectType brownfield), where Taiga reads an existing repository and drafts the documents from ' +
         'the code: link the repository (taiga_link_repository; linking is for owners and admins, so a member ' +
         'asks one), then taiga_start_import. Also what Taiga builds for it: its ' +
         'infrastructure code and its CI/CD pipelines, each following the organization unless decided here; when ' +
@@ -275,7 +275,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
         'returns one to the organization default), the sentence on how a half Taiga does not build is done today, ' +
         "and whether it inherits the organization's design standards (null follows the default for how the " +
         'product started). Later plans read the new answer; work already planned is not redone. Autonomy is ' +
-        'taiga_set_product_autonomy. Ask the person first.',
+        'taiga_set_product_autonomy.',
       inputSchema: z.object({
         productId,
         name: z.string().trim().min(1).max(255).optional().describe('A new name'),
@@ -312,7 +312,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
         "the chosen branch, or the repository's default): all of them, or the ones named (with " +
         'what they are derived from). For a document the import misread, refresh it rather than importing ' +
         'again; unchanged sections are not republished. Runs an agent in the background and returns the job; ' +
-        'taiga_wait_for_job says when it is done. Ask the person first.',
+        'taiga_wait_for_job says when it is done.',
       inputSchema: z.object({
         productId,
         docTypes: z
@@ -367,7 +367,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       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. Ask the person first.',
+        'Nothing built from them is undone.',
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },
@@ -390,7 +390,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
         "assessed against the organization's policies, and the first initiatives are planned when Discovery is " +
         'finished. Refused for a product started from scratch (the choice is made at creation), without a ' +
         'linked repository, or while an import runs. Runs agents in the background and returns the job; ' +
-        'taiga_wait_for_job says when it is done (it takes a while). Ask the person first.',
+        'taiga_wait_for_job says when it is done (it takes a while).',
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },