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

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.
@@ -1437,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({
@@ -2194,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 ?? [];
@@ -2219,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)";
@@ -2369,7 +2432,7 @@ const categoryEnum = z.enum([
 	"Advisory",
 	"SoftwareAndTraining"
 ]);
-const clientTypeEnum = z.enum([
+const clientTypeEnum$1 = z.enum([
 	"PrivateLimitedCompany",
 	"PublicLimitedCompany",
 	"LimitedLiabilityPartnership",
@@ -2387,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."),
@@ -2853,6 +2916,145 @@ async function handleGetCustomFieldDetails(api, args) {
 	}
 }
 //#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/get-contact.ts
+const GetContactInputSchema = { 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.") };
+async function handleGetContact(api, args) {
+	try {
+		const c = await api.getContact(args.contactCode);
+		const lines = [];
+		const name = [
+			c.title,
+			c.firstName,
+			c.middleName,
+			c.lastName
+		].filter(Boolean).join(" ") || "(no name)";
+		lines.push(`Contact: ${name} (${c.code ?? args.contactCode})`);
+		if (c.email) lines.push(`Email: ${c.email}`);
+		if (c.phone) lines.push(`Phone: ${c.phone}`);
+		if (c.mobile) lines.push(`Mobile: ${c.mobile}`);
+		if (c.address) lines.push(`Address: ${c.address}`);
+		if (c.dateOfBirth) lines.push(`Date of birth: ${c.dateOfBirth}`);
+		if (c.nationality) lines.push(`Nationality: ${c.nationality}`);
+		if (c.maritalStatus) lines.push(`Marital status: ${c.maritalStatus}`);
+		if (c.utr) lines.push(`UTR: ${c.utr}`);
+		if (c.niNumber) lines.push(`NI number: ${c.niNumber}`);
+		if (c.personalCode) lines.push(`Companies House person code: ${c.personalCode}`);
+		if (c.isDeceased) lines.push(`Deceased: yes${c.deceasedDate ? ` (${c.deceasedDate})` : ""}`);
+		if (c.clientCount !== void 0) lines.push(`Linked to ${c.clientCount} client(s)`);
+		if (c.client) lines.push(`Primary client: ${c.client.name} (${c.client.code})`);
+		if (c.individualClient) lines.push(`Individual client record: ${c.individualClient.name} (${c.individualClient.code})`);
+		if (c.portalUser) lines.push(`Portal user: ${c.portalUser.name} (${c.portalUser.code})`);
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error getting contact: ${error.message} (correlation: ${error.correlationId})` : `Error getting contact: ${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",
@@ -3081,6 +3283,16 @@ async function buildServer(config) {
 			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.",
@@ -3181,6 +3393,16 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListContacts(api, args));
+	server.registerTool("get_contact", {
+		title: "Get full details of a contact",
+		description: "Get all fields for a single contact by code: name, title, email, phone, mobile, address, date of birth, nationality, marital status, UTR, NI number, Companies House person code, deceased status, linked clients, and portal user. Use after list_contacts identifies the contact of interest, or when the user asks for details about a specific contact. Also useful before update_contact to see current values.",
+		inputSchema: GetContactInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleGetContact(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.",
@@ -3192,6 +3414,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.",

package/package.json

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