@sodiumhq/mcp-pm 0.1.0-beta.6354 → 0.1.0-beta.6355

package/dist/http.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as buildServer } from "./src-Cf9c-hOi.mjs";
+import { t as buildServer } from "./src--vw5xenq.mjs";
 import { createRequire } from "node:module";
 import { SUPPORTED_PROTOCOL_VERSIONS, createMcpHandler } from "@modelcontextprotocol/server";
 import { createHash, randomUUID } from "node:crypto";

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as buildServer } from "./src-Cf9c-hOi.mjs";
+import { t as buildServer } from "./src--vw5xenq.mjs";
 import { createRequire } from "node:module";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { parseArgs } from "node:util";

package/dist/{src-Cf9c-hOi.mjs → src--vw5xenq.mjs}

@@ -9600,7 +9600,7 @@ async function buildServer(config) {
 	}, (args) => handleListClients(api, args));
 	registerTenantTool(server, api, "get_client_summary", {
 		title: "Get a full summary of one client",
-		description: "Get a consolidated overview of a single client by code: identity (name, status, type, assignments), business details (company number, incorporation date, trading name, registered address, VAT status, UTR, PAYE ref), custom fields (all user-defined fields with current values, data types, and field codes — use these codes with update_client_custom_fields), key statutory dates (year-end, accounts due, VAT return due, confirmation statement due, etc. — upcoming first, then past), all contacts, active services with pricing, overdue task count + top 5, and tasks due in the next 7 days. Use this AFTER list_clients identifies the client of interest, or when the user references a specific client by code. Also answers 'when is ACME's year-end?' / 'is ACME VAT registered?' / 'what are ACME's custom fields?' in a single call. Tolerates partial failures — if one section can't be loaded, the rest is still returned with a note about what's missing.",
+		description: "Get a consolidated overview of a single client by code: identity (name, status, type, assignments), business details (company number, incorporation date, trading name, registered address, VAT status, UTR, PAYE ref), custom fields (all user-defined fields with current values, data types, and field codes — use these codes with update_client_custom_fields), key statutory dates (year-end, accounts due, VAT return due, confirmation statement due, etc. — upcoming first, then past), all contacts, active services with pricing, overdue task count + top 5, and tasks due in the next 7 days. Takes a client code, as returned by list_clients or given by the user. Also answers 'when is ACME's year-end?' / 'is ACME VAT registered?' / 'what are ACME's custom fields?' in a single call. Tolerates partial failures — if one section can't be loaded, the rest is still returned with a note about what's missing.",
 		inputSchema: GetClientSummaryInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -9630,7 +9630,7 @@ async function buildServer(config) {
 	}, (args) => handleListClientNotes(api, args));
 	registerTenantTool(server, api, "list_tasks", {
 		title: "List / filter tasks across the practice",
-		description: "List tasks with any combination of filters: assigned user(s), unassigned, client(s), the primary client's client manager / partner (portfolio views: 'tasks across the clients Jane manages'), status, overdue flag, preset date range (Today / ThisWeek / Next7Days / CustomDateRange etc), category, team, billable service, workflow, workflow step type, current step name, recurring task template, free-text search, saved filter, include-projected, include-workflow-steps (Agenda Mode), sort, and pagination. Use for: 'my tasks' (pass current user's code from startup context), 'Jane's overdue tasks' (user + isOverdue), 'tasks for ACME due this week' (client + dateRange=Next7Days + dateBasis=DueDate), 'what is the team working on this month' (dateRange=ThisMonth, no user filter). Returns up to 50 tasks per page; each row shows due date, statutory due date (when set), client, billable service (name + code), assignee, status and workflow progress. IMPORTANT constraints to avoid API errors and keep queries efficient: (1) Querying NotStarted tasks requires one of — a dateRange, isOverdue=true, or restricting status to non-NotStarted values. (2) Prefer the narrowest date range that answers the question — broad ranges (quarterly/yearly) are expensive; prefer Today / ThisWeek / Next7Days / ThisMonth over larger windows unless explicitly asked. (3) For 'oldest incomplete tasks' prefer status=['InProgress','Blocked'] with sortBy=StartDate (no date range needed), or add isOverdue=true if 'oldest overdue' is meant. (4) For 'how many X?' questions, pass limit=0 to get just the total count without fetching any task data — much cheaper than fetching a full page and counting.",
+		description: "List tasks with any combination of filters: assigned user(s), unassigned, client(s), the primary client's client manager / partner (portfolio views: 'tasks across the clients Jane manages'), status, overdue flag, preset date range (Today / ThisWeek / Next7Days / CustomDateRange etc), category, team, billable service, workflow, workflow step type, current step name, recurring task template, free-text search, saved filter, include-projected, include-workflow-steps (Agenda Mode), sort, and pagination. Use for: 'my tasks' (user = the signed-in user's practice user code, which whoami shows), 'Jane's overdue tasks' (user + isOverdue), 'tasks for ACME due this week' (client + dateRange=Next7Days + dateBasis=DueDate), 'what is the team working on this month' (dateRange=ThisMonth, no user filter). Returns up to 50 tasks per page; each row shows due date, statutory due date (when set), client, billable service (name + code), assignee, status and workflow progress. Constraints that avoid API errors and keep queries efficient: (1) Querying NotStarted tasks requires one of — a dateRange, isOverdue=true, or restricting status to non-NotStarted values. (2) Narrow date ranges are cheaper: broad ranges (quarterly/yearly) are expensive, and Today / ThisWeek / Next7Days / ThisMonth answer most questions. (3) For 'oldest incomplete tasks', status=['InProgress','Blocked'] with sortBy=StartDate needs no date range; add isOverdue=true if 'oldest overdue' is meant. (4) For 'how many X?' questions, pass limit=0 to get just the total count without fetching any task data — much cheaper than fetching a full page and counting.",
 		inputSchema: ListTasksInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -9640,7 +9640,7 @@ async function buildServer(config) {
 	}, (args) => handleListTasks(api, args));
 	registerTenantTool(server, api, "get_task_context", {
 		title: "Get full context for a single task",
-		description: "Get a consolidated view of one task by code: identity (name, code, status, overdue flag, start/due/statutory dates, time estimate, assignee, category, billable service, recurring/workflow templates), description, task-level checklist, workflow progress (groups and steps with status, assignee, and completion info — only if the task has a workflow attached), notes (pinned first, then newest first), and the parent client. Use this AFTER list_tasks identifies a task of interest, or when the user references a specific task by code. Tolerates partial failures — if notes or workflow steps can't be loaded, the task details are still returned with a note about what's missing. Only fails outright if the task itself can't be fetched (e.g. unknown code).",
+		description: "Get a consolidated view of one task by code: identity (name, code, status, overdue flag, start/due/statutory dates, time estimate, assignee, category, billable service, recurring/workflow templates), description, task-level checklist, workflow progress (groups and steps with status, assignee, and completion info — only if the task has a workflow attached), notes (pinned first, then newest first), and the parent client. Takes a task code, as returned by list_tasks or given by the user. Tolerates partial failures — if notes or workflow steps can't be loaded, the task details are still returned with a note about what's missing. Only fails outright if the task itself can't be fetched (e.g. unknown code).",
 		inputSchema: GetTaskContextInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -9670,7 +9670,7 @@ async function buildServer(config) {
 	}, (args) => handleListEngagements(api, args));
 	registerTenantTool(server, api, "get_proposal_summary", {
 		title: "Get full detail of one proposal",
-		description: "Get a consolidated view of a single proposal by engagement code: identity (code, status, type, date), client, recipient, value breakdown (annual / quarterly / monthly / one-off incl. catch-up fees / total), the proposed services with pricing (and each service's catch-up fee share), acceptance record (if accepted), PDF availability (proposal + letter of engagement), email history, and the acceptance link. REQUIRES a concrete engagement code as input — do NOT call this tool unless you already have the code. If the user describes an engagement by attribute — e.g. 'the unsent proposal', 'the proposal for ACME', 'our most recent proposal', 'the rejected one' — you MUST call list_proposals FIRST with the matching filters to look up the code, then call this tool with that code. Returns identical data to get_engagement_letter_summary — both aliases back the same Engagement entity. Tolerates partial failures (email history or the practice's catch-up fee label may be missing with a note); only fails hard if the engagement itself can't be fetched.",
+		description: "Get a consolidated view of a single proposal by engagement code: identity (code, status, type, date), client, recipient, value breakdown (annual / quarterly / monthly / one-off incl. catch-up fees / total), the proposed services with pricing (and each service's catch-up fee share), acceptance record (if accepted), PDF availability (proposal + letter of engagement), email history, and the acceptance link. Requires a concrete engagement code as input. list_proposals returns the codes and filters by status, client and date, which covers descriptions such as 'the unsent proposal', 'the proposal for ACME', 'our most recent proposal' or 'the rejected one'. Returns identical data to get_engagement_letter_summary — both aliases back the same Engagement entity. Tolerates partial failures (email history or the practice's catch-up fee label may be missing with a note); only fails hard if the engagement itself can't be fetched.",
 		inputSchema: GetEngagementSummaryInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -9680,7 +9680,7 @@ async function buildServer(config) {
 	}, (args) => handleGetEngagementSummary(api, args));
 	registerTenantTool(server, api, "get_engagement_letter_summary", {
 		title: "Get full detail of one letter of engagement",
-		description: "Get a consolidated view of a single letter of engagement by code: identity (code, status, type, date), client, recipient, value breakdown (annual / quarterly / monthly / one-off incl. catch-up fees / total), services included with pricing (and each service's catch-up fee share), acceptance record (accepted date, whether accepted via portal or recorded manually), PDF availability (proposal + letter of engagement), email history, and the acceptance link. REQUIRES a concrete engagement code as input — do NOT call this tool unless you already have the code. If the user describes the engagement by attribute — e.g. 'ACME's letter of engagement', 'the most recent signed engagement', 'the live engagement for Smith & Co' — you MUST call list_engagement_letters FIRST with the matching filters to look up the code, then call this tool with that code. Returns identical data to get_proposal_summary — both aliases back the same Engagement entity. Tolerates partial failures (email history or the practice's catch-up fee label may be missing with a note); only fails hard if the engagement itself can't be fetched.",
+		description: "Get a consolidated view of a single letter of engagement by code: identity (code, status, type, date), client, recipient, value breakdown (annual / quarterly / monthly / one-off incl. catch-up fees / total), services included with pricing (and each service's catch-up fee share), acceptance record (accepted date, whether accepted via portal or recorded manually), PDF availability (proposal + letter of engagement), email history, and the acceptance link. Requires a concrete engagement code as input. list_engagement_letters returns the codes and filters by status, search text and date, which covers descriptions such as 'ACME's letter of engagement', 'the most recent signed engagement' or 'the live engagement for Smith & Co'. Returns identical data to get_proposal_summary — both aliases back the same Engagement entity. Tolerates partial failures (email history or the practice's catch-up fee label may be missing with a note); only fails hard if the engagement itself can't be fetched.",
 		inputSchema: GetEngagementSummaryInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -9700,7 +9700,7 @@ async function buildServer(config) {
 	}, (args) => handleListServices(api, args));
 	registerTenantTool(server, api, "get_service_details", {
 		title: "Get a single service's full configuration",
-		description: "Get a consolidated view of one billable service by code: identity (name, code, category, status, VAT rate, accounting code, description, default manager, pricing mode), applicable client types (explicit list, or 'all client types' if unrestricted), HMRC agent authorisations, pricing options (one per billing frequency with base price + override counts), custom pricing tiers (only when pricingMode=CustomTiers), professional clearance request items, and pricing-factor presence (count + factor questions only — exact factor band values are intentionally not dumped; computed pricing per client lives in the proposal tools). Use this AFTER list_services identifies the service, or when the user references a specific service by code. Enables service-audit workflows like 'is Self Assessment correctly restricted to Individual clients?' and 'what clearance items do we request for new bookkeeping clients?'",
+		description: "Get a consolidated view of one billable service by code: identity (name, code, category, status, VAT rate, accounting code, description, default manager, pricing mode), applicable client types (explicit list, or 'all client types' if unrestricted), HMRC agent authorisations, pricing options (one per billing frequency with base price + override counts), custom pricing tiers (only when pricingMode=CustomTiers), professional clearance request items, and pricing-factor presence (count + factor questions only — exact factor band values are intentionally not dumped; computed pricing per client lives in the proposal tools). Takes a service code, as returned by list_services or given by the user. Enables service-audit workflows like 'is Self Assessment correctly restricted to Individual clients?' and 'what clearance items do we request for new bookkeeping clients?'",
 		inputSchema: GetServiceDetailsInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -9745,13 +9745,13 @@ async function buildServer(config) {
 	};
 	registerTenantTool(server, api, "get_service_delivery_report", {
 		title: "Service delivery turnaround report",
-		description: "Are we delivering client services as quickly as we should? Cohort = tasks COMPLETED in the window. Summary KPIs (count, avg/median turnaround from planned start to completion, on-time %, statutory compliance %, currently-overdue snapshot) plus a breakdown grouped by Service (default), Client, AssignedUser, or Month. Answers 'how fast do we turn around VAT returns?', 'which clients' work runs late?', 'is our turnaround improving month on month?' (groupBy=Month over a long window). NOT the right tool for missed deadlines — a task still open past its deadline never completed, so it isn't in this cohort; use get_deadline_compliance_report for that. For per-step bottlenecks within one service, follow up with get_service_delivery_steps. Constraints: dateRange='CustomDateRange' requires both startDate and endDate; summary always covers the whole cohort even when breakdown rows are paged.",
+		description: "Are we delivering client services as quickly as we should? Cohort = tasks COMPLETED in the window. Summary KPIs (count, avg/median turnaround from planned start to completion, on-time %, statutory compliance %, currently-overdue snapshot) plus a breakdown grouped by Service (default), Client, AssignedUser, or Month. Answers 'how fast do we turn around VAT returns?', 'which clients' work runs late?', 'is our turnaround improving month on month?' (groupBy=Month over a long window). It does not cover missed deadlines — a task still open past its deadline never completed, so it isn't in this cohort; get_deadline_compliance_report covers those. For per-step bottlenecks within one service, follow up with get_service_delivery_steps. Constraints: dateRange='CustomDateRange' requires both startDate and endDate; summary always covers the whole cohort even when breakdown rows are paged.",
 		inputSchema: GetServiceDeliveryReportInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetServiceDeliveryReport(api, args));
 	registerTenantTool(server, api, "get_service_delivery_steps", {
 		title: "Per-step bottlenecks for one service",
-		description: "Where does the time go inside one billable service's workflow? For tasks of the given service completed in the window: average elapsed days per workflow step (measured from the previous step's completion, so queue/idle time counts), skip counts, chase counts, and each step flagged client-wait (waiting on the client: document requests, approvals, confirmations, data forms) vs internal — splitting 'we were slow' from 'the client was slow'. Use AFTER get_service_delivery_report flags a slow service, or directly for 'why do accounts jobs take so long?'. Requires serviceCode (from list_services). Note: steps are compared by name across tasks, so a renamed workflow step appears as separate rows.",
+		description: "Where does the time go inside one billable service's workflow? For tasks of the given service completed in the window: average elapsed days per workflow step (measured from the previous step's completion, so queue/idle time counts), skip counts, chase counts, and each step flagged client-wait (waiting on the client: document requests, approvals, confirmations, data forms) vs internal — splitting 'we were slow' from 'the client was slow'. Follows on from get_service_delivery_report when it flags a slow service, and answers 'why do accounts jobs take so long?' directly. Requires serviceCode (from list_services). Note: steps are compared by name across tasks, so a renamed workflow step appears as separate rows.",
 		inputSchema: GetServiceDeliveryStepsInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetServiceDeliverySteps(api, args));
@@ -9814,7 +9814,7 @@ async function buildServer(config) {
 	}, (args) => handleListWorkflows(api, args));
 	registerTenantTool(server, api, "get_workflow", {
 		title: "Get one workflow template's full structure",
-		description: "Get a single workflow template by code: the ordered groups and steps with step types (email, document request, approval, client confirmation, data form, etc.), assignment rules, auto-execute flags, dependencies, time estimates, and conditions. Answers 'what are the steps in our VAT return workflow?' and 'which steps in this workflow wait on the client?'. REQUIRES a concrete workflow code — call list_workflows first if the user named the workflow instead. For how the workflow performs in practice (durations, bottlenecks), use get_workflow_step_analysis.",
+		description: "Get a single workflow template by code: the ordered groups and steps with step types (email, document request, approval, client confirmation, data form, etc.), assignment rules, auto-execute flags, dependencies, time estimates, and conditions. Answers 'what are the steps in our VAT return workflow?' and 'which steps in this workflow wait on the client?'. Requires a concrete workflow code, as listed by list_workflows. For how the workflow performs in practice (durations, bottlenecks), use get_workflow_step_analysis.",
 		inputSchema: GetWorkflowInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetWorkflow(api, args));
@@ -9838,25 +9838,25 @@ async function buildServer(config) {
 	}, (args) => handleListServiceCategories(api, args));
 	registerTenantTool(server, api, "list_saved_task_filters", {
 		title: "List saved task views",
-		description: "List the user's saved task views/filters, showing each view's code AND the criteria it encodes (statuses, date range, users, teams, clients, categories, overdue/unassigned flags). Use when the user references a saved view by name ('run my Weekly Review', 'my compliance filter') — resolve the code here, then pass it as list_tasks' savedFilter. The echoed criteria also let you answer 'what does my Weekly Review view actually show?' without running it. Prefer menuOnly=true when guessing which view the user means — those are the ones they use daily.",
+		description: "List the user's saved task views/filters, showing each view's code AND the criteria it encodes (statuses, date range, users, teams, clients, categories, overdue/unassigned flags). Use when the user references a saved view by name ('run my Weekly Review', 'my compliance filter') — resolve the code here, then pass it as list_tasks' savedFilter. The echoed criteria also let you answer 'what does my Weekly Review view actually show?' without running it. menuOnly=true returns only the views pinned to the user's menu, which are the ones they use daily.",
 		inputSchema: ListSavedTaskFiltersInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListSavedTaskFilters(api, args));
 	registerTenantTool(server, api, "list_saved_client_filters", {
 		title: "List saved client views",
-		description: "List the user's saved client views/filters, showing each view's code AND the criteria it encodes (statuses, client types, managers, partners, services, teams). Use when the user references a saved view by name ('my VAT clients view') — resolve the code here, then pass it as list_clients' savedFilter. Prefer menuOnly=true when guessing which view the user means.",
+		description: "List the user's saved client views/filters, showing each view's code AND the criteria it encodes (statuses, client types, managers, partners, services, teams). Use when the user references a saved view by name ('my VAT clients view') — resolve the code here, then pass it as list_clients' savedFilter. menuOnly=true returns only the views pinned to the user's menu.",
 		inputSchema: ListSavedClientFiltersInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListSavedClientFilters(api, args));
 	registerTenantTool(server, api, "search_companies_house", {
 		title: "Search Companies House",
-		description: "Search the Companies House public register by company name (full or partial) or company number. Returns matches with number, status, type, incorporation date, and registered address — live data from the register, not limited to the practice's clients. Use for prospect due diligence ('look up Bristol Roofing'), finding a company number before get_companies_house_profile, or checking name availability. For an EXISTING client's company number, prefer get_client_summary (business details) over searching by name.",
+		description: "Search the Companies House public register by company name (full or partial) or company number. Returns matches with number, status, type, incorporation date, and registered address — live data from the register, not limited to the practice's clients. Use for prospect due diligence ('look up Bristol Roofing'), finding a company number before get_companies_house_profile, or checking name availability. An existing client's company number is in get_client_summary's business details.",
 		inputSchema: SearchCompaniesHouseInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleSearchCompaniesHouse(api, args));
 	registerTenantTool(server, api, "get_companies_house_profile", {
 		title: "Get a company's full Companies House profile",
-		description: "Get the live Companies House record for one company number: legal status, incorporation date, registered office, SIC codes, accounts and confirmation-statement deadlines (with OVERDUE flags), last-filed accounts, charges/insolvency/liquidation flags, and current + resigned officers. Answers 'when are ACME's accounts due at Companies House?', 'who are the directors?', 'does this prospect have insolvency history?'. REQUIRES a company number — use search_companies_house for name lookups, or get_client_summary's business details for an existing client's number. Pass includeOfficers=false when only filing dates matter. Officers tolerate partial failure — the profile still returns if they can't be loaded.",
+		description: "Get the live Companies House record for one company number: legal status, incorporation date, registered office, SIC codes, accounts and confirmation-statement deadlines (with OVERDUE flags), last-filed accounts, charges/insolvency/liquidation flags, and current + resigned officers. Answers 'when are ACME's accounts due at Companies House?', 'who are the directors?', 'does this prospect have insolvency history?'. Requires a company number: search_companies_house finds one by name, and get_client_summary's business details holds an existing client's. Pass includeOfficers=false when only filing dates matter. Officers tolerate partial failure — the profile still returns if they can't be loaded.",
 		inputSchema: GetCompaniesHouseProfileInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetCompaniesHouseProfile(api, args));
@@ -9874,7 +9874,7 @@ async function buildServer(config) {
 	}, (args) => handleListDataFormRequests(api, args));
 	registerTenantTool(server, api, "list_time_entries", {
 		title: "List / filter time entries",
-		description: "List recorded time entries with filters: team member, client, task, preset date range (or CustomDateRange + fromDate/toDate), billable flag, billed flag, search, sort, pagination. Answers 'how much time have I logged this week?' (userCode = current user, dateRange=ThisWeek), 'time spent on ACME this month' (clientCode + dateRange=ThisMonth), 'what unbilled time do we have?' (isBillable=true, isBilled=false — the WIP question), 'biggest time entries on this job' (taskItemCode, sortBy=DurationMinutes, sortDesc=true). Each page also shows its summed duration. IMPORTANT: prefer a narrow dateRange — unwindowed queries scan all history. For 'how many entries?' pass limit=0. For aggregate per-service/per-client totals over a period prefer get_service_time_report — it sums the whole window in one call instead of paging entries.",
+		description: "List recorded time entries with filters: team member, client, task, preset date range (or CustomDateRange + fromDate/toDate), billable flag, billed flag, search, sort, pagination. Answers 'how much time have I logged this week?' (userCode = current user, dateRange=ThisWeek), 'time spent on ACME this month' (clientCode + dateRange=ThisMonth), 'what unbilled time do we have?' (isBillable=true, isBilled=false — the WIP question), 'biggest time entries on this job' (taskItemCode, sortBy=DurationMinutes, sortDesc=true). Each page also shows its summed duration. Unwindowed queries scan all history, so a narrow dateRange is much faster. For 'how many entries?' pass limit=0. get_service_time_report gives aggregate per-service/per-client totals over a period, summing the whole window in one call instead of paging entries.",
 		inputSchema: ListTimeEntriesInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListTimeEntries(api, args));
@@ -9898,7 +9898,7 @@ async function buildServer(config) {
 	}, (args) => handleListRecurringTasks(api, args));
 	registerTenantTool(server, api, "list_sent_emails", {
 		title: "List emails Sodium sent (delivery audit trail)",
-		description: "List the emails Sodium sent on the practice's behalf — proposal/engagement emails, document-request chases, portal invitations, broadcasts — with delivery status (Queued/Processing/Sent/Failed/Cancelled), recipient, subject, date window, search, sort, pagination. THE tool for 'did the proposal email to ACME actually go out?', 'which emails failed this week?' (status=Failed + fromDate), 'what chases went to John?' (search on his address). This is the OUTBOUND SYSTEM audit trail only — for two-way email correspondence with a client (their replies, ad-hoc emails) use list_client_emails instead. Prefer a fromDate/toDate window; pass limit=0 for count-only. Follow up with get_sent_email for full recipient/error detail.",
+		description: "List the emails Sodium sent on the practice's behalf — proposal/engagement emails, document-request chases, portal invitations, broadcasts — with delivery status (Queued/Processing/Sent/Failed/Cancelled), recipient, subject, date window, search, sort, pagination. THE tool for 'did the proposal email to ACME actually go out?', 'which emails failed this week?' (status=Failed + fromDate), 'what chases went to John?' (search on his address). This is the OUTBOUND SYSTEM audit trail only — for two-way email correspondence with a client (their replies, ad-hoc emails) use list_client_emails instead. A fromDate/toDate window keeps results small; limit=0 returns a count only. Follow up with get_sent_email for full recipient/error detail.",
 		inputSchema: ListSentEmailsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListSentEmails(api, args));
@@ -9964,7 +9964,7 @@ async function buildServer(config) {
 	}, (args) => handleListUnbilledTimeClients(api, args));
 	registerTenantTool(server, api, "get_engagement_pipeline_summary", {
 		title: "Proposal pipeline totals (counts + values by status)",
-		description: "One-call aggregate of the engagement pipeline: counts and total values for Unsent / Sent / Viewed / Accepted / Rejected, plus the open pipeline (sent + viewed awaiting a decision). Answers 'what's our proposal pipeline worth?', 'how much did we win this quarter?' (dateRange=ThisQuarter, read the Accepted line), 'how much value is sitting unsigned?'. Omit the window for the all-time picture. Much cheaper than paging list_proposals and adding up — prefer this for any totals question; use list_proposals for the individual engagements. Constraints: dateRange='CustomDateRange' requires dateFrom and dateTo.",
+		description: "One-call aggregate of the engagement pipeline: counts and total values for Unsent / Sent / Viewed / Accepted / Rejected, plus the open pipeline (sent + viewed awaiting a decision). Answers 'what's our proposal pipeline worth?', 'how much did we win this quarter?' (dateRange=ThisQuarter, read the Accepted line), 'how much value is sitting unsigned?'. Omit the window for the all-time picture. Much cheaper than paging list_proposals and adding up, so it suits any totals question; list_proposals lists the individual engagements. Constraints: dateRange='CustomDateRange' requires dateFrom and dateTo.",
 		inputSchema: GetEngagementPipelineSummaryInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetEngagementPipelineSummary(api, args));
@@ -10018,7 +10018,7 @@ async function buildServer(config) {
 	}, (args) => handleGetEmailBroadcast(api, args));
 	registerTenantTool(server, api, "get_client_email_thread", {
 		title: "Read one email conversation (synced mailbox)",
-		description: "Drill into one email thread from the synced mailbox: every message in order with date, sender, read/attachment flags, and preview text, plus which clients and tasks the thread is linked to. Requires configCode AND conversationId — both shown per thread in list_client_emails output; never guess them. Answers 'what did ACME actually say in that thread?', 'show me the whole conversation about the VAT surcharge'. Message previews are snippets, not complete bodies — full bodies and attachments are opened in Sodium.",
+		description: "Drill into one email thread from the synced mailbox: every message in order with date, sender, read/attachment flags, and preview text, plus which clients and tasks the thread is linked to. Requires configCode AND conversationId, both shown per thread in list_client_emails output. Answers 'what did ACME actually say in that thread?', 'show me the whole conversation about the VAT surcharge'. Message previews are snippets, not complete bodies — full bodies and attachments are opened in Sodium.",
 		inputSchema: GetClientEmailThreadInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetClientEmailThread(api, args));
@@ -10063,7 +10063,7 @@ async function buildServer(config) {
 	}, (args) => handleUpdateServiceCategory(api, args));
 	registerWriteTool(server, api, config.context, "apply_service_package", {
 		title: "Apply a service package to a client",
-		description: "Put a client on one of the practice's bundled packages in a single call. The package definition decides everything: which services the client gets, at what frequency, and whether they are billed as one package price or service by service. Requires clientCode (list_clients) and packageCode (list_service_packages — check its contents and pricing mode there first so you can tell the user what they are agreeing to). Optional: startDate (defaults to today), status (defaults to Active; use 'Proposed' when quoting), and createOnboardingTasks (defaults to true; pass false when recording an arrangement that is already running, e.g. migrating or backdating). Use for 'put ACME on the Growth package', 'add the Startup bundle to Bristol Roofing from 1 April'. IMPORTANT: (1) The API does NOT check whether the client already has this package — calling twice applies it a SECOND time. Always check get_client_summary first and tell the user if it is already there rather than applying again. (2) Prefer this over repeated add_client_service calls: only this tool links the result to the package, which is what makes package pricing and package removal work in the Sodium UI. (3) Auto-invoicing follows the practice's client-billing settings; it is not controllable per call. (4) Nothing about the package can be overridden per client — use add_client_service for a bespoke arrangement. Archived packages are rejected.",
+		description: "Put a client on one of the practice's bundled packages in a single call. The package definition decides everything: which services the client gets, at what frequency, and whether they are billed as one package price or service by service. Requires clientCode (list_clients) and packageCode (list_service_packages — check its contents and pricing mode there first so you can tell the user what they are agreeing to). Optional: startDate (defaults to today), status (defaults to Active; use 'Proposed' when quoting), and createOnboardingTasks (defaults to true; pass false when recording an arrangement that is already running, e.g. migrating or backdating). Use for 'put ACME on the Growth package', 'add the Startup bundle to Bristol Roofing from 1 April'. Notes: (1) The API does not check whether the client already has this package, so calling twice applies it a second time; get_client_summary shows whether it is already there. (2) Unlike repeated add_client_service calls, only this tool links the result to the package, which is what makes package pricing and package removal work in the Sodium UI. (3) Auto-invoicing follows the practice's client-billing settings; it is not controllable per call. (4) Nothing about the package can be overridden per client — use add_client_service for a bespoke arrangement. Archived packages are rejected.",
 		inputSchema: ApplyServicePackageInputSchema,
 		annotations: {
 			readOnlyHint: false,
@@ -10085,7 +10085,7 @@ async function buildServer(config) {
 	}, (args) => handleUpdateClientServiceStage(api, args));
 	registerWriteTool(server, api, config.context, "create_document_request", {
 		title: "Draft a document request for a client",
-		description: "Create a document request as a DRAFT — nothing is sent and the client is not notified. Requires clientCode and a title; optional client-facing description (write it as the client will read it), deadline, and a team member to notify on submission. Use for 'ask ACME for their year-end records', 'request the Jan–Mar bank statements from Greggs'. The user reviews and sends it from the client's Documents tab in Sodium — ALWAYS tell them it's drafted, not sent. Track it afterwards with list_document_requests (status=Draft).",
+		description: "Create a document request as a DRAFT — nothing is sent and the client is not notified. Requires clientCode and a title; optional client-facing description (write it as the client will read it), deadline, and a team member to notify on submission. Use for 'ask ACME for their year-end records', 'request the Jan–Mar bank statements from Greggs'. It is saved as a draft and not sent; the user reviews and sends it from the client's Documents tab in Sodium. Track it afterwards with list_document_requests (status=Draft).",
 		inputSchema: CreateDocumentRequestInputSchema,
 		annotations: {
 			readOnlyHint: false,
@@ -10107,7 +10107,7 @@ async function buildServer(config) {
 	}, (args) => handleSendDataForm(api, args));
 	registerWriteTool(server, api, config.context, "create_proposal", {
 		title: "Draft a proposal / letter of engagement",
-		description: "Create an engagement in UNSENT (draft) state — the client is NOT emailed; sending is a deliberate separate action in the Sodium UI. Requires clientCode and date. type defaults to ProposalAndEngagementLetter ('EngagementLetter' for existing clients needing only the letter). clientBillableServiceCodes are the CLIENT'S service-subscription codes (get_client_summary's services section), not catalogue codes — to propose a service the client doesn't have yet, first add_client_service with status 'Proposed', then include its new code here. Recipient defaults to the client's main contact when omitted; only use an email from the client's contacts or given by the user. Use for 'draft a proposal for Bristol Roofing covering bookkeeping and VAT'. Always report the drafted value and that it has NOT been sent; full detail via get_proposal_summary.",
+		description: "Create an engagement in UNSENT (draft) state — the client is NOT emailed; sending is a deliberate separate action in the Sodium UI. Requires clientCode and date. type defaults to ProposalAndEngagementLetter ('EngagementLetter' for existing clients needing only the letter). clientBillableServiceCodes are the CLIENT'S service-subscription codes (get_client_summary's services section), not catalogue codes — to propose a service the client doesn't have yet, first add_client_service with status 'Proposed', then include its new code here. Recipient defaults to the client's main contact when omitted; only use an email from the client's contacts or given by the user. Use for 'draft a proposal for Bristol Roofing covering bookkeeping and VAT'. The result states the drafted value and that it has not been sent; full detail via get_proposal_summary.",
 		inputSchema: CreateProposalInputSchema,
 		annotations: {
 			readOnlyHint: false,
@@ -10118,7 +10118,7 @@ async function buildServer(config) {
 	}, (args) => handleCreateProposal(api, args));
 	registerWriteTool(server, api, config.context, "update_client_dates", {
 		title: "Set key/statutory dates on a client",
-		description: "Set one or more of a client's key dates (year-end, VAT return due, PAYE/CIS filing due, pension re-enrolment...). Takes an array of { dateType, date } — only the types you pass change; pass date=null to clear one. Current values are in get_client_summary's key-dates section. Use for 'set ACME's year-end to 31 March', 'record the pension re-enrolment date'. CAUTION: for clients connected to Companies House, register-derived dates (accounts due, confirmation statement) are synced automatically and manual values may be overwritten — prefer setting only non-CH dates (YearEnd, VAT, PAYE, pension) on connected clients, and say so if asked to set a CH-derived one.",
+		description: "Set one or more of a client's key dates (year-end, VAT return due, PAYE/CIS filing due, pension re-enrolment...). Takes an array of { dateType, date } — only the types you pass change; pass date=null to clear one. Current values are in get_client_summary's key-dates section. Use for 'set ACME's year-end to 31 March', 'record the pension re-enrolment date'. For clients connected to Companies House, register-derived dates (accounts due, confirmation statement) are synced automatically and manual values may be overwritten; YearEnd, VAT, PAYE and pension dates are safe to set on connected clients.",
 		inputSchema: UpdateClientDatesInputSchema,
 		annotations: {
 			readOnlyHint: false,
@@ -10151,7 +10151,7 @@ async function buildServer(config) {
 	}, (args) => handleCreateSavedTaskFilter(api, args));
 	registerWriteTool(server, api, config.context, "update_workflow_step", {
 		title: "Update a workflow step (complete, skip, block, reassign)",
-		description: "Update one workflow step on a task: set status (Completed / Skipped / InProgress / Blocked with a blockedReason) and/or reassign to a user or team. Identify the step by taskCode + groupNumber + stepNumber exactly as shown in get_task_context's workflow section — ALWAYS call get_task_context first to confirm the numbers and current status. Use for 'mark the review step on TSK-123 as done', 'skip the client-approval step, they confirmed by phone', 'assign the bookkeeping steps to Jane'. Constraints: steps with dependencies may be rejected until prior steps complete — report the API's reason rather than retrying; auto-executing steps (emails, document requests) fire when their turn comes, so completing them manually may skip the automated action — warn the user if get_task_context showed the step as auto-executing. Step content/configuration is not editable here — that's done in the Sodium UI.",
+		description: "Update one workflow step on a task: set status (Completed / Skipped / InProgress / Blocked with a blockedReason) and/or reassign to a user or team. Identify the step by taskCode + groupNumber + stepNumber exactly as shown in get_task_context's workflow section, which also shows each step's current status. Use for 'mark the review step on TSK-123 as done', 'skip the client-approval step, they confirmed by phone', 'assign the bookkeeping steps to Jane'. Constraints: steps with dependencies may be rejected until prior steps complete — report the API's reason rather than retrying; auto-executing steps (emails, document requests) fire when their turn comes, so completing them manually may skip the automated action — warn the user if get_task_context showed the step as auto-executing. Step content/configuration is not editable here — that's done in the Sodium UI.",
 		inputSchema: UpdateWorkflowStepInputSchema,
 		annotations: {
 			readOnlyHint: false,
@@ -10162,7 +10162,7 @@ async function buildServer(config) {
 	}, (args) => handleUpdateWorkflowStep(api, args));
 	registerWriteTool(server, api, config.context, "create_task", {
 		title: "Create a new task",
-		description: "Create a one-off task. Requires name, startDate, and dueDate (YYYY-MM-DD — 'due Friday' resolves against today from the startup context). Optional: description, status (defaults NotStarted), statutory due date, time estimate, client(s) (codes from list_clients), assignee (user code from the roster/list_users, or team code from list_teams), linked client-billable-service, category (list_task_categories), and a checklist (array of item texts). Use for 'create a task to chase ACME's rental schedule, due Friday', 'add a task for Jane to review the draft accounts'. Do NOT use for recurring schedules or workflow-driven tasks — those are set up in the Sodium UI. If the user gave a client or person by name, resolve codes first; ask rather than guess when multiple matches exist.",
+		description: "Create a one-off task. Requires name, startDate, and dueDate (YYYY-MM-DD — 'due Friday' resolves against today's date). Optional: description, status (defaults NotStarted), statutory due date, time estimate, client(s) (codes from list_clients), assignee (user code from the roster/list_users, or team code from list_teams), linked client-billable-service, category (list_task_categories), and a checklist (array of item texts). Use for 'create a task to chase ACME's rental schedule, due Friday', 'add a task for Jane to review the draft accounts'. Do NOT use for recurring schedules or workflow-driven tasks — those are set up in the Sodium UI. If the user gave a client or person by name, resolve codes first; ask rather than guess when multiple matches exist.",
 		inputSchema: CreateTaskInputSchema,
 		annotations: {
 			readOnlyHint: false,
@@ -10184,7 +10184,7 @@ async function buildServer(config) {
 	}, (args) => handleUpdateTask(api, args));
 	registerWriteTool(server, api, config.context, "log_time_entry", {
 		title: "Log a time entry",
-		description: "Record time spent, after the fact. Requires entryDate (YYYY-MM-DD — use today from the startup context when the user doesn't say) and durationMinutes ('2 hours' → 120). Optional: description (strongly recommended — it feeds billing narratives), client code, task code, workflow group/step numbers (from get_task_context), billable flag, hourly rate, and userCode when logging on someone else's behalf (defaults to the authenticated user). Use for 'log 2 hours on ACME for today — reviewing the draft accounts', 'add 45 minutes against the Greggs VAT task'. Billable and rate default from practice/team-member configuration — only pass them when the user is explicit. Some practices require a client or task link; if the API rejects the entry saying so, ask the user which client/task to attach.",
+		description: "Record time spent, after the fact. Requires entryDate (YYYY-MM-DD — today's date applies when none is given) and durationMinutes ('2 hours' → 120). Optional: description (strongly recommended — it feeds billing narratives), client code, task code, workflow group/step numbers (from get_task_context), billable flag, hourly rate, and userCode when logging on someone else's behalf (defaults to the authenticated user). Use for 'log 2 hours on ACME for today — reviewing the draft accounts', 'add 45 minutes against the Greggs VAT task'. Billable and rate default from practice/team-member configuration — only pass them when the user is explicit. Some practices require a client or task link; if the API rejects the entry saying so, ask the user which client/task to attach.",
 		inputSchema: LogTimeEntryInputSchema,
 		annotations: {
 			readOnlyHint: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sodiumhq/mcp-pm",
-  "version": "0.1.0-beta.6354",
+  "version": "0.1.0-beta.6355",
   "description": "Sodium Practice Management MCP server — lets AI assistants interact with your Sodium tenant",
   "type": "module",
   "bin": {