@taiga-ai/mcp-server 0.26.0-dev.506 → 0.26.0-dev.507

package/dist/index.js

@@ -1457,6 +1457,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 +2461,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 +2952,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 +3924,17 @@ async function publishDraft(scope) {
 		...published.warnings ? { warnings: published.warnings } : {}
 	});
 }
+/** 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 +3942,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.` : "Name the document (type) to read its sections; a control id such as SEC-5.1 names its policy itself.");
 			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 })]);
@@ -5436,7 +5471,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 +5579,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 +5590,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;
@@ -5788,6 +5838,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 +6113,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.26.0-dev.506",
+  "version": "0.26.0-dev.507",
   "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",