@taiga-ai/mcp-server 0.7.0-dev.396 → 0.8.0-dev.397

package/dist/index.js

@@ -106,9 +106,13 @@ var TaigaClient = class {
 	async getProduct(id) {
 		return this.request("GET", `/products/${seg(id)}`);
 	}
+	async listProductRepositories(productId) {
+		return this.request("GET", `/products/${seg(productId)}/repositories`);
+	}
 	async listTenantDocuments(opts) {
 		const params = new URLSearchParams();
 		if (opts?.limit) params.set("limit", String(opts.limit));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
 		const qs = params.toString();
 		return this.request("GET", `/tenants/current/documents${qs ? `?${qs}` : ""}`);
 	}
@@ -128,6 +132,7 @@ var TaigaClient = class {
 	async listFactoryDocuments(factoryId, opts) {
 		const params = new URLSearchParams();
 		if (opts?.limit) params.set("limit", String(opts.limit));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
 		const qs = params.toString();
 		return this.request("GET", `/factories/${seg(factoryId)}/documents${qs ? `?${qs}` : ""}`);
 	}
@@ -162,6 +167,7 @@ var TaigaClient = class {
 		if (opts?.category) params.set("category", opts.category);
 		if (opts?.includeArchived) params.set("includeArchived", "true");
 		if (opts?.limit) params.set("limit", String(opts.limit));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
 		const qs = params.toString();
 		return this.request("GET", `/products/${seg(productId)}/backlog${qs ? `?${qs}` : ""}`);
 	}
@@ -172,6 +178,7 @@ var TaigaClient = class {
 		const params = new URLSearchParams();
 		if (opts?.backlogItemId) params.set("backlogItemId", opts.backlogItemId);
 		if (opts?.limit) params.set("limit", String(opts.limit));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
 		const qs = params.toString();
 		return this.request("GET", `/products/${seg(productId)}/builds${qs ? `?${qs}` : ""}`);
 	}
@@ -187,6 +194,7 @@ var TaigaClient = class {
 	async listFactories(opts) {
 		const params = new URLSearchParams();
 		if (opts?.limit) params.set("limit", String(opts.limit));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
 		const qs = params.toString();
 		return this.request("GET", `/factories${qs ? `?${qs}` : ""}`);
 	}
@@ -219,6 +227,17 @@ const READ_ONLY = {
 	openWorldHint: false
 };
 //#endregion
+//#region src/tools/inputs.ts
+/** The inputs several tools share, so a product or a page is named the same way everywhere. */
+const productId = z.string().uuid().describe("Product ID -- taiga_get_product_context, taiga_resolve_product or taiga_list_products give it");
+/** The page inputs every list tool takes; `nextCursor` of one page is the `cursor` of the next. */
+const pagination = {
+	limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)"),
+	cursor: z.string().max(256).optional().describe("The nextCursor of the previous page, to read the next one; omit for the first page")
+};
+const slug = z.string().max(63).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "A slug is lowercase words joined by hyphens").describe("Product slug, as it appears in Taiga URLs");
+const remoteUrl = z.string().min(1).max(2048).describe("The git remote URL of a checkout (git remote get-url origin): https://, git@host:owner/repo.git or ssh://");
+//#endregion
 //#region ../../packages/types/dist/tenants.js
 const TENANT_DOCUMENT_TYPES = [
 	"policy_security",
@@ -436,6 +455,16 @@ const PRODUCT_DOCUMENT_DISPLAY_NAMES = {
 	service_blueprint: "Service Blueprint"
 };
 const PRODUCT_DOCUMENT_ORIGINS = ["plan", "reality"];
+//#endregion
+//#region ../../packages/types/dist/backlog.js
+/** Dispositions that end an item's pipeline life: settled work neither blocks
+*  dependants nor counts toward completion denominators. */
+const SETTLED_BACKLOG_STATUSES = ["done", "canceled"];
+/** Finished work: settled by a person or a merge, or archived. The one
+*  predicate every "can this still move / plan / build" guard reads. */
+function isSettledOrArchived(item) {
+	return item.archivedAt != null || SETTLED_BACKLOG_STATUSES.includes(item.status);
+}
 const TURN_EVENT_TRIGGERS = [
 	"defined",
 	"plan_started",
@@ -1109,6 +1138,19 @@ function toolError(error, message) {
 		isError: true
 	};
 }
+/**
+* fetch rejects with a TypeError carrying a `cause` when the API cannot be
+* reached; a TypeError from our own code carries none and is a bug to surface.
+*/
+function isNetworkFailure(error) {
+	return error instanceof TypeError && "cause" in error;
+}
+/** What went wrong on the wire: undici's message is the constant "fetch failed", the cause says why. */
+function networkFailureDetail(error) {
+	const cause = error.cause;
+	const why = typeof cause?.code === "string" ? cause.code : typeof cause?.message === "string" ? cause.message : null;
+	return why ? `${error.message} (${why})` : error.message;
+}
 const CODE_BY_STATUS = {
 	400: "VALIDATION_FAILED",
 	401: "UNAUTHENTICATED",
@@ -1129,7 +1171,7 @@ async function runTool(handler) {
 		return await handler();
 	} catch (error) {
 		if (error instanceof TaigaApiError) return toolError(error.code ?? CODE_BY_STATUS[error.status] ?? "API_ERROR", error.apiMessage ?? `Taiga API answered ${error.status}.`);
-		if (error instanceof TypeError) return toolError("NETWORK_ERROR", `Could not reach the Taiga API: ${error.message}. Check TAIGA_API_URL.`);
+		if (isNetworkFailure(error)) return toolError("NETWORK_ERROR", `Could not reach the Taiga API: ${networkFailureDetail(error)}. Check TAIGA_API_URL.`);
 		throw error;
 	}
 }
@@ -1246,6 +1288,19 @@ function stripProvenance(doc) {
 		}
 	};
 }
+/**
+* The free-form text of an instructions document, the way the API hands it
+* to the agents (factory-instructions.ts: every non-empty section, in order,
+* joined by a blank line). Null when there is nothing to read.
+*/
+function instructionsText(sections) {
+	const parts = [];
+	for (const section of Object.values(sections)) {
+		const content = isRecord(section) ? section.content : void 0;
+		if (typeof content === "string" && content.trim()) parts.push(content.trim());
+	}
+	return parts.join("\n\n").trim() || null;
+}
 //#endregion
 //#region src/tools/summarize.ts
 /**
@@ -1260,6 +1315,13 @@ function pickFields(items, fields) {
 		return picked;
 	});
 }
+/** The page a list tool returns: the rows the model asked for and where the next page starts. */
+function page(data, nextCursor) {
+	return {
+		data,
+		nextCursor: nextCursor ?? null
+	};
+}
 //#endregion
 //#region src/tools/products.ts
 /** What a product row needs to say for the model to pick one and read it in full. */
@@ -1295,12 +1357,12 @@ const PAGE_SIZE = 100;
 * matches is not a resolution the model can act on anyway.
 */
 const RESOLVE_PAGE_LIMIT = 10;
-const productId = z.string().uuid().describe("Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products");
 const originInput = z.enum(PRODUCT_DOCUMENT_ORIGINS).optional().describe(`Which timeline. ${ORIGIN_MEANING.plan} ${ORIGIN_MEANING.reality} Omit it to read the product's own timeline: reality for an imported product, plan for every other, and always plan for the documents a person writes (Look & Feel, Product Instructions).`);
 /**
 * 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.
+* out or the cap is hit, in which case the list says it is truncated. A page
+* that FAILS is different: it fails the call, like every other tool, rather
+* than being folded into a truncated list that would read as a complete one.
 */
 async function linkedProducts(client, repository, repositoryHost) {
 	const products = [];
@@ -1400,14 +1462,46 @@ function describeMiss(type, wanted, timelines, product) {
 	}
 	return parts.join(" ");
 }
+/**
+* One product from whichever name the caller has: its ID, its slug (through
+* the list's slug filter) or the git remote of a checkout (through the
+* repository filter). Exactly one of the three; a remote linked to several
+* products is ambiguous and says so.
+*/
+async function resolveProductRef(client, ref, accepted) {
+	if ([
+		ref.productId,
+		ref.slug,
+		ref.remoteUrl
+	].filter((v) => v !== void 0).length !== 1) return { error: toolError("VALIDATION_FAILED", `Name the product exactly once: ${accepted.join(" or ")}. Two names could mean two products.`) };
+	if (ref.productId) return { product: (await client.getProduct(ref.productId)).data };
+	if (ref.slug) {
+		const [product] = (await client.listProducts({
+			slug: ref.slug,
+			limit: 1
+		})).data;
+		if (!product) return { error: toolError("NOT_FOUND", `No product you can see has the slug "${ref.slug}". taiga_list_products shows the ones you can.`) };
+		return { product };
+	}
+	const remote = parseRemote(ref.remoteUrl);
+	if (!remote) return { error: toolError("INVALID_REMOTE", `"${ref.remoteUrl}" is not a remote of the form host/owner/repo. Pass the URL git remote get-url origin prints.`) };
+	const { products } = await linkedProducts(client, remote.repository, remote.host);
+	if (products.length === 0) return { error: 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.`) };
+	if (products.length > 1) {
+		const names = pickFields(products, PRODUCT_SUMMARY_FIELDS).map((p) => `${String(p.name)} (${String(p.id)})`).join(", ");
+		return { error: toolError("AMBIGUOUS", `${remote.repository} is linked to several products: ${names}. Call again with the productId of the one you mean.`) };
+	}
+	return { product: products[0] };
+}
 function registerProductTools(server, client) {
 	if (client.hasCapability("factories:read")) server.registerTool("taiga_list_factories", {
 		title: "List factories",
 		description: "List all factories in the organization. A factory is the group that owns a set of products. Use this to find factory IDs for reading factory instructions. Factory instructions carry the factory's standing guidance: domain context, tech preferences, and the conventions its products follow.",
-		inputSchema: { limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)") },
+		inputSchema: { ...pagination },
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		return toolResult((await client.listFactories(params)).data);
+		const result = await client.listFactories(params);
+		return toolResult(page(result.data, result.nextCursor));
 	}));
 	if (client.hasCapability("products:read")) {
 		server.registerTool("taiga_list_products", {
@@ -1416,35 +1510,29 @@ function registerProductTools(server, client) {
 			inputSchema: {
 				factoryId: z.string().uuid().optional().describe("Filter by factory ID -- get factory IDs from taiga_list_factories"),
 				status: z.enum(PRODUCT_STATUSES).optional().describe("Filter by status: draft until the product finishes setup in Taiga, active after that, archived when retired."),
-				limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)")
+				...pagination
 			},
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult(pickFields((await client.listProducts(params)).data, PRODUCT_SUMMARY_FIELDS));
+			const result = await client.listProducts(params);
+			return toolResult(page(pickFields(result.data, PRODUCT_SUMMARY_FIELDS), result.nextCursor));
 		}));
 		server.registerTool("taiga_get_product", {
 			title: "Get product",
 			description: "Get one product in full, by ID or by slug: 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: productId.optional(),
-				slug: z.string().max(63).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "A slug is lowercase words joined by hyphens").optional().describe("Product slug, as it appears in Taiga URLs -- an alternative to productId")
+				slug: slug.optional()
 			},
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			if (params.productId && params.slug) return toolError("VALIDATION_FAILED", "Pass productId or slug, not both: they could name two products.");
-			if (params.productId) return toolResult((await client.getProduct(params.productId)).data);
-			if (!params.slug) return toolError("VALIDATION_FAILED", "Pass productId or slug.");
-			const [product] = (await client.listProducts({
-				slug: params.slug,
-				limit: 1
-			})).data;
-			if (!product) return toolError("NOT_FOUND", `No product you can see has the slug "${params.slug}". taiga_list_products shows the ones you can.`);
-			return toolResult(product);
+			const resolved = await resolveProductRef(client, params, ["productId", "slug"]);
+			return "error" in resolved ? resolved.error : toolResult(resolved.product);
 		}));
 		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 1000); 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://...") },
+			description: "Find the Taiga product a git checkout belongs to from its remote URL (the output of `git remote get-url origin`). taiga_get_product_context takes the same URL and returns the whole context at once; use this when you only need the ID. Returns every product the repository is linked to (several when the organization shares repositories; `truncated` is true past 1000); NOT_FOUND means nobody linked it, or the key cannot see the product.",
+			inputSchema: { remoteUrl },
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
 			const remote = parseRemote(params.remoteUrl);
@@ -1583,11 +1671,11 @@ function registerDocumentTools(server, client) {
 		server.registerTool("taiga_list_documents", {
 			title: "List company documents",
 			description: `List the organization's documents as summaries (type, name, description, version, draft state). The ${POLICY_TYPES.length} policies (${named(POLICY_TYPES)}) define the security, data privacy, SDLC, operations, architecture and compliance rules that apply across all factories and products; the other documents (${named(OTHER_TENANT_DOCUMENT_TYPES)}) carry goals, standards, voice and standing instructions. Use taiga_get_document with the type to read one in full.`,
-			inputSchema: { limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)") },
+			inputSchema: { ...pagination },
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
 			const result = await client.listTenantDocuments(params);
-			return toolResult(summaries(result.data));
+			return toolResult(page(summaries(result.data), result.nextCursor));
 		}));
 		server.registerTool("taiga_get_document", {
 			title: "Get company document",
@@ -1641,12 +1729,12 @@ function registerDocumentTools(server, client) {
 			description: `List a factory's documents, published and draft, as summaries (type, name, version, draft state). A factory has one document type, ${named(FACTORY_DOCUMENT_TYPES)}: its free-form standing guidance (domain context, tech preferences, conventions) that applies to every product it owns. Drafts are listed too (isDraft true); an empty list means neither a publication nor a draft exists. 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().int().min(1).max(100).optional().describe("Max results (default 25)")
+				...pagination
 			},
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			const result = await client.listFactoryDocuments(params.factoryId, { limit: params.limit });
-			return toolResult(summaries(result.data));
+			const result = await client.listFactoryDocuments(params.factoryId, params);
+			return toolResult(page(summaries(result.data), result.nextCursor));
 		}));
 		server.registerTool("taiga_get_factory_document", {
 			title: "Get factory instructions",
@@ -1725,7 +1813,7 @@ function registerBacklogTools(server, client) {
 		title: "List backlog items",
 		description: "List a product's backlog items (initiatives): titles, category, status and where each one is on the line (backlog, todo, queue, plan, build, done). Use this to find the item you are working on, then read its acceptance criteria and technical context with taiga_get_backlog_item. Archived items are left out unless asked for.",
 		inputSchema: {
-			productId: z.string().uuid().describe("Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products"),
+			productId,
 			status: z.enum([
 				"backlog",
 				"in_progress",
@@ -1745,11 +1833,12 @@ function registerBacklogTools(server, client) {
 				"improvement"
 			]).optional().describe("Only this category"),
 			includeArchived: z.boolean().optional().describe("Include archived items (default false)"),
-			limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)")
+			...pagination
 		},
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		return toolResult(pickFields((await client.listBacklogItems(params.productId, params)).data, BACKLOG_SUMMARY_FIELDS));
+		const result = await client.listBacklogItems(params.productId, params);
+		return toolResult(page(pickFields(result.data, BACKLOG_SUMMARY_FIELDS), result.nextCursor));
 	}));
 	server.registerTool("taiga_get_backlog_item", {
 		title: "Get backlog item",
@@ -1792,13 +1881,14 @@ function registerBuildTools(server, client) {
 		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"),
+			productId,
 			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)")
+			...pagination
 		},
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		return toolResult(pickFields((await client.listBuildRuns(params.productId, params)).data, BUILD_SUMMARY_FIELDS));
+		const result = await client.listBuildRuns(params.productId, params);
+		return toolResult(page(pickFields(result.data, BUILD_SUMMARY_FIELDS), result.nextCursor));
 	}));
 	server.registerTool("taiga_get_build", {
 		title: "Get build run",
@@ -1814,6 +1904,240 @@ function registerBuildTools(server, client) {
 	}));
 }
 //#endregion
+//#region src/tools/context.ts
+/**
+* One call at the start of a coding session: everything the model would
+* otherwise collect in eight, fanned out here. Each part stands on its own
+* (Promise.allSettled): a part the API refuses or fails is named under
+* `unavailable` with what the API said, a part the key's capabilities do not
+* cover is named under `notGranted`, and neither is ever shown as empty. A
+* failure that is not the API's (a bug in this code) is not downgraded; it
+* fails the call so it surfaces.
+*/
+/** The two documents a coding session starts from; the rest are a read away. */
+const CONTEXT_DOCUMENT_TYPES = ["specification", "architecture"];
+const REPOSITORY_SUMMARY_FIELDS = [
+	"id",
+	"provider",
+	"repositoryName",
+	"repositoryUrl",
+	"effectiveBranch",
+	"isManaged"
+];
+/** How many of the latest runs to carry; taiga_list_builds pages the rest. */
+const BUILDS_IN_CONTEXT = 10;
+/** Pages of 100 the backlog part follows before it stops and says so. */
+const BACKLOG_PAGE_LIMIT = 10;
+const PARTS = {
+	factory: "factories:read",
+	documents: "products:read",
+	policies: "tenant:documents:read",
+	backlog: "backlog:read",
+	repositories: "products:read",
+	builds: "products:read"
+};
+/** What the API said when a part failed, in the words the bundle reports. */
+function unavailableReason(reason) {
+	if (reason instanceof TaigaApiError) return `${reason.status} ${reason.code ?? ""}`.trim() + (reason.apiMessage ? `: ${reason.apiMessage}` : "");
+	return `the API could not be reached: ${networkFailureDetail(reason)}`;
+}
+/** Whether a failed part is the API's doing; anything else is ours and propagates. */
+function isApiFailure(reason) {
+	return reason instanceof TaigaApiError || isNetworkFailure(reason);
+}
+function isNotFound(reason) {
+	return reason instanceof TaigaApiError && reason.status === 404;
+}
+/** The factory's standing guidance in full; null, with a note, when none is published or it is not section-shaped. */
+async function factoryPart(client, factoryId) {
+	const factory = (await client.getFactory(factoryId)).data;
+	const base = {
+		id: factory.id,
+		name: factory.name,
+		slug: factory.slug
+	};
+	try {
+		const doc = (await client.getFactoryDocument(factoryId, "factory_instructions")).data;
+		const sections = sectionsOf(doc.data);
+		if (!sections) return {
+			...base,
+			instructions: null,
+			instructionsVersion: doc.version,
+			note: "The published instructions are not made of sections; read them with taiga_get_factory_document."
+		};
+		return {
+			...base,
+			instructions: instructionsText(sections),
+			instructionsVersion: doc.version
+		};
+	} catch (error) {
+		if (!isNotFound(error)) throw error;
+		return {
+			...base,
+			instructions: null,
+			instructionsVersion: null,
+			note: "This factory has not published instructions yet."
+		};
+	}
+}
+/**
+* The specification and architecture from the product's own timeline: in full
+* by default, or as section ids when the caller wants a small bundle. Null,
+* with a note, where unpublished.
+*/
+async function documentsPart(client, product, full) {
+	const productId = String(product.id);
+	const origin = defaultOriginFor(product);
+	const reads = await Promise.allSettled(CONTEXT_DOCUMENT_TYPES.map((type) => client.getProductDocument(productId, type, origin)));
+	const out = { origin };
+	const notes = [];
+	CONTEXT_DOCUMENT_TYPES.forEach((type, index) => {
+		const read = reads[index];
+		if (read.status === "fulfilled") {
+			const doc = stripProvenance(read.value.data);
+			if (full) out[type] = doc;
+			else {
+				const sections = sectionsOf(doc.data ?? {});
+				if (sections) out[type] = {
+					version: doc.version,
+					sections: Object.keys(sections)
+				};
+				else {
+					out[type] = {
+						version: doc.version,
+						sections: null
+					};
+					notes.push(`The ${origin} ${type} is not made of sections; read it with taiga_get_product_document.`);
+				}
+			}
+		} else if (isNotFound(read.reason)) {
+			out[type] = null;
+			notes.push(`No published ${origin} ${type}; taiga_list_product_documents shows what the product has.`);
+		} else throw read.reason;
+	});
+	return {
+		...out,
+		notes
+	};
+}
+/** Every published policy as its section ids, so the model knows which one to read with taiga_get_document. */
+async function policiesPart(client) {
+	return (await client.listTenantDocuments({ limit: 100 })).data.filter((row) => POLICY_TYPES.includes(String(row.type)) && row.isDraft === false).map((row) => ({
+		type: row.type,
+		name: row.name,
+		version: row.version,
+		sections: Object.keys(sectionsOf(row.data ?? {}) ?? {})
+	}));
+}
+/** The statuses an item is open in; the API's filter takes one at a time. */
+const OPEN_BACKLOG_STATUSES = ["backlog", "in_progress"];
+/**
+* The items still open: one status-filtered read per open status (the API
+* leaves archived items out), each paged in full up to a cap the result
+* reports. The list is oldest first and the open items are the newest, so a
+* single page would miss exactly the ones that matter. Rows carrying a
+* retired status (readable for a rolling deploy) match neither filter;
+* the settled check below keeps the shape honest for whatever comes back.
+*/
+async function backlogPart(client, productId) {
+	const open = /* @__PURE__ */ new Map();
+	let truncated = false;
+	for (const status of OPEN_BACKLOG_STATUSES) {
+		let cursor;
+		for (let pageIndex = 0;; pageIndex += 1) {
+			if (pageIndex === BACKLOG_PAGE_LIMIT) {
+				truncated = true;
+				break;
+			}
+			const result = await client.listBacklogItems(productId, {
+				status,
+				limit: 100,
+				cursor
+			});
+			for (const row of result.data) if (!isSettledOrArchived({
+				status: String(row.status),
+				archivedAt: row.archivedAt ?? null
+			})) open.set(String(row.id), row);
+			if (!result.nextCursor) break;
+			cursor = result.nextCursor;
+		}
+	}
+	return {
+		items: pickFields([...open.values()], BACKLOG_SUMMARY_FIELDS),
+		truncated
+	};
+}
+/**
+* The linked repositories. The route serves one page of 100 and takes no
+* cursor, so past that the bundle says the list is cut rather than complete.
+*/
+async function repositoriesPart(client, productId) {
+	const result = await client.listProductRepositories(productId);
+	return {
+		items: pickFields(result.data, REPOSITORY_SUMMARY_FIELDS),
+		truncated: result.nextCursor !== null
+	};
+}
+async function buildsPart(client, productId) {
+	const rows = (await client.listBuildRuns(productId, { limit: BUILDS_IN_CONTEXT })).data;
+	return pickFields(rows, BUILD_SUMMARY_FIELDS);
+}
+async function productContext(client, product, options) {
+	const productId = String(product.id);
+	const granted = (part) => client.hasCapability(PARTS[part]);
+	const notGranted = Object.keys(PARTS).filter((part) => !granted(part));
+	const fetchers = {
+		factory: () => factoryPart(client, String(product.factoryId)),
+		documents: () => documentsPart(client, product, options.fullDocuments),
+		policies: () => policiesPart(client),
+		backlog: () => backlogPart(client, productId),
+		repositories: () => repositoriesPart(client, productId),
+		builds: () => buildsPart(client, productId)
+	};
+	const parts = Object.keys(fetchers).filter(granted);
+	const settled = await Promise.allSettled(parts.map((part) => fetchers[part]()));
+	const bundle = { product: {
+		...pickFields([product], PRODUCT_SUMMARY_FIELDS)[0],
+		projectType: isImportedProduct(product) ? "brownfield" : "greenfield",
+		defaultOrigin: defaultOriginFor(product)
+	} };
+	const unavailable = {};
+	parts.forEach((part, index) => {
+		const result = settled[index];
+		if (result.status === "fulfilled") bundle[part] = result.value;
+		else if (isApiFailure(result.reason)) unavailable[part] = unavailableReason(result.reason);
+		else throw result.reason;
+	});
+	return toolResult({
+		...bundle,
+		notGranted: notGranted.map((part) => `${part} (needs ${PARTS[part]})`),
+		unavailable,
+		readNext: "Read a policy in full with taiga_get_document, another product document with taiga_get_product_document, a backlog item with taiga_get_backlog_item and a run with taiga_get_build."
+	});
+}
+function registerContextTools(server, client) {
+	if (!client.hasCapability("products:read")) return;
+	server.registerTool("taiga_get_product_context", {
+		title: "Get product context",
+		description: "Everything a coding session starts from, in one call: the product and which document timeline is its own, its factory with the instructions in full, the specification and architecture from that timeline, every published policy as its section ids, the open backlog items, the linked repositories and the latest runs. Name the product by ID, slug or the git remote URL of the checkout. A part the API refused or failed is named under unavailable with what it said; a part the key cannot read is named under notGranted; neither is shown as empty. The two documents come in full, which on a large product is several thousand tokens; pass fullDocuments: false for their section ids only. Call this first, then read what you need in full.",
+		inputSchema: {
+			productId: productId.optional(),
+			slug: slug.optional(),
+			remoteUrl: remoteUrl.optional(),
+			fullDocuments: z.boolean().default(true).describe("Carry the specification and architecture in full (default) or as section ids only")
+		},
+		annotations: READ_ONLY
+	}, (params) => runTool(async () => {
+		const resolved = await resolveProductRef(client, params, [
+			"productId",
+			"slug",
+			"remoteUrl"
+		]);
+		if ("error" in resolved) return resolved.error;
+		return productContext(client, resolved.product, { fullDocuments: params.fullDocuments });
+	}));
+}
+//#endregion
 //#region src/tools/index.ts
 /**
 * Register all MCP tools based on the API key's effective capabilities.
@@ -1825,6 +2149,7 @@ function registerAllTools(server, client) {
 	registerDocumentTools(server, client);
 	registerBacklogTools(server, client);
 	registerBuildTools(server, client);
+	registerContextTools(server, client);
 }
 //#endregion
 //#region src/tools/instructions.ts
@@ -1873,8 +2198,12 @@ const SERVER_INSTRUCTIONS = [
 	"`priority: core` marks the sections every organization keeps. Neither changes what the section",
 	"requires of you.",
 	"",
-	"Workflow: inside a git checkout, start with taiga_resolve_product on the remote URL to find the product.",
-	"Otherwise use taiga_list_factories and taiga_list_products. Then read the factory instructions,",
+	"Workflow: start with taiga_get_product_context, naming the product by its git remote URL inside a checkout",
+	"(git remote get-url origin), else by slug or ID from taiga_list_products. It returns the product, the",
+	"factory instructions, the specification and architecture, every policy as its section ids, the open backlog",
+	"items, the repositories and the latest runs in one call, and names any part it could not read. Then read",
+	"what you need in full: a policy with taiga_get_document, a backlog item with taiga_get_backlog_item.",
+	"Without it, use taiga_list_factories and taiga_list_products, then read the factory instructions,",
 	"the product's specification and architecture, and the backlog item you are working on. A document",
 	"read that finds nothing tells you what does exist and which tool reads or writes it.",
 	"",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.7.0-dev.396",
+  "version": "0.8.0-dev.397",
   "description": "MCP server for Taiga -- gives AI assistants access to documents and products",
   "type": "module",
   "main": "./dist/index.js",