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

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

@@ -777,6 +777,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 +845,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.
@@ -1383,6 +1451,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 +1487,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})`;
@@ -2630,6 +2749,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 +2821,121 @@ 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/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 +3071,16 @@ 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_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 +3171,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.",
@@ -2953,6 +3214,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.2767",
   "description": "Sodium Practice Management MCP server — lets AI assistants interact with your Sodium tenant",
   "type": "module",
   "bin": {