@sodiumhq/mcp-pm 0.1.0-beta.4465 → 0.1.0-beta.4579

package/README.md

@@ -2,6 +2,8 @@
 
 Model Context Protocol (MCP) server for [Sodium Practice Management](https://sodiumhq.com). Lets AI assistants like Claude Desktop, Claude Code, Cursor, and VS Code interact with your Sodium tenant.
 
+> **Using a browser assistant?** claude.ai, ChatGPT, and Gemini can connect to Sodium without installing anything — add `https://mcp.sodiumhq.com` as a custom connector and sign in with your Sodium account. This npm package is the local (stdio) alternative, authenticated with an API key.
+
 > **Full setup guide and example prompts:** [sodiumhq.com/features/mcp](https://sodiumhq.com/features/mcp)
 
 ## Status
@@ -151,6 +153,7 @@ Only enable write mode with an AI client you trust — it hands the client the a
 - **`update_task`** — change a task's status, dates, assignment, or details. Only the fields you mention change; everything else is preserved. "Mark TSK-123 complete", "push the deadline to Friday", "reassign it to Jane."
 - **`update_workflow_step`** — complete, skip, block, or reassign a single workflow step on a task. "Mark the review step as done", "skip the client-approval step — they confirmed by phone."
 - **`add_client_service`** — put a client on a catalogue service with frequency, pricing, and start date. "Put ACME on monthly bookkeeping."
+- **`apply_service_package`** — put a client on one of the practice's bundled packages in a single call; contents and pricing follow the package definition. "Put ACME on the Growth package from 1 April."
 - **`update_client_service_stage`** — move a client's service across the kanban board. "Move ACME's VAT return to Records In."
 - **`create_document_request`** — draft (never send) a document request for a client. Sending stays in the Sodium UI.
 - **`send_data_form`** — send a questionnaire to a client. Sends immediately, so your assistant confirms with you first.

package/dist/http.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as buildServer } from "./src-uJ9liBF-.mjs";
+import { t as buildServer } from "./src-dwGvEajk.mjs";
 import { createRequire } from "node:module";
 import { createHash, randomUUID } from "node:crypto";
 import { createServer } from "node:http";

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as buildServer } from "./src-uJ9liBF-.mjs";
+import { t as buildServer } from "./src-dwGvEajk.mjs";
 import { createRequire } from "node:module";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { parseArgs } from "node:util";

package/dist/{src-uJ9liBF-.mjs → src-dwGvEajk.mjs}

@@ -1719,6 +1719,26 @@ const listServicePackages = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Apply Service Package to Client
+*
+* Applies a service package to a client, creating ClientBillableService records for each item in the package.
+*/
+const applyServicePackageToClient = (options) => (options.client ?? client).post({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/clients/{clientCode}/apply-service-package/{packageCode}",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
 * List BillableServices
 *
 * Lists all BillableServices for the given tenant.
@@ -3403,6 +3423,21 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `assign service to client ${clientCode}`);
 		return data;
 	}
+	async applyServicePackageToClient(clientCode, packageCode, body) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await applyServicePackageToClient({
+			path: {
+				tenant: this.tenant,
+				clientCode,
+				packageCode
+			},
+			body,
+			headers: { "X-Correlation-Id": correlationId },
+			client: this.http
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `apply package ${packageCode} to client ${clientCode}`);
+		return data;
+	}
 	async updateClientServiceStage(clientCode, clientServiceCode, body) {
 		const correlationId = randomUUID();
 		const { error, response } = await updateClientBillableServiceStage({
@@ -3738,7 +3773,7 @@ async function handleGetPracticeDetails(api) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-clients.ts
-const statusEnum$14 = z.enum([
+const statusEnum$15 = z.enum([
 	"Active",
 	"Inactive",
 	"Prospect",
@@ -3757,7 +3792,7 @@ const typeEnum$1 = z.enum([
 const sortByEnum$19 = z.enum(["Name", "InternalReference"]);
 const ListClientsInputSchema = {
 	search: z.string().min(3, "Search must be at least 3 characters when provided").optional().describe("Free-text search across client code, name, and internal reference. Minimum 3 characters. Omit to browse by filter only."),
-	status: z.array(statusEnum$14).optional().describe("Filter by client status. Defaults to all statuses if omitted. Example: ['Active'] for active clients only."),
+	status: z.array(statusEnum$15).optional().describe("Filter by client status. Defaults to all statuses if omitted. Example: ['Active'] for active clients only."),
 	type: z.array(typeEnum$1).optional().describe("Filter by organisation type. Use ['PrivateLimitedCompany', 'PublicLimitedCompany'] for 'limited companies'. Use ['LimitedLiabilityPartnership'] for LLPs. Defaults to all types if omitted."),
 	managerCode: z.array(z.string()).optional().describe("Filter by assigned manager user codes."),
 	partnerCode: z.array(z.string()).optional().describe("Filter by assigned partner user codes."),
@@ -4544,7 +4579,7 @@ function describeFilters$3(args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-tasks.ts
-const statusEnum$13 = z.enum([
+const statusEnum$14 = z.enum([
 	"NotStarted",
 	"InProgress",
 	"Blocked",
@@ -4587,7 +4622,7 @@ const sortByEnum$17 = z.enum([
 const ListTasksInputSchema = {
 	user: z.array(z.string()).optional().describe("Filter by assigned user codes. For 'my tasks' use the current user's code from the startup context. For another team member's tasks, pass their code. Omit to see tasks across all users (useful for practice managers)."),
 	client: z.array(z.string()).optional().describe("Filter by client codes — tasks belonging to these specific clients only."),
-	status: z.array(statusEnum$13).optional().describe("Filter by task status. Typical: ['NotStarted', 'InProgress'] to exclude completed/skipped. Leave empty for all statuses. IMPORTANT: if the query includes NotStarted (the default for new tasks), you must ALSO provide one of: dateRange, isOverdue=true, or restrict status to non-NotStarted values only — otherwise the API rejects the call to prevent unbounded queries."),
+	status: z.array(statusEnum$14).optional().describe("Filter by task status. Typical: ['NotStarted', 'InProgress'] to exclude completed/skipped. Leave empty for all statuses. IMPORTANT: if the query includes NotStarted (the default for new tasks), you must ALSO provide one of: dateRange, isOverdue=true, or restrict status to non-NotStarted values only — otherwise the API rejects the call to prevent unbounded queries."),
 	isOverdue: z.boolean().optional().describe("Set true to return only overdue tasks (DueDate before today, not completed/skipped). When true, no date range is required. Useful for sidestepping the NotStarted + date-range requirement."),
 	dateRange: dateRangeEnum$2.optional().describe("Preset date range. Use 'Today' for today's tasks, 'Next7Days' for 'due this week', 'Last30Days' for recent activity. If 'CustomDateRange', also provide startDate and/or endDate. REQUIRED when querying NotStarted tasks unless you pass isOverdue=true."),
 	startDate: z.string().optional().describe("Start of custom date range (YYYY-MM-DD). Used when dateRange='CustomDateRange'. Prefer specifying both startDate and endDate with a narrow window for performance — broad ranges strain the API. If startDate > endDate the API swaps them silently. Maximum allowed total range is 2 years."),
@@ -4665,7 +4700,7 @@ function describeFilters$2(args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-users.ts
-const statusEnum$12 = z.enum([
+const statusEnum$13 = z.enum([
 	"Created",
 	"Invited",
 	"Active",
@@ -4685,7 +4720,7 @@ const sortByEnum$16 = z.enum([
 ]);
 const ListUsersInputSchema = {
 	search: z.string().min(3, "Search must be at least 3 characters when provided").optional().describe("Free-text search across user code, first name, last name, and email. Minimum 3 characters. Use for 'find Jane' when the name isn't in the startup roster (large teams, non-active users)."),
-	status: statusEnum$12.optional().describe("Filter by a single user status. Use 'Active' for currently-working members, 'Invited' for pending invitations, 'Disabled' for offboarded users, 'Deleted' for removed users. Note: this is a single value, not an array."),
+	status: statusEnum$13.optional().describe("Filter by a single user status. Use 'Active' for currently-working members, 'Invited' for pending invitations, 'Disabled' for offboarded users, 'Deleted' for removed users. Note: this is a single value, not an array."),
 	systemRole: systemRoleEnum.optional().describe("Filter by system role. Admin = full access, StandardUser = normal access, Viewer = read-only. Single value."),
 	isClientManager: z.boolean().optional().describe("Set true to return only users flagged as client managers; false to exclude them."),
 	isPartner: z.boolean().optional().describe("Set true to return only users flagged as partners; false to exclude them. Use for 'list partners' queries."),
@@ -6199,7 +6234,7 @@ async function handleGetCompaniesHouseProfile(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-document-requests.ts
-const statusEnum$11 = z.enum([
+const statusEnum$12 = z.enum([
 	"Draft",
 	"Open",
 	"Submitted",
@@ -6213,7 +6248,7 @@ const sortByEnum$11 = z.enum([
 	"Deadline"
 ]);
 const ListDocumentRequestsInputSchema = {
-	status: statusEnum$11.optional().describe("Filter by request status. 'Open' = sent and waiting on the client (use for 'what are we waiting on from clients?'). 'Submitted' = client responded, awaiting practice review (use for 'what needs reviewing?'). 'Draft' = not yet sent. 'Accepted'/'Rejected' = reviewed. Single value — call per status for multiple."),
+	status: statusEnum$12.optional().describe("Filter by request status. 'Open' = sent and waiting on the client (use for 'what are we waiting on from clients?'). 'Submitted' = client responded, awaiting practice review (use for 'what needs reviewing?'). 'Draft' = not yet sent. 'Accepted'/'Rejected' = reviewed. Single value — call per status for multiple."),
 	clientCode: z.string().optional().describe("Filter to one client's document requests. Get the code from list_clients."),
 	managerCode: z.string().optional().describe("Filter by the client manager's user code — 'what are MY clients waiting to send us?' for a manager."),
 	partnerCode: z.string().optional().describe("Filter by the client partner's user code."),
@@ -6279,10 +6314,10 @@ async function handleListDocumentRequests(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-data-form-requests.ts
-const statusEnum$10 = z.enum(["PendingResponse", "ResponseReceived"]);
+const statusEnum$11 = z.enum(["PendingResponse", "ResponseReceived"]);
 const sortByEnum$10 = z.enum(["CreatedDate", "Status"]);
 const ListDataFormRequestsInputSchema = {
-	status: statusEnum$10.optional().describe("Filter by request status. 'PendingResponse' = sent, waiting on the client to fill the form in (use for 'which questionnaires are clients sitting on?'). 'ResponseReceived' = the client submitted — answers may still need review (see pendingReviewCount in the output)."),
+	status: statusEnum$11.optional().describe("Filter by request status. 'PendingResponse' = sent, waiting on the client to fill the form in (use for 'which questionnaires are clients sitting on?'). 'ResponseReceived' = the client submitted — answers may still need review (see pendingReviewCount in the output)."),
 	clientCode: z.string().optional().describe("Filter to one client's form requests. Get the code from list_clients."),
 	formCode: z.string().optional().describe("Filter by the data-form template code — 'who still hasn't returned the SA questionnaire?'."),
 	categoryCode: z.string().optional().describe("Filter by the form's category code."),
@@ -6667,6 +6702,7 @@ const TOPICS = {
 - "Set the 'Referral source' custom field on ACME to 'Google'"
 - "Mark the review step on the Greggs year-end task as complete" / "Skip the client-approval step — they confirmed by phone"
 - "Put ACME on monthly bookkeeping at £350 from the 1st" / "Move their VAT return to 'Records In' on the board"
+- "Put Bristol Roofing on the Growth package from 1 April" — the whole bundle in one step
 - "Draft a document request to ACME for their year-end records" (drafted — you press send)
 - "Send the SA questionnaire to Greggs" (sends immediately — the assistant confirms first)
 - "Draft a proposal for Bristol Roofing covering bookkeeping and VAT" (drafted Unsent — you review and send)
@@ -6698,7 +6734,7 @@ async function handleGetUsageExamples(args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/create-task.ts
-const statusEnum$9 = z.enum([
+const statusEnum$10 = z.enum([
 	"NotStarted",
 	"InProgress",
 	"Blocked",
@@ -6708,7 +6744,7 @@ const statusEnum$9 = z.enum([
 const CreateTaskInputSchema = {
 	name: z.string().min(1).describe("The task name — short and action-oriented, e.g. 'Chase rental schedule for year-end'."),
 	description: z.string().optional().describe("Longer description of what needs doing. Optional."),
-	status: statusEnum$9.optional().describe("Initial status. Defaults to NotStarted — only override when the work is already underway (InProgress)."),
+	status: statusEnum$10.optional().describe("Initial status. Defaults to NotStarted — only override when the work is already underway (InProgress)."),
 	startDate: z.string().describe("When work should start (YYYY-MM-DD). For ad-hoc tasks, today is usually right — get today's date from the startup context."),
 	dueDate: z.string().describe("When the task is due (YYYY-MM-DD). Must be on or after startDate."),
 	statutoryDueDate: z.string().optional().describe("The statutory deadline (YYYY-MM-DD), for compliance tasks with a legal filing date distinct from the internal due date."),
@@ -6768,7 +6804,7 @@ async function handleCreateTask(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/update-task.ts
-const statusEnum$8 = z.enum([
+const statusEnum$9 = z.enum([
 	"NotStarted",
 	"InProgress",
 	"Blocked",
@@ -6777,7 +6813,7 @@ const statusEnum$8 = z.enum([
 ]);
 const UpdateTaskInputSchema = {
 	taskCode: z.string().min(1).describe("The code of the task to update. Get it from list_tasks or get_task_context."),
-	status: statusEnum$8.optional().describe("New status. 'Completed' for 'mark it done', 'InProgress' for 'I've started it', 'Blocked' when waiting on something. Note: completing a task does NOT complete its workflow steps — mention open steps to the user if get_task_context showed any."),
+	status: statusEnum$9.optional().describe("New status. 'Completed' for 'mark it done', 'InProgress' for 'I've started it', 'Blocked' when waiting on something. Note: completing a task does NOT complete its workflow steps — mention open steps to the user if get_task_context showed any."),
 	name: z.string().min(1).optional().describe("New task name. Omit to keep the current name."),
 	description: z.string().nullable().optional().describe("New description. Pass null to clear it. Omit to keep the current one."),
 	startDate: z.string().optional().describe("New start date (YYYY-MM-DD)."),
@@ -6893,7 +6929,7 @@ async function handleLogTimeEntry(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-sent-emails.ts
-const statusEnum$7 = z.enum([
+const statusEnum$8 = z.enum([
 	"Queued",
 	"Processing",
 	"Sent",
@@ -6906,7 +6942,7 @@ const sortByEnum$7 = z.enum([
 	"Status"
 ]);
 const ListSentEmailsInputSchema = {
-	status: statusEnum$7.optional().describe("Filter by delivery status. 'Failed' answers 'which emails didn't get through?' — the most actionable query. 'Queued'/'Processing' show what's still going out."),
+	status: statusEnum$8.optional().describe("Filter by delivery status. 'Failed' answers 'which emails didn't get through?' — the most actionable query. 'Queued'/'Processing' show what's still going out."),
 	search: z.string().optional().describe("Search in email subject and recipient email address — 'emails to john@acme.co.uk', 'the proposal email'."),
 	fromDate: z.string().optional().describe("Only emails created on or after this date (YYYY-MM-DD). Prefer setting a window — unbounded queries scan all history."),
 	toDate: z.string().optional().describe("Only emails created on or before this date (YYYY-MM-DD)."),
@@ -7189,7 +7225,7 @@ async function handleGetAmlClient(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-billing-line-items.ts
-const statusEnum$6 = z.enum([
+const statusEnum$7 = z.enum([
 	"Pending",
 	"Approved",
 	"Invoiced",
@@ -7202,7 +7238,7 @@ const sortByEnum$5 = z.enum([
 	"UnitPrice"
 ]);
 const ListBillingLineItemsInputSchema = {
-	status: statusEnum$6.optional().describe("Filter by line-item status. 'Pending' = generated, awaiting approval (the 'what's waiting to be billed?' question). 'Approved' = ready for invoicing. 'Invoiced' = sent to the accounting system. Single value — call per status for multiple."),
+	status: statusEnum$7.optional().describe("Filter by line-item status. 'Pending' = generated, awaiting approval (the 'what's waiting to be billed?' question). 'Approved' = ready for invoicing. 'Invoiced' = sent to the accounting system. Single value — call per status for multiple."),
 	clientCode: z.string().optional().describe("Filter to one client's billing lines — 'what are we about to bill ACME?'."),
 	billableServiceCode: z.string().optional().describe("Filter by the billable service — 'what bookkeeping revenue is queued?'. Get codes from list_services."),
 	clientBillableServiceCode: z.string().optional().describe("Filter by one client's specific service subscription (the code from get_client_summary's services section). Narrower than billableServiceCode."),
@@ -7265,7 +7301,7 @@ async function handleListBillingLineItems(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/update-workflow-step.ts
-const statusEnum$5 = z.enum([
+const statusEnum$6 = z.enum([
 	"NotStarted",
 	"InProgress",
 	"Blocked",
@@ -7276,7 +7312,7 @@ const UpdateWorkflowStepInputSchema = {
 	taskCode: z.string().min(1).describe("The task whose workflow step to update. Get it from list_tasks or get_task_context."),
 	groupNumber: z.number().int().min(1).describe("The workflow group number, exactly as shown in get_task_context's workflow section."),
 	stepNumber: z.number().int().min(1).describe("The step number within the group, exactly as shown in get_task_context."),
-	status: statusEnum$5.optional().describe("New step status. 'Completed' for 'mark the review step done', 'Skipped' when the step doesn't apply, 'InProgress' when starting it, 'Blocked' with blockedReason when stuck. Steps may have dependencies — if the API rejects the change, report why rather than retrying."),
+	status: statusEnum$6.optional().describe("New step status. 'Completed' for 'mark the review step done', 'Skipped' when the step doesn't apply, 'InProgress' when starting it, 'Blocked' with blockedReason when stuck. Steps may have dependencies — if the API rejects the change, report why rather than retrying."),
 	blockedReason: z.string().optional().describe("Why the step is blocked. Only meaningful with status='Blocked'."),
 	assignedUserCode: z.string().nullable().optional().describe("Reassign the step to this user code (resolve names via the roster or list_users). Pass null to unassign."),
 	assignedTeamCode: z.string().nullable().optional().describe("Assign the step to this team code (from list_teams), independent of the user assignment. Pass null to clear.")
@@ -7631,7 +7667,7 @@ async function handleListClientDocuments(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-data-forms.ts
-const statusEnum$4 = z.enum([
+const statusEnum$5 = z.enum([
 	"Draft",
 	"Published",
 	"Archived"
@@ -7639,7 +7675,7 @@ const statusEnum$4 = z.enum([
 const sortByEnum$2 = z.enum(["Name", "Status"]);
 const ListDataFormsInputSchema = {
 	search: z.string().optional().describe("Search over form name — 'the SA questionnaire', 'onboarding form'."),
-	status: statusEnum$4.optional().describe("Filter by form status. 'Published' = sendable to clients (the usual filter); 'Draft' = still being built; 'Archived' = retired."),
+	status: statusEnum$5.optional().describe("Filter by form status. 'Published' = sendable to clients (the usual filter); 'Draft' = still being built; 'Archived' = retired."),
 	sortBy: sortByEnum$2.optional().describe("Field to sort by. Defaults to Name."),
 	sortDesc: z.boolean().optional().describe("Sort in descending order. Defaults to ascending."),
 	limit: z.number().int().min(0).max(50).optional().describe("Maximum forms per page. Default 10, max 50. Pass 0 for count-only."),
@@ -7749,7 +7785,7 @@ async function handleGetTaskHistory(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-invoice-submissions.ts
-const statusEnum$3 = z.enum([
+const statusEnum$4 = z.enum([
 	"Pending",
 	"Submitted",
 	"Failed",
@@ -7762,7 +7798,7 @@ const sortByEnum$1 = z.enum([
 	"TotalAmount"
 ]);
 const ListInvoiceSubmissionsInputSchema = {
-	status: statusEnum$3.optional().describe("Filter by status. 'Failed' answers 'which invoices didn't reach the accounting system?' (the actionable one). 'Pending' = queued to submit; 'Submitted' = in the accounting system; 'Projected' = forecast only, not yet generated."),
+	status: statusEnum$4.optional().describe("Filter by status. 'Failed' answers 'which invoices didn't reach the accounting system?' (the actionable one). 'Pending' = queued to submit; 'Submitted' = in the accounting system; 'Projected' = forecast only, not yet generated."),
 	clientCode: z.string().optional().describe("Filter to one client's invoice submissions."),
 	billingDateFrom: z.string().optional().describe("Only submissions with billing date on or after this date (YYYY-MM-DD)."),
 	billingDateTo: z.string().optional().describe("Only submissions with billing date on or before this date (YYYY-MM-DD)."),
@@ -7867,7 +7903,7 @@ async function handleListServicePackages(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-email-broadcasts.ts
-const statusEnum$2 = z.enum([
+const statusEnum$3 = z.enum([
 	"Draft",
 	"Queued",
 	"Sending",
@@ -7877,7 +7913,7 @@ const statusEnum$2 = z.enum([
 ]);
 const sortByEnum = z.enum(["CreatedDate", "Status"]);
 const ListEmailBroadcastsInputSchema = {
-	status: statusEnum$2.optional().describe("Filter by broadcast status. 'Completed' for sent campaigns, 'Draft' for unsent, 'Failed' for broadcasts that errored."),
+	status: statusEnum$3.optional().describe("Filter by broadcast status. 'Completed' for sent campaigns, 'Draft' for unsent, 'Failed' for broadcasts that errored."),
 	sortBy: sortByEnum.optional().describe("Field to sort by. Defaults to CreatedDate — pair with sortDesc=true for newest first."),
 	sortDesc: z.boolean().optional().describe("Sort in descending order. Defaults to ascending."),
 	limit: z.number().int().min(0).max(50).optional().describe("Maximum broadcasts per page. Default 10, max 50. Pass 0 for count-only."),
@@ -8308,7 +8344,7 @@ const frequencyEnum = z.enum([
 	"Quarterly",
 	"Monthly"
 ]);
-const statusEnum$1 = z.enum([
+const statusEnum$2 = z.enum([
 	"Active",
 	"Inactive",
 	"Paused",
@@ -8320,7 +8356,7 @@ const AddClientServiceInputSchema = {
 	billingFrequency: frequencyEnum.describe("How the service is billed to this client. Match one of the service's configured pricing options (visible in get_service_details)."),
 	startDate: z.string().describe("When the service starts for this client (YYYY-MM-DD)."),
 	endDate: z.string().optional().describe("Optional end date (YYYY-MM-DD). Omit for ongoing."),
-	status: statusEnum$1.optional().describe("Service status. Defaults to Active. Use 'Proposed' when the service is being quoted but not yet agreed."),
+	status: statusEnum$2.optional().describe("Service status. Defaults to Active. Use 'Proposed' when the service is being quoted but not yet agreed."),
 	price: z.number().min(0).optional().describe("Custom base price for this client. Only used with overridePricing=true — omit both to use the service's standard pricing."),
 	overridePricing: z.boolean().optional().describe("true = use the custom 'price' instead of the service's standard pricing. Must be accompanied by 'price'."),
 	pricingTierCode: z.string().optional().describe("Required when the service uses CustomTiers pricing (see get_service_details) — the tier code to apply."),
@@ -8374,6 +8410,66 @@ async function handleAddClientService(api, args) {
 	}
 }
 //#endregion
+//#region ../mcp-core/src/tools/apply-service-package.ts
+const statusEnum$1 = z.enum([
+	"Active",
+	"Inactive",
+	"Paused",
+	"Proposed"
+]);
+const ApplyServicePackageInputSchema = {
+	clientCode: z.string().min(1).describe("The client to apply the package to. Get the code from list_clients."),
+	packageCode: z.string().min(1).describe("The service package to apply. Get the code from list_service_packages — check its contents and pricing mode there first so you can tell the user what they are about to get and how it will be billed. Archived packages are rejected by the API."),
+	startDate: z.string().optional().describe("When the package takes effect for this client (YYYY-MM-DD). Defaults to today. Use for 'put them on the Growth package from the 1st'."),
+	status: statusEnum$1.optional().describe("Status the package is applied at. Defaults to Active. Use 'Proposed' when it is being quoted but not yet agreed — that also suppresses onboarding tasks, which are only created for Active services."),
+	createOnboardingTasks: z.boolean().optional().describe("Whether to raise onboarding tasks from each service's templates. Defaults to true, which is right for a client genuinely starting the package now. Pass false when recording an arrangement that is already up and running — migrating historical data, or backdating a package the practice has been delivering for months — so the team isn't handed onboarding work for something already onboarded.")
+};
+function formatCreatedService(s) {
+	const name = s.billableService?.name?.trim() || s.billableService?.code || "(unnamed service)";
+	const frequency = s.billingFrequency ? ` · ${s.billingFrequency}` : "";
+	return `- ${name} (${s.code ?? "no code"})${frequency}`;
+}
+async function handleApplyServicePackage(api, args) {
+	try {
+		const body = {
+			status: args.status ?? "Active",
+			startDate: args.startDate ?? null,
+			createOnboardingTasks: args.createOnboardingTasks ?? true
+		};
+		const created = await api.applyServicePackageToClient(args.clientCode, args.packageCode, body);
+		if (created.length === 0) return { content: [{
+			type: "text",
+			text: `Package ${args.packageCode} was applied to ${args.clientCode} but created no services — the package appears to be empty. Check its contents with list_service_packages.`
+		}] };
+		const packageName = created[0]?.servicePackage?.name?.trim() || args.packageCode;
+		const startDate = created[0]?.startDate?.slice(0, 10);
+		const status = created[0]?.status ?? args.status ?? "Active";
+		const autoInvoiced = created.filter((s) => s.autoInvoice).length;
+		const lines = [
+			`Package applied: ${packageName} on client ${args.clientCode} — ${created.length} service${created.length === 1 ? "" : "s"} created`,
+			`Status: ${status}${startDate ? ` · starting ${startDate}` : ""}`,
+			"",
+			...created.map(formatCreatedService),
+			"",
+			"What the client is billed follows the package's own pricing setup — either a single package price or each service priced separately. Check list_service_packages for the package's pricing, or get_client_summary for the client's resulting services."
+		];
+		if (args.createOnboardingTasks === false) lines.push("", "Onboarding tasks were suppressed for this application.");
+		if (autoInvoiced > 0) lines.push("", `Auto-invoicing is on for ${autoInvoiced} of these services (the practice has client billing enabled), so they will generate billing lines automatically.`);
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error applying package ${args.packageCode} to ${args.clientCode}: ${error.message} (correlation: ${error.correlationId})` : `Error applying package ${args.packageCode} to ${args.clientCode}: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+//#endregion
 //#region ../mcp-core/src/tools/update-client-service-stage.ts
 const UpdateClientServiceStageInputSchema = {
 	clientCode: z.string().min(1).describe("The client whose service to move. Get the code from list_clients."),
@@ -8550,7 +8646,7 @@ const dateTypeEnum = z.enum([
 	"ConfirmationStatementNextMadeUpTo",
 	"LastConfirmationStatementFiled",
 	"LastConfirmationStatementMadeUpTo",
-	"NextVatReturnDue",
+	"NextVatReturnDueAnnual",
 	"NextVatPeriodEndQuarterly",
 	"NextVatReturnDueQuarterly",
 	"NextVatPeriodEndMonthly",
@@ -9262,7 +9358,7 @@ async function buildServer(config) {
 	}, (args) => handleListInvoiceSubmissions(api, args));
 	registerTenantTool(server, api, "list_service_packages", {
 		title: "List service packages (bundled offerings)",
-		description: "List the practice's service packages — bundled offerings like a 'Growth package' — with contents (which services at which frequency), pricing mode (single package price vs per-service), and approximate annual value. Filters: search, contains-service (billableServiceCode array — 'which packages include bookkeeping?'), pagination. Complements list_services (individual catalogue). Applying a package to a client is done in the Sodium UI.",
+		description: "List the practice's service packages — bundled offerings like a 'Growth package' — with contents (which services at which frequency), pricing mode (single package price vs per-service), and approximate annual value. Filters: search, contains-service (billableServiceCode array — 'which packages include bookkeeping?'), pagination. Complements list_services (individual catalogue). With write mode enabled, apply_service_package puts a client on one of these.",
 		inputSchema: ListServicePackagesInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListServicePackages(api, args));
@@ -9307,6 +9403,17 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleAddClientService(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.",
+		inputSchema: ApplyServicePackageInputSchema,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: true
+		}
+	}, (args) => handleApplyServicePackage(api, args));
 	registerWriteTool(server, api, config.context, "update_client_service_stage", {
 		title: "Move a client's service to a different stage (kanban)",
 		description: "Move one client-service card to a different workflow stage — the kanban move, from chat. Requires the client code, the client's service-subscription code (from get_client_summary's services section — NOT the catalogue service code), and the target stageCode (stage codes are in get_service_details for the underlying service). Pass stageCode=null to clear the stage. Use for 'move ACME's VAT return to Records In', 'mark the bookkeeping as Finished on the board'. Note: workflows can also set stages automatically via SetServiceStage steps — a manual move may be overridden by the next automated step.",

package/package.json

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