@taiga-ai/mcp-server 0.4.0 → 0.5.0-dev.390

package/dist/index.js

@@ -7,6 +7,49 @@ const SERVER_VERSION = createRequire(import.meta.url)("../package.json").version
 //#endregion
 //#region src/client.ts
 /**
+* A non-2xx answer from the Taiga API. Carries the status and the API's own
+* `code` and `message` so a tool can hand the model something it can act on
+* (a 400 from the publish gate names the section that still holds template
+* residue) instead of one opaque string.
+*/
+var TaigaApiError = class extends Error {
+	status;
+	code;
+	apiMessage;
+	constructor(method, path, status, body) {
+		const parsed = parseErrorBody(body);
+		super(`Taiga API ${method} ${path} failed (${status}): ${parsed.message ?? body}`);
+		this.name = "TaigaApiError";
+		this.status = status;
+		this.code = parsed.code;
+		this.apiMessage = parsed.message;
+	}
+};
+/**
+* One path segment. Every id and type a tool passes is validated at the
+* tool boundary; this is the second wall. Encoding keeps a slash inside the
+* segment, and the dot segments are refused outright: encodeURIComponent
+* leaves "." and ".." as they are, and the URL parser in fetch would then
+* collapse `/documents/../publish` into a different route.
+*/
+function seg(value) {
+	if (value === "" || value === "." || value === "..") throw new TypeError(`Invalid path segment: ${JSON.stringify(value)}`);
+	return encodeURIComponent(value);
+}
+function parseErrorBody(body) {
+	try {
+		const json = JSON.parse(body);
+		const message = typeof json.message === "string" ? json.message : void 0;
+		const details = Array.isArray(json.details) ? json.details.map((d) => [d.instancePath, d.message].filter((x) => typeof x === "string" && x).join(" ")).filter(Boolean) : [];
+		return {
+			...typeof json.code === "string" ? { code: json.code } : {},
+			...message ? { message: details.length ? `${message}: ${details.join("; ")}` : message } : {}
+		};
+	} catch {
+		return {};
+	}
+}
+/**
 * HTTP client for the Taiga API.
 * Used by the MCP server to proxy tool calls to the backend.
 */
@@ -22,17 +65,17 @@ var TaigaClient = class {
 		const url = `${this.baseUrl}/v1${path}`;
 		const headers = {
 			Authorization: `Bearer ${this.apiKey}`,
-			"Content-Type": "application/json",
 			"User-Agent": `taiga-ai-mcp-server/${SERVER_VERSION}`
 		};
+		if (body !== void 0) headers["Content-Type"] = "application/json";
 		const response = await fetch(url, {
 			method,
 			headers,
-			body: body ? JSON.stringify(body) : void 0
+			body: body === void 0 ? null : JSON.stringify(body)
 		});
 		if (!response.ok) {
 			const text = await response.text().catch(() => "");
-			throw new Error(`Taiga API ${method} ${path} failed (${response.status}): ${text}`);
+			throw new TaigaApiError(method, path, response.status, text);
 		}
 		return response.json();
 	}
@@ -57,7 +100,7 @@ var TaigaClient = class {
 		return this.request("GET", `/products${qs ? `?${qs}` : ""}`);
 	}
 	async getProduct(id) {
-		return this.request("GET", `/products/${id}`);
+		return this.request("GET", `/products/${seg(id)}`);
 	}
 	async listTenantDocuments(opts) {
 		const params = new URLSearchParams();
@@ -66,31 +109,45 @@ var TaigaClient = class {
 		return this.request("GET", `/tenants/current/documents${qs ? `?${qs}` : ""}`);
 	}
 	async getTenantDocument(type) {
-		return this.request("GET", `/tenants/current/documents/${type}`);
+		return this.request("GET", `/tenants/current/documents/${seg(type)}`);
+	}
+	/** The shared draft for a document type, or `{ data: null }` when none exists. */
+	async getTenantDocumentDraft(type) {
+		return this.request("GET", `/tenants/current/documents/${seg(type)}/draft`);
 	}
 	async saveTenantDocumentDraft(type, body) {
-		return this.request("PUT", `/tenants/current/documents/${type}/draft`, body);
+		return this.request("PUT", `/tenants/current/documents/${seg(type)}/draft`, body);
+	}
+	async publishTenantDocument(type) {
+		return this.request("POST", `/tenants/current/documents/${seg(type)}/publish`);
 	}
 	async listFactoryDocuments(factoryId, opts) {
 		const params = new URLSearchParams();
 		if (opts?.limit) params.set("limit", String(opts.limit));
 		const qs = params.toString();
-		return this.request("GET", `/factories/${factoryId}/documents${qs ? `?${qs}` : ""}`);
+		return this.request("GET", `/factories/${seg(factoryId)}/documents${qs ? `?${qs}` : ""}`);
 	}
 	async getFactoryDocument(factoryId, type) {
-		return this.request("GET", `/factories/${factoryId}/documents/${type}`);
+		return this.request("GET", `/factories/${seg(factoryId)}/documents/${seg(type)}`);
+	}
+	/** The shared draft for a factory document type, or `{ data: null }` when none exists. */
+	async getFactoryDocumentDraft(factoryId, type) {
+		return this.request("GET", `/factories/${seg(factoryId)}/documents/${seg(type)}/draft`);
 	}
 	async saveFactoryDocumentDraft(factoryId, type, body) {
-		return this.request("PUT", `/factories/${factoryId}/documents/${type}/draft`, body);
+		return this.request("PUT", `/factories/${seg(factoryId)}/documents/${seg(type)}/draft`, body);
+	}
+	async publishFactoryDocument(factoryId, type) {
+		return this.request("POST", `/factories/${seg(factoryId)}/documents/${seg(type)}/publish`);
 	}
 	async listProductDocuments(productId, opts) {
 		const params = new URLSearchParams();
 		if (opts?.limit) params.set("limit", String(opts.limit));
 		const qs = params.toString();
-		return this.request("GET", `/products/${productId}/documents${qs ? `?${qs}` : ""}`);
+		return this.request("GET", `/products/${seg(productId)}/documents${qs ? `?${qs}` : ""}`);
 	}
 	async getProductDocument(productId, type) {
-		return this.request("GET", `/products/${productId}/documents/${type}`);
+		return this.request("GET", `/products/${seg(productId)}/documents/${seg(type)}`);
 	}
 	/**
 	* Fetch the full context for a product in parallel: product metadata,
@@ -98,7 +155,7 @@ var TaigaClient = class {
 	* Returns a structured bundle optimized for coding agent consumption.
 	*/
 	async getProductContext(productId) {
-		const product = await this.request("GET", `/products/${productId}`);
+		const product = await this.request("GET", `/products/${seg(productId)}`);
 		const factoryId = product.data.factoryId;
 		const [productDocs, factoryDocs] = await Promise.all([this.listProductDocuments(productId, { limit: 20 }).catch(() => ({ data: [] })), factoryId ? this.listFactoryDocuments(factoryId, { limit: 20 }).catch(() => ({ data: [] })) : Promise.resolve({ data: [] })]);
 		const keyProductDocTypes = [
@@ -151,13 +208,13 @@ var TaigaClient = class {
 		const params = new URLSearchParams();
 		if (opts?.limit) params.set("limit", String(opts.limit));
 		const qs = params.toString();
-		return this.request("GET", `/products/${productId}/backlog${qs ? `?${qs}` : ""}`);
+		return this.request("GET", `/products/${seg(productId)}/backlog${qs ? `?${qs}` : ""}`);
 	}
 	async getBacklogItem(itemId) {
-		return this.request("GET", `/backlog/${itemId}`);
+		return this.request("GET", `/backlog/${seg(itemId)}`);
 	}
 	async listEnvironments(productId) {
-		return this.request("GET", `/products/${productId}/environments`);
+		return this.request("GET", `/products/${seg(productId)}/environments`);
 	}
 	async listFactories(opts) {
 		const params = new URLSearchParams();
@@ -167,6 +224,82 @@ var TaigaClient = class {
 	}
 };
 //#endregion
+//#region src/config.ts
+const envSchema = z.object({
+	TAIGA_API_KEY: z.string().min(1),
+	TAIGA_API_URL: z.string().default("https://api.taiga.app")
+});
+/** Null when TAIGA_API_KEY is missing or empty: it is the one setting with no default. */
+function readConfig() {
+	const parsed = envSchema.safeParse(process.env);
+	if (!parsed.success) return null;
+	return {
+		apiKey: parsed.data.TAIGA_API_KEY,
+		apiUrl: parsed.data.TAIGA_API_URL
+	};
+}
+//#endregion
+//#region src/tools/errors.ts
+/** A successful tool result: one JSON text block the model reads. */
+function toolResult(value) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(value, null, 2)
+	}] };
+}
+/**
+* A failed tool result the model can branch on: a stable code and a message
+* that says what to do next. Returned, not thrown, so the client sees
+* `isError` rather than a protocol error.
+*/
+function toolError(error, message) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({
+				error,
+				message
+			})
+		}],
+		isError: true
+	};
+}
+const CODE_BY_STATUS = {
+	400: "VALIDATION_FAILED",
+	401: "UNAUTHENTICATED",
+	403: "FORBIDDEN",
+	404: "NOT_FOUND",
+	409: "CONFLICT",
+	429: "RATE_LIMITED"
+};
+/**
+* Run a tool handler and turn a failure into a structured error. An API
+* refusal keeps the API's own code when it sent one and its message whole:
+* on a refused publish that names the section holding template residue,
+* which is what the model needs to fix the draft. A failed connection is
+* structured too, so every failure the model sees has the same shape.
+*/
+async function runTool(handler) {
+	try {
+		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.`);
+		throw error;
+	}
+}
+//#endregion
+//#region src/tools/inputs.ts
+/**
+* A document type as the API names one: policy_security, factory_instructions,
+* specification. An identifier, never a path: the value is interpolated into
+* the route, and a type that carried a slash would reach a different
+* document's route than the tool's description promises. The API's own enum
+* stays the source of truth for which identifiers exist (it answers 400 with
+* the valid list); this only rules out what could not be a type at all.
+*/
+const documentType = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/, "A document type is a lowercase identifier such as policy_security");
+//#endregion
 //#region src/tools/summarize.ts
 /**
 * Strip heavy content from list responses to avoid context window bloat.
@@ -196,150 +329,257 @@ function summarizeList(items) {
 }
 //#endregion
 //#region src/tools/products.ts
+const READ_ONLY$1 = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: false
+};
 function registerProductTools(server, client) {
-	if (client.hasCapability("factories:read")) server.tool("taiga_list_factories", "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.", { limit: z.number().min(1).max(100).optional().describe("Max results (default 25)") }, {
-		readOnlyHint: true,
-		openWorldHint: false
-	}, async (params) => {
-		const result = await client.listFactories(params);
-		return { content: [{
-			type: "text",
-			text: JSON.stringify(result.data, null, 2)
-		}] };
-	});
+	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().min(1).max(100).optional().describe("Max results (default 25)") },
+		annotations: READ_ONLY$1
+	}, (params) => runTool(async () => {
+		return toolResult((await client.listFactories(params)).data);
+	}));
 	if (client.hasCapability("products:read")) {
-		server.tool("taiga_list_products", "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. Can filter by factory; a status filter also exists but no longer distinguishes anything (see its description).", {
-			factoryId: z.string().uuid().optional().describe("Filter by factory ID -- get factory IDs from taiga_list_factories"),
-			status: z.enum([
-				"draft",
-				"active",
-				"archived"
-			]).optional().describe("Filter by status. Taiga no longer surfaces product status in its UI (PRO-543), so every 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)")
-		}, {
-			readOnlyHint: true,
-			openWorldHint: false
-		}, async (params) => {
-			const result = await client.listProducts(params);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(result.data, null, 2)
-			}] };
-		});
-		server.tool("taiga_list_product_documents", "List documents for a specific product (names and types only). Product documents are generated during intake: specification (requirements), architecture (system design), technology decisions, data flow, privacy assessment, threat model (security risks), risk register, user flow, and service blueprint. Use taiga_get_product_document to read the full content.", {
-			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)")
-		}, {
-			readOnlyHint: true,
-			openWorldHint: false
-		}, async (params) => {
-			const summaries = summarizeList((await client.listProductDocuments(params.productId, { limit: params.limit })).data);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(summaries, null, 2)
-			}] };
-		});
-		server.tool("taiga_get_product_document", "Get the full content of a specific product document. Use this when you need to understand what to build (specification), how the system is designed (architecture), what security risks exist (threat model), or what technology choices were made (technology_decisions). Types: specification, architecture, technology_decisions, data_flow, privacy_assessment, threat_model, risk_register, user_flow, service_blueprint, ui_direction, codebase_snapshot, and product_instructions (the product's standing instructions).", {
-			productId: z.string().uuid().describe("Product ID -- get from taiga_list_products"),
-			type: z.string().describe("Document type -- get available types from taiga_list_product_documents. Common: specification, architecture, threat_model, technology_decisions")
-		}, {
-			readOnlyHint: true,
-			openWorldHint: false
-		}, async (params) => {
-			const result = await client.getProductDocument(params.productId, params.type);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(result.data, null, 2)
-			}] };
-		});
+		server.registerTool("taiga_list_products", {
+			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. Can filter by factory; a status filter also exists but no longer distinguishes anything (see its description).",
+			inputSchema: {
+				factoryId: z.string().uuid().optional().describe("Filter by factory ID -- get factory IDs from taiga_list_factories"),
+				status: z.enum([
+					"draft",
+					"active",
+					"archived"
+				]).optional().describe("Filter by status. Taiga no longer surfaces product status in its UI (PRO-543), so every 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)")
+			},
+			annotations: READ_ONLY$1
+		}, (params) => runTool(async () => {
+			return toolResult((await client.listProducts(params)).data);
+		}));
+		server.registerTool("taiga_list_product_documents", {
+			title: "List product documents",
+			description: "List documents for a specific product (names and types only). Product documents are generated during intake: specification (requirements), architecture (system design), technology decisions, data flow, privacy assessment, threat model (security risks), risk register, user flow, and service blueprint. 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)")
+			},
+			annotations: READ_ONLY$1
+		}, (params) => runTool(async () => {
+			return toolResult(summarizeList((await client.listProductDocuments(params.productId, { limit: params.limit })).data));
+		}));
+		server.registerTool("taiga_get_product_document", {
+			title: "Get product document",
+			description: "Get the full content of a specific product document. Use this when you need to understand what to build (specification), how the system is designed (architecture), what security risks exist (threat model), or what technology choices were made (technology_decisions). Types: specification, architecture, technology_decisions, data_flow, privacy_assessment, threat_model, risk_register, user_flow, service_blueprint, ui_direction, codebase_snapshot, and product_instructions (the product's standing instructions).",
+			inputSchema: {
+				productId: z.string().uuid().describe("Product ID -- get from taiga_list_products"),
+				type: documentType.describe("Document type -- get available types from taiga_list_product_documents. Common: specification, architecture, threat_model, technology_decisions")
+			},
+			annotations: READ_ONLY$1
+		}, (params) => runTool(async () => {
+			return toolResult((await client.getProductDocument(params.productId, params.type)).data);
+		}));
 	}
 }
 //#endregion
+//#region src/tools/sections.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The `sections` map of a document, or null when the document is not section-shaped. */
+function sectionsOf(data) {
+	return isRecord(data.sections) ? data.sections : null;
+}
+/** The text of one section, or null when the section does not exist. */
+function sectionContent(sections, sectionId) {
+	const section = sections[sectionId];
+	if (section === void 0 || section === null) return null;
+	if (typeof section === "string") return section;
+	return isRecord(section) && typeof section.content === "string" ? section.content : "";
+}
+/** The map with one section's text replaced (or the section added); every other section untouched. */
+function applySectionEdit(sections, sectionId, content) {
+	const prior = sections[sectionId];
+	return {
+		...sections,
+		[sectionId]: isRecord(prior) ? {
+			...prior,
+			content
+		} : { content }
+	};
+}
+//#endregion
 //#region src/tools/documents.ts
+const READ_ONLY = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: false
+};
+const DRAFT_WRITE = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: false
+};
+const PUBLISH = {
+	readOnlyHint: false,
+	destructiveHint: true,
+	idempotentHint: false,
+	openWorldHint: false
+};
+const sectionId = z.string().min(1).describe("Section id -- the keys of `data.sections` in taiga_get_document, e.g. summary, scope, apiDesign. An id that does not exist yet adds a section.");
+const sectionContentInput = z.string().describe("The full new Markdown text of the section; it replaces the old text");
+const tenantDocumentType = documentType.describe("Document type (e.g. policy_security, policy_sdlc) -- see taiga_list_documents");
+/** Everything the model needs back from a write, without the content it already holds. */
+function documentSummary(doc) {
+	const { data, ...rest } = doc;
+	return {
+		...rest,
+		sections: Object.keys(sectionsOf(data) ?? {})
+	};
+}
+/**
+* The document a section edit starts from: the draft when one exists, else
+* the published version, else (instructions documents start empty and
+* unpublished, PRO-502) an empty section map. The API seeds the draft the
+* same way on the first save, so the merge happens on what it would hold.
+*/
+async function editBase(scope) {
+	const draft = (await scope.getDraft()).data;
+	if (draft) return draft.data;
+	try {
+		return (await scope.getPublished()).data.data;
+	} catch (error) {
+		if (error instanceof TaigaApiError && error.status === 404) return { sections: {} };
+		throw error;
+	}
+}
+/**
+* Edit one section of a document's draft; the edit keeps every other section
+* and the section's own metadata, see sections.ts.
+*/
+async function updateSection(scope, type, id, content) {
+	const base = await editBase(scope);
+	const sections = sectionsOf(base);
+	if (!sections) return toolError("UNSUPPORTED_DOCUMENT", `Document ${type} is not made of sections and cannot be edited section by section. Edit it in the Taiga app.`);
+	const saved = await scope.saveDraft({
+		...base,
+		sections: applySectionEdit(sections, id, content)
+	});
+	return toolResult({
+		...documentSummary(saved.data),
+		section: {
+			id,
+			content: sectionContent(sectionsOf(saved.data.data) ?? {}, id)
+		}
+	});
+}
+/** Publish the draft; the API answers 404 when there is none and 400 when the residue gate refuses it. */
+async function publishDraft(scope) {
+	return toolResult(documentSummary((await scope.publish()).data));
+}
 function registerDocumentTools(server, client) {
 	if (client.hasCapability("tenant:documents:read")) {
-		server.tool("taiga_list_documents", "List company-level policy documents (names and types only). Policies define security, data privacy, SDLC, operations, architecture, and compliance rules that apply across all factories and products. Use taiga_get_document with the document type to read the full policy content.", { limit: z.number().min(1).max(100).optional().describe("Max results (default 25)") }, {
-			readOnlyHint: true,
-			openWorldHint: false
-		}, async (params) => {
-			const summaries = summarizeList((await client.listTenantDocuments(params)).data);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(summaries, null, 2)
-			}] };
-		});
-		server.tool("taiga_get_document", "Get the full content of a company policy document. Use this when you need to understand security requirements, data handling rules, architecture standards, or compliance controls that apply to your code. Types: policy_security, policy_data, policy_sdlc, policy_ops, policy_tic, policy_risk, policy_architecture, policy_supply_chain, policy_cloud_governance, policy_acceptable_use, policy_ip.", { type: z.string().describe("Document type -- get available types from taiga_list_documents. Common: policy_security, policy_data, policy_sdlc, policy_architecture") }, {
-			readOnlyHint: true,
-			openWorldHint: false
-		}, async (params) => {
-			const result = await client.getTenantDocument(params.type);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(result.data, null, 2)
-			}] };
+		server.registerTool("taiga_list_documents", {
+			title: "List company documents",
+			description: "List company-level policy documents (names and types only). Policies define security, data privacy, SDLC, operations, architecture, and compliance rules 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)") },
+			annotations: READ_ONLY
+		}, (params) => runTool(async () => {
+			return toolResult(summarizeList((await client.listTenantDocuments(params)).data));
+		}));
+		server.registerTool("taiga_get_document", {
+			title: "Get company document",
+			description: "Get the full content of a company policy document. Use this when you need to understand security requirements, data handling rules, architecture standards, or compliance controls that apply to your code. Types: policy_security, policy_data, policy_sdlc, policy_ops, policy_tic, policy_risk, policy_architecture, policy_supply_chain, policy_cloud_governance, policy_acceptable_use, policy_ip.",
+			inputSchema: { type: documentType.describe("Document type -- get available types from taiga_list_documents. Common: policy_security, policy_data, policy_sdlc, policy_architecture") },
+			annotations: READ_ONLY
+		}, (params) => runTool(async () => {
+			return toolResult((await client.getTenantDocument(params.type)).data);
+		}));
+	}
+	if (client.hasCapability("tenant:documents:read") && client.hasCapability("tenant:documents:write")) {
+		const tenantScope = (type) => ({
+			getDraft: () => client.getTenantDocumentDraft(type),
+			getPublished: () => client.getTenantDocument(type),
+			saveDraft: (data) => client.saveTenantDocumentDraft(type, { data }),
+			publish: () => client.publishTenantDocument(type)
 		});
+		server.registerTool("taiga_update_document", {
+			title: "Update a section of a company document draft",
+			description: "Replace the text of one section of a company policy document, in its draft. Every other section stays as it is. Does not publish: people and agents keep reading the published version until taiga_publish_document is called. Read the document with taiga_get_document first to see its sections and their current text. Use this when you notice a policy is outdated or needs corrections while reviewing code.",
+			inputSchema: {
+				type: tenantDocumentType,
+				sectionId,
+				content: sectionContentInput
+			},
+			annotations: DRAFT_WRITE
+		}, (params) => runTool(() => updateSection(tenantScope(params.type), params.type, params.sectionId, params.content)));
+		server.registerTool("taiga_publish_document", {
+			title: "Publish a company document draft",
+			description: "Publish a company policy document's draft as its next version, the one every agent and person reads from then on. Only publish when the person asked for it; save edits with taiga_update_document first. A refused publish names what to fix in the draft.",
+			inputSchema: { type: tenantDocumentType },
+			annotations: PUBLISH
+		}, (params) => runTool(() => publishDraft(tenantScope(params.type))));
 	}
-	if (client.hasCapability("tenant:documents:write")) server.tool("taiga_update_document", "Update the draft content of a company policy document. Only updates the draft -- does not publish. Use this when you notice a policy is outdated or needs corrections while reviewing code.", {
-		type: z.string().describe("Document type (e.g. policy_security, policy_sdlc)"),
-		data: z.record(z.string(), z.unknown()).describe("Document content to save as JSON")
-	}, {
-		readOnlyHint: false,
-		destructiveHint: false,
-		idempotentHint: true,
-		openWorldHint: false
-	}, async (params) => {
-		const { type, ...body } = params;
-		const result = await client.saveTenantDocumentDraft(type, body);
-		return { content: [{
-			type: "text",
-			text: JSON.stringify(result.data, null, 2)
-		}] };
-	});
 	if (client.hasCapability("factories:read")) {
-		server.tool("taiga_list_factory_documents", "List documents for a specific factory (names and types only). A factory has one document: its instructions, the factory's free-form standing guidance (domain context, tech preferences, conventions) that applies to every product it owns. Use taiga_get_factory_document to read the full content.", {
-			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)")
-		}, {
-			readOnlyHint: true,
-			openWorldHint: false
-		}, async (params) => {
-			const summaries = summarizeList((await client.listFactoryDocuments(params.factoryId, { limit: params.limit })).data);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(summaries, null, 2)
-			}] };
-		});
-		server.tool("taiga_get_factory_document", "Get the full content of a factory's instructions. Use this when you need the domain context, tech preferences, or conventions the factory expects every product it owns to follow.", {
-			factoryId: z.string().uuid().describe("Factory ID -- get from taiga_list_factories"),
-			type: z.string().describe("Document type -- get available types from taiga_list_factory_documents. The factory instructions document is `factory_instructions`.")
-		}, {
-			readOnlyHint: true,
-			openWorldHint: false
-		}, async (params) => {
-			const result = await client.getFactoryDocument(params.factoryId, params.type);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(result.data, null, 2)
-			}] };
+		server.registerTool("taiga_list_factory_documents", {
+			title: "List factory documents",
+			description: "List documents for a specific factory (names and types only). A factory has one document: its instructions, the factory's free-form standing guidance (domain context, tech preferences, conventions) that applies to every product it owns. 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)")
+			},
+			annotations: READ_ONLY
+		}, (params) => runTool(async () => {
+			return toolResult(summarizeList((await client.listFactoryDocuments(params.factoryId, { limit: params.limit })).data));
+		}));
+		server.registerTool("taiga_get_factory_document", {
+			title: "Get factory instructions",
+			description: "Get the full content of a factory's instructions. Use this when you need the domain context, tech preferences, or conventions the factory expects every product it owns to follow.",
+			inputSchema: {
+				factoryId: z.string().uuid().describe("Factory ID -- get from taiga_list_factories"),
+				type: documentType.describe("Document type -- get available types from taiga_list_factory_documents. The factory instructions document is `factory_instructions`.")
+			},
+			annotations: READ_ONLY
+		}, (params) => runTool(async () => {
+			return toolResult((await client.getFactoryDocument(params.factoryId, params.type)).data);
+		}));
+	}
+	if (client.hasCapability("factories:read") && client.hasCapability("factories:documents:write")) {
+		const factoryScope = (factoryId, type) => ({
+			getDraft: () => client.getFactoryDocumentDraft(factoryId, type),
+			getPublished: () => client.getFactoryDocument(factoryId, type),
+			saveDraft: (data) => client.saveFactoryDocumentDraft(factoryId, type, { data }),
+			publish: () => client.publishFactoryDocument(factoryId, type)
 		});
+		const factoryId = z.string().uuid().describe("Factory ID -- get from taiga_list_factories");
+		const factoryDocumentType = documentType.describe("Document type (`factory_instructions`)");
+		server.registerTool("taiga_update_factory_document", {
+			title: "Update a section of factory instructions",
+			description: "Replace the text of one section of a factory's instructions, in its draft. The instructions document has one section, `instructions`. Does not publish: products keep following the published version until taiga_publish_factory_document is called. Read the current text with taiga_get_factory_document first. Use this when the factory conventions, domain context or tech preferences need updating while working on the codebase.",
+			inputSchema: {
+				factoryId,
+				type: factoryDocumentType,
+				sectionId: sectionId.default("instructions"),
+				content: sectionContentInput
+			},
+			annotations: DRAFT_WRITE
+		}, (params) => runTool(() => updateSection(factoryScope(params.factoryId, params.type), params.type, params.sectionId, params.content)));
+		server.registerTool("taiga_publish_factory_document", {
+			title: "Publish factory instructions draft",
+			description: "Publish a factory's instructions draft as the next version every product of the factory follows. Only publish when the person asked for it; save edits with taiga_update_factory_document first.",
+			inputSchema: {
+				factoryId,
+				type: factoryDocumentType
+			},
+			annotations: PUBLISH
+		}, (params) => runTool(() => publishDraft(factoryScope(params.factoryId, params.type))));
 	}
-	if (client.hasCapability("factories:read") && client.hasCapability("tenant:documents:write")) server.tool("taiga_update_factory_document", "Update the draft of a factory's instructions. Only updates the draft -- does not publish. Use this when you notice the factory conventions, domain context, or tech preferences need updating while working on the codebase.", {
-		factoryId: z.string().uuid().describe("Factory ID -- get from taiga_list_factories"),
-		type: z.string().describe("Document type (`factory_instructions`)"),
-		data: z.record(z.string(), z.unknown()).describe("Document content to save as JSON")
-	}, {
-		readOnlyHint: false,
-		destructiveHint: false,
-		idempotentHint: true,
-		openWorldHint: false
-	}, async (params) => {
-		const { factoryId, type, ...body } = params;
-		const result = await client.saveFactoryDocumentDraft(factoryId, type, body);
-		return { content: [{
-			type: "text",
-			text: JSON.stringify(result.data, null, 2)
-		}] };
-	});
 }
 //#endregion
 //#region src/tools/index.ts
@@ -357,17 +597,16 @@ function registerAllTools(server, client) {
 }
 //#endregion
 //#region src/index.ts
-const DEFAULT_API_URL = "https://api.taiga.app";
 async function main() {
-	const apiKey = process.env.TAIGA_API_KEY;
-	if (!apiKey) {
+	const config = readConfig();
+	if (!config) {
 		console.error("Error: TAIGA_API_KEY environment variable is required.");
 		console.error("Create an API key at https://app.taiga.app/settings/api-keys");
 		process.exit(1);
 	}
 	const client = new TaigaClient({
-		baseUrl: process.env.TAIGA_API_URL ?? DEFAULT_API_URL,
-		apiKey
+		baseUrl: config.apiUrl,
+		apiKey: config.apiKey
 	});
 	const introspection = await client.introspect().catch((error) => {
 		const message = error instanceof Error ? error.message : String(error);
@@ -398,8 +637,9 @@ async function main() {
 		"For product-specific work, use taiga_list_products to find the product,",
 		"then read its specification and architecture.",
 		"",
-		"When you notice a policy or factory instructions are outdated, use the update tools",
-		"(taiga_update_document, taiga_update_factory_document) to fix it.",
+		"When you notice a policy or factory instructions are outdated, fix the section with",
+		"taiga_update_document or taiga_update_factory_document. That saves a draft nobody follows yet;",
+		"publish it with taiga_publish_document or taiga_publish_factory_document only when the person asks.",
 		"This keeps the knowledge base accurate for everyone."
 	].join("\n") });
 	registerAllTools(server, client);