@taiga-ai/mcp-server 0.26.0-rc.504 → 0.26.0-rc.514

package/dist/index.js

@@ -356,6 +356,17 @@ var TaigaClient = class {
 	async getFinding(id) {
 		return this.request("GET", `/maintenance/findings/${seg(id)}`);
 	}
+	/** The package inventory (PRO-2862); 404 where the `licenses` feature is not enabled. */
+	async listPackages(productId, opts) {
+		return this.request("GET", `/products/${seg(productId)}/maintenance/packages${query$1({ ...opts })}`);
+	}
+	async getLicenseSummary(productId) {
+		return this.request("GET", `/products/${seg(productId)}/maintenance/licenses`);
+	}
+	/** A repository's CycloneDX 1.5 SBOM (PRO-2894), the document itself. */
+	async getSbom(productId, repositoryId) {
+		return this.request("GET", `/products/${seg(productId)}/maintenance/repositories/${seg(repositoryId)}/sbom`);
+	}
 	async updateFinding(id, body) {
 		return this.request("PATCH", `/maintenance/findings/${seg(id)}`, body);
 	}
@@ -1457,6 +1468,24 @@ function hardeningCoverage(result) {
 		gaps
 	};
 }
+//#endregion
+//#region ../../packages/types/dist/inbox.js
+/** What action is required. Drives icon, copy, and completion logic. */
+const INBOX_ITEM_KINDS = [
+	"review_plan",
+	"review_backlog",
+	"review_doc",
+	"review_pr",
+	"review_maintenance",
+	"review_policy",
+	"setup_env_var",
+	"setup_secret",
+	"setup_third_party",
+	"setup_dns",
+	"setup_billing",
+	"setup_cloud_permission",
+	"setup_manual"
+];
 z.discriminatedUnion("kind", [
 	z.object({
 		type: z.literal("narrative"),
@@ -2443,7 +2472,7 @@ const DOCUMENT_INPUTS = Object.freeze({
 * reads as deleted) and fields they explain would simply be missing. So it
 * refuses to start, and says what to do.
 */
-function apiLevelProblem(introspection, apiUrl, required = 2, version = SERVER_VERSION) {
+function apiLevelProblem(introspection, apiUrl, required = 3, version = SERVER_VERSION) {
 	const offered = introspection.mcpApiLevel ?? 0;
 	if (offered >= required) return null;
 	return `The Taiga API at ${apiUrl} is older than @taiga-ai/mcp-server ${version} needs (API level ${offered}, needs ${required}). Run the version published for it, or wait for that API to be updated; an earlier release of this package works against it.`;
@@ -2934,7 +2963,11 @@ async function runTool(handler) {
 		if (error instanceof TaigaApiError) {
 			const code = error.code ?? CODE_BY_STATUS[error.status] ?? "API_ERROR";
 			const worded = inProductWording(error.apiMessage ?? `Taiga API answered ${error.status}.`);
-			return toolError(code, error.status === 404 ? withNotFoundHint(worded) : worded, error.details);
+			return toolError(code, error.status === 404 ? withNotFoundHint(worded) : [
+				502,
+				503,
+				504
+			].includes(error.status) ? `${withStop(worded)} This is usually temporary: a read may answer on a retry; after a write, check whether it took effect before repeating it.` : worded, error.details);
 		}
 		if (isNetworkFailure(error)) return toolError("NETWORK_ERROR", `Could not reach the Taiga API: ${networkFailureDetail(error)}. Check TAIGA_API_URL.`);
 		throw error;
@@ -3902,10 +3935,21 @@ async function publishDraft(scope) {
 		...published.warnings ? { warnings: published.warnings } : {}
 	});
 }
+/** The section ids that are not control ids at all. GDPR-1.1 is a control id, so it is not among them, though it names no single policy. */
+function notControls(sections) {
+	return sections.filter((id) => !isControlId(id.toUpperCase()));
+}
+/** The policies the section ids name when every one is a control id (SEC-5.1), else none. */
+function policiesNamed(sections) {
+	if (sections.length === 0) return [];
+	const types = sections.map((id) => isControlId(id.toUpperCase()) ? policyNamedByControl(id.toUpperCase()) : void 0);
+	if (types.some((type) => type === void 0)) return [];
+	return [...new Set(types)];
+}
 function registerDocumentTools(server, client) {
 	if (client.hasCapability("tenant:documents:read")) server.registerTool("taiga_get_organization_document", {
 		title: "Get an organization document",
-		description: `Read the organization's own documents, which apply to every product. Two answers: without type, the list (type, name, version, draft state); with type, that document. The ${POLICY_TYPES.length} policies (${named$1(POLICY_TYPES)}) set the rules for every product; the others (${named$1(OTHER_TENANT_DOCUMENT_TYPES)}) carry goals, standards, voice and instructions. Policies are long: pass sections: [] for the outline, then the section ids you need, or a control id such as SEC-5.1; unknownSections names ids it lacks. A miss says which documents are published and whether a draft exists. A section's source (template, overlay-<id>, cloud-preset:<providers>) and priority (core: every organization keeps it) do not change what it requires.`,
+		description: `Read the organization's own documents, which apply to every product. Two answers: without type, the list (type, name, version, draft state); with type, that document. The ${POLICY_TYPES.length} policies (${named$1(POLICY_TYPES)}) set the rules for every product; the others (${named$1(OTHER_TENANT_DOCUMENT_TYPES)}) carry goals, standards, voice and instructions. Policies are long: pass sections: [] for the outline, then the section ids you need, or a control id such as SEC-5.1 (which names its policy, so type may be left out); unknownSections names ids it lacks. A miss says which documents are published and whether a draft exists. A section's source (template, overlay-<id>, cloud-preset:<providers>) and priority (core: every organization keeps it) do not change what it requires.`,
 		inputSchema: z.object({
 			type: tenantDocumentType.optional(),
 			sections: policySectionsInput,
@@ -3913,19 +3957,25 @@ function registerDocumentTools(server, client) {
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		if (params.type === void 0) {
-			if (params.sections) return toolError("VALIDATION_ERROR", "Name the document (type) to read its sections.");
+		const named = params.type === void 0 && params.sections ? policiesNamed(params.sections) : [];
+		const args = params.type === void 0 && named.length === 1 ? {
+			...params,
+			type: named[0],
+			sections: params.sections?.map((id) => id.toUpperCase())
+		} : params;
+		if (args.type === void 0) {
+			if (args.sections) return toolError("VALIDATION_ERROR", named.length > 1 ? `Those control ids are in different policies (${named.join(", ")}): read one type at a time.` : notControls(args.sections).length > 0 && notControls(args.sections).length < args.sections.length ? `Not a control id: ${notControls(args.sections).join(", ")}. A control id such as SEC-5.1 names its policy; any other section id needs type.` : "Name the document (type) to read its sections; a control id such as SEC-5.1 names its policy itself, but one of a family that spans policies (GDPR, NIS2) does not.");
 			const result = await client.listTenantDocuments({
-				limit: params.limit,
-				cursor: params.cursor
+				limit: args.limit,
+				cursor: args.cursor
 			});
 			return toolResult(page(summaries(result.data), result.nextCursor));
 		}
-		const type = params.type;
-		if (params.limit !== void 0 || params.cursor !== void 0) return toolError("VALIDATION_ERROR", "limit and cursor page the list; omit type to list, or drop them to read.");
+		const type = args.type;
+		if (args.limit !== void 0 || args.cursor !== void 0) return toolError("VALIDATION_ERROR", params.type === void 0 ? "limit and cursor page the list, which takes no sections; drop them to read the control." : "limit and cursor page the list; omit type to list, or drop them to read.");
 		try {
 			const doc = stripProvenance((await client.getTenantDocument(type)).data);
-			return params.sections ? sectionReadResult(doc, params.sections, type, { controlIds: POLICY_TYPES.includes(type) }) : toolResult(doc);
+			return args.sections ? sectionReadResult(doc, args.sections, type, { controlIds: POLICY_TYPES.includes(type) }) : toolResult(doc);
 		} catch (error) {
 			if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
 			const [draft, all] = await Promise.allSettled([client.getTenantDocumentDraft(type), client.listTenantDocuments({ limit: 100 })]);
@@ -4672,7 +4722,7 @@ function waitingOn(rows, station) {
 }
 const STATION_NAMED = 3;
 /** Who holds the station, or null when the key cannot read the backlog or the read failed. */
-async function stationHolders(client, product, head) {
+async function stationHolders(client, product, except) {
 	if (!client.hasCapability("backlog:read")) return null;
 	try {
 		const columns = await Promise.all(["plan", "build"].map((state) => client.listBacklogItems(product, {
@@ -4680,7 +4730,7 @@ async function stationHolders(client, product, head) {
 			order: "newest",
 			limit: 100
 		})));
-		const rows = columns.flatMap((page) => page.data).filter((row) => row.id !== head);
+		const rows = columns.flatMap((page) => page.data).filter((row) => !except.has(row.id));
 		const capped = columns.some((page) => page.nextCursor !== null);
 		return {
 			count: rows.length,
@@ -4756,10 +4806,14 @@ async function queueView(client, product, options = { name: "all" }) {
 	});
 	const note = unnamed === 0 ? null : !canName ? "Entries carry initiativeId only: naming them needs backlog:read, which this key lacks." : entries.length > NAMED_ENTRIES ? `Only the first ${NAMED_ENTRIES} entries are named; the rest carry initiativeId only.` : "An entry whose initiative could not be read carries initiativeId only; taiga_get_initiative reads it.";
 	const line = typeof paused === "string" ? `The line is paused (since ${paused}): nothing is planned or built until a person resumes it.` : null;
+	const idle = rows.length > 0 && blockingIndex(rows, (row) => row.entryState) < 0;
+	const station = rows.length > 0 || options.name === "all" ? await stationHolders(client, product, new Set(idle ? [rows[0].backlogItemId] : rows.map((row) => row.backlogItemId))) : null;
+	const offLine = !idle && station && station.count > 0 ? { offTheLine: `${station.atLeast ? "At least " : ""}${station.count} initiative${station.count === 1 ? " is" : "s are"} in Plan or Build without a queue entry (${station.titles.map((title) => `"${title}"`).join(", ")}${station.count > station.titles.length ? ", and more" : ""}): moved there by hand or waiting on a pull request review. Each holds the station like the active entry; taiga_list_initiatives with column: 'plan' or 'build' lists them.` } : {};
 	return {
 		linePaused: paused === null ? null : typeof paused === "string",
 		entries: rows.map(({ lifecycle: _lifecycle, runId: _runId, ...row }) => row),
-		waitingOn: line ?? waitingOn(rows, rows.length > 0 && blockingIndex(rows, (row) => row.entryState) < 0 ? await stationHolders(client, product, rows[0].backlogItemId) : null),
+		waitingOn: line ?? waitingOn(rows, idle ? station : null),
+		...offLine,
 		...note ? { note } : {}
 	};
 }
@@ -5363,6 +5417,19 @@ function registerPlanVerdicts(server, client) {
 * next sweep no longer detects it, so there is no tool for either.
 */
 /** A finding as a list row: enough to decide whether to open, fix or ignore it. */
+const PACKAGE_ROW_FIELDS = [
+	"id",
+	"ecosystem",
+	"packageName",
+	"version",
+	"purl",
+	"licenses",
+	"scope",
+	"relation",
+	"sourcePath",
+	"productRepositoryId",
+	"detectedAt"
+];
 const FINDING_ROW_FIELDS = [
 	"id",
 	"kind",
@@ -5436,7 +5503,7 @@ function findingRows(findings, extra = []) {
 		"dependencyGroups",
 		"dependencyRelation",
 		...extra
-	]).map((row) => withDependencyScope(row)).map(withFixability);
+	]).map((row) => withDependencyScope(row)).map(withFixability).map((row) => Object.fromEntries(Object.entries(row).filter(([key, value]) => value !== null || key === "ignoreExpiresAt" && row["status"] === "ignored")));
 }
 /** The parts of an advisory record an agent reads; the rest (every affected range, every reference) is full: true. */
 const ADVISORY_KEPT = [
@@ -5544,9 +5611,10 @@ function registerMaintenanceTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_list_findings", {
 		title: "List maintenance findings",
-		description: "List what maintenance sweeps found in a product's repository: dependencies, secrets, insecure code (sast) and infrastructure. The first page opens with sweep (open counts, latest sweeps), so an old or failed sweep is not read as an all-clear. Rows: severity, tier (act_now: known exploited; urgent: likely and serious; elevated: one of the two; routine), location, remediableBy (coding_agent: a run here can fix it; upstream_only: the code is in a submodule, so the fix belongs in its own repository), fixable: false when no fixed version is known yet, breached controls and initiativeId of a fix under way. Omit status for open findings. taiga_get_finding reads one.",
+		description: "List what maintenance sweeps found in a product's repository: dependencies, secrets, insecure code (sast) and infrastructure. The first page opens with sweep (open counts, latest sweeps), so an old or failed sweep is not read as an all-clear. Rows: severity, tier (act_now: known exploited; urgent: likely and serious; elevated: one of the two; routine), location, remediableBy (coding_agent: a run here can fix it; upstream_only: the code is in a submodule, so the fix belongs in its own repository), fixable: false when no fixed version is known yet, breached controls and initiativeId of a fix under way. Omit status for open findings. controlId lists the findings that breach one control. taiga_get_finding reads one.",
 		inputSchema: z.object({
 			productId,
+			controlId: z.string().trim().min(1).max(40).optional().describe("Only the findings that breach this control, such as SEC-5.1 (one page, searched across all)"),
 			status: z.enum(MAINTENANCE_FINDING_STATUSES).optional().describe("Only findings in this status; omit for the ones needing action"),
 			severity: z.enum(MAINTENANCE_FINDING_SEVERITIES).optional().describe("Only this severity"),
 			kind: z.enum(MAINTENANCE_FINDING_KINDS).optional().describe("Only this kind of finding"),
@@ -5554,7 +5622,21 @@ function registerMaintenanceTools(server, client) {
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		const { productId: id, ...filters } = params;
+		const { productId: id, controlId, ...filters } = params;
+		if (controlId) {
+			if (params.cursor !== void 0) return toolError("VALIDATION_ERROR", "controlId reads every page itself; drop the cursor.");
+			const wanted = controlId.toUpperCase();
+			const found = await searchPages((cursor) => client.listFindings(id, {
+				...filters,
+				limit: 100,
+				cursor
+			}), "", () => [""], params.limit ?? 25, (row) => Array.isArray(row["controls"]) && row["controls"].some((c) => String(c).toUpperCase() === wanted));
+			return toolResult({
+				...page(findingRows(found.rows), null),
+				...found.more ? { more: found.rows.length < (params.limit ?? 25) ? `Only the first 1000 findings were searched; narrow by status, severity or kind to reach the rest.` : "There may be more than the limit carries: raise the limit, or narrow by status, severity or kind." } : {},
+				...found.rows.length === 0 && !found.more ? { note: `No ${params.status ? `${params.status} ` : "open "}finding breaches ${wanted}. That is no all-clear on its own: taiga_list_findings without controlId says when the product was last swept.` } : {}
+			});
+		}
 		const [result, sweep] = await Promise.all([client.listFindings(id, filters), params.cursor === void 0 ? sweepOverview(client, id).catch((error) => {
 			if (error instanceof TaigaApiError || isNetworkFailure(error)) return "unread";
 			throw error;
@@ -5569,6 +5651,35 @@ function registerMaintenanceTools(server, client) {
 			...params.status === void 0 && params.severity === void 0 && params.kind === void 0 && typeof result.totalCount === "number" && sweep && sweep !== "unread" && typeof sweep["openFindings"] === "number" && sweep["openFindings"] !== result.totalCount ? { totalNote: "totalCount includes findings with a fix under way (remediating) and ignored findings whose ignore has expired; sweep.openFindings counts open ones only." } : {}
 		});
 	}));
+	server.registerTool("taiga_list_packages", {
+		title: "List the package inventory",
+		description: "Every package a product's repositories resolve, vulnerable or not, as the latest sweep read it: name, version, ecosystem, SPDX licenses, scope (dev / runtime / unknown), relation (direct / transitive / unknown) and the lockfile. The first page opens with licenses: each license string across the inventory, how many packages carry it and its standing against the allowlist (allowed, not_allowed, unknown), plus the allowlist and when each repository was last inventoried. Filter by one license string (UNKNOWN for the ones the data source could not name), a name substring or a repository. A license outside the allowlist is also a license_violation finding in taiga_list_findings. Where the licenses feature is not enabled the product answers NOT_FOUND. taiga_get_sbom downloads one repository as CycloneDX.",
+		inputSchema: z.object({
+			productId,
+			license: z.string().min(1).max(4096).optional().describe("Only packages carrying exactly this SPDX string"),
+			search: z.string().min(1).max(255).optional().describe("Case-insensitive substring of the package name"),
+			productRepositoryId: idInput("repository", "taiga_list_product_repositories gives it", "only this repository").optional(),
+			...pagination
+		}),
+		annotations: READ_ONLY
+	}, (params) => runTool(async () => {
+		const { productId: id, ...filters } = params;
+		const [result, summary] = await Promise.all([client.listPackages(id, filters), params.cursor === void 0 ? client.getLicenseSummary(id) : Promise.resolve(null)]);
+		return toolResult({
+			...summary ? { licenses: summary.data } : {},
+			...page(pickFields(result.data, PACKAGE_ROW_FIELDS), result.nextCursor),
+			...typeof result.totalCount === "number" ? { totalCount: result.totalCount } : {}
+		});
+	}));
+	server.registerTool("taiga_get_sbom", {
+		title: "Download a repository SBOM",
+		description: "One repository's software bill of materials as a CycloneDX 1.5 JSON document, rendered from the stored package inventory: metadata (timestamp, tools, the repository), every package with its purl, license and scope, and the packages the repository declares directly. The whole document is returned, so for a large repository the answer is large; read taiga_list_packages when a summary is enough. NOT_FOUND where the licenses feature is not enabled, and for a repository no sweep has inventoried yet.",
+		inputSchema: z.object({
+			productId,
+			repositoryId: idInput("repository", "taiga_list_product_repositories gives it")
+		}),
+		annotations: READ_ONLY
+	}, (params) => runTool(async () => toolResult(await client.getSbom(params.productId, params.repositoryId))));
 	server.registerTool("taiga_get_finding", {
 		title: "Get a maintenance finding",
 		description: "Read one maintenance finding: exploit likelihood (EPSS, known-exploited list), the advisory summarized (full: true for its whole record: every affected range and reference) and fixed version, code location, breached policy controls, why it ranks where it does, history (reintroduced, previously resolved) and the remediation under way. fixable: false with fixNote says taiga_fix_finding would refuse it. A secret's value is never stored, only the rule and location.",
@@ -5788,6 +5899,9 @@ function readWith(row, backlogRead) {
 * were the same things.
 */
 const KIND_SAID = { review_backlog: "review_initiatives" };
+/** The kinds as the rows say them, for the kind filter, and the way back to the API's word. */
+const KINDS_SAID = INBOX_ITEM_KINDS.map((kind) => KIND_SAID[kind] ?? kind);
+const KIND_FROM_SAID = Object.fromEntries(Object.entries(KIND_SAID).map(([api, said]) => [said, api]));
 const SUBJECT_SAID = {
 	backlog_item: "initiative",
 	build_run: "run",
@@ -6060,15 +6174,17 @@ function registerInboxTools(server, client) {
 		inputSchema: z.object({
 			productId: productId.optional(),
 			category: z.enum(["gate", "setup"]).optional().describe("gate: things to review; setup: things to set up"),
+			kind: z.enum(KINDS_SAID).optional().describe("Only this kind, such as review_plan or review_pr, as the rows name it"),
 			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
 	}, (params) => runTool(async () => {
-		const { resolved, full, ...rest } = params;
+		const { resolved, full, kind, ...rest } = params;
 		const query = {
 			...rest,
+			...kind ? { kind: KIND_FROM_SAID[kind] ?? kind } : {},
 			...resolved ? { resolved: true } : {}
 		};
 		const first = params.cursor === void 0;
@@ -6503,10 +6619,15 @@ async function standingPart(client, productId) {
 	const standing = (await client.getPolicyStanding(productId)).data;
 	const summary = standingSummary(standing);
 	const state = standing.assessment?.state;
+	const controls = Array.isArray(standing.controls) ? standing.controls : [];
+	const withAny = (key) => controls.filter((control) => Number(control[key] ?? 0) > 0).length;
 	return {
 		openViolations: summary.violations,
 		bySeverity: summary.bySeverity,
-		controlsViolated: summary.controls,
+		controlsBreached: withAny("findingCount"),
+		controlsDiverged: withAny("divergenceCount"),
+		controlsMet: summary.controlsMet,
+		controlsNotApplicable: summary.controlsNotApplicable,
 		...state === "never" || state === "failed" ? { note: `The assessment ${state === "never" ? "has never run" : "failed"}: no violations here is not an all-clear.` } : {}
 	};
 }
@@ -6864,7 +6985,7 @@ const ENVIRONMENT_FIELDS = [
 */
 function deploymentLines(rows) {
 	return rows.map((row) => {
-		const repository = row.metadata?.["repositoryFullName"];
+		const repository = row.metadata?.repositoryFullName;
 		return {
 			...pickFields([row], DEPLOYMENT_FIELDS)[0],
 			repository: typeof repository === "string" ? repository : null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.26.0-rc.504",
+  "version": "0.26.0-rc.514",
   "description": "Taiga for AI coding assistants: read products, policies, initiatives and runs, and operate the line, over MCP",
   "mcpName": "ga.tai/mcp-server",
   "type": "module",