@studiometa/productive-mcp 0.7.0 → 0.8.0

package/dist/{index-B2DTeltj.js → index-D743zTS1.js}

@@ -1,4 +1,100 @@
 import { formatBooking as formatBooking$1, formatListResponse as formatListResponse$1, formatDeal as formatDeal$1, formatTimer as formatTimer$1, formatComment as formatComment$1, formatCompany as formatCompany$1, formatPerson as formatPerson$1, formatService as formatService$1, formatTask as formatTask$1, formatTimeEntry as formatTimeEntry$1, formatProject as formatProject$1, ProductiveApi } from "@studiometa/productive-cli";
+class UserInputError extends Error {
+  hints;
+  constructor(message, hints) {
+    super(message);
+    this.name = "UserInputError";
+    this.hints = hints;
+  }
+  /**
+   * Format error message with hints for LLM consumption
+   */
+  toFormattedMessage() {
+    let msg = `**Input Error:** ${this.message}`;
+    if (this.hints && this.hints.length > 0) {
+      msg += "\n\n**Hints:**\n" + this.hints.map((h) => `- ${h}`).join("\n");
+    }
+    return msg;
+  }
+}
+const ErrorMessages = {
+  // Required field errors
+  missingId: (action) => new UserInputError(`id is required for ${action} action`, [
+    `Use action="list" first to find the resource ID`,
+    `Then use action="${action}" with the id parameter`
+  ]),
+  missingRequiredFields: (resource, fields) => new UserInputError(
+    `${fields.join(", ")} ${fields.length === 1 ? "is" : "are"} required for creating ${resource}`,
+    [
+      `Provide all required fields: ${fields.join(", ")}`,
+      `Use action="help" for detailed documentation on ${resource}`
+    ]
+  ),
+  // Invalid action errors
+  invalidAction: (action, resource, validActions) => new UserInputError(`Invalid action "${action}" for ${resource}`, [
+    `Valid actions are: ${validActions.join(", ")}`,
+    `Use action="help" with resource="${resource}" for detailed documentation`
+  ]),
+  // Unknown resource errors
+  unknownResource: (resource, validResources) => new UserInputError(`Unknown resource: ${resource}`, [
+    `Valid resources are: ${validResources.join(", ")}`,
+    `Use action="help" without a resource for an overview of all resources`
+  ]),
+  // Report-specific errors
+  missingReportType: () => new UserInputError("report_type is required for reports", [
+    'Specify report_type parameter (e.g., "time_reports", "project_reports")',
+    'Use action="help" with resource="reports" for available report types'
+  ]),
+  invalidReportType: (reportType, validTypes) => new UserInputError(`Invalid report_type: ${reportType}`, [
+    `Valid report types are: ${validTypes.join(", ")}`,
+    'Use action="help" with resource="reports" for detailed documentation'
+  ]),
+  // Timer-specific errors
+  missingServiceForTimer: () => new UserInputError("service_id is required to start a timer", [
+    'First find a service using resource="services" action="list"',
+    "Then start the timer with the service_id"
+  ]),
+  // People-specific errors
+  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'
+  ]),
+  // Comment-specific errors
+  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"'
+  ]),
+  // Booking-specific errors
+  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"'
+  ]),
+  // API errors
+  apiError: (statusCode, message) => {
+    const hints = [];
+    if (statusCode === 401) {
+      hints.push("Check that your API token is valid and not expired");
+      hints.push("Verify the organization ID is correct");
+    } else if (statusCode === 403) {
+      hints.push("You may not have permission to access this resource");
+      hints.push("Check your API token permissions");
+    } else if (statusCode === 404) {
+      hints.push("The resource may not exist or you may not have access");
+      hints.push("Verify the resource ID is correct");
+      hints.push('Use action="list" to find valid resource IDs');
+    } else if (statusCode === 422) {
+      hints.push("The request data may be invalid");
+      hints.push("Check the field values and types");
+      hints.push('Use action="help" for field documentation');
+    } else if (statusCode >= 500) {
+      hints.push("This is a server error - try again later");
+    }
+    return new UserInputError(`API error (${statusCode}): ${message}`, hints);
+  }
+};
+function isUserInputError(error) {
+  return error instanceof UserInputError;
+}
 const MCP_FORMAT_OPTIONS = {
   includeRelationshipIds: false,
   includeTimestamps: false,
@@ -101,10 +197,23 @@ function jsonResult(data) {
 }
 function errorResult(message) {
   return {
-    content: [{ type: "text", text: `Error: ${message}` }],
+    content: [{ type: "text", text: `**Error:** ${message}` }],
     isError: true
   };
 }
+function inputErrorResult(error) {
+  return {
+    content: [{ type: "text", text: error.toFormattedMessage() }],
+    isError: true
+  };
+}
+function formatError(error) {
+  if (isUserInputError(error)) {
+    return inputErrorResult(error);
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return errorResult(message);
+}
 function toStringFilter(filter) {
   if (!filter) return void 0;
   const result = {};
@@ -116,21 +225,24 @@ function toStringFilter(filter) {
   return Object.keys(result).length > 0 ? result : void 0;
 }
 const DEFAULT_BOOKING_INCLUDE = ["person", "service"];
+const VALID_ACTIONS$a = ["list", "get", "create", "update"];
 async function handleBookings(action, args, ctx) {
   const { api, 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 ? [.../* @__PURE__ */ new Set([...DEFAULT_BOOKING_INCLUDE, ...userInclude])] : DEFAULT_BOOKING_INCLUDE;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getBooking(id, { include });
     return jsonResult(formatBooking(result.data, { ...formatOptions, included: result.included }));
   }
   if (action === "create") {
     if (!person_id || !started_on || !ended_on) {
-      return errorResult("person_id, started_on, and ended_on are required for create");
+      return inputErrorResult(
+        ErrorMessages.missingRequiredFields("booking", ["person_id", "started_on", "ended_on"])
+      );
     }
     if (!service_id && !event_id) {
-      return errorResult("service_id or event_id is required for create");
+      return inputErrorResult(ErrorMessages.missingBookingTarget());
     }
     const result = await api.createBooking({
       person_id,
@@ -144,7 +256,7 @@ async function handleBookings(action, args, ctx) {
     return jsonResult({ success: true, ...formatBooking(result.data, formatOptions) });
   }
   if (action === "update") {
-    if (!id) return errorResult("id is required for update action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
     const updateData = {};
     if (started_on !== void 0) updateData.started_on = started_on;
     if (ended_on !== void 0) updateData.ended_on = ended_on;
@@ -162,22 +274,23 @@ async function handleBookings(action, args, ctx) {
       })
     );
   }
-  return errorResult(`Invalid action "${action}" for bookings. Use: list, get, create, update`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "bookings", VALID_ACTIONS$a));
 }
 const DEFAULT_COMMENT_INCLUDE = ["creator"];
+const VALID_ACTIONS$9 = ["list", "get", "create", "update"];
 async function handleComments(action, args, ctx) {
   const { api, formatOptions, filter, page, perPage, include: userInclude } = ctx;
   const { id, body, task_id, deal_id, company_id } = args;
   const include = userInclude?.length ? [.../* @__PURE__ */ new Set([...DEFAULT_COMMENT_INCLUDE, ...userInclude])] : DEFAULT_COMMENT_INCLUDE;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getComment(id, { include });
     return jsonResult(formatComment(result.data, { ...formatOptions, included: result.included }));
   }
   if (action === "create") {
-    if (!body) return errorResult("body is required for create");
+    if (!body) return inputErrorResult(ErrorMessages.missingRequiredFields("comment", ["body"]));
     if (!task_id && !deal_id && !company_id) {
-      return errorResult("task_id, deal_id, or company_id is required for create");
+      return inputErrorResult(ErrorMessages.missingCommentTarget());
     }
     const result = await api.createComment({
       body,
@@ -188,8 +301,9 @@ async function handleComments(action, args, ctx) {
     return jsonResult({ success: true, ...formatComment(result.data, formatOptions) });
   }
   if (action === "update") {
-    if (!id) return errorResult("id is required for update action");
-    if (!body) return errorResult("body is required for update");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
+    if (!body)
+      return inputErrorResult(ErrorMessages.missingRequiredFields("comment update", ["body"]));
     const result = await api.updateComment(id, { body });
     return jsonResult({ success: true, ...formatComment(result.data, formatOptions) });
   }
@@ -202,23 +316,24 @@ async function handleComments(action, args, ctx) {
       })
     );
   }
-  return errorResult(`Invalid action "${action}" for comments. Use: list, get, create, update`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "comments", VALID_ACTIONS$9));
 }
+const VALID_ACTIONS$8 = ["list", "get", "create", "update"];
 async function handleCompanies(action, args, ctx) {
   const { api, formatOptions, filter, page, perPage } = ctx;
   const { id, name } = args;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getCompany(id);
     return jsonResult(formatCompany(result.data, formatOptions));
   }
   if (action === "create") {
-    if (!name) return errorResult("name is required for create");
+    if (!name) return inputErrorResult(ErrorMessages.missingRequiredFields("company", ["name"]));
     const result = await api.createCompany({ name });
     return jsonResult({ success: true, ...formatCompany(result.data, formatOptions) });
   }
   if (action === "update") {
-    if (!id) return errorResult("id is required for update action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
     const updateData = {};
     if (name !== void 0) updateData.name = name;
     const result = await api.updateCompany(id, updateData);
@@ -228,28 +343,29 @@ async function handleCompanies(action, args, ctx) {
     const result = await api.getCompanies({ filter, page, perPage });
     return jsonResult(formatListResponse(result.data, formatCompany, result.meta, formatOptions));
   }
-  return errorResult(`Invalid action "${action}" for companies. Use: list, get, create, update`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "companies", VALID_ACTIONS$8));
 }
 const DEFAULT_DEAL_INCLUDE_GET = ["company", "deal_status", "responsible"];
 const DEFAULT_DEAL_INCLUDE_LIST = ["company", "deal_status"];
+const VALID_ACTIONS$7 = ["list", "get", "create", "update"];
 async function handleDeals(action, args, ctx) {
   const { api, formatOptions, filter, page, perPage, include: userInclude } = ctx;
   const { id, name, company_id } = args;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const include = userInclude?.length ? [.../* @__PURE__ */ new Set([...DEFAULT_DEAL_INCLUDE_GET, ...userInclude])] : DEFAULT_DEAL_INCLUDE_GET;
     const result = await api.getDeal(id, { include });
     return jsonResult(formatDeal(result.data, { ...formatOptions, included: result.included }));
   }
   if (action === "create") {
     if (!name || !company_id) {
-      return errorResult("name and company_id are required for create");
+      return inputErrorResult(ErrorMessages.missingRequiredFields("deal", ["name", "company_id"]));
     }
     const result = await api.createDeal({ name, company_id });
     return jsonResult({ success: true, ...formatDeal(result.data, formatOptions) });
   }
   if (action === "update") {
-    if (!id) return errorResult("id is required for update action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
     const updateData = {};
     if (name !== void 0) updateData.name = name;
     const result = await api.updateDeal(id, updateData);
@@ -270,7 +386,7 @@ async function handleDeals(action, args, ctx) {
       })
     );
   }
-  return errorResult(`Invalid action "${action}" for deals. Use: list, get, create, update`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "deals", VALID_ACTIONS$7));
 }
 const RESOURCE_HELP = {
   projects: {
@@ -685,11 +801,12 @@ function handleHelpOverview() {
     resources: overview
   });
 }
+const VALID_ACTIONS$6 = ["list", "get", "me"];
 async function handlePeople(action, args, ctx, credentials) {
   const { api, formatOptions, filter, page, perPage } = ctx;
   const { id } = args;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getPerson(id);
     return jsonResult(formatPerson(result.data, formatOptions));
   }
@@ -700,6 +817,7 @@ async function handlePeople(action, args, ctx, credentials) {
     }
     return jsonResult({
       message: "User ID not configured. Set userId in credentials to use this action.",
+      hint: 'Use action="list" to find people, or configure the user ID in your credentials.',
       organizationId: credentials.organizationId
     });
   }
@@ -707,13 +825,14 @@ async function handlePeople(action, args, ctx, credentials) {
     const result = await api.getPeople({ filter, page, perPage });
     return jsonResult(formatListResponse(result.data, formatPerson, result.meta, formatOptions));
   }
-  return errorResult(`Invalid action "${action}" for people. Use: list, get, me`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "people", VALID_ACTIONS$6));
 }
+const VALID_ACTIONS$5 = ["list", "get"];
 async function handleProjects(action, args, ctx) {
   const { api, formatOptions, filter, page, perPage } = ctx;
   const { id } = args;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getProject(id);
     return jsonResult(formatProject(result.data, formatOptions));
   }
@@ -721,7 +840,7 @@ async function handleProjects(action, args, ctx) {
     const result = await api.getProjects({ filter, page, perPage });
     return jsonResult(formatListResponse(result.data, formatProject, result.meta, formatOptions));
   }
-  return errorResult(`Invalid action "${action}" for projects. Use: list, get`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "projects", VALID_ACTIONS$5));
 }
 function formatReportData(data) {
   return data.map((item) => {
@@ -746,19 +865,18 @@ const VALID_REPORT_TYPES = [
   "deal_reports",
   "timesheet_reports"
 ];
+const VALID_ACTIONS$4 = ["get"];
 async function handleReports(action, args, ctx) {
   const { api, filter, page, perPage } = ctx;
   const { report_type, group, from, to, person_id, project_id, company_id, deal_id, status } = args;
   if (action !== "get") {
-    return errorResult(`Invalid action "${action}" for reports. Use: get`);
+    return inputErrorResult(ErrorMessages.invalidAction(action, "reports", VALID_ACTIONS$4));
   }
   if (!report_type) {
-    return errorResult(`report_type is required. Valid types: ${VALID_REPORT_TYPES.join(", ")}`);
+    return inputErrorResult(ErrorMessages.missingReportType());
   }
   if (!VALID_REPORT_TYPES.includes(report_type)) {
-    return errorResult(
-      `Invalid report_type "${report_type}". Valid types: ${VALID_REPORT_TYPES.join(", ")}`
-    );
+    return inputErrorResult(ErrorMessages.invalidReportType(report_type, VALID_REPORT_TYPES));
   }
   const reportFilter = { ...filter };
   if (from) {
@@ -844,27 +962,31 @@ async function handleReports(action, args, ctx) {
     meta: result.meta
   });
 }
+const VALID_ACTIONS$3 = ["list"];
 async function handleServices(action, _args, ctx) {
   const { api, formatOptions, filter, page, perPage } = ctx;
   if (action === "list") {
     const result = await api.getServices({ filter, page, perPage });
     return jsonResult(formatListResponse(result.data, formatService, result.meta, formatOptions));
   }
-  return errorResult(`Invalid action "${action}" for services. Use: list`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "services", VALID_ACTIONS$3));
 }
 const DEFAULT_TASK_INCLUDE = ["project", "project.company"];
+const VALID_ACTIONS$2 = ["list", "get", "create", "update"];
 async function handleTasks(action, args, ctx) {
   const { api, formatOptions, filter, page, perPage, include: userInclude } = ctx;
   const { id, title, project_id, task_list_id, description, assignee_id } = args;
   const include = userInclude?.length ? [.../* @__PURE__ */ new Set([...DEFAULT_TASK_INCLUDE, ...userInclude])] : DEFAULT_TASK_INCLUDE;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getTask(id, { include });
     return jsonResult(formatTask(result.data, { ...formatOptions, included: result.included }));
   }
   if (action === "create") {
     if (!title || !project_id || !task_list_id) {
-      return errorResult("title, project_id, and task_list_id are required for create");
+      return inputErrorResult(
+        ErrorMessages.missingRequiredFields("task", ["title", "project_id", "task_list_id"])
+      );
     }
     const result = await api.createTask({
       title,
@@ -876,7 +998,7 @@ async function handleTasks(action, args, ctx) {
     return jsonResult({ success: true, ...formatTask(result.data, formatOptions) });
   }
   if (action === "update") {
-    if (!id) return errorResult("id is required for update action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
     const updateData = {};
     if (title !== void 0) updateData.title = title;
     if (description !== void 0) updateData.description = description;
@@ -893,19 +1015,27 @@ async function handleTasks(action, args, ctx) {
       })
     );
   }
-  return errorResult(`Invalid action "${action}" for tasks. Use: list, get, create, update`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "tasks", VALID_ACTIONS$2));
 }
+const VALID_ACTIONS$1 = ["list", "get", "create", "update"];
 async function handleTime(action, args, ctx) {
   const { api, formatOptions, filter, page, perPage } = ctx;
   const { id, person_id, service_id, task_id, time, date, note } = args;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getTimeEntry(id);
     return jsonResult(formatTimeEntry(result.data, formatOptions));
   }
   if (action === "create") {
     if (!person_id || !service_id || !time || !date) {
-      return errorResult("person_id, service_id, time, and date are required for create");
+      return inputErrorResult(
+        ErrorMessages.missingRequiredFields("time entry", [
+          "person_id",
+          "service_id",
+          "time",
+          "date"
+        ])
+      );
     }
     const result = await api.createTimeEntry({
       person_id,
@@ -918,7 +1048,7 @@ async function handleTime(action, args, ctx) {
     return jsonResult({ success: true, ...formatTimeEntry(result.data, formatOptions) });
   }
   if (action === "update") {
-    if (!id) return errorResult("id is required for update action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("update"));
     const updateData = {};
     if (time !== void 0) updateData.time = time;
     if (date !== void 0) updateData.date = date;
@@ -930,25 +1060,26 @@ async function handleTime(action, args, ctx) {
     const result = await api.getTimeEntries({ filter, page, perPage });
     return jsonResult(formatListResponse(result.data, formatTimeEntry, result.meta, formatOptions));
   }
-  return errorResult(`Invalid action "${action}" for time. Use: list, get, create, update`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "time", VALID_ACTIONS$1));
 }
+const VALID_ACTIONS = ["list", "get", "start", "stop"];
 async function handleTimers(action, args, ctx) {
   const { api, formatOptions, filter, page, perPage, include } = ctx;
   const { id, service_id, time_entry_id } = args;
   if (action === "get") {
-    if (!id) return errorResult("id is required for get action");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getTimer(id, { include });
     return jsonResult(formatTimer(result.data));
   }
   if (action === "start" || action === "create") {
     if (!service_id && !time_entry_id) {
-      return errorResult("service_id or time_entry_id is required to start a timer");
+      return inputErrorResult(ErrorMessages.missingServiceForTimer());
     }
     const result = await api.startTimer({ service_id, time_entry_id });
     return jsonResult({ success: true, ...formatTimer(result.data) });
   }
   if (action === "stop") {
-    if (!id) return errorResult("id is required to stop a timer");
+    if (!id) return inputErrorResult(ErrorMessages.missingId("stop"));
     const result = await api.stopTimer(id);
     return jsonResult({ success: true, ...formatTimer(result.data) });
   }
@@ -956,8 +1087,21 @@ async function handleTimers(action, args, ctx) {
     const result = await api.getTimers({ filter, page, perPage, include });
     return jsonResult(formatListResponse(result.data, formatTimer, result.meta, formatOptions));
   }
-  return errorResult(`Invalid action "${action}" for timers. Use: list, get, start, stop`);
+  return inputErrorResult(ErrorMessages.invalidAction(action, "timers", VALID_ACTIONS));
 }
+const VALID_RESOURCES = [
+  "projects",
+  "time",
+  "tasks",
+  "services",
+  "people",
+  "companies",
+  "comments",
+  "timers",
+  "deals",
+  "bookings",
+  "reports"
+];
 const DEFAULT_PER_PAGE = 20;
 async function executeToolWithCredentials(name, args, credentials) {
   const api = new ProductiveApi({
@@ -1012,14 +1156,22 @@ async function executeToolWithCredentials(name, args, credentials) {
       case "reports":
         return await handleReports(action, restArgs, ctx);
       default:
-        return errorResult(`Unknown resource: ${resource}`);
+        return inputErrorResult(ErrorMessages.unknownResource(resource, VALID_RESOURCES));
     }
   } catch (error) {
+    if (isUserInputError(error)) {
+      return formatError(error);
+    }
     const message = error instanceof Error ? error.message : String(error);
+    const statusMatch = message.match(/(\d{3})/);
+    if (statusMatch) {
+      const statusCode = Number.parseInt(statusMatch[1], 10);
+      return inputErrorResult(ErrorMessages.apiError(statusCode, message));
+    }
     return errorResult(message);
   }
 }
 export {
   executeToolWithCredentials as e
 };
-//# sourceMappingURL=index-B2DTeltj.js.map
+//# sourceMappingURL=index-D743zTS1.js.map