@sodiumhq/mcp-pm 0.1.0-beta.2600 → 0.1.0-beta.2611

package/README.md

@@ -48,6 +48,13 @@ Then ask: *"give me a summary of my practice"*.
 | `SODIUM_API_KEY` | yes | — | Your Sodium API key |
 | `SODIUM_TENANT` | yes | — | Your tenant code |
 | `SODIUM_API_URL` | no | `https://api.sodiumhq.com` | Override for staging/dev |
+| `SODIUM_ENABLE_WRITES` | no | `false` | Set to `true` or `1` to allow write tools (equivalent to `--enable-writes`) |
+
+## Write mode
+
+Write tools are **off by default** — the server exposes only read tools unless you opt in. Enable writes by adding `--enable-writes` to `args`, or by setting `SODIUM_ENABLE_WRITES=true` (or `1`) in `env`. Destructive and bulk operations (delete, batch) stay blocked either way.
+
+Only enable write mode with an AI client you trust — it hands the client the ability to modify data under your API key. To check whether writes are on, ask your AI assistant *"can you make changes to my Sodium data?"* — it will tell you.
 
 ## What it can do today
 
@@ -66,15 +73,23 @@ Then ask: *"give me a summary of my practice"*.
 - **`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
 
+**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?"
+- **`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?"
+
 **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?"
 
+**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.
+
 More tools land iteratively as the beta progresses.
 
 ## Requirements
 
 - Node.js 20 or later
-- An active Sodium Practice Management subscription at the Pro tier
+- An active Sodium Practice Management subscription
 - API key and tenant code from your Sodium account
 
 ## Licence

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { parseArgs } from "node:util";
 //#region ../mcp-core/src/generated/core/bodySerializer.gen.ts
 const jsonBodySerializer = { bodySerializer: (body) => JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value) };
 Object.entries({
@@ -669,6 +670,26 @@ const getClientDates = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Create Note for Client
+*
+* Creates a new Note for the specified client.
+*/
+const createClientNoteForClient = (options) => (options.client ?? client).post({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/clients/{client}/clientnote",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
 * List Client Services for Client
 *
 * Lists all Client Services for the specified client.
@@ -787,6 +808,38 @@ const getPracticeDetails = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* List BillableServices
+*
+* Lists all BillableServices for the given tenant.
+*/
+const listBillableServices = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/services",
+	...options
+});
+/**
+* Get BillableService
+*
+* Gets a BillableService for the specified tenant.
+*/
+const getBillableService = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/services/{code}",
+	...options
+});
+/**
 * List Notes for Task
 *
 * Lists notes for the specified task. By default only returns task-level notes. Set includeStepNotes=true to also include notes attached to workflow steps.
@@ -803,6 +856,26 @@ const listTaskItemNotes = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Create Note
+*
+* Creates a new note for the specified task.
+*/
+const createTaskItemNote = (options) => (options.client ?? client).post({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/tasks/{taskCode}/taskitemnote",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
 * Get Task Workflow Groups
 *
 * Retrieves comprehensive workflow progress information for a TaskItem.
@@ -1099,6 +1172,32 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, "list users");
 		return data;
 	}
+	async listServices(query = {}) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await listBillableServices({
+			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 services");
+		return data;
+	}
+	async getService(code) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await getBillableService({
+			path: {
+				tenant: this.ctx.tenant,
+				code
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `get service ${code}`);
+		return data;
+	}
 	async listTasks(query = {}) {
 		const correlationId = randomUUID();
 		const { data, error, response } = await listTaskItems({
@@ -1192,6 +1291,32 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `get workflow groups for task ${taskCode}`);
 		return data;
 	}
+	async createTaskNote(taskCode, body) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await createTaskItemNote({
+			path: {
+				tenant: this.ctx.tenant,
+				taskCode
+			},
+			body,
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `add note to task ${taskCode}`);
+		return data;
+	}
+	async createClientNote(clientCode, body) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await createClientNoteForClient({
+			path: {
+				tenant: this.ctx.tenant,
+				client: clientCode
+			},
+			body,
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `add note to client ${clientCode}`);
+		return data;
+	}
 	toError(response, error, correlationId, operation) {
 		const status = response.status;
 		let message = `Failed to ${operation} (HTTP ${status})`;
@@ -1203,7 +1328,7 @@ var SodiumApiClient = class {
 //#endregion
 //#region ../mcp-core/src/context/instructions.ts
 const ROSTER_CAP = 20;
-async function buildInstructions(api) {
+async function buildInstructions(api, writesEnabled) {
 	const [user, tenant, practice, team] = await Promise.allSettled([
 		api.getCurrentUser(),
 		api.getTenantDetails(),
@@ -1237,6 +1362,7 @@ async function buildInstructions(api) {
 	}
 	if (tenant.status === "fulfilled") lines.push(`Tenant: ${tenant.value.name} (${tenant.value.code})`);
 	if (practice.status === "fulfilled") lines.push(`Practice: ${practice.value.name}`);
+	lines.push("", writesEnabled ? "Write mode: ENABLED. Create/update tools are available; destructive and bulk operations are not." : "Write mode: DISABLED. Read-only — tell the user to relaunch with --enable-writes if they want changes made.");
 	if (team.status === "fulfilled") {
 		const members = team.value.data ?? [];
 		const total = team.value.totalCount ?? members.length;
@@ -1255,7 +1381,7 @@ async function buildInstructions(api) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/get-practice-details.ts
-function format$3(tenant, practice) {
+function format$4(tenant, practice) {
 	const lines = [];
 	lines.push(`Practice: ${practice.name}`);
 	lines.push(`Tenant: ${tenant.name} (${tenant.code})`);
@@ -1289,7 +1415,7 @@ async function handleGetPracticeDetails(api) {
 		const [tenant, practice] = await Promise.all([api.getTenantDetails(), api.getPracticeDetails()]);
 		return { content: [{
 			type: "text",
-			text: format$3(tenant, practice)
+			text: format$4(tenant, practice)
 		}] };
 	} catch (error) {
 		return {
@@ -1319,7 +1445,7 @@ const typeEnum = z.enum([
 	"Charity",
 	"SoleTrader"
 ]);
-const sortByEnum$2 = z.enum(["Name", "InternalReference"]);
+const sortByEnum$3 = z.enum(["Name", "InternalReference"]);
 const ListClientsInputSchema = {
 	search: z.string().min(3, "Search must be at least 3 characters when provided").optional().describe("Free-text search across client code, name, and internal reference. Minimum 3 characters. Omit to browse by filter only."),
 	status: z.array(statusEnum$2).optional().describe("Filter by client status. Defaults to all statuses if omitted. Example: ['Active'] for active clients only."),
@@ -1329,7 +1455,7 @@ const ListClientsInputSchema = {
 	associateCode: z.array(z.string()).optional().describe("Filter by assigned associate user codes."),
 	serviceCode: z.array(z.string()).optional().describe("Filter by billable service codes that clients have assigned."),
 	savedFilter: z.string().optional().describe("Code of a user-saved filter to apply. Other filter parameters override fields from the saved filter."),
-	sortBy: sortByEnum$2.optional().describe("Field to sort by. Defaults to Name."),
+	sortBy: sortByEnum$3.optional().describe("Field to sort by. Defaults to Name."),
 	sortDesc: z.boolean().optional().describe("Sort in descending order. Defaults to ascending."),
 	limit: z.number().int().min(0).max(50).optional().describe("Maximum number of clients to return per page. Default 10, max 50. Pass 0 to return only the total count without any client data — use this for 'how many X?' questions so the API doesn't fetch a full page just to be counted."),
 	offset: z.number().int().min(0).optional().describe("Number of records to skip for pagination. Default 0.")
@@ -1347,20 +1473,20 @@ async function handleListClients(api, args) {
 		const items = result.data ?? [];
 		const total = result.totalCount ?? items.length;
 		if (args.limit === 0) {
-			const desc = describeFilters$3(args);
+			const desc = describeFilters$4(args);
 			return { content: [{
 				type: "text",
 				text: desc ? `Total: ${total} client${total === 1 ? "" : "s"} matching ${desc}.` : `Total: ${total} client${total === 1 ? "" : "s"}.`
 			}] };
 		}
 		if (items.length === 0) {
-			const desc = describeFilters$3(args);
+			const desc = describeFilters$4(args);
 			return { content: [{
 				type: "text",
 				text: desc ? `No clients match ${desc}.` : "No clients found."
 			}] };
 		}
-		const desc = describeFilters$3(args);
+		const desc = describeFilters$4(args);
 		const lines = [
 			desc ? total > items.length ? `Found ${total} clients matching ${desc} (showing ${items.length}):` : `Found ${items.length} client${items.length === 1 ? "" : "s"} matching ${desc}:` : total > items.length ? `Showing ${items.length} of ${total} clients:` : `${items.length} client${items.length === 1 ? "" : "s"}:`,
 			"",
@@ -1384,7 +1510,7 @@ async function handleListClients(api, args) {
 		};
 	}
 }
-function describeFilters$3(args) {
+function describeFilters$4(args) {
 	const parts = [];
 	if (args.search) parts.push(`search "${args.search}"`);
 	if (args.status?.length) parts.push(`status ${args.status.join("/")}`);
@@ -1430,7 +1556,7 @@ async function handleGetClientSummary(api, { code }) {
 	}
 	return { content: [{
 		type: "text",
-		text: format$2({
+		text: format$3({
 			client: clientResult.value,
 			contacts: extract(contactsResult),
 			services: extract(servicesResult),
@@ -1453,7 +1579,7 @@ function extract(result) {
 	if (result.status !== "fulfilled") return [];
 	return result.value.data ?? [];
 }
-function format$2(input) {
+function format$3(input) {
 	const { client, contacts, services, businessDetails, clientDates, overdueTasks, upcomingTasks, gaps } = input;
 	const lines = [];
 	const name = client.name ?? "(no name)";
@@ -1570,14 +1696,14 @@ async function handleGetEngagementSummary(api, { code }) {
 	const engagement = engagementResult.value;
 	return { content: [{
 		type: "text",
-		text: format$1({
+		text: format$2({
 			engagement,
 			emails: emailsResult.status === "fulfilled" ? emailsResult.value : [],
 			gaps: emailsResult.status === "rejected" ? ["email history"] : []
 		})
 	}] };
 }
-function format$1(input) {
+function format$2(input) {
 	const { engagement: e, emails, gaps } = input;
 	const lines = [];
 	const code = e.code ?? "(no code)";
@@ -1597,7 +1723,7 @@ function format$1(input) {
 	const services = e.proposalServices ?? [];
 	if (services.length > 0) {
 		lines.push("", `--- Services (${services.length}) ---`);
-		for (const s of services) lines.push(`- ${formatService(s)}`);
+		for (const s of services) lines.push(`- ${formatService$1(s)}`);
 	}
 	if (e.acceptance && e.status === "Accepted") {
 		lines.push("", "--- Acceptance ---");
@@ -1632,7 +1758,7 @@ function formatValues(e) {
 	if (e.totalValue && e.totalValue > 0) out.push(`Total contracted value: £${formatMoney$1(e.totalValue)}`);
 	return out;
 }
-function formatService(s) {
+function formatService$1(s) {
 	const name = s.billableService?.name ?? "(unnamed)";
 	const freq = s.billingFrequency ? ` ${s.billingFrequency}` : "";
 	if (s.effectivePrice !== void 0 && s.effectivePrice !== null) return `${name} — £${formatMoney$1(s.effectivePrice)}${freq}`;
@@ -1648,6 +1774,83 @@ function formatMoney$1(n) {
 	});
 }
 //#endregion
+//#region ../mcp-core/src/tools/get-service-details.ts
+const GetServiceDetailsInputSchema = { code: z.string().min(1, "Service code is required").describe("The service code (identifier). Usually discovered via list_services first.") };
+async function handleGetServiceDetails(api, { code }) {
+	try {
+		return { content: [{
+			type: "text",
+			text: format$1(await api.getService(code))
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error getting service: ${error.message} (correlation: ${error.correlationId})` : `Error getting service: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+function format$1(s) {
+	const lines = [];
+	const name = s.name ?? "(no name)";
+	const code = s.code ?? "(no code)";
+	lines.push(`Service: ${name} (${code})`);
+	const meta = [];
+	if (s.category) meta.push(s.category);
+	meta.push(s.isArchived ? "Archived" : "Active");
+	if (s.vatRate) meta.push(`VAT: ${s.vatRate}`);
+	if (s.pricingMode) meta.push(`Pricing: ${s.pricingMode}`);
+	if (meta.length > 0) lines.push(meta.join(" · "));
+	if (s.accountingCode) lines.push(`Accounting code: ${s.accountingCode}`);
+	if (s.description) lines.push(`Description: ${s.description}`);
+	if (s.defaultManagedByUser) lines.push(`Default manager: ${s.defaultManagedByUser.name} (${s.defaultManagedByUser.code})`);
+	lines.push("", "--- Applicable Client Types ---");
+	if (!s.clientTypes || s.clientTypes.length === 0) lines.push("All client types (no restriction configured).");
+	else for (const ct of s.clientTypes) lines.push(`- ${ct}`);
+	lines.push("", `--- HMRC Agent Authorisations (${s.agentAuthorisations?.length ?? 0}) ---`);
+	if (!s.agentAuthorisations || s.agentAuthorisations.length === 0) lines.push("None configured.");
+	else for (const a of s.agentAuthorisations) lines.push(`- ${a}`);
+	lines.push("", `--- Pricing Options (${s.pricing?.length ?? 0}) ---`);
+	if (!s.pricing || s.pricing.length === 0) lines.push("No pricing options configured.");
+	else for (const p of s.pricing) lines.push(formatPricingOption(p));
+	if (s.pricingMode === "CustomTiers" && s.pricingTiers && s.pricingTiers.length > 0) {
+		lines.push("", `--- Custom Pricing Tiers (${s.pricingTiers.length}) ---`);
+		const tiers = [...s.pricingTiers].sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0));
+		for (const t of tiers) lines.push(formatTier(t));
+	}
+	lines.push("", `--- Professional Clearance Items (${s.pcrItems?.length ?? 0}) ---`);
+	if (!s.pcrItems || s.pcrItems.length === 0) lines.push("None configured.");
+	else for (const item of s.pcrItems) lines.push(formatCodeAndName$1(item));
+	const factorCount = s.pricingFactors?.length ?? 0;
+	lines.push("", "--- Pricing Factors ---");
+	if (factorCount === 0) lines.push("None configured.");
+	else {
+		lines.push(`${factorCount} pricing factor${factorCount === 1 ? "" : "s"} configured.`);
+		for (const f of s.pricingFactors ?? []) if (f.description) lines.push(`- ${f.description}`);
+		lines.push("Note: exact pricing computed from factors is available via the proposal tools (get_proposal_summary / get_engagement_letter_summary) — those return effectivePrice per service.");
+	}
+	if (s.recurringTaskCount && s.recurringTaskCount > 0) lines.push("", `Recurring tasks using this service: ${s.recurringTaskCount}`);
+	return lines.join("\n");
+}
+function formatPricingOption(p) {
+	const freq = p.frequency ?? "(no frequency)";
+	const price = typeof p.price === "number" ? `£${p.price.toFixed(2)}` : "(no price)";
+	const rangeCount = p.revenueRangeOverrides?.length ?? 0;
+	const tierCount = p.tierOverrides?.length ?? 0;
+	const overrides = [];
+	if (rangeCount > 0) overrides.push(`${rangeCount} revenue-range override${rangeCount === 1 ? "" : "s"}`);
+	if (tierCount > 0) overrides.push(`${tierCount} tier override${tierCount === 1 ? "" : "s"}`);
+	return `- ${freq}: ${price}${overrides.length > 0 ? ` (+ ${overrides.join(", ")})` : ""}`;
+}
+function formatTier(t) {
+	return `- ${t.name ?? "(unnamed)"} (${t.code ?? "(no code)"})`;
+}
+function formatCodeAndName$1(item) {
+	return `- ${item.name ?? "(unnamed)"} (${item.code ?? "(no code)"})`;
+}
+//#endregion
 //#region ../mcp-core/src/tools/get-task-context.ts
 const GetTaskContextInputSchema = { code: z.string().min(1, "Task code is required").describe("The task code (identifier). Usually discovered via list_tasks first, or supplied directly by the user when they quote a task code.") };
 async function handleGetTaskContext(api, { code }) {
@@ -1845,20 +2048,20 @@ async function handleListEngagements(api, args) {
 		const items = result.data ?? [];
 		const total = result.totalCount ?? items.length;
 		if (args.limit === 0) {
-			const desc = describeFilters$2(args);
+			const desc = describeFilters$3(args);
 			return { content: [{
 				type: "text",
 				text: desc ? `Total: ${total} engagement${total === 1 ? "" : "s"} matching ${desc}.` : `Total: ${total} engagement${total === 1 ? "" : "s"}.`
 			}] };
 		}
 		if (items.length === 0) {
-			const desc = describeFilters$2(args);
+			const desc = describeFilters$3(args);
 			return { content: [{
 				type: "text",
 				text: desc ? `No engagements match ${desc}.` : "No engagements found."
 			}] };
 		}
-		const desc = describeFilters$2(args);
+		const desc = describeFilters$3(args);
 		const lines = [
 			desc ? total > items.length ? `Found ${total} engagements matching ${desc} (showing ${items.length}):` : `Found ${items.length} engagement${items.length === 1 ? "" : "s"} matching ${desc}:` : total > items.length ? `Showing ${items.length} of ${total} engagements:` : `${items.length} engagement${items.length === 1 ? "" : "s"}:`,
 			"",
@@ -1896,7 +2099,7 @@ function formatMoney(n) {
 		maximumFractionDigits: 2
 	});
 }
-function describeFilters$2(args) {
+function describeFilters$3(args) {
 	const parts = [];
 	if (args.status) parts.push(`status ${args.status}`);
 	if (args.search) parts.push(`search "${args.search}"`);
@@ -1905,6 +2108,101 @@ function describeFilters$2(args) {
 	return parts.join(", ");
 }
 //#endregion
+//#region ../mcp-core/src/tools/list-services.ts
+const categoryEnum = z.enum([
+	"Other",
+	"CoreAccounting",
+	"Tax",
+	"Payroll",
+	"CompanySecretarial",
+	"Advisory",
+	"SoftwareAndTraining"
+]);
+const clientTypeEnum = z.enum([
+	"PrivateLimitedCompany",
+	"PublicLimitedCompany",
+	"LimitedLiabilityPartnership",
+	"Partnership",
+	"Individual",
+	"Trust",
+	"Charity",
+	"SoleTrader"
+]);
+const sortByEnum$2 = z.enum([
+	"Name",
+	"Category",
+	"AccountingCode"
+]);
+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)."),
+	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."),
+	limit: z.number().int().min(0).max(50).optional().describe("Maximum number of services per page. Default 10, max 50. Pass 0 to return only the total count without any service data — use for 'how many services do we offer?' questions."),
+	offset: z.number().int().min(0).optional().describe("Pagination offset. Default 0.")
+};
+function formatService(s) {
+	const code = s.code ?? "(no code)";
+	const name = s.name ?? "(unnamed)";
+	const category = s.category ? ` · ${s.category}` : "";
+	const pricing = s.pricingMode ? ` · ${s.pricingMode}` : "";
+	return `- ${name} (${code})${s.isArchived ? " [ARCHIVED]" : ""}${category}${pricing}${s.accountingCode ? ` · a/c ${s.accountingCode}` : ""}${s.recurringTaskCount && s.recurringTaskCount > 0 ? ` · ${s.recurringTaskCount} recurring task${s.recurringTaskCount === 1 ? "" : "s"}` : ""}`;
+}
+async function handleListServices(api, args) {
+	try {
+		const query = args;
+		const result = await api.listServices(query);
+		const items = result.data ?? [];
+		const total = result.totalCount ?? items.length;
+		if (args.limit === 0) {
+			const desc = describeFilters$2(args);
+			return { content: [{
+				type: "text",
+				text: desc ? `Total: ${total} service${total === 1 ? "" : "s"} matching ${desc}.` : `Total: ${total} service${total === 1 ? "" : "s"}.`
+			}] };
+		}
+		if (items.length === 0) {
+			const desc = describeFilters$2(args);
+			return { content: [{
+				type: "text",
+				text: desc ? `No services match ${desc}.` : "No services found."
+			}] };
+		}
+		const desc = describeFilters$2(args);
+		const lines = [
+			desc ? total > items.length ? `Found ${total} services matching ${desc} (showing ${items.length}):` : `Found ${items.length} service${items.length === 1 ? "" : "s"} matching ${desc}:` : total > items.length ? `Showing ${items.length} of ${total} services:` : `${items.length} service${items.length === 1 ? "" : "s"}:`,
+			"",
+			...items.map(formatService)
+		];
+		if (result.hasMore) {
+			const nextOffset = (args.offset ?? 0) + items.length;
+			lines.push("", `More results available — call again with offset: ${nextOffset} to see the next page.`);
+		}
+		return { content: [{
+			type: "text",
+			text: lines.join("\n")
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error listing services: ${error.message} (correlation: ${error.correlationId})` : `Error listing services: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+function describeFilters$2(args) {
+	const parts = [];
+	if (args.search) parts.push(`search "${args.search}"`);
+	if (args.category) parts.push(`category ${args.category}`);
+	if (args.clientType) parts.push(`clientType ${args.clientType}`);
+	if (args.isArchived !== void 0) parts.push(`isArchived=${args.isArchived}`);
+	return parts.join(", ");
+}
+//#endregion
 //#region ../mcp-core/src/tools/list-tasks.ts
 const statusEnum$1 = z.enum([
 	"NotStarted",
@@ -2121,10 +2419,74 @@ function describeFilters(args) {
 	return parts.join(", ");
 }
 //#endregion
+//#region ../mcp-core/src/tools/add-client-note.ts
+const AddClientNoteInputSchema = {
+	clientCode: z.string().min(1, "Client code is required").describe("The client code (identifier) to attach the note to. Usually discovered via list_clients or get_client_summary."),
+	text: z.string().min(1, "Note text cannot be empty").describe("The note body. Keep it concise and factual — something the user can scan later. The user can edit or delete the note in the UI if the wording isn't right."),
+	pinnedLevel: z.number().int().min(0).max(2).optional().describe("Pin level for the note. 0 = not pinned (default), 1 = pinned to the notes section (surfaces at the top of the client's notes list), 2 = pinned to the client page (surfaces on the main client record, most prominent). Only set above 0 if the user explicitly asks for the note to be pinned; use 2 when they say 'pin to the client' / 'client-level pin' / 'pin at the top of the client page', and 1 when they just say 'pin' or 'pin in notes'.")
+};
+async function handleAddClientNote(api, args) {
+	try {
+		const user = await api.getCurrentUser();
+		const note = await api.createClientNote(args.clientCode, {
+			text: args.text,
+			date: (/* @__PURE__ */ new Date()).toISOString(),
+			noteFromUserCode: user.code ?? "",
+			pinnedLevel: args.pinnedLevel ?? 0
+		});
+		return { content: [{
+			type: "text",
+			text: `Added note to client ${args.clientCode} (note code: ${note.code ?? "(no code)"}).`
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error adding client note: ${error.message} (correlation: ${error.correlationId})` : `Error adding client note: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+//#endregion
+//#region ../mcp-core/src/tools/add-task-note.ts
+const AddTaskNoteInputSchema = {
+	taskCode: z.string().min(1, "Task code is required").describe("The task code (identifier) to attach the note to. Usually discovered via list_tasks or get_task_context."),
+	text: z.string().min(1, "Note text cannot be empty").describe("The note body. Keep it concise and factual — something the user can scan later. The user can edit or delete the note in the UI if the wording isn't right."),
+	pinnedLevel: z.number().int().min(0).max(2).optional().describe("Pin level for the note. 0 = not pinned (default), 1 = pinned to the notes section (surfaces at the top of the task's notes list), 2 = pinned to the task page (surfaces on the main task record, most prominent). Only set above 0 if the user explicitly asks for the note to be pinned; use 2 when they say 'pin to the task' / 'task-level pin' / 'pin at the top of the task page', and 1 when they just say 'pin' or 'pin in notes'.")
+};
+async function handleAddTaskNote(api, args) {
+	try {
+		const user = await api.getCurrentUser();
+		const note = await api.createTaskNote(args.taskCode, {
+			text: args.text,
+			date: (/* @__PURE__ */ new Date()).toISOString(),
+			noteFromUserCode: user.code ?? "",
+			pinnedLevel: args.pinnedLevel ?? 0
+		});
+		return { content: [{
+			type: "text",
+			text: `Added note to task ${args.taskCode} (note code: ${note.code ?? "(no code)"}).`
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof SodiumApiError ? `Error adding task note: ${error.message} (correlation: ${error.correlationId})` : `Error adding task note: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+//#endregion
 //#region ../mcp-core/src/server.ts
+function registerWriteTool(server, ctx, name, config, cb) {
+	if (!ctx.writesEnabled) return;
+	server.registerTool(name, config, cb);
+}
 async function buildServer(config) {
 	const api = new SodiumApiClient(config.context, { serverVersion: config.serverVersion });
-	const instructions = await buildInstructions(api);
+	const instructions = await buildInstructions(api, config.context.writesEnabled);
 	const server = new McpServer({
 		name: config.serverName,
 		version: config.serverVersion
@@ -2229,6 +2591,26 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleGetEngagementSummary(api, args));
+	server.registerTool("list_services", {
+		title: "List / search / filter the practice's service catalogue",
+		description: "List the practice's configured billable services with any combination of: search (3+ chars over code and name), category (Tax / Payroll / CoreAccounting / CompanySecretarial / Advisory / SoftwareAndTraining / Other — single value), clientType (PrivateLimitedCompany / PublicLimitedCompany / LimitedLiabilityPartnership / Partnership / Individual / Trust / Charity / SoleTrader — single value; matches services configured for that type plus services with no client-type restriction), isArchived (omit for all, false for active only, true for archive), sort (Name / Category / AccountingCode), and pagination. Use for: 'what services do we offer?' (no filter, isArchived=false), 'list our tax services' (category=Tax), 'what do we offer limited companies?' (clientType=PrivateLimitedCompany, isArchived=false), 'how many active services do we have?' (isArchived=false, limit=0 for count-only). Returns up to 50 per page. Follow up with get_service_details for one service's full configuration (client types, pricing options, clearance items, HMRC authorisations).",
+		inputSchema: ListServicesInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleListServices(api, args));
+	server.registerTool("get_service_details", {
+		title: "Get a single service's full configuration",
+		description: "Get a consolidated view of one billable service by code: identity (name, code, category, status, VAT rate, accounting code, description, default manager, pricing mode), applicable client types (explicit list, or 'all client types' if unrestricted), HMRC agent authorisations, pricing options (one per billing frequency with base price + override counts), custom pricing tiers (only when pricingMode=CustomTiers), professional clearance request items, and pricing-factor presence (count + factor questions only — exact factor band values are intentionally not dumped; computed pricing per client lives in the proposal tools). Use this AFTER list_services identifies the service, or when the user references a specific service by code. Enables service-audit workflows like 'is Self Assessment correctly restricted to Individual clients?' and 'what clearance items do we request for new bookkeeping clients?'",
+		inputSchema: GetServiceDetailsInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleGetServiceDetails(api, args));
 	server.registerTool("list_users", {
 		title: "List / search / filter tenant users",
 		description: "Find tenant users by name, email, role, or status. Use this when the user mentioned in a request isn't present in the startup roster (large teams have more than the top 20 active members shown there), or when filtering is needed beyond name resolution. Typical queries: 'find Jane' (search), 'list all partners' (isPartner=true), 'who's been invited but not joined yet?' (status=Invited), 'how many active users do we have?' (status=Active, limit=0). For 'how many X?' questions, pass limit=0 to get just the total count without fetching any user data.",
@@ -2239,6 +2621,28 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListUsers(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.",
+		inputSchema: AddTaskNoteInputSchema,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: true
+		}
+	}, (args) => handleAddTaskNote(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.",
+		inputSchema: AddClientNoteInputSchema,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: true
+		}
+	}, (args) => handleAddClientNote(api, args));
 	return server;
 }
 //#endregion
@@ -2249,10 +2653,21 @@ function loadContext() {
 	const baseUrl = process.env.SODIUM_API_URL ?? "https://api.sodiumhq.com";
 	if (!apiKey) throw new Error("SODIUM_API_KEY environment variable is required. Generate one in Sodium → Settings → API Keys.");
 	if (!tenant) throw new Error("SODIUM_TENANT environment variable is required. Find your tenant code in Sodium → Settings → Practice.");
+	const { values } = parseArgs({
+		args: process.argv.slice(2),
+		options: { "enable-writes": {
+			type: "boolean",
+			default: false
+		} },
+		strict: false
+	});
+	const cliWrites = values["enable-writes"] === true;
+	const envRaw = (process.env.SODIUM_ENABLE_WRITES ?? "").trim().toLowerCase();
 	return {
 		apiKey,
 		tenant,
-		baseUrl
+		baseUrl,
+		writesEnabled: cliWrites || envRaw === "true" || envRaw === "1"
 	};
 }
 //#endregion
@@ -2267,7 +2682,7 @@ async function main() {
 	});
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
-	console.error(`[sodium-pm-mcp] v${VERSION} ready (tenant: ${context.tenant})`);
+	console.error(`[sodium-pm-mcp] v${VERSION} ready (tenant: ${context.tenant}, writes: ${context.writesEnabled ? "enabled" : "disabled"})`);
 }
 main().catch((error) => {
 	const message = error instanceof Error ? error.message : String(error);

package/package.json

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