@studiometa/productive-mcp 0.8.1 → 0.8.3

package/dist/{index-D743zTS1.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) {
@@ -397,9 +799,11 @@ const RESOURCE_HELP = {
     },
     filters: {
       query: "Text search on project name",
-      project_type_id: "Filter by project type",
+      project_type: "Filter by project type: 1=internal, 2=client",
       company_id: "Filter by company",
-      archived: "Filter by archived status (true/false)"
+      responsible_id: "Filter by project manager",
+      person_id: "Filter by team member",
+      status: "Filter by status: 1=active, 2=archived"
     },
     fields: {
       id: "Unique project identifier",
@@ -434,9 +838,18 @@ const RESOURCE_HELP = {
     filters: {
       query: "Text search on task title",
       project_id: "Filter by project",
+      company_id: "Filter by company",
       assignee_id: "Filter by assigned person",
-      status: "Filter by status (open, closed, all)",
-      task_list_id: "Filter by task list"
+      creator_id: "Filter by task creator",
+      status: 'Filter by status: 1=open, 2=closed (or "open", "closed", "all")',
+      task_list_id: "Filter by task list",
+      board_id: "Filter by board",
+      workflow_status_id: "Filter by workflow status (kanban column)",
+      parent_task_id: "Filter by parent task (for subtasks)",
+      overdue_status: "Filter by overdue: 1=not overdue, 2=overdue",
+      due_date_on: "Filter by exact due date (YYYY-MM-DD)",
+      due_date_before: "Filter by due date before (YYYY-MM-DD)",
+      due_date_after: "Filter by due date after (YYYY-MM-DD)"
     },
     includes: [
       "project",
@@ -501,11 +914,18 @@ const RESOURCE_HELP = {
       update: "Update an existing time entry"
     },
     filters: {
-      person_id: "Filter by person",
+      person_id: 'Filter by person (use "me" for current user)',
       service_id: "Filter by service",
       project_id: "Filter by project",
+      task_id: "Filter by task",
+      company_id: "Filter by company",
+      deal_id: "Filter by deal",
+      budget_id: "Filter by budget",
       after: "Filter entries after date (YYYY-MM-DD)",
-      before: "Filter entries before date (YYYY-MM-DD)"
+      before: "Filter entries before date (YYYY-MM-DD)",
+      status: "Filter by approval status: 1=approved, 2=unapproved, 3=rejected",
+      billing_type_id: "Filter by billing type: 1=fixed, 2=actuals, 3=non_billable",
+      invoicing_status: "Filter by invoicing: 1=not_invoiced, 2=drafted, 3=finalized"
     },
     fields: {
       id: "Unique time entry identifier",
@@ -545,7 +965,12 @@ const RESOURCE_HELP = {
     },
     filters: {
       project_id: "Filter by project",
-      deal_id: "Filter by deal"
+      deal_id: "Filter by deal",
+      task_id: "Filter by task",
+      person_id: "Filter by person (trackable by)",
+      budget_status: "Filter by budget status: 1=open, 2=delivered",
+      billing_type: "Filter by billing type: 1=fixed, 2=actuals, 3=none",
+      time_tracking_enabled: "Filter by time tracking: true/false"
     },
     fields: {
       id: "Unique service identifier",
@@ -569,7 +994,12 @@ const RESOURCE_HELP = {
     },
     filters: {
       query: "Text search on name or email",
-      status: "Filter by status (active, inactive)"
+      status: "Filter by status: 1=active, 2=deactivated",
+      person_type: "Filter by type: 1=user, 2=contact, 3=placeholder",
+      company_id: "Filter by company",
+      project_id: "Filter by project",
+      role_id: "Filter by role",
+      team: "Filter by team name"
     },
     fields: {
       id: "Unique person identifier",
@@ -632,7 +1062,10 @@ const RESOURCE_HELP = {
     },
     filters: {
       task_id: "Filter by task",
-      deal_id: "Filter by deal"
+      deal_id: "Filter by deal",
+      project_id: "Filter by project",
+      page_id: "Filter by page",
+      discussion_id: "Filter by discussion"
     },
     includes: ["creator", "task", "deal"],
     fields: {
@@ -659,6 +1092,10 @@ const RESOURCE_HELP = {
       start: "Start a new timer (requires service_id or time_entry_id)",
       stop: "Stop an active timer by ID"
     },
+    filters: {
+      person_id: "Filter by person",
+      time_entry_id: "Filter by time entry"
+    },
     fields: {
       id: "Unique timer identifier",
       started_at: "When the timer started (ISO 8601)",
@@ -684,7 +1121,12 @@ const RESOURCE_HELP = {
     filters: {
       query: "Text search on deal name",
       company_id: "Filter by company",
-      deal_status_id: "Filter by status"
+      project_id: "Filter by project",
+      responsible_id: "Filter by responsible person",
+      pipeline_id: "Filter by pipeline",
+      stage_status_id: "Filter by stage: 1=open, 2=won, 3=lost",
+      type: "Filter by type: 1=deal, 2=budget",
+      budget_status: "Filter by budget status: 1=open, 2=closed"
     },
     includes: ["company", "deal_status", "responsible", "project"],
     fields: {
@@ -716,8 +1158,13 @@ const RESOURCE_HELP = {
     filters: {
       person_id: "Filter by person",
       service_id: "Filter by service",
+      project_id: "Filter by project",
+      company_id: "Filter by company",
+      event_id: "Filter by event",
       after: "Filter bookings after date (YYYY-MM-DD)",
-      before: "Filter bookings before date (YYYY-MM-DD)"
+      before: "Filter bookings before date (YYYY-MM-DD)",
+      booking_type: "Filter by type: event (absence) or service (budget)",
+      draft: "Filter by tentative status: true/false"
     },
     includes: ["person", "service", "event"],
     fields: {
@@ -808,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.",
@@ -834,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 });
@@ -980,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) {
@@ -1024,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) {
@@ -1069,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) {
@@ -1112,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);
@@ -1120,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") {
@@ -1174,4 +1678,4 @@ async function executeToolWithCredentials(name, args, credentials) {
 export {
   executeToolWithCredentials as e
 };
-//# sourceMappingURL=index-D743zTS1.js.map
+//# sourceMappingURL=index-CZpVCEu4.js.map