@studiometa/productive-mcp 0.8.2 → 0.8.4

package/dist/{index-BDke-bMP.js → index-CZpVCEu4.js}

@@ -190,6 +190,364 @@ function formatListResponse(data, formatter, meta, options) {
   });
   return result;
 }
+function getTaskHints(taskId, serviceId) {
+  const hints = {
+    related_resources: [
+      {
+        resource: "comments",
+        description: "Get comments on this task",
+        example: {
+          resource: "comments",
+          action: "list",
+          filter: { task_id: taskId }
+        }
+      },
+      {
+        resource: "time",
+        description: "Get time entries logged on this task",
+        example: {
+          resource: "time",
+          action: "list",
+          filter: { task_id: taskId }
+        }
+      },
+      {
+        resource: "tasks",
+        description: "Get subtasks of this task",
+        example: {
+          resource: "tasks",
+          action: "list",
+          filter: { parent_task_id: taskId }
+        }
+      }
+    ],
+    common_actions: [
+      {
+        action: "Add a comment",
+        example: {
+          resource: "comments",
+          action: "create",
+          task_id: taskId,
+          body: "<your comment>"
+        }
+      }
+    ]
+  };
+  if (serviceId) {
+    hints.common_actions.push({
+      action: "Log time on this task",
+      example: {
+        resource: "time",
+        action: "create",
+        service_id: serviceId,
+        task_id: taskId,
+        date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+        time: 60,
+        note: "<description of work>"
+      }
+    });
+  }
+  return hints;
+}
+function getProjectHints(projectId) {
+  return {
+    related_resources: [
+      {
+        resource: "tasks",
+        description: "Get tasks in this project",
+        example: {
+          resource: "tasks",
+          action: "list",
+          filter: { project_id: projectId }
+        }
+      },
+      {
+        resource: "services",
+        description: "Get services (budget lines) for this project",
+        example: {
+          resource: "services",
+          action: "list",
+          filter: { project_id: projectId }
+        }
+      },
+      {
+        resource: "time",
+        description: "Get time entries for this project",
+        example: {
+          resource: "time",
+          action: "list",
+          filter: { project_id: projectId }
+        }
+      },
+      {
+        resource: "comments",
+        description: "Get comments on this project",
+        example: {
+          resource: "comments",
+          action: "list",
+          filter: { project_id: projectId }
+        }
+      },
+      {
+        resource: "deals",
+        description: "Get deals/budgets for this project",
+        example: {
+          resource: "deals",
+          action: "list",
+          filter: { project_id: projectId }
+        }
+      }
+    ],
+    common_actions: [
+      {
+        action: "Create a task",
+        example: {
+          resource: "tasks",
+          action: "create",
+          project_id: projectId,
+          task_list_id: "<task_list_id>",
+          title: "<task title>"
+        }
+      }
+    ]
+  };
+}
+function getDealHints(dealId) {
+  return {
+    related_resources: [
+      {
+        resource: "comments",
+        description: "Get comments on this deal/budget",
+        example: {
+          resource: "comments",
+          action: "list",
+          filter: { deal_id: dealId }
+        }
+      },
+      {
+        resource: "services",
+        description: "Get services (budget lines) for this deal",
+        example: {
+          resource: "services",
+          action: "list",
+          filter: { deal_id: dealId }
+        }
+      },
+      {
+        resource: "time",
+        description: "Get time entries for this deal/budget",
+        example: {
+          resource: "time",
+          action: "list",
+          filter: { deal_id: dealId }
+        }
+      },
+      {
+        resource: "bookings",
+        description: "Get resource bookings for this deal",
+        example: {
+          resource: "bookings",
+          action: "list",
+          filter: { deal_id: dealId }
+        }
+      }
+    ],
+    common_actions: [
+      {
+        action: "Add a comment",
+        example: {
+          resource: "comments",
+          action: "create",
+          deal_id: dealId,
+          body: "<your comment>"
+        }
+      }
+    ]
+  };
+}
+function getPersonHints(personId) {
+  return {
+    related_resources: [
+      {
+        resource: "tasks",
+        description: "Get tasks assigned to this person",
+        example: {
+          resource: "tasks",
+          action: "list",
+          filter: { assignee_id: personId }
+        }
+      },
+      {
+        resource: "time",
+        description: "Get time entries by this person",
+        example: {
+          resource: "time",
+          action: "list",
+          filter: { person_id: personId }
+        }
+      },
+      {
+        resource: "bookings",
+        description: "Get bookings for this person",
+        example: {
+          resource: "bookings",
+          action: "list",
+          filter: { person_id: personId }
+        }
+      },
+      {
+        resource: "timers",
+        description: "Get active timers for this person",
+        example: {
+          resource: "timers",
+          action: "list",
+          filter: { person_id: personId }
+        }
+      }
+    ]
+  };
+}
+function getCompanyHints(companyId) {
+  return {
+    related_resources: [
+      {
+        resource: "projects",
+        description: "Get projects for this company",
+        example: {
+          resource: "projects",
+          action: "list",
+          filter: { company_id: companyId }
+        }
+      },
+      {
+        resource: "deals",
+        description: "Get deals for this company",
+        example: {
+          resource: "deals",
+          action: "list",
+          filter: { company_id: companyId }
+        }
+      },
+      {
+        resource: "tasks",
+        description: "Get tasks for this company",
+        example: {
+          resource: "tasks",
+          action: "list",
+          filter: { company_id: companyId }
+        }
+      },
+      {
+        resource: "people",
+        description: "Get contacts at this company",
+        example: {
+          resource: "people",
+          action: "list",
+          filter: { company_id: companyId }
+        }
+      }
+    ]
+  };
+}
+function getTimeEntryHints(timeEntryId, taskId, serviceId) {
+  const hints = {
+    related_resources: [],
+    common_actions: [
+      {
+        action: "Update this time entry",
+        example: {
+          resource: "time",
+          action: "update",
+          id: timeEntryId,
+          time: 120,
+          note: "<updated note>"
+        }
+      }
+    ]
+  };
+  if (serviceId) {
+    hints.related_resources.push({
+      resource: "services",
+      description: "Get the associated service",
+      example: {
+        resource: "services",
+        action: "get",
+        id: serviceId
+      }
+    });
+  }
+  return hints;
+}
+function getCommentHints(_commentId, commentableType, commentableId) {
+  const hints = {
+    related_resources: []
+  };
+  if (commentableType && commentableId) {
+    const resourceMap = {
+      task: "tasks",
+      deal: "deals",
+      project: "projects",
+      company: "companies"
+    };
+    const resource = resourceMap[commentableType];
+    if (resource) {
+      hints.related_resources.push({
+        resource,
+        description: `Get the ${commentableType} this comment is on`,
+        example: {
+          resource,
+          action: "get",
+          id: commentableId
+        }
+      });
+    }
+  }
+  return hints;
+}
+function getBookingHints(bookingId, personId) {
+  const hints = {
+    related_resources: [],
+    common_actions: [
+      {
+        action: "Update this booking",
+        example: {
+          resource: "bookings",
+          action: "update",
+          id: bookingId,
+          time: 480
+        }
+      }
+    ]
+  };
+  if (personId) {
+    hints.related_resources.push({
+      resource: "people",
+      description: "Get the person this booking is for",
+      example: {
+        resource: "people",
+        action: "get",
+        id: personId
+      }
+    });
+  }
+  return hints;
+}
+function getTimerHints(timerId, serviceId) {
+  const hints = {
+    common_actions: [
+      {
+        action: "Stop this timer",
+        example: {
+          resource: "timers",
+          action: "stop",
+          id: timerId
+        }
+      }
+    ],
+    related_resources: []
+  };
+  return hints;
+}
 function jsonResult(data) {
   return {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
@@ -233,7 +591,18 @@ async function handleBookings(action, args, ctx) {
   if (action === "get") {
     if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getBooking(id, { include });
-    return jsonResult(formatBooking(result.data, { ...formatOptions, included: result.included }));
+    const formatted = formatBooking(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) {
@@ -285,7 +654,26 @@ async function handleComments(action, args, ctx) {
   if (action === "get") {
     if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getComment(id, { include });
-    return jsonResult(formatComment(result.data, { ...formatOptions, included: result.included }));
+    const formatted = formatComment(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"]));
@@ -325,7 +713,14 @@ async function handleCompanies(action, args, ctx) {
   if (action === "get") {
     if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getCompany(id);
-    return jsonResult(formatCompany(result.data, formatOptions));
+    const formatted = formatCompany(result.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"]));
@@ -355,7 +750,14 @@ async function handleDeals(action, args, ctx) {
     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 }));
+    const formatted = formatDeal(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) {
@@ -853,12 +1255,26 @@ async function handlePeople(action, args, ctx, credentials) {
   if (action === "get") {
     if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getPerson(id);
-    return jsonResult(formatPerson(result.data, formatOptions));
+    const formatted = formatPerson(result.data, formatOptions);
+    if (ctx.includeHints !== false) {
+      return jsonResult({
+        ...formatted,
+        _hints: getPersonHints(id)
+      });
+    }
+    return jsonResult(formatted);
   }
   if (action === "me") {
     if (credentials.userId) {
       const result = await api.getPerson(credentials.userId);
-      return jsonResult(formatPerson(result.data, formatOptions));
+      const formatted = formatPerson(result.data, formatOptions);
+      if (ctx.includeHints !== false) {
+        return jsonResult({
+          ...formatted,
+          _hints: getPersonHints(credentials.userId)
+        });
+      }
+      return jsonResult(formatted);
     }
     return jsonResult({
       message: "User ID not configured. Set userId in credentials to use this action.",
@@ -879,7 +1295,14 @@ async function handleProjects(action, args, ctx) {
   if (action === "get") {
     if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getProject(id);
-    return jsonResult(formatProject(result.data, formatOptions));
+    const formatted = formatProject(result.data, formatOptions);
+    if (ctx.includeHints !== false) {
+      return jsonResult({
+        ...formatted,
+        _hints: getProjectHints(id)
+      });
+    }
+    return jsonResult(formatted);
   }
   if (action === "list") {
     const result = await api.getProjects({ filter, page, perPage });
@@ -1025,7 +1448,15 @@ async function handleTasks(action, args, ctx) {
   if (action === "get") {
     if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getTask(id, { include });
-    return jsonResult(formatTask(result.data, { ...formatOptions, included: result.included }));
+    const formatted = formatTask(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)
+      });
+    }
+    return jsonResult(formatted);
   }
   if (action === "create") {
     if (!title || !project_id || !task_list_id) {
@@ -1069,7 +1500,15 @@ async function handleTime(action, args, ctx) {
   if (action === "get") {
     if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getTimeEntry(id);
-    return jsonResult(formatTimeEntry(result.data, formatOptions));
+    const formatted = formatTimeEntry(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) {
@@ -1114,7 +1553,14 @@ async function handleTimers(action, args, ctx) {
   if (action === "get") {
     if (!id) return inputErrorResult(ErrorMessages.missingId("get"));
     const result = await api.getTimer(id, { include });
-    return jsonResult(formatTimer(result.data));
+    const formatted = formatTimer(result.data);
+    if (ctx.includeHints !== false) {
+      return jsonResult({
+        ...formatted,
+        _hints: getTimerHints(id)
+      });
+    }
+    return jsonResult(formatted);
   }
   if (action === "start" || action === "create") {
     if (!service_id && !time_entry_id) {
@@ -1157,7 +1603,18 @@ async function executeToolWithCredentials(name, args, credentials) {
   if (name !== "productive") {
     return errorResult(`Unknown tool: ${name}`);
   }
-  const { resource, action, filter, page, per_page, compact, include, query, ...restArgs } = args;
+  const {
+    resource,
+    action,
+    filter,
+    page,
+    per_page,
+    compact,
+    include,
+    query,
+    no_hints,
+    ...restArgs
+  } = args;
   const isCompact = compact ?? action !== "get";
   const formatOptions = { compact: isCompact };
   let stringFilter = toStringFilter(filter);
@@ -1165,13 +1622,15 @@ async function executeToolWithCredentials(name, args, credentials) {
   if (query) {
     stringFilter = { ...stringFilter, query };
   }
+  const includeHints = no_hints !== true && action === "get" && !isCompact;
   const ctx = {
     api,
     formatOptions,
     filter: stringFilter,
     page,
     perPage,
-    include
+    include,
+    includeHints
   };
   try {
     if (action === "help") {
@@ -1219,4 +1678,4 @@ async function executeToolWithCredentials(name, args, credentials) {
 export {
   executeToolWithCredentials as e
 };
-//# sourceMappingURL=index-BDke-bMP.js.map
+//# sourceMappingURL=index-CZpVCEu4.js.map