@studiometa/productive-mcp 0.10.0 → 0.10.1

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

@@ -988,6 +988,112 @@ const handleAttachments = createResourceHandler({
 	}
 });
 /**
+* 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 (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)
+		};
+	}
+}
+/**
+* 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;
+	}
+	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({
@@ -1228,6 +1334,56 @@ const handleDiscussions = createResourceHandler({
 	}
 });
 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: {
@@ -1949,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,
@@ -1966,7 +2123,8 @@ 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."
 	});
 }
 /**
@@ -2134,6 +2292,454 @@ async function handleReports(action, args, ctx) {
 	});
 }
 /**
+* 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 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
+	});
+}
+/**
+* Get schema overview for all resources
+*/
+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"
+];
+/**
+* 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) }];
+		}
+	});
+	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;
+	}
+	return jsonResult({
+		query: trimmedQuery,
+		resources_searched: resourcesToSearch,
+		results,
+		total_results: totalResults
+	});
+}
+/**
 * Services MCP handler.
 *
 * Uses the createResourceHandler factory for the common list pattern.
@@ -2315,14 +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,
 		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);
@@ -2344,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
@@ -2401,4 +3011,4 @@ async function executeToolWithCredentials(name, args, credentials) {
 }
 export { executeToolWithCredentials as t };
 
-//# sourceMappingURL=handlers-BE3CYyVX.js.map
+//# sourceMappingURL=handlers-DWowqxFA.js.map