@sodiumhq/mcp-pm 0.1.0-beta.2765 → 0.1.0-beta.2771

package/README.md

@@ -65,6 +65,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) + **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
+- **`get_custom_field_details`** — get the full definition of a custom field by code, including allowed options for Select/MultiSelect fields. Use before setting a dropdown field to discover valid values.
 
 **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?"
@@ -78,6 +79,9 @@ Only enable write mode with an AI client you trust — it hands the client the a
 - **`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?"
 - **`get_service_details`** — drill into one service: identity + applicable client types + HMRC agent authorisations + pricing options per billing frequency + custom tiers + professional clearance items + pricing-factor overview. Enables service-audit workflows like "is Self Assessment correctly restricted to Individual clients?"
 
+**Contacts**
+- **`list_contacts`** — search and filter contacts across the practice by name, email, phone, or client. Answers "find John Smith", "who are the contacts for ACME?", "search for jane@example.com".
+
 **Team**
 - **`list_users`** — find team members by name, email, role, or status — supports "who is Jane?", "list all partners", "who has been invited but not joined?"
 
@@ -85,6 +89,7 @@ Only enable write mode with an AI client you trust — it hands the client the a
 - **`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`.
+- **`update_contact`** — update a contact's details: name, email, phone, mobile, date of birth, UTR, NI number, address. Requires the contact code (discoverable via `list_contacts`).
 
 More tools land iteratively as the beta progresses.
 

package/dist/index.js

@@ -441,7 +441,7 @@ const createConfig = (override = {}) => ({
 });
 //#endregion
 //#region ../mcp-core/src/generated/client/client.gen.ts
-const createClient = (config = {}) => {
+const createClient$1 = (config = {}) => {
 	let _config = mergeConfigs(createConfig(), config);
 	const getConfig = () => ({ ..._config });
 	const setConfig = (config) => {
@@ -620,7 +620,7 @@ const createClient = (config = {}) => {
 };
 //#endregion
 //#region ../mcp-core/src/generated/client.gen.ts
-const client = createClient(createConfig());
+const client = createClient$1(createConfig());
 //#endregion
 //#region ../mcp-core/src/generated/sdk.gen.ts
 /**
@@ -706,6 +706,22 @@ const getClientDates = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* List Notes for Client
+*
+* Lists all Notes for the specified client.
+*/
+const listClientNotesForClient = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/clients/{client}/clientnote",
+	...options
+});
+/**
 * Create Note for Client
 *
 * Creates a new Note for the specified client.
@@ -761,6 +777,26 @@ const listClients = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Create Client
+*
+* Creates a new Client for the specified tenant.
+*/
+const createClient = (options) => (options.client ?? client).post({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/clients",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
 * Get Client
 *
 * Gets a Client for the specified tenant.
@@ -777,6 +813,58 @@ const getClient = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* List Contacts
+*
+* Lists all Contacts for the given tenant.
+*/
+const listContacts = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/contacts",
+	...options
+});
+/**
+* Get Contact
+*
+* Gets a Contact for the specified tenant.
+*/
+const getContact = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/contacts/{code}",
+	...options
+});
+/**
+* Update Contact
+*
+* Updates a Contact for the specified tenant.
+*/
+const updateContact = (options) => (options.client ?? client).put({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/contacts/{code}",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
 * List CustomFieldDefinitions
 *
 * Lists all CustomFieldDefinitions for the given tenant.
@@ -793,6 +881,22 @@ const listCustomFieldDefinitions = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get CustomFieldDefinition
+*
+* Gets a CustomFieldDefinition for the specified tenant.
+*/
+const getCustomFieldDefinition = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/custom-fields/{code}",
+	...options
+});
+/**
 * List Engagements
 *
 * Lists all Engagements for the given tenant.
@@ -1369,6 +1473,33 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `add note to client ${clientCode}`);
 		return data;
 	}
+	async createClient(body) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await createClient({
+			path: { tenant: this.ctx.tenant },
+			body,
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, "create client");
+		return data;
+	}
+	async listClientNotes(clientCode, query = {}) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await listClientNotesForClient({
+			path: {
+				tenant: this.ctx.tenant,
+				client: clientCode
+			},
+			query: {
+				...query,
+				limit: query.limit ?? 10,
+				offset: query.offset ?? 0
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `list notes for client ${clientCode}`);
+		return data;
+	}
 	async listCustomFieldDefinitions(query = {}) {
 		const correlationId = randomUUID();
 		const { data, error, response } = await listCustomFieldDefinitions({
@@ -1383,6 +1514,18 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, "list custom field definitions");
 		return data;
 	}
+	async getCustomFieldDefinition(code) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await getCustomFieldDefinition({
+			path: {
+				tenant: this.ctx.tenant,
+				code
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `get custom field definition ${code}`);
+		return data;
+	}
 	async getClientCustomFieldValues(clientCode) {
 		const correlationId = randomUUID();
 		const { data, error, response } = await getClientCustomFieldValues({
@@ -1407,6 +1550,45 @@ var SodiumApiClient = class {
 		});
 		if (error !== void 0) throw this.toError(response, error, correlationId, `set custom field values for client ${clientCode}`);
 	}
+	async listContacts(query = {}) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await listContacts({
+			path: { tenant: this.ctx.tenant },
+			query: {
+				...query,
+				limit: query.limit ?? 10,
+				offset: query.offset ?? 0
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, "list contacts");
+		return data;
+	}
+	async getContact(code) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await getContact({
+			path: {
+				tenant: this.ctx.tenant,
+				code
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `get contact ${code}`);
+		return data;
+	}
+	async updateContact(code, body) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await updateContact({
+			path: {
+				tenant: this.ctx.tenant,
+				code
+			},
+			body,
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `update contact ${code}`);
+		return data;
+	}
 	toError(response, error, correlationId, operation) {
 		const status = response.status;
 		let message = `Failed to ${operation} (HTTP ${status})`;
@@ -2075,7 +2257,7 @@ function format(input) {
 			return (b.date ?? b.createdDate ?? "").localeCompare(da);
 		});
 		lines.push("", `--- Notes (${notes.length}) ---`);
-		for (const note of sorted.slice(0, 20)) lines.push(formatNote(note));
+		for (const note of sorted.slice(0, 20)) lines.push(formatNote$1(note));
 		if (notes.length > 20) lines.push(`... and ${notes.length - 20} more notes`);
 	}
 	const clients = task.clients ?? [];
@@ -2100,7 +2282,7 @@ function formatStep(step) {
 	if (step.blockedReason) bits.push(`blocked: ${step.blockedReason}`);
 	return `Step ${num}: ${name}${bits.length > 0 ? ` — ${bits.join(" · ")}` : ""}`;
 }
-function formatNote(note) {
+function formatNote$1(note) {
 	const pinPrefix = (note.pinnedLevel ?? 0) > 0 ? "[pinned] " : "";
 	const dateStr = note.date ?? note.createdDate ?? "";
 	const author = note.noteFromUser?.name ?? "(unknown)";
@@ -2250,7 +2432,7 @@ const categoryEnum = z.enum([
 	"Advisory",
 	"SoftwareAndTraining"
 ]);
-const clientTypeEnum = z.enum([
+const clientTypeEnum$1 = z.enum([
 	"PrivateLimitedCompany",
 	"PublicLimitedCompany",
 	"LimitedLiabilityPartnership",
@@ -2268,7 +2450,7 @@ const sortByEnum$2 = z.enum([
 const ListServicesInputSchema = {
 	search: z.string().min(3, "Search must be at least 3 characters when provided").optional().describe("Free-text search across service code and name. Minimum 3 characters. Use for 'find our VAT services' or 'does the practice have a bookkeeping service?' when the exact code isn't known."),
 	category: categoryEnum.optional().describe("Filter by service category. Use 'Tax' for 'all tax services', 'Payroll' for payroll, 'CoreAccounting' for year-end / accounts / bookkeeping, 'CompanySecretarial' for confirmation statements / registered office, 'Advisory' for consulting / planning, 'SoftwareAndTraining' for software setup / training. Single value — to see multiple categories, call once per category or omit to see all."),
-	clientType: clientTypeEnum.optional().describe("Filter by the client type the service applies to. Use for service-audit questions like 'which services do we offer to individuals?' or 'what do we offer private limited companies?'. Returns services configured for that client type plus any service with no client-type restriction (those apply to everyone)."),
+	clientType: clientTypeEnum$1.optional().describe("Filter by the client type the service applies to. Use for service-audit questions like 'which services do we offer to individuals?' or 'what do we offer private limited companies?'. Returns services configured for that client type plus any service with no client-type restriction (those apply to everyone)."),
 	isArchived: z.boolean().optional().describe("Filter by archived status. Omit (default) to return everything; pass false for active services only; pass true for the archive. Most practice-manager questions ('what do we offer?') want isArchived=false."),
 	sortBy: sortByEnum$2.optional().describe("Field to sort by. Defaults to Name. Use 'Category' to group the output by category, 'AccountingCode' when reconciling against a chart of accounts."),
 	sortDesc: z.boolean().optional().describe("Sort in descending order. Defaults to ascending."),
@@ -2630,6 +2812,13 @@ async function handleSetClientCustomFields(api, args) {
 		});
 		const defMap = /* @__PURE__ */ new Map();
 		for (const d of definitions.data ?? []) if (d.code) defMap.set(d.code, d);
+		const selectFields = entries.filter(([code, val]) => val !== null && val !== "" && (defMap.get(code)?.dataType === "Select" || defMap.get(code)?.dataType === "MultiSelect"));
+		await Promise.all(selectFields.map(async ([code]) => {
+			try {
+				const full = await api.getCustomFieldDefinition(code);
+				defMap.set(code, full);
+			} catch {}
+		}));
 		const errors = [];
 		for (const [fieldCode, value] of entries) {
 			const def = defMap.get(fieldCode);
@@ -2695,6 +2884,217 @@ function validateFieldValue(def, value) {
 	}
 }
 //#endregion
+//#region ../mcp-core/src/tools/get-custom-field-details.ts
+const GetCustomFieldDetailsInputSchema = { fieldCode: z.string().min(1, "Field code is required").describe("The custom field definition code. Discoverable via the Custom Fields section of get_client_summary.") };
+async function handleGetCustomFieldDetails(api, args) {
+	try {
+		const def = await api.getCustomFieldDefinition(args.fieldCode);
+		const lines = [];
+		lines.push(`Custom Field: ${def.label ?? "(no label)"} (${def.code ?? args.fieldCode})`);
+		lines.push(`Data type: ${def.dataType ?? "(unknown)"}`);
+		lines.push(`Entity type: ${def.entityType ?? "(unknown)"}`);
+		lines.push(`Archived: ${def.isArchived ? "yes" : "no"}`);
+		if (def.sortOrder !== void 0) lines.push(`Sort order: ${def.sortOrder}`);
+		if (def.clientTypes && def.clientTypes.length > 0) lines.push(`Applicable client types: ${def.clientTypes.join(", ")}`);
+		else lines.push("Applicable client types: all");
+		if (def.options && def.options.length > 0) {
+			lines.push("", `Allowed options (${def.options.length}):`);
+			for (const opt of def.options) lines.push(`- ${opt}`);
+		} else if (def.dataType === "Select" || def.dataType === "MultiSelect") lines.push("", "Allowed options: (none configured)");
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error getting custom field definition: ${error.message} (correlation: ${error.correlationId})` : `Error getting custom field definition: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+//#endregion
+//#region ../mcp-core/src/tools/create-client.ts
+const clientTypeEnum = z.enum([
+	"PrivateLimitedCompany",
+	"PublicLimitedCompany",
+	"LimitedLiabilityPartnership",
+	"Partnership",
+	"Individual",
+	"Trust",
+	"Charity",
+	"SoleTrader"
+]);
+const clientStatusEnum = z.enum([
+	"Active",
+	"Inactive",
+	"Prospect",
+	"LostProspect"
+]);
+const CreateClientInputSchema = {
+	name: z.string().min(1, "Client name is required").describe("The name of the client (e.g. 'ACME Ltd', 'John Smith')."),
+	type: clientTypeEnum.describe("The client type. Determines which services and custom fields are applicable. Common types: PrivateLimitedCompany (most UK companies), Individual (sole traders' personal tax), SoleTrader (unincorporated businesses), Partnership, LimitedLiabilityPartnership."),
+	status: clientStatusEnum.optional().describe("Client status (default: Active). Use Prospect for leads not yet onboarded."),
+	email: z.string().nullable().optional().describe("Client email address."),
+	telephone: z.string().nullable().optional().describe("Client telephone number."),
+	internalReference: z.string().nullable().optional().describe("Internal reference number/code for the client."),
+	managerCode: z.string().nullable().optional().describe("Code of the user who will manage this client. Discoverable via list_users or the team roster in the startup context."),
+	partnerCode: z.string().nullable().optional().describe("Code of the partner user for this client."),
+	associateCode: z.string().nullable().optional().describe("Code of the associate user for this client."),
+	teamCode: z.string().nullable().optional().describe("Code of the team to assign to this client.")
+};
+async function handleCreateClient(api, args) {
+	try {
+		const created = await api.createClient(args);
+		const lines = [
+			`Created client: ${created.name} (${created.code ?? "(no code)"})`,
+			`Type: ${created.type ?? args.type}`,
+			`Status: ${created.status ?? "Active"}`
+		];
+		if (created.email) lines.push(`Email: ${created.email}`);
+		if (created.manager) lines.push(`Manager: ${created.manager.name} (${created.manager.code})`);
+		if (created.partner) lines.push(`Partner: ${created.partner.name} (${created.partner.code})`);
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error creating client: ${error.message} (correlation: ${error.correlationId})` : `Error creating client: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+//#endregion
+//#region ../mcp-core/src/tools/list-client-notes.ts
+const sortFieldEnum$1 = z.enum(["Date", "UpdatedDate"]);
+const ListClientNotesInputSchema = {
+	clientCode: z.string().min(1, "Client code is required").describe("The client code whose notes to list. Discoverable via list_clients or get_client_summary."),
+	search: z.string().min(3, "Search must be at least 3 characters when provided").optional().describe("Search across note text. Minimum 3 characters."),
+	authorCode: z.string().optional().describe("Filter by the user who wrote the note. Use the current user's code for 'my notes on ACME', or another user's code for 'what has Jane noted about this client?'."),
+	sortBy: sortFieldEnum$1.optional().describe("Sort by Date (note date) or UpdatedDate. Default: Date descending (newest first)."),
+	sortDesc: z.boolean().optional().describe("Sort descending (default: true for newest first)."),
+	limit: z.number().int().min(0).max(50).optional().describe("Max results to return (default: 10, max: 50)."),
+	offset: z.number().int().min(0).optional().describe("Number of records to skip for pagination.")
+};
+async function handleListClientNotes(api, args) {
+	try {
+		const { clientCode, ...query } = args;
+		const result = await api.listClientNotes(clientCode, query);
+		const notes = result.data ?? [];
+		const total = result.totalCount ?? notes.length;
+		if (notes.length === 0) return { content: [{
+			type: "text",
+			text: total === 0 ? `No notes found for client ${clientCode}.` : `${total} note(s) found, but none in this page (offset ${result.offset}).`
+		}] };
+		const lines = [`Notes for ${clientCode}: ${notes.length} of ${total}${result.hasMore ? " (more available)" : ""}`, ""];
+		for (const n of notes) lines.push(formatNote(n));
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error listing client notes: ${error.message} (correlation: ${error.correlationId})` : `Error listing client notes: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+function formatNote(n) {
+	return `- [${n.code ?? "(no code)"}] ${n.date ? n.date.slice(0, 10) : "(no date)"} by ${n.noteFromUser?.name ?? "(unknown)"}${n.pinnedLevel && n.pinnedLevel > 0 ? " [pinned]" : ""}: ${n.text ? n.text.length > 200 ? n.text.slice(0, 200) + "..." : n.text : "(empty)"}`;
+}
+//#endregion
+//#region ../mcp-core/src/tools/list-contacts.ts
+const sortFieldEnum = z.enum([
+	"Name",
+	"FirstName",
+	"LastName",
+	"ClientCount"
+]);
+const ListContactsInputSchema = {
+	search: z.string().min(3, "Search must be at least 3 characters when provided").optional().describe("Free-text search across contact code, name, email, and phone. Minimum 3 characters. Use for 'find John', 'who is jane@example.com', 'search for Smith'."),
+	clientCode: z.string().optional().describe("Filter to contacts linked to a specific client. Use when the user asks 'who are the contacts for ACME?' or 'list contacts on client CLI001'."),
+	sortBy: sortFieldEnum.optional().describe("Field to sort results by."),
+	sortDesc: z.boolean().optional().describe("Sort in descending order (default: ascending)."),
+	limit: z.number().int().min(0).max(50).optional().describe("Max results to return (default: 10, max: 50). Use limit=0 for count-only."),
+	offset: z.number().int().min(0).optional().describe("Number of records to skip for pagination.")
+};
+async function handleListContacts(api, args) {
+	try {
+		const result = await api.listContacts(args);
+		const contacts = result.data ?? [];
+		const total = result.totalCount ?? contacts.length;
+		if (contacts.length === 0) return { content: [{
+			type: "text",
+			text: total === 0 ? "No contacts found matching the criteria." : `${total} contact(s) found, but none in this page (offset ${result.offset}).`
+		}] };
+		const lines = [`Contacts: ${contacts.length} of ${total}${result.hasMore ? " (more available)" : ""}`, ""];
+		for (const c of contacts) lines.push(formatContact(c));
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error listing contacts: ${error.message} (correlation: ${error.correlationId})` : `Error listing contacts: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+function formatContact(c) {
+	const code = c.code ?? "(no code)";
+	return `- ${[c.firstName, c.lastName].filter(Boolean).join(" ") || "(no name)"} (${code})${c.email ? ` <${c.email}>` : ""}${c.phone || c.mobile ? ` | ${c.phone || c.mobile}` : ""}`;
+}
+//#endregion
+//#region ../mcp-core/src/tools/update-contact.ts
+const UpdateContactInputSchema = {
+	contactCode: z.string().min(1, "Contact code is required").describe("The contact code (identifier). Discoverable via list_contacts or the contacts section of get_client_summary."),
+	lastName: z.string().min(1).describe("The contact's last name (required by the API even if unchanged)."),
+	title: z.string().nullable().optional().describe("Title (e.g. Mr, Mrs, Dr). Pass null to clear."),
+	firstName: z.string().nullable().optional().describe("First name. Pass null to clear."),
+	middleName: z.string().nullable().optional().describe("Middle name. Pass null to clear."),
+	email: z.string().nullable().optional().describe("Email address. Pass null to clear."),
+	phone: z.string().nullable().optional().describe("Landline phone number. Pass null to clear."),
+	mobile: z.string().nullable().optional().describe("Mobile phone number. Pass null to clear."),
+	dateOfBirth: z.string().nullable().optional().describe("Date of birth in ISO 8601 format (e.g. '1985-03-15'). Pass null to clear."),
+	utr: z.string().nullable().optional().describe("Self Assessment UTR. Pass null to clear."),
+	niNumber: z.string().nullable().optional().describe("National Insurance Number. Pass null to clear."),
+	address: z.string().nullable().optional().describe("Contact address (only for Individual client type contacts). Pass null to clear.")
+};
+async function handleUpdateContact(api, args) {
+	try {
+		const { contactCode, ...body } = args;
+		const updated = await api.updateContact(contactCode, body);
+		const lines = [`Updated contact: ${[updated.firstName, updated.lastName].filter(Boolean).join(" ") || "(no name)"} (${updated.code ?? contactCode})`];
+		if (updated.email) lines.push(`Email: ${updated.email}`);
+		if (updated.phone) lines.push(`Phone: ${updated.phone}`);
+		if (updated.mobile) lines.push(`Mobile: ${updated.mobile}`);
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error updating contact: ${error.message} (correlation: ${error.correlationId})` : `Error updating contact: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+//#endregion
 //#region ../mcp-core/src/tools/whoami.ts
 async function handleWhoami(api) {
 	try {
@@ -2830,6 +3230,26 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleGetClientSummary(api, args));
+	server.registerTool("get_custom_field_details", {
+		title: "Get full details of a custom field definition",
+		description: "Get the full definition of a single custom field by code, including allowed options for Select and MultiSelect fields. The list endpoint and get_client_summary show field codes, labels, and data types but omit the allowed options — use this tool when you need to know the valid values before setting a Select or MultiSelect field via update_client_custom_fields. Also shows applicable client types and archived status.",
+		inputSchema: GetCustomFieldDetailsInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleGetCustomFieldDetails(api, args));
+	server.registerTool("list_client_notes", {
+		title: "List / search notes on a client",
+		description: "List notes attached to a client, with optional search and author filter. Answers 'show me the notes on ACME', 'what has Jane noted about this client?', 'search notes for VAT'. Notes are returned newest first by default. Each note shows its code, date, author, pinned status, and text (truncated to 200 chars).",
+		inputSchema: ListClientNotesInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleListClientNotes(api, args));
 	server.registerTool("list_tasks", {
 		title: "List / filter tasks across the practice",
 		description: "List tasks with any combination of filters: assigned user(s), client(s), status, overdue flag, preset date range (Today / ThisWeek / Next7Days / CustomDateRange etc), category, team, recurring task template, 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. 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.",
@@ -2920,6 +3340,16 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListUsers(api, args));
+	server.registerTool("list_contacts", {
+		title: "List / search contacts across the practice",
+		description: "Find contacts by free-text search (name, email, phone, code — minimum 3 characters) or filter to contacts linked to a specific client. Answers 'find John Smith', 'who are the contacts for ACME?', 'search for jane@example.com', 'how many contacts do we have?'. Supports pagination and sorting by Name, FirstName, LastName, or ClientCount.",
+		inputSchema: ListContactsInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleListContacts(api, args));
 	registerWriteTool(server, config.context, "add_task_note", {
 		title: "Add a note to a task",
 		description: "Create a new note on a task. Additive — does not modify or delete existing notes. The note is attributed to the authenticated API user (the current practice member) and timestamped to 'now'. Use this when the user asks you to capture something on a task: 'add a note on the Greggs year-end task that we're waiting on the rental schedule', 'log on the task that I called John today and got voicemail'. Notes can be pinned; only pin when the user explicitly asks for it. The user can always edit or delete notes in the Sodium UI if the wording isn't right.",
@@ -2931,6 +3361,17 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleAddTaskNote(api, args));
+	registerWriteTool(server, config.context, "create_client", {
+		title: "Create a new client",
+		description: "Create a new client record in the practice. Requires name and type (PrivateLimitedCompany, Individual, SoleTrader, etc.). Optionally set status (Active/Prospect/Inactive/LostProspect), email, telephone, internal reference, and assign a manager/partner/associate/team. The client code is auto-generated. Use when the user says 'add a new client', 'create client ACME Ltd', 'onboard a new prospect'.",
+		inputSchema: CreateClientInputSchema,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: true
+		}
+	}, (args) => handleCreateClient(api, args));
 	registerWriteTool(server, config.context, "add_client_note", {
 		title: "Add a note to a client",
 		description: "Create a new note on a client. Additive — does not modify or delete existing notes. The note is attributed to the authenticated API user and timestamped to 'now'. Use this when the user asks you to capture something on a client record: 'add a note on ACME that they mentioned expanding into Ireland', 'log on Greggs that they're switching bookkeeping software next quarter'. Client notes are the right place for persistent, client-level context; for task-specific notes use add_task_note. The user can edit or delete notes in the Sodium UI.",
@@ -2953,6 +3394,17 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleSetClientCustomFields(api, args));
+	registerWriteTool(server, config.context, "update_contact", {
+		title: "Update a contact's details",
+		description: "Update fields on an existing contact: name, email, phone, mobile, date of birth, UTR, NI number, address. The contact's lastName is always required (even if unchanged). Only include fields you want to change — but note the API replaces the entire contact record, so omitted optional fields may be cleared. To be safe, fetch the contact via list_contacts first, then pass all current values plus your changes. Use when the user says things like 'update John's email to ...', 'change the phone number for contact CON-001', 'set Jane's date of birth to ...'.",
+		inputSchema: UpdateContactInputSchema,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleUpdateContact(api, args));
 	return server;
 }
 //#endregion

package/package.json

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