@sodiumhq/mcp-pm 0.1.0-beta.2619 → 0.1.0-beta.2749

package/README.md

@@ -63,7 +63,7 @@ Only enable write mode with an AI client you trust — it hands the client the a
 
 **Clients**
 - **`list_clients`** — list and filter clients by search, status, type, assignee, services, saved filters
-- **`get_client_summary`** — one-call composite for a single client: identity + contacts + active services with pricing + business details (company number, VAT, UTR, trading address) + key statutory dates (year-end, accounts due, VAT return due, confirmation statement due) + overdue tasks + tasks due in next 7 days
+- **`get_client_summary`** — one-call composite for a single client: identity + contacts + active services with pricing + business details (company number, VAT, UTR, trading address) + **custom fields** (all user-defined fields with current values, data types, and field codes) + key statutory dates (year-end, accounts due, VAT return due, confirmation statement due) + overdue tasks + tasks due in next 7 days
 
 **Tasks**
 - **`list_tasks`** — find and count tasks by assignee (including "my tasks"), client, status, overdue, date range, category, team, or workflow. Answers "what's on my plate?", "what's Jane working on?", "what's overdue for ACME?", "how many tasks are due this week?"
@@ -83,6 +83,7 @@ Only enable write mode with an AI client you trust — it hands the client the a
 **Write tools** (require `--enable-writes` — see [Write mode](#write-mode))
 - **`add_task_note`** — capture a note against a specific task. Attributed to your API user, timestamped to now.
 - **`add_client_note`** — capture a note against a client record. Same shape as `add_task_note` but scoped to the client.
+- **`update_client_custom_fields`** — set or clear custom field values on a client. Accepts a map of field codes to values, validates against the field's data type (Text, Number, Date, Boolean, Select, MultiSelect). Pass null to clear a field. Field codes are discoverable via `get_client_summary`.
 
 More tools land iteratively as the beta progresses.
 

package/dist/index.js

@@ -654,6 +654,42 @@ const listClientContactsForClient = (options) => (options.client ?? client).get(
 	...options
 });
 /**
+* Get Custom Field Values
+*
+* Returns field code and value pairs for the specified client. Use the custom field definitions endpoint to retrieve data types, labels, and allowed options.
+*/
+const getClientCustomFieldValues = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/clients/{client}/custom-field-values",
+	...options
+});
+/**
+* Set Custom Field Values
+*
+* Sets or updates custom field values for the specified client. Only fields included in the request are updated. Use the custom field definitions endpoint to determine valid field codes and data types.
+*/
+const setClientCustomFieldValues = (options) => (options.client ?? client).put({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/clients/{client}/custom-field-values",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
 * Get Client Dates
 *
 * Returns all key dates for the specified client
@@ -741,6 +777,22 @@ const getClient = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* List CustomFieldDefinitions
+*
+* Lists all CustomFieldDefinitions for the given tenant.
+*/
+const listCustomFieldDefinitions = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/custom-fields",
+	...options
+});
+/**
 * List Engagements
 *
 * Lists all Engagements for the given tenant.
@@ -1317,6 +1369,44 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `add note to client ${clientCode}`);
 		return data;
 	}
+	async listCustomFieldDefinitions(query = {}) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await listCustomFieldDefinitions({
+			path: { tenant: this.ctx.tenant },
+			query: {
+				...query,
+				limit: query.limit ?? 50,
+				offset: query.offset ?? 0
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, "list custom field definitions");
+		return data;
+	}
+	async getClientCustomFieldValues(clientCode) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await getClientCustomFieldValues({
+			path: {
+				tenant: this.ctx.tenant,
+				client: clientCode
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `get custom field values for client ${clientCode}`);
+		return data;
+	}
+	async setClientCustomFieldValues(clientCode, values) {
+		const correlationId = randomUUID();
+		const { error, response } = await setClientCustomFieldValues({
+			path: {
+				tenant: this.ctx.tenant,
+				client: clientCode
+			},
+			body: values,
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0) throw this.toError(response, error, correlationId, `set custom field values for client ${clientCode}`);
+	}
 	toError(response, error, correlationId, operation) {
 		const status = response.status;
 		let message = `Failed to ${operation} (HTTP ${status})`;
@@ -1534,7 +1624,7 @@ function describeFilters$4(args) {
 //#region ../mcp-core/src/tools/get-client-summary.ts
 const GetClientSummaryInputSchema = { code: z.string().min(1, "Client code is required").describe("The client code (identifier). Usually discovered via list_clients first.") };
 async function handleGetClientSummary(api, { code }) {
-	const [clientResult, contactsResult, servicesResult, businessResult, datesResult, overdueResult, upcomingResult] = await Promise.allSettled([
+	const [clientResult, contactsResult, servicesResult, businessResult, datesResult, overdueResult, upcomingResult, customFieldDefsResult, customFieldValsResult] = await Promise.allSettled([
 		api.getClient(code),
 		api.listClientContacts(code),
 		api.listClientServices(code),
@@ -1550,7 +1640,13 @@ async function handleGetClientSummary(api, { code }) {
 			dateRange: "Next7Days",
 			dateBasis: "DueDate",
 			limit: 50
-		})
+		}),
+		api.listCustomFieldDefinitions({
+			entityType: "Client",
+			isArchived: false,
+			limit: 50
+		}),
+		api.getClientCustomFieldValues(code)
 	]);
 	if (clientResult.status === "rejected") {
 		const err = clientResult.reason;
@@ -1562,6 +1658,7 @@ async function handleGetClientSummary(api, { code }) {
 			isError: true
 		};
 	}
+	const customFieldsAvailable = customFieldDefsResult.status === "fulfilled" && customFieldValsResult.status === "fulfilled";
 	return { content: [{
 		type: "text",
 		text: format$3({
@@ -1572,13 +1669,16 @@ async function handleGetClientSummary(api, { code }) {
 			clientDates: datesResult.status === "fulfilled" ? datesResult.value : [],
 			overdueTasks: extract(overdueResult),
 			upcomingTasks: extract(upcomingResult),
+			customFieldDefs: customFieldsAvailable ? customFieldDefsResult.value.data ?? [] : [],
+			customFieldValues: customFieldsAvailable ? customFieldValsResult.value : [],
 			gaps: [
 				contactsResult.status === "rejected" ? "contacts" : null,
 				servicesResult.status === "rejected" ? "services" : null,
 				businessResult.status === "rejected" ? "business details" : null,
 				datesResult.status === "rejected" ? "key dates" : null,
 				overdueResult.status === "rejected" ? "overdue tasks" : null,
-				upcomingResult.status === "rejected" ? "upcoming tasks" : null
+				upcomingResult.status === "rejected" ? "upcoming tasks" : null,
+				!customFieldsAvailable ? "custom fields" : null
 			].filter((v) => v !== null)
 		})
 	}] };
@@ -1588,7 +1688,7 @@ function extract(result) {
 	return result.value.data ?? [];
 }
 function format$3(input) {
-	const { client, contacts, services, businessDetails, clientDates, overdueTasks, upcomingTasks, gaps } = input;
+	const { client, contacts, services, businessDetails, clientDates, overdueTasks, upcomingTasks, customFieldDefs, customFieldValues, gaps } = input;
 	const lines = [];
 	const name = client.name ?? "(no name)";
 	const code = client.code ?? "(no code)";
@@ -1603,6 +1703,18 @@ function format$3(input) {
 	if (client.associate) lines.push(`Associate: ${client.associate.name} (${client.associate.code})`);
 	const businessLines = formatBusinessDetails(businessDetails);
 	if (businessLines.length > 0) lines.push("", "--- Business Details ---", ...businessLines);
+	if (customFieldDefs.length > 0) {
+		const valueMap = /* @__PURE__ */ new Map();
+		for (const v of customFieldValues) if (v.fieldCode) valueMap.set(v.fieldCode, v.value ?? null);
+		lines.push("", `--- Custom Fields (${customFieldDefs.length}) ---`);
+		for (const def of customFieldDefs) {
+			const code = def.code ?? "(no code)";
+			const label = def.label ?? code;
+			const val = valueMap.get(code);
+			const typeHint = def.dataType ? ` [${def.dataType}]` : "";
+			lines.push(`- ${label} (${code})${typeHint}: ${val ?? "(not set)"}`);
+		}
+	}
 	if (clientDates.length > 0) {
 		lines.push("", `--- Key Dates (${clientDates.length}) ---`);
 		const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
@@ -2487,6 +2599,90 @@ async function handleAddTaskNote(api, args) {
 	}
 }
 //#endregion
+//#region ../mcp-core/src/tools/set-client-custom-fields.ts
+const SetClientCustomFieldsInputSchema = {
+	clientCode: z.string().min(1, "Client code is required").describe("The client code (identifier). Usually discovered via list_clients or get_client_summary."),
+	fields: z.record(z.string(), z.string().nullable()).describe("A map of custom field codes to values. Use null to clear a field. Values must match the field's data type: Text — any string; Number — a numeric string like \"42\" or \"3.14\"; Date — ISO 8601 date like \"2025-06-15\"; Boolean — \"true\" or \"false\"; Select — one of the field's allowed options (exact match); MultiSelect — comma-separated list of allowed options. Use get_client_summary to discover available field codes and their current values before setting.")
+};
+async function handleSetClientCustomFields(api, args) {
+	try {
+		const entries = Object.entries(args.fields);
+		if (entries.length === 0) return { content: [{
+			type: "text",
+			text: "No fields provided — nothing to update."
+		}] };
+		const definitions = await api.listCustomFieldDefinitions({
+			entityType: "Client",
+			isArchived: false,
+			limit: 50
+		});
+		const defMap = /* @__PURE__ */ new Map();
+		for (const d of definitions.data ?? []) if (d.code) defMap.set(d.code, d);
+		const errors = [];
+		for (const [fieldCode, value] of entries) {
+			const def = defMap.get(fieldCode);
+			if (!def) {
+				errors.push(`Unknown custom field code: "${fieldCode}"`);
+				continue;
+			}
+			if (value === null || value === "") continue;
+			const validation = validateFieldValue(def, value);
+			if (validation) errors.push(`${fieldCode}: ${validation}`);
+		}
+		if (errors.length > 0) return {
+			content: [{
+				type: "text",
+				text: `Validation failed:\n${errors.map((e) => `- ${e}`).join("\n")}`
+			}],
+			isError: true
+		};
+		await api.setClientCustomFieldValues(args.clientCode, entries.map(([fieldCode, value]) => ({
+			fieldCode,
+			value: value ?? null
+		})));
+		const summary = entries.map(([code, val]) => `- ${defMap.get(code)?.label ?? code}: ${val === null ? "(cleared)" : val}`).join("\n");
+		return { content: [{
+			type: "text",
+			text: `Updated ${entries.length} custom field(s) on client ${args.clientCode}:\n${summary}`
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error setting custom fields: ${error.message} (correlation: ${error.correlationId})` : `Error setting custom fields: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+function validateFieldValue(def, value) {
+	switch (def.dataType) {
+		case "Number":
+			if (isNaN(Number(value))) return `Expected a number, got "${value}"`;
+			return null;
+		case "Date": {
+			const d = new Date(value);
+			if (isNaN(d.getTime())) return `Expected an ISO 8601 date, got "${value}"`;
+			return null;
+		}
+		case "Boolean":
+			if (value !== "true" && value !== "false") return `Expected "true" or "false", got "${value}"`;
+			return null;
+		case "Select": {
+			const options = def.options ?? [];
+			if (!options.includes(value)) return `"${value}" is not a valid option. Allowed: ${options.join(", ")}`;
+			return null;
+		}
+		case "MultiSelect": {
+			const options = def.options ?? [];
+			const invalid = value.split(",").map((s) => s.trim()).filter((s) => !options.includes(s));
+			if (invalid.length > 0) return `Invalid option(s): ${invalid.join(", ")}. Allowed: ${options.join(", ")}`;
+			return null;
+		}
+		default: return null;
+	}
+}
+//#endregion
 //#region ../mcp-core/src/server.ts
 function registerWriteTool(server, ctx, name, config, cb) {
 	if (!ctx.writesEnabled) return;
@@ -2497,7 +2693,16 @@ async function buildServer(config) {
 	const instructions = await buildInstructions(api, config.context.writesEnabled);
 	const server = new McpServer({
 		name: config.serverName,
-		version: config.serverVersion
+		version: config.serverVersion,
+		icons: [{
+			src: "https://sodiumhq.com/assets/logo-no-text.png",
+			mimeType: "image/png",
+			theme: "light"
+		}, {
+			src: "https://sodiumhq.com/assets/logo-no-text-darkbg.png",
+			mimeType: "image/png",
+			theme: "dark"
+		}]
 	}, {
 		instructions,
 		capabilities: { tools: {} }
@@ -2531,7 +2736,7 @@ async function buildServer(config) {
 	}, (args) => handleListClients(api, args));
 	server.registerTool("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), 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?' 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. 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.",
 		inputSchema: GetClientSummaryInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -2651,6 +2856,17 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleAddClientNote(api, args));
+	registerWriteTool(server, config.context, "update_client_custom_fields", {
+		title: "Update custom field values on a client",
+		description: "Set or clear custom field values on a client. Accepts a map of field codes to values. Only fields included in the map are updated — omitted fields keep their current values. Pass null to clear a field. Field codes and current values are visible in the Custom Fields section of get_client_summary. Values are validated against the field's data type (Text, Number, Date, Boolean, Select, MultiSelect) before sending — invalid values return a validation error with guidance. Use this when the user says things like 'set the referral source on ACME to Google', 'update the fee review date for Smith & Co', 'clear the VAT scheme field on Greggs'. Multiple fields can be updated in a single call.",
+		inputSchema: SetClientCustomFieldsInputSchema,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleSetClientCustomFields(api, args));
 	return server;
 }
 //#endregion

package/package.json

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