@taiga-ai/mcp-server 0.5.0-rc.389 → 0.6.0-dev.391

package/src/tools/builds.ts

@@ -0,0 +1,89 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { TaigaClient } from '../client.js';
+import { READ_ONLY } from './annotations.js';
+import { runTool, toolResult } from './errors.js';
+import { pickFields } from './summarize.js';
+
+/** What a list row needs to say for the model to pick a run to read in full. */
+const BUILD_SUMMARY_FIELDS = [
+  'id',
+  'runNumber',
+  'backlogItemId',
+  'targetTitle',
+  'planId',
+  'status',
+  'failedReason',
+  'runtime',
+  'repositoryFullName',
+  'branch',
+  'baseBranch',
+  'completedSteps',
+  'totalSteps',
+  'prNumber',
+  'prUrl',
+  'prState',
+  'prDraft',
+  'prMerged',
+  'createdAt',
+  'startedAt',
+  'completedAt',
+] as const;
+
+export function registerBuildTools(server: McpServer, client: TaigaClient) {
+  if (!client.hasCapability('products:read')) return;
+
+  server.registerTool(
+    'taiga_list_builds',
+    {
+      title: 'List build runs',
+      description:
+        "List the coding agent's runs for a product, newest first: status, branch, pull request and step " +
+        'progress. Use this to see what Taiga already built or is building, then read one run with ' +
+        'taiga_get_build. Filter by backlog item to follow a single initiative.',
+      inputSchema: {
+        productId: z
+          .string()
+          .uuid()
+          .describe('Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products'),
+        backlogItemId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe("Only this backlog item's runs -- get from taiga_list_backlog_items"),
+        limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
+      },
+      annotations: READ_ONLY,
+    },
+    (params) =>
+      runTool(async () => {
+        const result = await client.listBuildRuns(params.productId, params);
+        return toolResult(pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS));
+      })
+  );
+
+  server.registerTool(
+    'taiga_get_build',
+    {
+      title: 'Get build run',
+      description:
+        'Get one run in full with its steps: what each step was meant to change, what it did change ' +
+        '(commit, files), its status and any error. Use this to pick up where the coding agent stopped, ' +
+        'or to understand the pull request it opened.',
+      inputSchema: {
+        buildId: z.string().uuid().describe('Build run ID -- get from taiga_list_builds'),
+      },
+      annotations: READ_ONLY,
+    },
+    (params) =>
+      runTool(async () => {
+        // Two routes, one answer: fanned out here rather than in the model's
+        // context, like the six-tool pattern asks.
+        const [run, steps] = await Promise.all([
+          client.getBuildRun(params.buildId),
+          client.listBuildRunSteps(params.buildId),
+        ]);
+        return toolResult({ ...(run.data as Record<string, unknown>), steps: steps.data });
+      })
+  );
+}

package/src/tools/documents.ts

@@ -1,12 +1,12 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { TaigaApiError, type TaigaClient, type TaigaDocument } from '../client.js';
+import { READ_ONLY } from './annotations.js';
 import { runTool, toolError, toolResult } from './errors.js';
 import { applySectionEdit, sectionContent, sectionsOf } from './sections.js';
 import { documentType } from './inputs.js';
 import { summarizeList } from './summarize.js';
 
-const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } as const;
 const DRAFT_WRITE = {
   readOnlyHint: false,
   destructiveHint: false,
@@ -105,7 +105,7 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           'that apply across all factories and products. ' +
           'Use taiga_get_document with the document type to read the full policy content.',
         inputSchema: {
-          limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+          limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
         },
         annotations: READ_ONLY,
       },
@@ -205,7 +205,7 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           'Use taiga_get_factory_document to read the full content.',
         inputSchema: {
           factoryId: z.string().uuid().describe('Factory ID -- get from taiga_list_factories'),
-          limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+          limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
         },
         annotations: READ_ONLY,
       },

package/src/tools/index.ts

@@ -3,17 +3,16 @@ import type { TaigaClient } from '../client.js';
 import { registerProductTools } from './products.js';
 import { registerDocumentTools } from './documents.js';
 import { registerBacklogTools } from './backlogs.js';
+import { registerBuildTools } from './builds.js';
 
 /**
  * Register all MCP tools based on the API key's effective capabilities.
  * Only tools matching the key's scopes are registered -- the AI assistant
  * never sees tools it can't use.
- *
- * Beta scope: Knowledge base access (policies and factory instructions).
- * Post-beta: Products, backlog items, environments, composite tools.
  */
 export function registerAllTools(server: McpServer, client: TaigaClient): void {
   registerProductTools(server, client);
   registerDocumentTools(server, client);
   registerBacklogTools(server, client);
+  registerBuildTools(server, client);
 }

package/src/tools/products.ts

@@ -1,11 +1,41 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
-import { runTool, toolResult } from './errors.js';
+import { READ_ONLY } from './annotations.js';
+import { runTool, toolError, toolResult } from './errors.js';
 import { documentType } from './inputs.js';
-import { summarizeList } from './summarize.js';
+import { parseRemote } from './remote.js';
+import { pickFields, summarizeList } from './summarize.js';
 
-const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } as const;
+/** What a product row needs to say for the model to pick one and read it in full. */
+const PRODUCT_SUMMARY_FIELDS = ['id', 'name', 'slug', 'status', 'factoryId', 'kind', 'discoveryStep'] as const;
+
+/** The API's page ceiling (paginationSchema in apps/api). */
+const PAGE_SIZE = 100;
+
+/**
+ * Pages the resolver follows before it stops and says so. A repository is
+ * linked to one product, or a handful where sharing is allowed; a thousand
+ * matches is not a resolution the model can act on anyway.
+ */
+const RESOLVE_PAGE_LIMIT = 10;
+
+/**
+ * Every product linked to the repository, page by page, until the API runs
+ * out or the cap is hit. A page that fails fails the call, like every other
+ * tool: a partial list marked truncated would read as a complete one.
+ */
+async function linkedProducts(client: TaigaClient, repository: string, repositoryHost: string) {
+  const products: Record<string, unknown>[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < RESOLVE_PAGE_LIMIT; page += 1) {
+    const result = await client.listProducts({ repository, repositoryHost, limit: PAGE_SIZE, cursor });
+    products.push(...(result.data as Record<string, unknown>[]));
+    if (!result.nextCursor) return { products, truncated: false };
+    cursor = result.nextCursor;
+  }
+  return { products, truncated: true };
+}
 
 export function registerProductTools(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('factories:read')) {
@@ -19,7 +49,7 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           "Factory instructions carry the factory's standing guidance: domain context, tech preferences, " +
           'and the conventions its products follow.',
         inputSchema: {
-          limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+          limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
         },
         annotations: READ_ONLY,
       },
@@ -37,8 +67,8 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       {
         title: 'List products',
         description:
-          'List products in the organization. Use this to find the product you are working on ' +
-          'so you can read its specification, architecture, and threat model. ' +
+          'List products in the organization. Use this to find a product by name; inside a git checkout, ' +
+          'taiga_resolve_product finds it from the remote URL instead. ' +
           'Can filter by factory; a status filter also exists but no longer distinguishes anything (see its description).',
         inputSchema: {
           factoryId: z
@@ -54,17 +84,85 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
                 'product is currently "draft" and filtering by "active" or "archived" returns nothing. ' +
                 'Omit this unless you are working with data set through the API directly.'
             ),
-          limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+          limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
         },
         annotations: READ_ONLY,
       },
       (params) =>
         runTool(async () => {
           const result = await client.listProducts(params);
+          return toolResult(pickFields(result.data as Record<string, unknown>[], PRODUCT_SUMMARY_FIELDS));
+        })
+    );
+
+    server.registerTool(
+      'taiga_get_product',
+      {
+        title: 'Get product',
+        description:
+          'Get one product in full: name, slug, factory, what Taiga owns for it (application, infrastructure, ' +
+          'deployment) and its settings; the list and resolve tools carry summaries. Use taiga_list_product_documents for its specification and design, ' +
+          'taiga_list_backlog_items for its work and taiga_list_builds for what the coding agent did.',
+        inputSchema: {
+          productId: z
+            .string()
+            .uuid()
+            .describe('Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products'),
+        },
+        annotations: READ_ONLY,
+      },
+      (params) =>
+        runTool(async () => {
+          const result = await client.getProduct(params.productId);
           return toolResult(result.data);
         })
     );
 
+    server.registerTool(
+      'taiga_resolve_product',
+      {
+        title: 'Resolve product from git remote',
+        description:
+          'Find the Taiga product a git checkout belongs to from its remote URL (the output of ' +
+          '`git remote get-url origin`). Call this first when working inside a repository, then use the ' +
+          'product ID with every other tool. Returns every product the repository is linked to (several ' +
+          `when the organization shares repositories; \`truncated\` is true past ${PAGE_SIZE * RESOLVE_PAGE_LIMIT}); ` +
+          'NOT_FOUND means nobody linked it, or the key cannot see the product.',
+        inputSchema: {
+          remoteUrl: z
+            .string()
+            .min(1)
+            .max(2048)
+            .describe('The remote URL: https://github.com/owner/repo.git, git@github.com:owner/repo.git or ssh://...'),
+        },
+        annotations: READ_ONLY,
+      },
+      (params) =>
+        runTool(async () => {
+          const remote = parseRemote(params.remoteUrl);
+          if (!remote) {
+            return toolError(
+              'INVALID_REMOTE',
+              `"${params.remoteUrl}" is not a remote of the form host/owner/repo. Pass the URL git remote get-url origin prints.`
+            );
+          }
+          const { products, truncated } = await linkedProducts(client, remote.repository, remote.host);
+          if (products.length === 0) {
+            return toolError(
+              'NOT_FOUND',
+              `No product you can see is linked to ${remote.repository} on ${remote.host}. ` +
+                'Link the repository to its product in Taiga, or find the product with taiga_list_products.'
+            );
+          }
+          return toolResult({
+            repository: remote.repository,
+            host: remote.host,
+            products: pickFields(products, PRODUCT_SUMMARY_FIELDS),
+            truncated,
+          });
+        })
+    );
+
     server.registerTool(
       'taiga_list_product_documents',
       {
@@ -77,7 +175,7 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           'Use taiga_get_product_document to read the full content.',
         inputSchema: {
           productId: z.string().uuid().describe('Product ID -- get from taiga_list_products'),
-          limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+          limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
         },
         annotations: READ_ONLY,
       },

package/src/tools/remote.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { parseRemote } from './remote.js';
+
+describe('parseRemote', () => {
+  it.each([
+    ['https://github.com/acme/web.git', 'https://github.com', 'acme/web'],
+    ['https://github.com/acme/web', 'https://github.com', 'acme/web'],
+    ['https://github.com/acme/web/', 'https://github.com', 'acme/web'],
+    ['https://github.com/acme/web.git/', 'https://github.com', 'acme/web'],
+    ['git@github.com:acme/web.git/', 'https://github.com', 'acme/web'],
+    ['https://user@GitHub.com/Acme/Web.git', 'https://github.com', 'Acme/Web'],
+    ['http://ghe.local:8443/acme/web.git', 'http://ghe.local:8443', 'acme/web'],
+    ['ssh://git@github.com/acme/web.git', 'https://github.com', 'acme/web'],
+    ['ssh://git@ghe.example.com:2222/acme/web.git', 'https://ghe.example.com', 'acme/web'],
+    ['git+ssh://git@github.com/acme/web.git', 'https://github.com', 'acme/web'],
+    ['git@github.com:acme/web.git', 'https://github.com', 'acme/web'],
+    ['git@taiga.ghe.com:taiga/taiga-app.git', 'https://taiga.ghe.com', 'taiga/taiga-app'],
+    ['  git@github.com:acme/web.git\n', 'https://github.com', 'acme/web'],
+    ['https://g/acme/web', 'https://g', 'acme/web'],
+  ])('reads %s as %s %s', (remote, host, repository) => {
+    expect(parseRemote(remote)).toEqual({ host, repository });
+  });
+
+  it.each([
+    [''],
+    ['not a remote'],
+    ['https://github.com/acme'],
+    ['https://gitlab.com/group/subgroup/repo.git'],
+    ['https://github.com/acme/../web'],
+    ['https://github.com/acme/tmp/../web'],
+    ['https://github.com/acme/tmp/%2e%2e/web'],
+    ['https://github.com/acme/./web'],
+    ['git@github.com:acme/tmp/../web.git'],
+    ['ftp://github.com/acme/web'],
+    ['/Users/dev/acme/web'],
+    ['C:/acme/web'],
+    ['git@ghe.local:8443:acme/web.git'],
+    ['git@github[.]com:acme/web.git'],
+    ['git@git hub.com:acme/web.git'],
+    ['acme/web'],
+  ])('refuses %s', (remote) => {
+    expect(parseRemote(remote)).toBeNull();
+  });
+});

package/src/tools/remote.ts

@@ -0,0 +1,107 @@
+/**
+ * What a git remote says about where a repository lives, in the terms Taiga
+ * stores: the web origin of the host and the `owner/repo` name. A developer's
+ * checkout knows its remote, not its Taiga product; this is the bridge.
+ *
+ * Accepted shapes: `https://host/owner/repo(.git)`, `ssh://git@host/owner/repo`,
+ * `git+ssh://...` and the scp-like `git@host:owner/repo.git`. Anything else,
+ * and any path that is not exactly two segments, is null: Taiga links
+ * `owner/repo` names only, so a deeper path can never match a link.
+ *
+ * An SSH remote names no web origin, so it is read as `https://host` on the
+ * default port. A host whose web UI sits on another port or on plain http
+ * does not resolve from its SSH remote; the https remote does.
+ */
+export interface ParsedRemote {
+  /** The web origin the link's URL starts with, such as `https://github.com`. */
+  host: string;
+  /** `owner/repo`, in the caller's case; the API matches it case-insensitively. */
+  repository: string;
+}
+
+const SCP_LIKE = /^(?:[^@\s/]+@)?([^:\s/]+):([^\s]+)$/;
+
+export function parseRemote(remote: string): ParsedRemote | null {
+  const trimmed = remote.trim();
+  if (trimmed === '') return null;
+
+  let host: string;
+  let path: string;
+  let scheme = 'https';
+
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    // The URL parser folds `..` away before the path can be looked at, so
+    // the raw text after the authority is checked first: a dot segment in a
+    // remote is never what `git remote get-url` prints.
+    if (hasDotSegment(trimmed.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i, ''))) return null;
+    let url: URL;
+    try {
+      url = new URL(trimmed);
+    } catch {
+      return null;
+    }
+    const protocol = url.protocol.replace(/:$/, '').toLowerCase();
+    if (protocol === 'http' || protocol === 'https') {
+      scheme = protocol;
+      // The port is part of the web origin a link was stored with.
+      host = url.port ? `${url.hostname}:${url.port}` : url.hostname;
+    } else if (protocol === 'ssh' || protocol === 'git+ssh' || protocol === 'git') {
+      // An SSH port says nothing about the web origin.
+      host = url.hostname;
+    } else {
+      return null;
+    }
+    path = url.pathname;
+  } else {
+    const match = SCP_LIKE.exec(trimmed);
+    if (!match) return null;
+    host = match[1]!;
+    path = match[2]!;
+    // Only this shape can misread a Windows drive (`C:/acme/web`) as a host;
+    // an explicit URL with a one-letter hostname is what it says it is.
+    if (host.length < 2) return null;
+  }
+
+  host = host.toLowerCase();
+  if (host === '') return null;
+
+  const segments = path
+    .replace(/\/+$/, '')
+    .replace(/\.git$/i, '')
+    .split('/')
+    .filter((segment) => segment !== '');
+  if (segments.length !== 2) return null;
+  // `.`/`..` would collapse into another route; a ':' is a port that landed
+  // in the path (`git@host:8443:owner/repo`), which no link name carries.
+  if (hasDotSegment(path) || segments.some((segment) => segment.includes(':'))) return null;
+
+  // The scp-like shape takes any host-looking text; only an origin the URL
+  // parser accepts is sent on, so `git@github[.]com:acme/web` is refused
+  // here rather than by the API after a request.
+  const origin = webOrigin(`${scheme}://${host}`);
+  if (origin === null) return null;
+
+  return { host: origin, repository: `${segments[0]}/${segments[1]}` };
+}
+
+/** Whether any segment of the path is `.` or `..`, percent-encoded or not. */
+function hasDotSegment(path: string): boolean {
+  return path.split('/').some((segment) => {
+    let decoded = segment;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+      // An undecodable segment is kept as is; it is not a dot segment.
+    }
+    return decoded === '.' || decoded === '..';
+  });
+}
+
+function webOrigin(url: string): string | null {
+  try {
+    const origin = new URL(url).origin;
+    return origin === 'null' ? null : origin;
+  } catch {
+    return null;
+  }
+}

package/src/tools/summarize.ts

@@ -28,3 +28,21 @@ export function summarizeList<T extends Record<string, unknown>>(
     return summary;
   });
 }
+
+/**
+ * Keep only the named fields of each item. For lists whose rows carry prose
+ * (a backlog item's description, a run's metrics) that `summarizeList`'s
+ * fixed field names would not catch.
+ */
+export function pickFields<T extends Record<string, unknown>>(
+  items: T[],
+  fields: readonly string[]
+): Record<string, unknown>[] {
+  return items.map((item) => {
+    const picked: Record<string, unknown> = {};
+    for (const field of fields) {
+      if (field in item) picked[field] = item[field];
+    }
+    return picked;
+  });
+}