@sodiumhq/mcp-pm 0.1.0-beta.5330 → 0.1.0-beta.5443

package/README.md

@@ -125,7 +125,7 @@ Only enable write mode with an AI client you trust — it hands the client the a
 **Proposals and engagements**
 - **`get_engagement_pipeline_summary`** — pipeline counts and values by status in one call. "What's our proposal pipeline worth?"
 - **`list_proposals`** and **`list_engagement_letters`** — aliased tools for the same underlying engagement pipeline (pre-acceptance vs signed). Filter by status, client, date range.
-- **`get_proposal_summary`** and **`get_engagement_letter_summary`** — aliased drill-ins: identity + client + value breakdown + services with pricing + PDFs + email history + acceptance record
+- **`get_proposal_summary`** and **`get_engagement_letter_summary`** — aliased drill-ins: identity + client + value breakdown (including catch-up fees, under the practice's own label) + services with pricing + PDFs + email history + acceptance record
 
 **Services**
 - **`list_services`** — find and count services in the practice's catalogue by search, category, applicable client type, or archived status. Answers "what do we offer?", "list our tax services", "what do we offer limited companies?", "how many active services do we have?"

package/dist/http.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as buildServer } from "./src-BY8wr-4D.mjs";
+import { t as buildServer } from "./src-CEXQpQbI.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-BY8wr-4D.mjs";
+import { t as buildServer } from "./src-CEXQpQbI.mjs";
 import { createRequire } from "node:module";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { parseArgs } from "node:util";

package/dist/{src-BY8wr-4D.mjs → src-CEXQpQbI.mjs}

@@ -1412,6 +1412,22 @@ const getMailboxConversation = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get engagement settings
+*
+* Returns the engagement settings for the specified tenant
+*/
+const getEngagementSettings = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/practice/engagement-settings",
+	...options
+});
+/**
 * List Engagements
 *
 * Lists all Engagements for the given tenant.
@@ -2678,6 +2694,16 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `get emails for engagement ${code}`);
 		return data;
 	}
+	async getEngagementSettings() {
+		const correlationId = randomUUID();
+		const { data, error, response } = await getEngagementSettings({
+			path: { tenant: this.tenant },
+			headers: { "X-Correlation-Id": correlationId },
+			client: this.http
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, "get engagement settings");
+		return data;
+	}
 	async getTaskWorkflowGroups(taskCode) {
 		const correlationId = randomUUID();
 		const { data, error, response } = await getTaskWorkflowGroups({
@@ -4248,9 +4274,17 @@ function humanizeDateType(type) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/get-engagement-summary.ts
+const DEFAULT_CATCH_UP_FEE_LABEL = "Catch-up fee";
+function labelInSentence(label) {
+	return /^[A-Z][A-Z]/.test(label) ? label : label.charAt(0).toLowerCase() + label.slice(1);
+}
 const GetEngagementSummaryInputSchema = { code: z.string().min(1, "Engagement code is required").describe("REQUIRED: The engagement code (identifier, e.g. 'ENG-123'). This is the unique code of a specific engagement — NOT a description like 'the unsent proposal' or 'ACME's proposal'. If the user describes an engagement by attribute (status, client, date) rather than by code, you MUST call list_proposals or list_engagement_letters first (with the appropriate filters) to find the engagement's code, then pass that code here.") };
 async function handleGetEngagementSummary(api, { code }) {
-	const [practice, [engagementResult, emailsResult]] = await Promise.all([api.getPracticeLocale(), Promise.allSettled([api.getEngagement(code), api.getEngagementEmails(code)])]);
+	const [practice, [engagementResult, emailsResult, settingsResult]] = await Promise.all([api.getPracticeLocale(), Promise.allSettled([
+		api.getEngagement(code),
+		api.getEngagementEmails(code),
+		api.getEngagementSettings()
+	])]);
 	if (engagementResult.status === "rejected") {
 		const err = engagementResult.reason;
 		return {
@@ -4262,18 +4296,24 @@ async function handleGetEngagementSummary(api, { code }) {
 		};
 	}
 	const engagement = engagementResult.value;
+	const emails = emailsResult.status === "fulfilled" ? emailsResult.value : [];
+	const catchUpFeeLabel = settingsResult.status === "fulfilled" && settingsResult.value.catchUpFeeLabel?.trim() || DEFAULT_CATCH_UP_FEE_LABEL;
+	const gaps = [];
+	if (emailsResult.status === "rejected") gaps.push("email history");
+	if (settingsResult.status === "rejected") gaps.push("the practice's catch-up fee label");
 	return { content: [{
 		type: "text",
 		text: format$2({
 			engagement,
-			emails: emailsResult.status === "fulfilled" ? emailsResult.value : [],
-			gaps: emailsResult.status === "rejected" ? ["email history"] : [],
-			practice
+			emails,
+			gaps,
+			practice,
+			catchUpFeeLabel
 		})
 	}] };
 }
 function format$2(input) {
-	const { engagement: e, emails, gaps, practice } = input;
+	const { engagement: e, emails, gaps, practice, catchUpFeeLabel } = input;
 	const lines = [];
 	const code = e.code ?? "(no code)";
 	const typeLabel = e.typeName ?? e.type ?? "";
@@ -4287,12 +4327,12 @@ function format$2(input) {
 		lines.push(`Recipient: ${recipientName || "(no name)"}${email}`);
 	}
 	if (e.lastViewed) lines.push(`Last viewed by client: ${e.lastViewed}`);
-	const valueLines = formatValues(e, practice);
+	const valueLines = formatValues(e, practice, catchUpFeeLabel);
 	if (valueLines.length > 0) lines.push("", "--- Value ---", ...valueLines);
 	const services = e.proposalServices ?? [];
 	if (services.length > 0) {
 		lines.push("", `--- Services (${services.length}) ---`);
-		for (const s of services) lines.push(`- ${formatService$1(s, practice)}`);
+		for (const s of services) lines.push(`- ${formatService$1(s, practice, catchUpFeeLabel)}`);
 	}
 	if (e.acceptance && e.status === "Accepted") {
 		lines.push("", "--- Acceptance ---");
@@ -4318,21 +4358,23 @@ function format$2(input) {
 	if (gaps.length > 0) lines.push("", `Note: could not load ${gaps.join(", ")} (partial failure). Retry for a complete picture.`);
 	return lines.join("\n");
 }
-function formatValues(e, practice) {
+function formatValues(e, practice, catchUpFeeLabel) {
 	const out = [];
 	if (e.annualTotal && e.annualTotal > 0) out.push(`Annual: ${money(e.annualTotal, practice)}`);
 	if (e.quarterlyTotal && e.quarterlyTotal > 0) out.push(`Quarterly: ${money(e.quarterlyTotal, practice)}`);
 	if (e.monthlyTotal && e.monthlyTotal > 0) out.push(`Monthly: ${money(e.monthlyTotal, practice)}`);
 	if (e.weeklyTotal && e.weeklyTotal > 0) out.push(`Weekly: ${money(e.weeklyTotal, practice)}`);
 	if (e.oneOffTotal && e.oneOffTotal > 0) out.push(`One-off: ${money(e.oneOffTotal, practice)}`);
+	if (e.catchUpTotal) out.push(`${catchUpFeeLabel}: ${money(e.catchUpTotal, practice)}`);
 	if (e.totalValue && e.totalValue > 0) out.push(`Total contracted value: ${money(e.totalValue, practice)}`);
 	return out;
 }
-function formatService$1(s, practice) {
+function formatService$1(s, practice, catchUpFeeLabel) {
 	const name = s.billableService?.name ?? "(unnamed)";
 	const freq = s.billingFrequency ? ` ${s.billingFrequency}` : "";
-	if (s.effectivePrice !== void 0 && s.effectivePrice !== null) return `${name} — ${money(s.effectivePrice, practice)}${freq}`;
-	return freq ? `${name} —${freq}` : name;
+	const catchUp = s.catchUp?.fee ? ` + ${money(s.catchUp.fee, practice)} ${labelInSentence(catchUpFeeLabel)} (${s.catchUp.months ?? "?"} months)` : "";
+	if (s.effectivePrice !== void 0 && s.effectivePrice !== null) return `${name} — ${money(s.effectivePrice, practice)}${freq}${catchUp}`;
+	return freq ? `${name} —${freq}${catchUp}` : `${name}${catchUp}`;
 }
 function formatEmail$1(em) {
 	return `- ${em.sentDate ?? "(no date)"}: ${em.subject ?? "(no subject)"}${em.status ? ` · ${em.status}` : ""}${em.toRecipients?.length ? ` → ${em.toRecipients.join(", ")}` : ""}`;
@@ -8816,8 +8858,7 @@ const AddClientServiceInputSchema = {
 	overrideSetupFee: z.boolean().optional().describe("true = use the custom setupFee instead of the service default."),
 	managedByUserCode: z.string().optional().describe("User who manages this service for the client. Resolve names via the roster or list_users."),
 	stageCode: z.string().optional().describe("Initial workflow stage for the service, if the service uses stages."),
-	autoInvoice: z.boolean().optional().describe("Whether the service auto-generates billing line items. Omit to use the default; only set when the user is explicit."),
-	nextBillingDate: z.string().optional().describe("First billing date (YYYY-MM-DD) when autoInvoice is on. Omit to default from startDate.")
+	autoInvoice: z.boolean().optional().describe("Whether the service auto-generates billing line items. Omit to use the default; only set when the user is explicit.")
 };
 async function handleAddClientService(api, args) {
 	try {
@@ -8835,8 +8876,7 @@ async function handleAddClientService(api, args) {
 			...rest.setupFee !== void 0 ? { setupFee: rest.setupFee } : {},
 			managedByUserCode: rest.managedByUserCode ?? null,
 			stageCode: rest.stageCode ?? null,
-			...rest.autoInvoice !== void 0 ? { autoInvoice: rest.autoInvoice } : {},
-			nextBillingDate: rest.nextBillingDate ?? null
+			...rest.autoInvoice !== void 0 ? { autoInvoice: rest.autoInvoice } : {}
 		};
 		const [practice, created] = await Promise.all([api.getPracticeLocale(), api.createClientService(clientCode, body)]);
 		const lines = [
@@ -8846,7 +8886,7 @@ async function handleAddClientService(api, args) {
 		];
 		if (created.managedByUser?.name) lines.push(`Managed by: ${created.managedByUser.name}`);
 		if (created.stage?.name) lines.push(`Stage: ${created.stage.name}`);
-		if (created.autoInvoice) lines.push(`Auto-invoicing on${created.nextBillingDate ? `, next billing ${created.nextBillingDate.slice(0, 10)}` : ""}`);
+		if (created.autoInvoice) lines.push("Auto-invoicing on");
 		return { content: [{
 			type: "text",
 			text: lines.join("\n")
@@ -9507,7 +9547,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 / total), the proposed services with pricing, 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 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 — 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.",
 		inputSchema: GetEngagementSummaryInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -9517,7 +9557,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 / total), services included with pricing, 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 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 — 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.",
 		inputSchema: GetEngagementSummaryInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -9867,7 +9907,7 @@ async function buildServer(config) {
 	}, (args) => handleListClientLinks(api, args));
 	registerWriteTool(server, api, config.context, "add_client_service", {
 		title: "Assign a catalogue service to a client",
-		description: "Put a client on one of the practice's services: requires billableServiceCode (from list_services), billingFrequency (must match one of the service's configured pricing options — check get_service_details first), and startDate. Optional: status (default Active; use 'Proposed' when quoting), custom price (with overridePricing=true), pricing tier (REQUIRED for CustomTiers-priced services), setup fee, managing user, initial stage, auto-invoicing and first billing date. Use for 'put ACME on monthly bookkeeping', 'add VAT returns to Greggs from next month'. NOT exposed: pricing-factor questionnaires — services priced by factors should be configured in the Sodium UI; if the API rejects the call asking for pricing answers, say so and point the user to the UI. Check get_client_summary first to avoid assigning a duplicate service.",
+		description: "Put a client on one of the practice's services: requires billableServiceCode (from list_services), billingFrequency (must match one of the service's configured pricing options — check get_service_details first), and startDate. Optional: status (default Active; use 'Proposed' when quoting), custom price (with overridePricing=true), pricing tier (REQUIRED for CustomTiers-priced services), setup fee, managing user, initial stage and auto-invoicing (billing dates come from the client's billing schedule). Use for 'put ACME on monthly bookkeeping', 'add VAT returns to Greggs from next month'. NOT exposed: pricing-factor questionnaires — services priced by factors should be configured in the Sodium UI; if the API rejects the call asking for pricing answers, say so and point the user to the UI. Check get_client_summary first to avoid assigning a duplicate service.",
 		inputSchema: AddClientServiceInputSchema,
 		annotations: {
 			readOnlyHint: false,

package/package.json

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