@studiometa/productive-mcp 0.9.2 → 0.10.1

package/dist/{handlers-D4tRd30c.js → handlers-DWowqxFA.js}

@@ -1,5 +1,5 @@
-import { ProductiveApi, formatAttachment, formatBooking, formatBudget, formatComment, formatCompany, formatDeal, formatDiscussion, formatListResponse, formatPage, formatPerson, formatProject, formatService, formatTask, formatTimeEntry, formatTimer } from "@studiometa/productive-api";
-import { RESOURCES, ResolveError, VALID_REPORT_TYPES, createBooking, createComment, createCompany, createDeal, createDiscussion, createPage, createTask, createTimeEntry, deleteAttachment, deleteDiscussion, deletePage, fromHandlerContext, getAttachment, getBooking, getBudget, getComment, getCompany, getDeal, getDiscussion, getPage, getPerson, getProject, getReport, getTask, getTimeEntry, getTimer, listAttachments, listBookings, listBudgets, listComments, listCompanies, listDeals, listDiscussions, listPages, listPeople, listProjects, listServices, listTasks, listTimeEntries, listTimers, reopenDiscussion, resolveDiscussion, resolveResource, startTimer, stopTimer, updateBooking, updateComment, updateCompany, updateDeal, updateDiscussion, updatePage, updateTask, updateTimeEntry } from "@studiometa/productive-core";
+import { ProductiveApi, formatAttachment, formatBooking, formatComment, formatCompany, formatDeal, formatDiscussion, formatListResponse, formatPage, formatPerson, formatProject, formatService, formatTask, formatTimeEntry, formatTimer } from "@studiometa/productive-api";
+import { RESOURCES, ResolveError, VALID_REPORT_TYPES, createBooking, createComment, createCompany, createDeal, createDiscussion, createPage, createTask, createTimeEntry, deleteAttachment, deleteDiscussion, deletePage, deleteTimeEntry, fromHandlerContext, getAttachment, getBooking, getComment, getCompany, getDeal, getDiscussion, getPage, getPerson, getProject, getReport, getTask, getTimeEntry, getTimer, listAttachments, listBookings, listComments, listCompanies, listDeals, listDiscussions, listPages, listPeople, listProjects, listServices, listTasks, listTimeEntries, listTimers, reopenDiscussion, resolveDiscussion, resolveResource, startTimer, stopTimer, updateBooking, updateComment, updateCompany, updateDeal, updateDiscussion, updatePage, updateTask, updateTimeEntry } from "@studiometa/productive-core";
 /**
 * Custom error classes for MCP server
 *
@@ -42,6 +42,7 @@ const ErrorMessages = {
 	noUserIdConfigured: () => new UserInputError("User ID not configured", ["The \"me\" action requires a user ID to be configured", "Use action=\"list\" to find people, or configure the user ID"]),
 	missingCommentTarget: () => new UserInputError("A target is required for creating a comment", ["Provide one of: task_id, deal_id, or company_id", "Find targets using resource=\"tasks\", \"deals\", or \"companies\" with action=\"list\""]),
 	missingBookingTarget: () => new UserInputError("A service or event is required for creating a booking", ["Provide either: service_id or event_id", "Find services using resource=\"services\" with action=\"list\""]),
+	noUpdateFieldsSpecified: (allowedFields) => new UserInputError(`No updates specified. Provide at least one of: ${allowedFields.join(", ")}`, ["Specify at least one field to update", `Updatable fields are: ${allowedFields.join(", ")}`]),
 	apiError: (statusCode, message) => {
 		const hints = [];
 		if (statusCode === 401) {
@@ -156,14 +157,6 @@ function formatService$1(service, options) {
 	return result;
 }
 /**
-* Format budget for agent consumption
-*/
-function formatBudget$1(budget, options) {
-	const result = formatBudget(budget, MCP_FORMAT_OPTIONS);
-	if (options?.compact) return compactify(result, ["budget_type", "currency"]);
-	return result;
-}
-/**
 * Format company for agent consumption
 */
 function formatCompany$1(company, options) {
@@ -434,40 +427,6 @@ function getDealHints(dealId) {
 	};
 }
 /**
-* Generate hints for a budget
-*/
-function getBudgetHints(budgetId) {
-	return { related_resources: [
-		{
-			resource: "services",
-			description: "Get services (budget lines) for this budget",
-			example: {
-				resource: "services",
-				action: "list",
-				filter: { budget_id: budgetId }
-			}
-		},
-		{
-			resource: "time",
-			description: "Get time entries for this budget",
-			example: {
-				resource: "time",
-				action: "list",
-				filter: { budget_id: budgetId }
-			}
-		},
-		{
-			resource: "bookings",
-			description: "Get bookings for this budget",
-			example: {
-				resource: "bookings",
-				action: "list",
-				filter: { budget_id: budgetId }
-			}
-		}
-	] };
-}
-/**
 * Generate hints for a person
 */
 function getPersonHints(personId) {
@@ -848,236 +807,6 @@ function toStringFilter(filter) {
 	return Object.keys(result).length > 0 ? result : void 0;
 }
 /**
-* Attachments MCP handler.
-*/
-var VALID_ACTIONS$14 = [
-	"list",
-	"get",
-	"delete"
-];
-async function handleAttachments(action, args, ctx) {
-	const { formatOptions, filter, page, perPage } = ctx;
-	const { id, task_id, comment_id, deal_id } = args;
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const result = await getAttachment({ id }, execCtx);
-		const formatted = formatAttachment$1(result.data, formatOptions);
-		if (ctx.includeHints !== false) {
-			const attachableType = result.data.attributes?.attachable_type;
-			return jsonResult({
-				...formatted,
-				_hints: getAttachmentHints(id, attachableType)
-			});
-		}
-		return jsonResult(formatted);
-	}
-	if (action === "delete") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("delete"));
-		await deleteAttachment({ id }, execCtx);
-		return jsonResult({
-			success: true,
-			deleted: id
-		});
-	}
-	if (action === "list") {
-		const options = { ...filter };
-		if (task_id) options.task_id = task_id;
-		if (comment_id) options.comment_id = comment_id;
-		if (deal_id) options.deal_id = deal_id;
-		const result = await listAttachments({
-			page,
-			perPage,
-			additionalFilters: options
-		}, execCtx);
-		return jsonResult(formatListResponse$1(result.data, formatAttachment$1, result.meta, formatOptions));
-	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "attachments", VALID_ACTIONS$14));
-}
-/**
-* Bookings MCP handler.
-*/
-var VALID_ACTIONS$13 = [
-	"list",
-	"get",
-	"create",
-	"update"
-];
-async function handleBookings(action, args, ctx) {
-	const { formatOptions, filter, page, perPage, include: userInclude } = ctx;
-	const { id, person_id, service_id, event_id, started_on, ended_on, time, note } = args;
-	const include = userInclude?.length ? [...new Set([
-		"person",
-		"service",
-		...userInclude
-	])] : ["person", "service"];
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const result = await getBooking({
-			id,
-			include
-		}, execCtx);
-		const formatted = formatBooking$1(result.data, {
-			...formatOptions,
-			included: result.included
-		});
-		if (ctx.includeHints !== false) {
-			const personId = result.data.relationships?.person?.data?.id;
-			return jsonResult({
-				...formatted,
-				_hints: getBookingHints(id, personId)
-			});
-		}
-		return jsonResult(formatted);
-	}
-	if (action === "create") {
-		if (!person_id || !started_on || !ended_on) return inputErrorResult(ErrorMessages.missingRequiredFields("booking", [
-			"person_id",
-			"started_on",
-			"ended_on"
-		]));
-		if (!service_id && !event_id) return inputErrorResult(ErrorMessages.missingBookingTarget());
-		return jsonResult({
-			success: true,
-			...formatBooking$1((await createBooking({
-				personId: person_id,
-				serviceId: service_id ?? "",
-				startedOn: started_on,
-				endedOn: ended_on,
-				time,
-				note,
-				eventId: event_id
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "update") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
-		return jsonResult({
-			success: true,
-			...formatBooking$1((await updateBooking({
-				id,
-				startedOn: started_on,
-				endedOn: ended_on,
-				time,
-				note
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "list") {
-		const result = await listBookings({
-			page,
-			perPage,
-			additionalFilters: filter,
-			include
-		}, execCtx);
-		return jsonResult(formatListResponse$1(result.data, formatBooking$1, result.meta, formatOptions));
-	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "bookings", VALID_ACTIONS$13));
-}
-/**
-* Budgets MCP handler.
-*
-* Thin adapter that delegates business logic to core executors
-* and handles MCP-specific concerns (hints, error formatting, JSON results).
-*/
-var VALID_ACTIONS$12 = ["list", "get"];
-async function handleBudgets(action, args, ctx) {
-	const { formatOptions, filter, page, perPage } = ctx;
-	const { id } = args;
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const formatted = formatBudget$1((await getBudget({ id }, execCtx)).data, formatOptions);
-		if (ctx.includeHints !== false) return jsonResult({
-			...formatted,
-			_hints: getBudgetHints(id)
-		});
-		return jsonResult(formatted);
-	}
-	if (action === "list") {
-		const result = await listBudgets({
-			page,
-			perPage,
-			additionalFilters: filter
-		}, execCtx);
-		return jsonResult(formatListResponse$1(result.data, formatBudget$1, result.meta, formatOptions));
-	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "budgets", VALID_ACTIONS$12));
-}
-/**
-* Comments MCP handler.
-*/
-var VALID_ACTIONS$11 = [
-	"list",
-	"get",
-	"create",
-	"update"
-];
-async function handleComments(action, args, ctx) {
-	const { formatOptions, filter, page, perPage, include: userInclude } = ctx;
-	const { id, body, task_id, deal_id, company_id } = args;
-	const include = userInclude?.length ? [...new Set(["creator", ...userInclude])] : ["creator"];
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const result = await getComment({
-			id,
-			include
-		}, execCtx);
-		const formatted = formatComment$1(result.data, {
-			...formatOptions,
-			included: result.included
-		});
-		if (ctx.includeHints !== false) {
-			const commentableType = result.data.attributes?.commentable_type;
-			let commentableId;
-			if (commentableType === "task") commentableId = result.data.relationships?.task?.data?.id;
-			else if (commentableType === "deal") commentableId = result.data.relationships?.deal?.data?.id;
-			else if (commentableType === "company") commentableId = result.data.relationships?.company?.data?.id;
-			return jsonResult({
-				...formatted,
-				_hints: getCommentHints(id, commentableType, commentableId)
-			});
-		}
-		return jsonResult(formatted);
-	}
-	if (action === "create") {
-		if (!body) return inputErrorResult(ErrorMessages.missingRequiredFields("comment", ["body"]));
-		if (!task_id && !deal_id && !company_id) return inputErrorResult(ErrorMessages.missingCommentTarget());
-		return jsonResult({
-			success: true,
-			...formatComment$1((await createComment({
-				body,
-				taskId: task_id,
-				dealId: deal_id,
-				companyId: company_id
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "update") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
-		if (!body) return inputErrorResult(ErrorMessages.missingRequiredFields("comment update", ["body"]));
-		return jsonResult({
-			success: true,
-			...formatComment$1((await updateComment({
-				id,
-				body
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "list") {
-		const result = await listComments({
-			page,
-			perPage,
-			additionalFilters: filter,
-			include
-		}, execCtx);
-		return jsonResult(formatListResponse$1(result.data, formatComment$1, result.meta, formatOptions));
-	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "comments", VALID_ACTIONS$11));
-}
-/**
 * Resolve handler for MCP.
 *
 * Thin wrapper around core's resource resolver.
@@ -1108,242 +837,559 @@ async function handleResolve(args, ctx) {
 	}
 }
 /**
-* Companies MCP handler.
+* Merge user includes with defaults, ensuring no duplicates
 */
-var VALID_ACTIONS$10 = [
-	"list",
-	"get",
-	"create",
-	"update",
-	"resolve"
-];
-async function handleCompanies(action, args, ctx) {
-	const { formatOptions, filter, page, perPage } = ctx;
-	const { id, name, query, type } = args;
-	if (action === "resolve") return handleResolve({
-		query,
-		type
-	}, ctx);
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const formatted = formatCompany$1((await getCompany({ id }, execCtx)).data, formatOptions);
-		if (ctx.includeHints !== false) return jsonResult({
-			...formatted,
-			_hints: getCompanyHints(id)
-		});
-		return jsonResult(formatted);
-	}
-	if (action === "create") {
-		if (!name) return inputErrorResult(ErrorMessages.missingRequiredFields("company", ["name"]));
-		return jsonResult({
-			success: true,
-			...formatCompany$1((await createCompany({ name }, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "update") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
-		return jsonResult({
-			success: true,
-			...formatCompany$1((await updateCompany({
-				id,
-				name
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "list") {
-		const result = await listCompanies({
-			page,
-			perPage,
-			additionalFilters: filter
-		}, execCtx);
-		const response = formatListResponse$1(result.data, formatCompany$1, result.meta, formatOptions);
-		if (result.resolved && Object.keys(result.resolved).length > 0) return jsonResult({
-			...response,
-			_resolved: result.resolved
-		});
-		return jsonResult(response);
-	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "companies", VALID_ACTIONS$10));
+function mergeIncludes(userInclude, defaults) {
+	if (!userInclude?.length && !defaults?.length) return void 0;
+	if (!userInclude?.length) return defaults;
+	if (!defaults?.length) return userInclude;
+	return [...new Set([...defaults, ...userInclude])];
 }
 /**
-* Deals MCP handler.
+* Create a resource handler function from configuration.
+*
+* @example
+* ```typescript
+* export const handleProjects = createResourceHandler({
+*   resource: 'projects',
+*   actions: ['list', 'get', 'resolve'],
+*   formatter: formatProject,
+*   hints: (data, id) => getProjectHints(id),
+*   supportsResolve: true,
+*   executors: {
+*     list: listProjects,
+*     get: getProject,
+*   },
+* });
+* ```
 */
-var VALID_ACTIONS$9 = [
-	"list",
-	"get",
-	"create",
-	"update",
-	"resolve"
-];
-async function handleDeals(action, args, ctx) {
-	const { formatOptions, filter, page, perPage, include: userInclude } = ctx;
-	const { id, name, company_id, query, type } = args;
-	if (action === "resolve") return handleResolve({
-		query,
-		type
-	}, ctx);
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const result = await getDeal({
-			id,
-			include: userInclude?.length ? [...new Set([
-				"company",
-				"deal_status",
-				"responsible",
-				...userInclude
-			])] : [
-				"company",
-				"deal_status",
-				"responsible"
-			]
-		}, execCtx);
-		const formatted = formatDeal$1(result.data, {
-			...formatOptions,
-			included: result.included
-		});
-		if (ctx.includeHints !== false) return jsonResult({
-			...formatted,
-			_hints: getDealHints(id)
-		});
-		return jsonResult(formatted);
-	}
-	if (action === "create") {
-		if (!name || !company_id) return inputErrorResult(ErrorMessages.missingRequiredFields("deal", ["name", "company_id"]));
-		return jsonResult({
-			success: true,
-			...formatDeal$1((await createDeal({
-				name,
-				companyId: company_id
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "update") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
-		return jsonResult({
-			success: true,
-			...formatDeal$1((await updateDeal({
+function createResourceHandler(config) {
+	const { resource, displayName = resource, actions, formatter, hints, defaultInclude, supportsResolve, listFilterFromArgs, resolveArgsFromArgs, customActions, create: createConfig, update: updateConfig, executors } = config;
+	return async (action, args, ctx) => {
+		const { formatOptions, filter, page, perPage, include: userInclude } = ctx;
+		const { id, query, type } = args;
+		const execCtx = ctx.executor();
+		if (customActions?.[action]) return customActions[action](args, ctx, execCtx);
+		if (action === "resolve") {
+			if (!supportsResolve) return inputErrorResult(ErrorMessages.invalidAction(action, resource, actions));
+			return handleResolve({
+				query,
+				type,
+				...resolveArgsFromArgs?.(args)
+			}, ctx);
+		}
+		if (action === "get") {
+			if (!executors.get) return inputErrorResult(ErrorMessages.invalidAction(action, resource, actions));
+			if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
+			const include = mergeIncludes(userInclude, defaultInclude?.get);
+			const result = await executors.get({
 				id,
-				name
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "list") {
-		const result = await listDeals({
-			page,
-			perPage,
-			additionalFilters: filter,
-			include: userInclude?.length ? [...new Set([
-				"company",
-				"deal_status",
-				...userInclude
-			])] : ["company", "deal_status"]
-		}, execCtx);
-		const response = formatListResponse$1(result.data, formatDeal$1, result.meta, {
-			...formatOptions,
-			included: result.included
-		});
-		if (result.resolved && Object.keys(result.resolved).length > 0) return jsonResult({
-			...response,
-			_resolved: result.resolved
-		});
-		return jsonResult(response);
-	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "deals", VALID_ACTIONS$9));
+				include
+			}, execCtx);
+			const formatted = formatter(result.data, {
+				...formatOptions,
+				included: result.included
+			});
+			if (ctx.includeHints !== false && hints) return jsonResult({
+				...formatted,
+				_hints: hints(result.data, id)
+			});
+			return jsonResult(formatted);
+		}
+		if (action === "create") {
+			if (!executors.create || !createConfig) return inputErrorResult(ErrorMessages.invalidAction(action, resource, actions));
+			const missingFields = createConfig.required.filter((field) => !args[field]);
+			if (missingFields.length > 0) return inputErrorResult(ErrorMessages.missingRequiredFields(displayName, missingFields));
+			if (createConfig.validateArgs) {
+				const errorResult = createConfig.validateArgs(args);
+				if (errorResult) return errorResult;
+			}
+			const options = createConfig.mapOptions(args);
+			return jsonResult({
+				success: true,
+				...formatter((await executors.create(options, execCtx)).data, formatOptions)
+			});
+		}
+		if (action === "update") {
+			if (!executors.update || !updateConfig) return inputErrorResult(ErrorMessages.invalidAction(action, resource, actions));
+			if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
+			if (updateConfig.allowedFields && updateConfig.allowedFields.length > 0) {
+				if (!updateConfig.allowedFields.some((field) => args[field] !== void 0)) return inputErrorResult(ErrorMessages.noUpdateFieldsSpecified(updateConfig.allowedFields));
+			}
+			const options = {
+				id,
+				...updateConfig.mapOptions(args)
+			};
+			return jsonResult({
+				success: true,
+				...formatter((await executors.update(options, execCtx)).data, formatOptions)
+			});
+		}
+		if (action === "delete") {
+			if (!executors.delete) return inputErrorResult(ErrorMessages.invalidAction(action, resource, actions));
+			if (!id) return inputErrorResult(ErrorMessages.missingId("delete"));
+			await executors.delete({ id }, execCtx);
+			return jsonResult({
+				success: true,
+				deleted: id
+			});
+		}
+		if (action === "list") {
+			const include = mergeIncludes(userInclude, defaultInclude?.list);
+			const additionalFilters = {
+				...filter,
+				...listFilterFromArgs?.(args)
+			};
+			const result = await executors.list({
+				page,
+				perPage,
+				additionalFilters,
+				include
+			}, execCtx);
+			const response = formatListResponse$1(result.data, formatter, result.meta, {
+				...formatOptions,
+				included: result.included
+			});
+			if (result.resolved && Object.keys(result.resolved).length > 0) return jsonResult({
+				...response,
+				_resolved: result.resolved
+			});
+			return jsonResult(response);
+		}
+		return inputErrorResult(ErrorMessages.invalidAction(action, resource, actions));
+	};
 }
 /**
-* Discussions MCP handler.
+* Attachments MCP handler.
 */
-var VALID_ACTIONS$8 = [
-	"list",
-	"get",
-	"create",
-	"update",
-	"delete",
-	"resolve",
-	"reopen"
-];
-async function handleDiscussions(action, args, ctx) {
-	const { formatOptions, filter, page, perPage } = ctx;
-	const { id, title, body, page_id, status } = args;
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const formatted = formatDiscussion$1((await getDiscussion({ id }, execCtx)).data, formatOptions);
-		if (ctx.includeHints !== false) return jsonResult({
-			...formatted,
-			_hints: getDiscussionHints(id, page_id)
-		});
-		return jsonResult(formatted);
+const handleAttachments = createResourceHandler({
+	resource: "attachments",
+	actions: [
+		"list",
+		"get",
+		"delete"
+	],
+	formatter: formatAttachment$1,
+	hints: (data, id) => {
+		const attachableType = data.attributes?.attachable_type;
+		return getAttachmentHints(id, attachableType);
+	},
+	listFilterFromArgs: (args) => {
+		const filters = {};
+		if (args.task_id) filters.task_id = args.task_id;
+		if (args.comment_id) filters.comment_id = args.comment_id;
+		if (args.deal_id) filters.deal_id = args.deal_id;
+		return filters;
+	},
+	executors: {
+		list: listAttachments,
+		get: getAttachment,
+		delete: deleteAttachment
 	}
-	if (action === "create") {
-		if (!body || !page_id) return inputErrorResult(ErrorMessages.missingRequiredFields("discussion", ["body", "page_id"]));
-		return jsonResult({
-			success: true,
-			...formatDiscussion$1((await createDiscussion({
-				body,
-				pageId: page_id,
-				title
-			}, execCtx)).data, formatOptions)
-		});
+});
+/**
+* Validate batch operations array
+*/
+function validateOperations(operations) {
+	if (!Array.isArray(operations)) throw new UserInputError("operations must be an array", ["Provide an array of operation objects", "Each operation needs: { resource: \"...\", action: \"...\", ...params }"]);
+	if (operations.length === 0) throw new UserInputError("operations array cannot be empty", ["Provide at least one operation", "Example: operations: [{ resource: \"projects\", action: \"list\" }]"]);
+	if (operations.length > 10) throw new UserInputError(`operations array exceeds maximum size of 10`, [`Split your batch into chunks of 10 or fewer operations`, `You provided ${operations.length} operations`]);
+	const validatedOps = [];
+	const errors = [];
+	for (let i = 0; i < operations.length; i++) {
+		const op = operations[i];
+		if (typeof op !== "object" || op === null) {
+			errors.push(`Operation at index ${i}: must be an object`);
+			continue;
+		}
+		const { resource, action } = op;
+		if (typeof resource !== "string" || resource.trim() === "") errors.push(`Operation at index ${i}: missing or invalid "resource" field`);
+		if (typeof action !== "string" || action.trim() === "") errors.push(`Operation at index ${i}: missing or invalid "action" field`);
+		if (errors.length === 0) validatedOps.push(op);
 	}
-	if (action === "update") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
-		return jsonResult({
-			success: true,
-			...formatDiscussion$1((await updateDiscussion({
-				id,
-				title,
-				body
-			}, execCtx)).data, formatOptions)
-		});
+	if (errors.length > 0) throw new UserInputError("Invalid operations in batch", errors);
+	return validatedOps;
+}
+/**
+* Execute a single operation and capture result
+*/
+async function executeOperation(operation, index, credentials, execute) {
+	const { resource, action, ...params } = operation;
+	try {
+		const result = await execute("productive", {
+			resource,
+			action,
+			...params
+		}, credentials);
+		const content = result.content[0];
+		if (content?.type === "text") try {
+			const data = JSON.parse(content.text);
+			if (result.isError) return {
+				resource,
+				action,
+				index,
+				error: content.text
+			};
+			return {
+				resource,
+				action,
+				index,
+				data
+			};
+		} catch {
+			if (result.isError) return {
+				resource,
+				action,
+				index,
+				error: content.text
+			};
+			return {
+				resource,
+				action,
+				index,
+				data: content.text
+			};
+		}
+		return {
+			resource,
+			action,
+			index,
+			data: null
+		};
+	} catch (err) {
+		return {
+			resource,
+			action,
+			index,
+			error: err instanceof Error ? err.message : String(err)
+		};
 	}
-	if (action === "delete") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("delete"));
-		await deleteDiscussion({ id }, execCtx);
-		return jsonResult({
-			success: true,
-			deleted: id
-		});
+}
+/**
+* Handle batch operation - execute multiple operations in parallel
+*
+* @param operations - Array of operations to execute
+* @param credentials - API credentials
+* @param execute - Function to execute individual operations (injected for testability)
+* @returns Batch response with summary and individual results
+*/
+async function handleBatch(operations, credentials, execute) {
+	let validatedOps;
+	try {
+		validatedOps = validateOperations(operations);
+	} catch (err) {
+		if (err instanceof UserInputError) return inputErrorResult(err);
+		throw err;
 	}
-	if (action === "resolve") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("resolve"));
-		return jsonResult({
-			success: true,
-			...formatDiscussion$1((await resolveDiscussion({ id }, execCtx)).data, formatOptions)
-		});
+	const results = await Promise.all(validatedOps.map((op, index) => executeOperation(op, index, credentials, execute)));
+	const succeeded = results.filter((r) => r.data !== void 0 && r.error === void 0).length;
+	const failed = results.filter((r) => r.error !== void 0).length;
+	return jsonResult({
+		_batch: {
+			total: results.length,
+			succeeded,
+			failed
+		},
+		results
+	});
+}
+/**
+* Bookings MCP handler.
+*/
+const handleBookings = createResourceHandler({
+	resource: "bookings",
+	displayName: "booking",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update"
+	],
+	formatter: formatBooking$1,
+	hints: (data, id) => {
+		const personId = data.relationships?.person?.data?.id;
+		return getBookingHints(id, personId);
+	},
+	defaultInclude: {
+		list: ["person", "service"],
+		get: ["person", "service"]
+	},
+	create: {
+		required: [
+			"person_id",
+			"started_on",
+			"ended_on"
+		],
+		validateArgs: (args) => {
+			if (!args.service_id && !args.event_id) return inputErrorResult(ErrorMessages.missingBookingTarget());
+		},
+		mapOptions: (args) => ({
+			personId: args.person_id,
+			serviceId: args.service_id ?? "",
+			startedOn: args.started_on,
+			endedOn: args.ended_on,
+			time: args.time,
+			note: args.note,
+			eventId: args.event_id
+		})
+	},
+	update: { mapOptions: (args) => ({
+		startedOn: args.started_on,
+		endedOn: args.ended_on,
+		time: args.time,
+		note: args.note
+	}) },
+	executors: {
+		list: listBookings,
+		get: getBooking,
+		create: createBooking,
+		update: updateBooking
 	}
-	if (action === "reopen") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("reopen"));
-		return jsonResult({
-			success: true,
-			...formatDiscussion$1((await reopenDiscussion({ id }, execCtx)).data, formatOptions)
-		});
+});
+/**
+* Comments MCP handler.
+*/
+const handleComments = createResourceHandler({
+	resource: "comments",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update"
+	],
+	formatter: formatComment$1,
+	hints: (data, id) => {
+		const commentableType = data.attributes?.commentable_type;
+		let commentableId;
+		if (commentableType === "task") commentableId = data.relationships?.task?.data?.id;
+		else if (commentableType === "deal") commentableId = data.relationships?.deal?.data?.id;
+		else if (commentableType === "company") commentableId = data.relationships?.company?.data?.id;
+		return getCommentHints(id, commentableType, commentableId);
+	},
+	defaultInclude: {
+		list: ["creator"],
+		get: ["creator"]
+	},
+	create: {
+		required: ["body"],
+		validateArgs: (args) => {
+			if (!args.task_id && !args.deal_id && !args.company_id) return inputErrorResult(ErrorMessages.missingCommentTarget());
+		},
+		mapOptions: (args) => ({
+			body: args.body,
+			taskId: args.task_id,
+			dealId: args.deal_id,
+			companyId: args.company_id
+		})
+	},
+	update: {
+		allowedFields: ["body"],
+		mapOptions: (args) => ({ body: args.body })
+	},
+	executors: {
+		list: listComments,
+		get: getComment,
+		create: createComment,
+		update: updateComment
 	}
-	if (action === "list") {
-		const listOptions = {
-			page,
-			perPage,
-			additionalFilters: filter
-		};
-		if (status) listOptions.status = status;
-		const result = await listDiscussions(listOptions, execCtx);
-		const response = formatListResponse$1(result.data, formatDiscussion$1, result.meta, formatOptions);
-		if (result.resolved && Object.keys(result.resolved).length > 0) return jsonResult({
-			...response,
-			_resolved: result.resolved
-		});
-		return jsonResult(response);
+});
+/**
+* Companies MCP handler.
+*
+* Uses the createResourceHandler factory for the common list/get/create/update/resolve pattern.
+*/
+/**
+* Handle companies resource.
+*
+* Supports: list, get, create, update, resolve
+*/
+const handleCompanies = createResourceHandler({
+	resource: "companies",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update",
+		"resolve"
+	],
+	formatter: formatCompany$1,
+	hints: (_data, id) => getCompanyHints(id),
+	supportsResolve: true,
+	create: {
+		required: ["name"],
+		mapOptions: (args) => ({ name: args.name })
+	},
+	update: { mapOptions: (args) => ({ name: args.name }) },
+	executors: {
+		list: listCompanies,
+		get: getCompany,
+		create: createCompany,
+		update: updateCompany
 	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "discussions", VALID_ACTIONS$8));
-}
+});
+/**
+* Deals MCP handler.
+*/
+const handleDeals = createResourceHandler({
+	resource: "deals",
+	displayName: "deal",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update",
+		"resolve"
+	],
+	formatter: formatDeal$1,
+	hints: (_data, id) => getDealHints(id),
+	supportsResolve: true,
+	defaultInclude: {
+		list: ["company", "deal_status"],
+		get: [
+			"company",
+			"deal_status",
+			"responsible"
+		]
+	},
+	create: {
+		required: ["name", "company_id"],
+		mapOptions: (args) => ({
+			name: args.name,
+			companyId: args.company_id
+		})
+	},
+	update: { mapOptions: (args) => ({ name: args.name }) },
+	executors: {
+		list: listDeals,
+		get: getDeal,
+		create: createDeal,
+		update: updateDeal
+	}
+});
+/**
+* Discussions MCP handler.
+*/
+var STATUS_MAP = {
+	active: "1",
+	resolved: "2"
+};
+const handleDiscussions = createResourceHandler({
+	resource: "discussions",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update",
+		"delete",
+		"resolve",
+		"reopen"
+	],
+	formatter: formatDiscussion$1,
+	hints: (data, id) => {
+		const pageId = data.relationships?.page?.data?.id;
+		return getDiscussionHints(id, pageId);
+	},
+	listFilterFromArgs: (args) => {
+		const filters = {};
+		if (args.status) {
+			const mapped = STATUS_MAP[args.status.toLowerCase()];
+			if (mapped) filters.status = mapped;
+		}
+		return filters;
+	},
+	create: {
+		required: ["body", "page_id"],
+		mapOptions: (args) => ({
+			body: args.body,
+			pageId: args.page_id,
+			title: args.title
+		})
+	},
+	update: { mapOptions: (args) => ({
+		title: args.title,
+		body: args.body
+	}) },
+	customActions: {
+		resolve: async (args, ctx, execCtx) => {
+			if (!args.id) return inputErrorResult(ErrorMessages.missingId("resolve"));
+			return jsonResult({
+				success: true,
+				...formatDiscussion$1((await resolveDiscussion({ id: args.id }, execCtx)).data, ctx.formatOptions)
+			});
+		},
+		reopen: async (args, ctx, execCtx) => {
+			if (!args.id) return inputErrorResult(ErrorMessages.missingId("reopen"));
+			return jsonResult({
+				success: true,
+				...formatDiscussion$1((await reopenDiscussion({ id: args.id }, execCtx)).data, ctx.formatOptions)
+			});
+		}
+	},
+	executors: {
+		list: listDiscussions,
+		get: getDiscussion,
+		create: createDiscussion,
+		update: updateDiscussion,
+		delete: deleteDiscussion
+	}
+});
 var RESOURCE_HELP = {
+	batch: {
+		description: "Execute multiple operations in a single call. Operations run in parallel via Promise.all, reducing round-trips for AI agents.",
+		actions: { run: "Execute a batch of operations (max 10)" },
+		fields: { operations: "Array of operation objects. Each must have \"resource\" and \"action\", plus any additional params for that resource." },
+		examples: [{
+			description: "Batch multiple queries",
+			params: {
+				resource: "batch",
+				action: "run",
+				operations: [
+					{
+						resource: "projects",
+						action: "get",
+						id: "123"
+					},
+					{
+						resource: "time",
+						action: "list",
+						filter: { project_id: "123" }
+					},
+					{
+						resource: "services",
+						action: "list",
+						filter: { project_id: "123" }
+					}
+				]
+			}
+		}, {
+			description: "Batch create time entries",
+			params: {
+				resource: "batch",
+				action: "run",
+				operations: [{
+					resource: "time",
+					action: "create",
+					service_id: "111",
+					date: "2024-01-15",
+					time: 60,
+					note: "Morning work"
+				}, {
+					resource: "time",
+					action: "create",
+					service_id: "111",
+					date: "2024-01-15",
+					time: 120,
+					note: "Afternoon work"
+				}]
+			}
+		}]
+	},
 	projects: {
 		description: "Manage projects in Productive.io",
 		actions: {
 			list: "List all projects with optional filters",
-			get: "Get a single project by ID with full details"
+			get: "Get a single project by ID (supports PRJ-123, P-123 format)",
+			resolve: "Resolve by project number (PRJ-123, P-123)"
 		},
 		filters: {
 			query: "Text search on project name",
@@ -1393,7 +1439,8 @@ var RESOURCE_HELP = {
 			list: "List tasks with optional filters",
 			get: "Get a single task by ID with full details (description, comments, etc.)",
 			create: "Create a new task (requires title, project_id, task_list_id)",
-			update: "Update an existing task"
+			update: "Update an existing task",
+			resolve: "Resolve by text search"
 		},
 		filters: {
 			query: "Text search on task title",
@@ -1478,7 +1525,9 @@ var RESOURCE_HELP = {
 			list: "List time entries with optional filters",
 			get: "Get a single time entry by ID",
 			create: "Create a new time entry (requires person_id, service_id, date, time)",
-			update: "Update an existing time entry"
+			update: "Update an existing time entry",
+			delete: "Delete a time entry",
+			resolve: "Resolve related resources (person, project, service)"
 		},
 		filters: {
 			person_id: "Filter by person (use \"me\" for current user)",
@@ -1559,8 +1608,9 @@ var RESOURCE_HELP = {
 		description: "Team members and contacts",
 		actions: {
 			list: "List people with optional filters",
-			get: "Get a single person by ID",
-			me: "Get the currently authenticated user"
+			get: "Get a single person by ID (supports email address)",
+			me: "Get the currently authenticated user",
+			resolve: "Resolve by email address"
 		},
 		filters: {
 			query: "Text search on name or email",
@@ -1610,9 +1660,10 @@ var RESOURCE_HELP = {
 		description: "Client companies and organizations",
 		actions: {
 			list: "List companies with optional filters",
-			get: "Get a single company by ID",
+			get: "Get a single company by ID (supports company name)",
 			create: "Create a new company (requires name)",
-			update: "Update an existing company"
+			update: "Update an existing company",
+			resolve: "Resolve by company name"
 		},
 		filters: {
 			query: "Text search on company name",
@@ -1776,12 +1827,13 @@ var RESOURCE_HELP = {
 		]
 	},
 	deals: {
-		description: "Sales deals and opportunities",
+		description: "Sales deals, opportunities, and budgets. Budgets are deals with budget=true — use filter[type]=2 to list only budgets.",
 		actions: {
 			list: "List deals with optional filters",
-			get: "Get a single deal by ID",
+			get: "Get a single deal by ID (supports D-123, DEAL-123 format)",
 			create: "Create a new deal (requires name, company_id)",
-			update: "Update an existing deal"
+			update: "Update an existing deal",
+			resolve: "Resolve by deal number (D-123, DEAL-123)"
 		},
 		filters: {
 			query: "Text search on deal name",
@@ -1804,23 +1856,35 @@ var RESOURCE_HELP = {
 			name: "Deal name",
 			number: "Deal number",
 			date: "Deal date",
+			budget: "Whether this deal is a budget (true/false)",
 			status: "Current status (from deal_status)"
 		},
-		examples: [{
-			description: "Search deals",
-			params: {
-				resource: "deals",
-				action: "list",
-				query: "website redesign"
-			}
-		}, {
-			description: "List deals for a company",
-			params: {
-				resource: "deals",
-				action: "list",
-				filter: { company_id: "12345" }
+		examples: [
+			{
+				description: "Search deals",
+				params: {
+					resource: "deals",
+					action: "list",
+					query: "website redesign"
+				}
+			},
+			{
+				description: "List deals for a company",
+				params: {
+					resource: "deals",
+					action: "list",
+					filter: { company_id: "12345" }
+				}
+			},
+			{
+				description: "List only budgets",
+				params: {
+					resource: "deals",
+					action: "list",
+					filter: { type: "2" }
+				}
 			}
-		}]
+		]
 	},
 	bookings: {
 		description: "Resource scheduling and capacity planning",
@@ -1863,66 +1927,6 @@ var RESOURCE_HELP = {
 			}
 		}]
 	},
-	budgets: {
-		description: "Budget tracking and financial overview",
-		actions: {
-			list: "List budgets with optional filters",
-			get: "Get a single budget by ID with full details"
-		},
-		filters: {
-			project_id: "Filter by project",
-			company_id: "Filter by company",
-			deal_id: "Filter by deal",
-			billable: "Filter by billable status (true/false)",
-			budget_type: "Filter by budget type"
-		},
-		fields: {
-			id: "Unique budget identifier",
-			name: "Budget name",
-			budget_type: "Type of budget",
-			billable: "Whether the budget is billable",
-			started_on: "Budget start date (YYYY-MM-DD)",
-			ended_on: "Budget end date (YYYY-MM-DD)",
-			currency: "Budget currency code",
-			total_time_budget: "Total time budget in minutes",
-			remaining_time_budget: "Remaining time budget in minutes",
-			total_monetary_budget: "Total monetary budget",
-			remaining_monetary_budget: "Remaining monetary budget"
-		},
-		examples: [
-			{
-				description: "List all budgets",
-				params: {
-					resource: "budgets",
-					action: "list"
-				}
-			},
-			{
-				description: "List budgets for a project",
-				params: {
-					resource: "budgets",
-					action: "list",
-					filter: { project_id: "12345" }
-				}
-			},
-			{
-				description: "Get budget details",
-				params: {
-					resource: "budgets",
-					action: "get",
-					id: "67890"
-				}
-			},
-			{
-				description: "List billable budgets",
-				params: {
-					resource: "budgets",
-					action: "list",
-					filter: { billable: "true" }
-				}
-			}
-		]
-	},
 	pages: {
 		description: "Manage pages (wiki/docs) within projects",
 		actions: {
@@ -2101,7 +2105,8 @@ function handleHelp(resource) {
 	const help = RESOURCE_HELP[resource];
 	if (!help) return jsonResult({
 		error: `Unknown resource: ${resource}`,
-		available_resources: Object.keys(RESOURCE_HELP)
+		available_resources: Object.keys(RESOURCE_HELP),
+		_tip: "Call { action: 'help' } without a resource to see all available resources."
 	});
 	return jsonResult({
 		resource,
@@ -2118,82 +2123,57 @@ function handleHelpOverview() {
 			resource,
 			description: help.description,
 			actions: Object.keys(help.actions)
-		}))
+		})),
+		_tip: "Always call { action: 'help', resource: '<name>' } before your first interaction with any resource to learn valid filters, required fields, and examples."
 	});
 }
 /**
 * Pages MCP handler.
+*
+* Uses the createResourceHandler factory for the common list/get/create/update/delete pattern.
 */
-var VALID_ACTIONS$7 = [
-	"list",
-	"get",
-	"create",
-	"update",
-	"delete"
-];
-async function handlePages(action, args, ctx) {
-	const { formatOptions, filter, page, perPage } = ctx;
-	const { id, title, body, project_id, parent_page_id } = args;
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const formatted = formatPage$1((await getPage({ id }, execCtx)).data, formatOptions);
-		if (ctx.includeHints !== false) return jsonResult({
-			...formatted,
-			_hints: getPageHints(id)
-		});
-		return jsonResult(formatted);
-	}
-	if (action === "create") {
-		if (!title || !project_id) return inputErrorResult(ErrorMessages.missingRequiredFields("page", ["title", "project_id"]));
-		return jsonResult({
-			success: true,
-			...formatPage$1((await createPage({
-				title,
-				projectId: project_id,
-				body,
-				parentPageId: parent_page_id
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "update") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
-		return jsonResult({
-			success: true,
-			...formatPage$1((await updatePage({
-				id,
-				title,
-				body
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "delete") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("delete"));
-		await deletePage({ id }, execCtx);
-		return jsonResult({
-			success: true,
-			deleted: id
-		});
-	}
-	if (action === "list") {
-		const result = await listPages({
-			page,
-			perPage,
-			additionalFilters: filter
-		}, execCtx);
-		const response = formatListResponse$1(result.data, formatPage$1, result.meta, formatOptions);
-		if (result.resolved && Object.keys(result.resolved).length > 0) return jsonResult({
-			...response,
-			_resolved: result.resolved
-		});
-		return jsonResult(response);
+/**
+* Handle pages resource.
+*
+* Supports: list, get, create, update, delete
+*/
+const handlePages = createResourceHandler({
+	resource: "pages",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update",
+		"delete"
+	],
+	formatter: formatPage$1,
+	hints: (_data, id) => getPageHints(id),
+	supportsResolve: false,
+	create: {
+		required: ["title", "project_id"],
+		mapOptions: (args) => ({
+			title: args.title,
+			projectId: args.project_id,
+			body: args.body,
+			parentPageId: args.parent_page_id
+		})
+	},
+	update: { mapOptions: (args) => ({
+		title: args.title,
+		body: args.body
+	}) },
+	executors: {
+		list: listPages,
+		get: getPage,
+		create: createPage,
+		update: updatePage,
+		delete: deletePage
 	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "pages", VALID_ACTIONS$7));
-}
+});
 /**
 * People MCP handler.
 */
-var VALID_ACTIONS$6 = [
+var VALID_ACTIONS$1 = [
 	"list",
 	"get",
 	"me",
@@ -2244,48 +2224,33 @@ async function handlePeople(action, args, ctx, credentials) {
 		});
 		return jsonResult(response);
 	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "people", VALID_ACTIONS$6));
+	return inputErrorResult(ErrorMessages.invalidAction(action, "people", VALID_ACTIONS$1));
 }
 /**
 * Projects MCP handler.
+*
+* Uses the createResourceHandler factory for the common list/get/resolve pattern.
 */
-var VALID_ACTIONS$5 = [
-	"list",
-	"get",
-	"resolve"
-];
-async function handleProjects(action, args, ctx) {
-	const { formatOptions, filter, page, perPage } = ctx;
-	const { id, query, type } = args;
-	if (action === "resolve") return handleResolve({
-		query,
-		type
-	}, ctx);
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const formatted = formatProject$1((await getProject({ id }, execCtx)).data, formatOptions);
-		if (ctx.includeHints !== false) return jsonResult({
-			...formatted,
-			_hints: getProjectHints(id)
-		});
-		return jsonResult(formatted);
-	}
-	if (action === "list") {
-		const result = await listProjects({
-			page,
-			perPage,
-			additionalFilters: filter
-		}, execCtx);
-		const response = formatListResponse$1(result.data, formatProject$1, result.meta, formatOptions);
-		if (result.resolved && Object.keys(result.resolved).length > 0) return jsonResult({
-			...response,
-			_resolved: result.resolved
-		});
-		return jsonResult(response);
+/**
+* Handle projects resource.
+*
+* Supports: list, get, resolve
+*/
+const handleProjects = createResourceHandler({
+	resource: "projects",
+	actions: [
+		"list",
+		"get",
+		"resolve"
+	],
+	formatter: formatProject$1,
+	hints: (_data, id) => getProjectHints(id),
+	supportsResolve: true,
+	executors: {
+		list: listProjects,
+		get: getProject
 	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "projects", VALID_ACTIONS$5));
-}
+});
 /**
 * Reports MCP handler.
 */
@@ -2299,11 +2264,11 @@ function formatReportData(data) {
 		};
 	});
 }
-var VALID_ACTIONS$4 = ["get"];
+var VALID_ACTIONS = ["get"];
 async function handleReports(action, args, ctx) {
 	const { filter, page, perPage } = ctx;
 	const { report_type, group, from, to, person_id, project_id, company_id, deal_id, status } = args;
-	if (action !== "get") return inputErrorResult(ErrorMessages.invalidAction(action, "reports", VALID_ACTIONS$4));
+	if (action !== "get") return inputErrorResult(ErrorMessages.invalidAction(action, "reports", VALID_ACTIONS));
 	if (!report_type) return inputErrorResult(ErrorMessages.missingReportType());
 	if (!VALID_REPORT_TYPES.includes(report_type)) return inputErrorResult(ErrorMessages.invalidReportType(report_type, [...VALID_REPORT_TYPES]));
 	const execCtx = ctx.executor();
@@ -2327,245 +2292,620 @@ async function handleReports(action, args, ctx) {
 	});
 }
 /**
-* Services MCP handler.
+* Schema definitions for all resources.
+*
+* This provides a compact, machine-readable specification of each resource's
+* capabilities. For detailed documentation with examples, use action=help.
 */
-var VALID_ACTIONS$3 = ["list"];
-async function handleServices(action, _args, ctx) {
-	const { formatOptions, filter, page, perPage } = ctx;
-	if (action === "list") {
-		const execCtx = ctx.executor();
-		const result = await listServices({
-			page,
-			perPage,
-			additionalFilters: filter
-		}, execCtx);
-		return jsonResult(formatListResponse$1(result.data, formatService$1, result.meta, formatOptions));
-	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "services", VALID_ACTIONS$3));
+var RESOURCE_SCHEMAS = {
+	projects: {
+		actions: [
+			"list",
+			"get",
+			"resolve"
+		],
+		filters: {
+			query: "string — text search on project name",
+			project_type: "1=internal|2=client",
+			company_id: "string",
+			responsible_id: "string",
+			person_id: "string",
+			status: "1=active|2=archived"
+		}
+	},
+	time: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update",
+			"delete"
+		],
+		filters: {
+			person_id: "string — use 'me' for current user",
+			after: "date YYYY-MM-DD",
+			before: "date YYYY-MM-DD",
+			project_id: "string",
+			service_id: "string",
+			task_id: "string",
+			status: "1=approved|2=unapproved|3=rejected"
+		},
+		create: {
+			person_id: {
+				required: true,
+				type: "string"
+			},
+			service_id: {
+				required: true,
+				type: "string"
+			},
+			date: {
+				required: true,
+				type: "date YYYY-MM-DD"
+			},
+			time: {
+				required: true,
+				type: "minutes integer"
+			},
+			note: {
+				required: false,
+				type: "string"
+			},
+			task_id: {
+				required: false,
+				type: "string"
+			}
+		},
+		includes: [
+			"person",
+			"service",
+			"task"
+		]
+	},
+	tasks: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update",
+			"resolve"
+		],
+		filters: {
+			query: "string — text search on task title",
+			project_id: "string",
+			assignee_id: "string",
+			status: "1=open|2=closed (or \"open\", \"closed\", \"all\")",
+			task_list_id: "string",
+			workflow_status_id: "string — kanban column"
+		},
+		create: {
+			title: {
+				required: true,
+				type: "string"
+			},
+			project_id: {
+				required: true,
+				type: "string"
+			},
+			task_list_id: {
+				required: true,
+				type: "string"
+			},
+			description: {
+				required: false,
+				type: "string"
+			},
+			assignee_id: {
+				required: false,
+				type: "string"
+			}
+		},
+		includes: [
+			"project",
+			"assignee",
+			"comments",
+			"subtasks",
+			"workflow_status"
+		]
+	},
+	services: {
+		actions: ["list", "get"],
+		filters: {
+			project_id: "string",
+			deal_id: "string",
+			task_id: "string",
+			budget_status: "1=open|2=delivered"
+		}
+	},
+	people: {
+		actions: [
+			"list",
+			"get",
+			"me",
+			"resolve"
+		],
+		filters: {
+			query: "string — text search on name or email",
+			status: "1=active|2=deactivated",
+			company_id: "string"
+		}
+	},
+	companies: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update",
+			"resolve"
+		],
+		filters: {
+			query: "string — text search on company name",
+			archived: "boolean"
+		},
+		create: { name: {
+			required: true,
+			type: "string"
+		} }
+	},
+	comments: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update"
+		],
+		filters: {
+			task_id: "string",
+			deal_id: "string",
+			page_id: "string",
+			discussion_id: "string"
+		},
+		create: {
+			body: {
+				required: true,
+				type: "string"
+			},
+			task_id: {
+				required: false,
+				type: "string — one of task_id, deal_id required"
+			},
+			deal_id: {
+				required: false,
+				type: "string — one of task_id, deal_id required"
+			}
+		},
+		includes: ["creator"]
+	},
+	attachments: {
+		actions: [
+			"list",
+			"get",
+			"delete"
+		],
+		filters: {
+			task_id: "string",
+			comment_id: "string",
+			deal_id: "string",
+			page_id: "string"
+		}
+	},
+	timers: {
+		actions: [
+			"list",
+			"get",
+			"start",
+			"stop"
+		],
+		filters: {
+			person_id: "string",
+			time_entry_id: "string"
+		}
+	},
+	deals: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update",
+			"resolve"
+		],
+		filters: {
+			query: "string — text search on deal name",
+			company_id: "string",
+			type: "1=deal|2=budget",
+			stage_status_id: "1=open|2=won|3=lost"
+		},
+		create: {
+			name: {
+				required: true,
+				type: "string"
+			},
+			company_id: {
+				required: true,
+				type: "string"
+			}
+		},
+		includes: ["company", "deal_status"]
+	},
+	bookings: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update"
+		],
+		filters: {
+			person_id: "string",
+			after: "date YYYY-MM-DD",
+			before: "date YYYY-MM-DD",
+			service_id: "string"
+		},
+		create: {
+			person_id: {
+				required: true,
+				type: "string"
+			},
+			started_on: {
+				required: true,
+				type: "date YYYY-MM-DD"
+			},
+			ended_on: {
+				required: true,
+				type: "date YYYY-MM-DD"
+			},
+			service_id: {
+				required: false,
+				type: "string — one of service_id, event_id required"
+			},
+			event_id: {
+				required: false,
+				type: "string — one of service_id, event_id required"
+			}
+		}
+	},
+	pages: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update",
+			"delete"
+		],
+		filters: { project_id: "string" },
+		create: {
+			title: {
+				required: true,
+				type: "string"
+			},
+			project_id: {
+				required: true,
+				type: "string"
+			},
+			body: {
+				required: false,
+				type: "string"
+			},
+			parent_page_id: {
+				required: false,
+				type: "string"
+			}
+		}
+	},
+	discussions: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update",
+			"delete",
+			"resolve",
+			"reopen"
+		],
+		filters: {
+			page_id: "string",
+			status: "1=active|2=resolved"
+		},
+		create: {
+			body: {
+				required: true,
+				type: "string"
+			},
+			page_id: {
+				required: true,
+				type: "string"
+			}
+		}
+	},
+	reports: {
+		actions: ["get"],
+		filters: {
+			person_id: "string",
+			project_id: "string",
+			company_id: "string",
+			after: "date YYYY-MM-DD",
+			before: "date YYYY-MM-DD"
+		},
+		create: {
+			report_type: {
+				required: true,
+				type: "time_reports|project_reports|budget_reports|..."
+			},
+			from: {
+				required: false,
+				type: "date YYYY-MM-DD"
+			},
+			to: {
+				required: false,
+				type: "date YYYY-MM-DD"
+			},
+			group: {
+				required: false,
+				type: "string — grouping dimension"
+			}
+		}
+	}
+};
+/**
+* Handle schema action - returns compact specification for a specific resource
+*/
+function handleSchema(resource) {
+	const schema = RESOURCE_SCHEMAS[resource];
+	if (!schema) return errorResult(`Unknown resource: ${resource}. Valid resources: ${Object.keys(RESOURCE_SCHEMAS).join(", ")}`);
+	return jsonResult({
+		resource,
+		...schema
+	});
 }
 /**
-* Tasks MCP handler.
+* Get schema overview for all resources
 */
-var DEFAULT_TASK_INCLUDE = ["project", "project.company"];
-var VALID_ACTIONS$2 = [
-	"list",
-	"get",
-	"create",
-	"update",
-	"resolve"
+function handleSchemaOverview() {
+	return jsonResult({
+		_tip: "Use action=\"schema\" with a specific resource for full filter/create/includes spec",
+		resources: Object.entries(RESOURCE_SCHEMAS).map(([resource, schema]) => ({
+			resource,
+			actions: schema.actions
+		}))
+	});
+}
+/**
+* Resources that support the query filter for text search
+*/
+const SEARCHABLE_RESOURCES = [
+	"projects",
+	"companies",
+	"people",
+	"tasks",
+	"deals"
 ];
-async function handleTasks(action, args, ctx) {
-	const { formatOptions, filter, page, perPage, include: userInclude } = ctx;
-	const { id, title, project_id, task_list_id, description, assignee_id, query, type } = args;
-	const include = userInclude?.length ? [...new Set([...DEFAULT_TASK_INCLUDE, ...userInclude])] : DEFAULT_TASK_INCLUDE;
-	if (action === "resolve") return handleResolve({
-		query,
-		type,
-		project_id
-	}, ctx);
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const result = await getTask({
-			id,
-			include
-		}, execCtx);
-		const formatted = formatTask$1(result.data, {
-			...formatOptions,
-			included: result.included
-		});
-		if (ctx.includeHints !== false) {
-			const serviceId = result.data.relationships?.service?.data?.id;
-			return jsonResult({
-				...formatted,
-				_hints: getTaskHints(id, serviceId)
-			});
+/**
+* Default resources to search when not specified
+*/
+var DEFAULT_SEARCH_RESOURCES = [
+	"projects",
+	"companies",
+	"people",
+	"tasks"
+];
+/**
+* Handle cross-resource search.
+*
+* @param query - Search query text (required)
+* @param resources - Resource types to search (optional, defaults to DEFAULT_SEARCH_RESOURCES)
+* @param credentials - Productive API credentials
+* @param execute - Function to execute tool calls (injected for delegation and testing)
+* @returns Grouped search results across all requested resources
+*/
+async function handleSearch(query, resources, credentials, execute) {
+	if (!query || query.trim() === "") return errorResult("Missing required parameter: query. Provide a non-empty search string.");
+	const trimmedQuery = query.trim();
+	const resourcesToSearch = resources && resources.length > 0 ? resources : DEFAULT_SEARCH_RESOURCES;
+	const invalidResources = resourcesToSearch.filter((r) => !SEARCHABLE_RESOURCES.includes(r));
+	if (invalidResources.length > 0) return errorResult(`Invalid searchable resources: ${invalidResources.join(", ")}. Valid searchable resources: ${SEARCHABLE_RESOURCES.join(", ")}.`);
+	const searchPromises = resourcesToSearch.map(async (resource) => {
+		try {
+			const textContent = (await execute("productive", {
+				resource,
+				action: "list",
+				query: trimmedQuery,
+				compact: true,
+				per_page: 10
+			}, credentials)).content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") return [resource, { error: "No content in response" }];
+			try {
+				const parsed = JSON.parse(textContent.text);
+				const items = parsed.items ?? parsed.data ?? [];
+				return [resource, { items: Array.isArray(items) ? items : [] }];
+			} catch {
+				return [resource, { error: "Failed to parse response JSON" }];
+			}
+		} catch (err) {
+			return [resource, { error: err instanceof Error ? err.message : String(err) }];
 		}
-		return jsonResult(formatted);
+	});
+	const searchResults = await Promise.all(searchPromises);
+	const results = {};
+	let totalResults = 0;
+	for (const [resource, result] of searchResults) if (result.error) results[resource] = { error: result.error };
+	else {
+		const items = result.items ?? [];
+		results[resource] = items;
+		totalResults += items.length;
 	}
-	if (action === "create") {
-		if (!title || !project_id || !task_list_id) return inputErrorResult(ErrorMessages.missingRequiredFields("task", [
+	return jsonResult({
+		query: trimmedQuery,
+		resources_searched: resourcesToSearch,
+		results,
+		total_results: totalResults
+	});
+}
+/**
+* Services MCP handler.
+*
+* Uses the createResourceHandler factory for the common list pattern.
+*/
+/**
+* Handle services resource.
+*
+* Supports: list
+*/
+const handleServices = createResourceHandler({
+	resource: "services",
+	actions: ["list"],
+	formatter: formatService$1,
+	executors: { list: listServices }
+});
+/**
+* Tasks MCP handler.
+*/
+const handleTasks = createResourceHandler({
+	resource: "tasks",
+	displayName: "task",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update",
+		"resolve"
+	],
+	formatter: formatTask$1,
+	hints: (data, id) => {
+		const serviceId = data.relationships?.service?.data?.id;
+		return getTaskHints(id, serviceId);
+	},
+	supportsResolve: true,
+	resolveArgsFromArgs: (args) => ({ project_id: args.project_id }),
+	defaultInclude: {
+		list: ["project", "project.company"],
+		get: ["project", "project.company"]
+	},
+	create: {
+		required: [
 			"title",
 			"project_id",
 			"task_list_id"
-		]));
-		return jsonResult({
-			success: true,
-			...formatTask$1((await createTask({
-				title,
-				projectId: project_id,
-				taskListId: task_list_id,
-				assigneeId: assignee_id,
-				description
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "update") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
-		return jsonResult({
-			success: true,
-			...formatTask$1((await updateTask({
-				id,
-				title,
-				description,
-				assigneeId: assignee_id
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "list") {
-		const result = await listTasks({
-			page,
-			perPage,
-			additionalFilters: filter,
-			include
-		}, execCtx);
-		const response = formatListResponse$1(result.data, formatTask$1, result.meta, {
-			...formatOptions,
-			included: result.included
-		});
-		if (result.resolved && Object.keys(result.resolved).length > 0) return jsonResult({
-			...response,
-			_resolved: result.resolved
-		});
-		return jsonResult(response);
+		],
+		mapOptions: (args) => ({
+			title: args.title,
+			projectId: args.project_id,
+			taskListId: args.task_list_id,
+			assigneeId: args.assignee_id,
+			description: args.description
+		})
+	},
+	update: { mapOptions: (args) => ({
+		title: args.title,
+		description: args.description,
+		assigneeId: args.assignee_id
+	}) },
+	executors: {
+		list: listTasks,
+		get: getTask,
+		create: createTask,
+		update: updateTask
 	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "tasks", VALID_ACTIONS$2));
-}
+});
 /**
 * Time entries MCP handler.
 *
 * Thin adapter that delegates business logic to core executors
 * and handles MCP-specific concerns (hints, error formatting, JSON results).
 */
-var VALID_ACTIONS$1 = [
-	"list",
-	"get",
-	"create",
-	"update",
-	"resolve"
-];
-async function handleTime(action, args, ctx) {
-	const { formatOptions, filter, page, perPage } = ctx;
-	const { id, person_id, service_id, task_id, time, date, note, query, type, project_id } = args;
-	if (action === "resolve") return handleResolve({
-		query,
-		type,
-		project_id
-	}, ctx);
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const result = await getTimeEntry({ id }, execCtx);
-		const formatted = formatTimeEntry$1(result.data, formatOptions);
-		if (ctx.includeHints !== false) {
-			const serviceId = result.data.relationships?.service?.data?.id;
-			return jsonResult({
-				...formatted,
-				_hints: getTimeEntryHints(id, void 0, serviceId)
-			});
-		}
-		return jsonResult(formatted);
-	}
-	if (action === "create") {
-		if (!person_id || !service_id || !time || !date) return inputErrorResult(ErrorMessages.missingRequiredFields("time entry", [
+const handleTime = createResourceHandler({
+	resource: "time",
+	displayName: "time entry",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update",
+		"delete",
+		"resolve"
+	],
+	formatter: formatTimeEntry$1,
+	hints: (data, id) => {
+		const serviceId = data.relationships?.service?.data?.id;
+		return getTimeEntryHints(id, void 0, serviceId);
+	},
+	supportsResolve: true,
+	resolveArgsFromArgs: (args) => ({ project_id: args.project_id }),
+	create: {
+		required: [
 			"person_id",
 			"service_id",
 			"time",
 			"date"
-		]));
-		return jsonResult({
-			success: true,
-			...formatTimeEntry$1((await createTimeEntry({
-				personId: person_id,
-				serviceId: service_id,
-				time,
-				date,
-				note: note ?? void 0,
-				taskId: task_id,
-				projectId: project_id
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "update") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
-		return jsonResult({
-			success: true,
-			...formatTimeEntry$1((await updateTimeEntry({
-				id,
-				time: time ?? void 0,
-				date: date ?? void 0,
-				note: note ?? void 0
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "list") {
-		const result = await listTimeEntries({
-			page,
-			perPage,
-			additionalFilters: filter
-		}, execCtx);
-		const response = formatListResponse$1(result.data, formatTimeEntry$1, result.meta, formatOptions);
-		if (result.resolved && Object.keys(result.resolved).length > 0) return jsonResult({
-			...response,
-			_resolved: result.resolved
-		});
-		return jsonResult(response);
+		],
+		mapOptions: (args) => ({
+			personId: args.person_id,
+			serviceId: args.service_id,
+			time: args.time,
+			date: args.date,
+			note: args.note ?? void 0,
+			taskId: args.task_id,
+			projectId: args.project_id
+		})
+	},
+	update: { mapOptions: (args) => ({
+		time: args.time ?? void 0,
+		date: args.date ?? void 0,
+		note: args.note ?? void 0
+	}) },
+	executors: {
+		list: listTimeEntries,
+		get: getTimeEntry,
+		create: createTimeEntry,
+		update: updateTimeEntry,
+		delete: deleteTimeEntry
 	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "time", VALID_ACTIONS$1));
-}
+});
 /**
 * Timers MCP handler.
 */
-var VALID_ACTIONS = [
-	"list",
-	"get",
-	"start",
-	"stop"
-];
-async function handleTimers(action, args, ctx) {
-	const { formatOptions, filter, page, perPage, include } = ctx;
-	const { id, service_id, time_entry_id } = args;
-	const execCtx = ctx.executor();
-	if (action === "get") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
-		const formatted = formatTimer$1((await getTimer({
-			id,
-			include
-		}, execCtx)).data, formatOptions);
-		if (ctx.includeHints !== false) return jsonResult({
-			...formatted,
-			_hints: getTimerHints(id)
-		});
-		return jsonResult(formatted);
-	}
-	if (action === "start" || action === "create") {
-		if (!service_id && !time_entry_id) return inputErrorResult(ErrorMessages.missingServiceForTimer());
-		return jsonResult({
-			success: true,
-			...formatTimer$1((await startTimer({
-				serviceId: service_id,
-				timeEntryId: time_entry_id
-			}, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "stop") {
-		if (!id) return inputErrorResult(ErrorMessages.missingId("stop"));
-		return jsonResult({
-			success: true,
-			...formatTimer$1((await stopTimer({ id }, execCtx)).data, formatOptions)
-		});
-	}
-	if (action === "list") {
-		const result = await listTimers({
-			page,
-			perPage,
-			additionalFilters: filter,
-			include
-		}, execCtx);
-		return jsonResult(formatListResponse$1(result.data, formatTimer$1, result.meta, formatOptions));
+const handleTimers = createResourceHandler({
+	resource: "timers",
+	actions: [
+		"list",
+		"get",
+		"start",
+		"stop"
+	],
+	formatter: formatTimer$1,
+	hints: (_data, id) => getTimerHints(id),
+	customActions: {
+		start: async (args, ctx, execCtx) => {
+			if (!args.service_id && !args.time_entry_id) return inputErrorResult(ErrorMessages.missingServiceForTimer());
+			return jsonResult({
+				success: true,
+				...formatTimer$1((await startTimer({
+					serviceId: args.service_id,
+					timeEntryId: args.time_entry_id
+				}, execCtx)).data, ctx.formatOptions)
+			});
+		},
+		create: async (args, ctx, execCtx) => {
+			if (!args.service_id && !args.time_entry_id) return inputErrorResult(ErrorMessages.missingServiceForTimer());
+			return jsonResult({
+				success: true,
+				...formatTimer$1((await startTimer({
+					serviceId: args.service_id,
+					timeEntryId: args.time_entry_id
+				}, execCtx)).data, ctx.formatOptions)
+			});
+		},
+		stop: async (args, ctx, execCtx) => {
+			if (!args.id) return inputErrorResult(ErrorMessages.missingId("stop"));
+			return jsonResult({
+				success: true,
+				...formatTimer$1((await stopTimer({ id: args.id }, execCtx)).data, ctx.formatOptions)
+			});
+		}
+	},
+	executors: {
+		list: listTimers,
+		get: getTimer
 	}
-	return inputErrorResult(ErrorMessages.invalidAction(action, "timers", VALID_ACTIONS));
-}
+});
 /**
 * Tool execution handlers for Productive MCP server
 * These are shared between stdio and HTTP transports
@@ -2581,13 +2921,17 @@ var DEFAULT_PER_PAGE = 20;
 * Execute a tool with the given credentials and arguments
 */
 async function executeToolWithCredentials(name, args, credentials) {
+	if (name !== "productive") return errorResult(`Unknown tool: ${name}`);
+	const typedArgs = args;
+	if (typedArgs.resource === "batch") return handleBatch(typedArgs.operations, credentials, executeToolWithCredentials);
+	const { resource, action, filter, page, per_page, compact, include, query, resources, no_hints, type, ...restArgs } = typedArgs;
+	if (resource === "search") return await handleSearch(query, resources, credentials, executeToolWithCredentials);
 	const api = new ProductiveApi({ config: {
 		apiToken: credentials.apiToken,
 		organizationId: credentials.organizationId,
-		userId: credentials.userId
+		userId: credentials.userId,
+		baseUrl: process.env.PRODUCTIVE_BASE_URL
 	} });
-	if (name !== "productive") return errorResult(`Unknown tool: ${name}`);
-	const { resource, action, filter, page, per_page, compact, include, query, no_hints, type, ...restArgs } = args;
 	const isCompact = compact ?? action !== "get";
 	const formatOptions = { compact: isCompact };
 	let stringFilter = toStringFilter(filter);
@@ -2609,6 +2953,7 @@ async function executeToolWithCredentials(name, args, credentials) {
 	};
 	try {
 		if (action === "help") return resource ? handleHelp(resource) : handleHelpOverview();
+		if (action === "schema") return resource ? handleSchema(resource) : handleSchemaOverview();
 		const resolveArgs = {
 			query,
 			type
@@ -2643,10 +2988,14 @@ async function executeToolWithCredentials(name, args, credentials) {
 				...resolveArgs
 			}, ctx);
 			case "bookings": return await handleBookings(action, restArgs, ctx);
-			case "budgets": return await handleBudgets(action, restArgs, ctx);
 			case "pages": return await handlePages(action, restArgs, ctx);
 			case "discussions": return await handleDiscussions(action, restArgs, ctx);
 			case "reports": return await handleReports(action, restArgs, ctx);
+			case "budgets": return inputErrorResult(new UserInputError("The \"budgets\" resource has been removed. Budgets are deals with type=2.", [
+				"Use resource=\"deals\" with filter[type]=\"2\" to list only budgets",
+				"To create a budget: resource=\"deals\" action=\"create\" with budget=true",
+				"Use action=\"help\" resource=\"deals\" for full documentation"
+			]));
 			default: return inputErrorResult(ErrorMessages.unknownResource(resource, VALID_RESOURCES));
 		}
 	} catch (error) {
@@ -2662,4 +3011,4 @@ async function executeToolWithCredentials(name, args, credentials) {
 }
 export { executeToolWithCredentials as t };
 
-//# sourceMappingURL=handlers-D4tRd30c.js.map
+//# sourceMappingURL=handlers-DWowqxFA.js.map