@sodiumhq/mcp-pm 0.1.0-beta.2589 → 0.1.0-beta.2592

package/dist/index.js

@@ -705,6 +705,60 @@ const getPracticeDetails = (options) => (options.client ?? client).get({
 	...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.
+*/
+const listTaskItemNotes = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/tasks/{taskCode}/taskitemnote",
+	...options
+});
+/**
+* Get Task Workflow Groups
+*
+* Retrieves comprehensive workflow progress information for a TaskItem.
+*
+* Returns detailed progress data including:
+* - Overall completion statistics (total steps, completed steps, percentage)
+* - All workflow steps with current status and assignments
+* - Available steps that can be worked on next
+* - Steps grouped by workflow groups for organized display
+*
+* Use this endpoint to:
+* - Display workflow progress dashboards
+* - Show step-by-step task execution status
+* - Identify bottlenecks and available work
+* - Track overall workflow completion
+*
+* Example Response:
+* {
+* "totalSteps": 8,
+* "completedSteps": 3,
+* "progressPercentage": 37.5,
+* "allSteps": [...],
+* "availableSteps": [...],
+* "groupedSteps": [...]
+* }
+*/
+const getTaskWorkflowGroups = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/tasks/{taskCode}/workflow/groups",
+	...options
+});
+/**
 * List TaskItems
 *
 * Lists TaskItems for the given tenant.
@@ -744,6 +798,22 @@ const listTaskItems = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get TaskItem
+*
+* Gets a TaskItem for the specified tenant.
+*/
+const getTaskItem = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/tasks/{code}",
+	...options
+});
+/**
 * Get Tenant
 *
 * Retrieves the details of a tenant using its Code identifier.
@@ -775,6 +845,22 @@ const getCurrentUser = (options) => (options?.client ?? client).get({
 	url: "/users/me",
 	...options
 });
+/**
+* List TenantUsers
+*
+* Lists all TenantUsers for the given tenant.
+*/
+const listTenantUsers = (options) => (options.client ?? client).get({
+	security: [{
+		name: "x-api-key",
+		type: "apiKey"
+	}, {
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/tenants/{tenant}/users",
+	...options
+});
 //#endregion
 //#region ../mcp-core/src/http/client.ts
 var SodiumApiError = class extends Error {
@@ -875,6 +961,20 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `list services for client ${clientCode}`);
 		return data;
 	}
+	async listUsers(query = {}) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await listTenantUsers({
+			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 users");
+		return data;
+	}
 	async listTasks(query = {}) {
 		const correlationId = randomUUID();
 		const { data, error, response } = await listTaskItems({
@@ -889,6 +989,47 @@ var SodiumApiClient = class {
 		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, "list tasks");
 		return data;
 	}
+	async getTask(code) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await getTaskItem({
+			path: {
+				tenant: this.ctx.tenant,
+				code
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `get task ${code}`);
+		return data;
+	}
+	async listTaskNotes(taskCode, options) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await listTaskItemNotes({
+			path: {
+				tenant: this.ctx.tenant,
+				taskCode
+			},
+			query: {
+				limit: options?.limit ?? 50,
+				offset: options?.offset ?? 0,
+				includeStepNotes: options?.includeStepNotes ?? false
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `list notes for task ${taskCode}`);
+		return data;
+	}
+	async getTaskWorkflowGroups(taskCode) {
+		const correlationId = randomUUID();
+		const { data, error, response } = await getTaskWorkflowGroups({
+			path: {
+				tenant: this.ctx.tenant,
+				taskCode
+			},
+			headers: { "X-Correlation-Id": correlationId }
+		});
+		if (error !== void 0 || !data) throw this.toError(response, error, correlationId, `get workflow groups for task ${taskCode}`);
+		return data;
+	}
 	toError(response, error, correlationId, operation) {
 		const status = response.status;
 		let message = `Failed to ${operation} (HTTP ${status})`;
@@ -899,11 +1040,17 @@ var SodiumApiClient = class {
 };
 //#endregion
 //#region ../mcp-core/src/context/instructions.ts
+const ROSTER_CAP = 20;
 async function buildInstructions(api) {
-	const [user, tenant, practice] = await Promise.allSettled([
+	const [user, tenant, practice, team] = await Promise.allSettled([
 		api.getCurrentUser(),
 		api.getTenantDetails(),
-		api.getPracticeDetails()
+		api.getPracticeDetails(),
+		api.listUsers({
+			status: "Active",
+			limit: ROSTER_CAP,
+			sortBy: "LastName"
+		})
 	]);
 	const now = /* @__PURE__ */ new Date();
 	const lines = [
@@ -918,12 +1065,25 @@ 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("", "When interpreting relative dates (today, this week, next month), use the date above.", "All codes (client, task, engagement) are string identifiers, not numeric IDs.");
+	if (team.status === "fulfilled") {
+		const members = team.value.data ?? [];
+		const total = team.value.totalCount ?? members.length;
+		if (members.length > 0) {
+			lines.push("", `Team members (${members.length}${total > members.length ? ` of ${total}` : ""} active):`);
+			for (const m of members) {
+				const code = m.code ?? "(no code)";
+				const display = m.displayName ?? [m.firstName, m.lastName].filter(Boolean).join(" ") ?? m.email ?? "(no name)";
+				lines.push(`- ${display} (${code})`);
+			}
+			if (total > members.length) lines.push(`... and ${total - members.length} more. Use list_users to see the rest or filter by role / status.`);
+		}
+	}
+	lines.push("", "When interpreting relative dates (today, this week, next month), use the date above.", "When the user names a team member (e.g. 'Jane's tasks'), resolve to their code from the team roster above before calling other tools.", "All codes (client, task, engagement, user) are string identifiers, not numeric IDs.");
 	return lines.join("\n");
 }
 //#endregion
 //#region ../mcp-core/src/tools/get-practice-details.ts
-function format$1(tenant, practice) {
+function format$2(tenant, practice) {
 	const lines = [];
 	lines.push(`Practice: ${practice.name}`);
 	lines.push(`Tenant: ${tenant.name} (${tenant.code})`);
@@ -957,7 +1117,7 @@ async function handleGetPracticeDetails(api) {
 		const [tenant, practice] = await Promise.all([api.getTenantDetails(), api.getPracticeDetails()]);
 		return { content: [{
 			type: "text",
-			text: format$1(tenant, practice)
+			text: format$2(tenant, practice)
 		}] };
 	} catch (error) {
 		return {
@@ -971,7 +1131,7 @@ async function handleGetPracticeDetails(api) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-clients.ts
-const statusEnum$1 = z.enum([
+const statusEnum$2 = z.enum([
 	"Active",
 	"Inactive",
 	"Prospect",
@@ -987,19 +1147,19 @@ const typeEnum = z.enum([
 	"Charity",
 	"SoleTrader"
 ]);
-const sortByEnum$1 = z.enum(["Name", "InternalReference"]);
+const sortByEnum$2 = 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$1).optional().describe("Filter by client status. Defaults to all statuses if omitted. Example: ['Active'] for active clients only."),
+	status: z.array(statusEnum$2).optional().describe("Filter by client status. Defaults to all statuses if omitted. Example: ['Active'] for active clients only."),
 	type: z.array(typeEnum).optional().describe("Filter by organisation type. Use ['PrivateLimitedCompany', 'PublicLimitedCompany'] for 'limited companies'. Use ['LimitedLiabilityPartnership'] for LLPs. Defaults to all types if omitted."),
 	managerCode: z.array(z.string()).optional().describe("Filter by assigned manager user codes."),
 	partnerCode: z.array(z.string()).optional().describe("Filter by assigned partner user codes."),
 	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$1.optional().describe("Field to sort by. Defaults to Name."),
+	sortBy: sortByEnum$2.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(1).max(50).optional().describe("Maximum number of clients to return per page. Default 10, max 50."),
+	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.")
 };
 function formatClient(c) {
@@ -1013,15 +1173,22 @@ async function handleListClients(api, args) {
 		const query = args;
 		const result = await api.listClients(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} client${total === 1 ? "" : "s"} matching ${desc}.` : `Total: ${total} client${total === 1 ? "" : "s"}.`
+			}] };
+		}
 		if (items.length === 0) {
-			const desc = describeFilters$1(args);
+			const desc = describeFilters$2(args);
 			return { content: [{
 				type: "text",
 				text: desc ? `No clients match ${desc}.` : "No clients found."
 			}] };
 		}
-		const total = result.totalCount ?? items.length;
-		const desc = describeFilters$1(args);
+		const desc = describeFilters$2(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"}:`,
 			"",
@@ -1045,7 +1212,7 @@ async function handleListClients(api, args) {
 		};
 	}
 }
-function describeFilters$1(args) {
+function describeFilters$2(args) {
 	const parts = [];
 	if (args.search) parts.push(`search "${args.search}"`);
 	if (args.status?.length) parts.push(`status ${args.status.join("/")}`);
@@ -1089,7 +1256,7 @@ async function handleGetClientSummary(api, { code }) {
 	}
 	return { content: [{
 		type: "text",
-		text: format({
+		text: format$1({
 			client: clientResult.value,
 			contacts: extract(contactsResult),
 			services: extract(servicesResult),
@@ -1108,7 +1275,7 @@ function extract(result) {
 	if (result.status !== "fulfilled") return [];
 	return result.value.data ?? [];
 }
-function format(input) {
+function format$1(input) {
 	const { client, contacts, services, overdueTasks, upcomingTasks, gaps } = input;
 	const lines = [];
 	const name = client.name ?? "(no name)";
@@ -1158,11 +1325,150 @@ function format(input) {
 }
 function formatTask$1(t) {
 	const taskCode = t.code ?? "(no code)";
-	return `${t.name ?? "(unnamed)"} (${taskCode})${t.dueDate ? ` — due ${t.dueDate}` : ""}${t.assignedUser?.name ? ` — ${t.assignedUser.name}` : ""}`;
+	return `${t.name ?? "(unnamed)"} (${taskCode})${t.dueDate ? ` — due ${t.dueDate}` : ""}${t.assignedUser?.name ? ` — ${t.assignedUser.name}` : ""}${t.workflow ? ` — workflow ${t.workflowStepsComplete ?? 0}/${t.workflowSteps ?? 0}` : ""}`;
+}
+//#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 }) {
+	const [taskResult, notesResult, workflowResult] = await Promise.allSettled([
+		api.getTask(code),
+		api.listTaskNotes(code, {
+			includeStepNotes: false,
+			limit: 50
+		}),
+		api.getTaskWorkflowGroups(code)
+	]);
+	if (taskResult.status === "rejected") {
+		const err = taskResult.reason;
+		return {
+			content: [{
+				type: "text",
+				text: err instanceof SodiumApiError ? `Error getting task: ${err.message} (correlation: ${err.correlationId})` : `Error getting task: ${err instanceof Error ? err.message : String(err)}`
+			}],
+			isError: true
+		};
+	}
+	const task = taskResult.value;
+	const notes = notesResult.status === "fulfilled" ? notesResult.value.data ?? [] : [];
+	const workflowGroups = workflowResult.status === "fulfilled" ? workflowResult.value : [];
+	const gaps = [];
+	if (notesResult.status === "rejected") gaps.push("notes");
+	if (workflowResult.status === "rejected" && task.workflow) gaps.push("workflow steps");
+	return { content: [{
+		type: "text",
+		text: format({
+			task,
+			notes,
+			workflowGroups,
+			gaps
+		})
+	}] };
+}
+function format(input) {
+	const { task, notes, workflowGroups, gaps } = input;
+	const lines = [];
+	const name = task.name ?? "(no name)";
+	const code = task.code ?? "(no code)";
+	lines.push(`Task: ${name} (${code})`);
+	const statusBits = [];
+	if (task.status) statusBits.push(task.status);
+	if (task.isOverdue) statusBits.push("OVERDUE");
+	if (task.isProjected) statusBits.push("projected");
+	if (statusBits.length > 0) lines.push(`Status: ${statusBits.join(" · ")}`);
+	const dateBits = [];
+	if (task.startDate) dateBits.push(`start ${task.startDate}`);
+	if (task.dueDate) dateBits.push(`due ${task.dueDate}`);
+	if (task.statutoryDueDate) dateBits.push(`statutory ${task.statutoryDueDate}`);
+	if (dateBits.length > 0) lines.push(`Dates: ${dateBits.join(" · ")}`);
+	if (task.timeEstimate !== void 0 && task.timeEstimate !== null) lines.push(`Time estimate: ${task.timeEstimate}h`);
+	if (task.assignedUser) lines.push(`Assigned user: ${formatCodeAndName(task.assignedUser)}`);
+	if (task.assignedTeam) lines.push(`Assigned team: ${formatCodeAndName(task.assignedTeam)}`);
+	if (task.category) lines.push(`Category: ${formatCodeAndName(task.category)}`);
+	if (task.recurringTask) lines.push(`Recurring template: ${formatCodeAndName(task.recurringTask)}`);
+	if (task.workflow) lines.push(`Workflow template: ${formatCodeAndName(task.workflow)}`);
+	const description = task.description?.trim();
+	if (description) lines.push("", "--- Description ---", description);
+	const checklist = task.checklist ?? [];
+	if (checklist.length > 0) {
+		lines.push("", `--- Checklist (${countCompleted(checklist)}/${checklist.length}) ---`);
+		const ordered = [...checklist].sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0));
+		for (const item of ordered) {
+			const mark = item.isCompleted ? "[x]" : "[ ]";
+			lines.push(`${mark} ${item.text ?? ""}`);
+		}
+	}
+	if (workflowGroups.length > 0) {
+		const totalSteps = task.workflowSteps ?? sumBy(workflowGroups, (g) => g.totalSteps ?? 0);
+		const doneSteps = task.workflowStepsComplete ?? sumBy(workflowGroups, (g) => g.completedSteps ?? 0);
+		lines.push("", `--- Workflow progress (${doneSteps}/${totalSteps} steps complete) ---`);
+		for (const group of workflowGroups) {
+			const gName = group.groupName ?? `Group ${group.groupNumber ?? "?"}`;
+			const gTotal = group.totalSteps ?? 0;
+			const gDone = group.completedSteps ?? 0;
+			const deadline = group.groupDeadline ? ` — deadline ${group.groupDeadline}` : "";
+			lines.push(`Group: ${gName} (${gDone}/${gTotal})${deadline}`);
+			for (const step of group.steps ?? []) lines.push(`  ${formatStep(step)}`);
+		}
+	}
+	if (notes.length > 0) {
+		const sorted = [...notes].sort((a, b) => {
+			const pa = a.pinnedLevel ?? 0;
+			const pb = b.pinnedLevel ?? 0;
+			if (pa !== pb) return pb - pa;
+			const da = a.date ?? a.createdDate ?? "";
+			return (b.date ?? b.createdDate ?? "").localeCompare(da);
+		});
+		lines.push("", `--- Notes (${notes.length}) ---`);
+		for (const note of sorted.slice(0, 20)) lines.push(formatNote(note));
+		if (notes.length > 20) lines.push(`... and ${notes.length - 20} more notes`);
+	}
+	const clients = task.clients ?? [];
+	const primaryCode = task.primaryClient?.code;
+	const secondary = clients.filter((c) => c.code !== primaryCode);
+	if (task.primaryClient || clients.length > 0) {
+		lines.push("", "--- Parent client ---");
+		if (task.primaryClient) lines.push(`Primary: ${formatCodeAndName(task.primaryClient)}`);
+		if (secondary.length > 0) lines.push(`Also linked: ${secondary.map(formatCodeAndName).join(", ")}`);
+	}
+	if (gaps.length > 0) lines.push("", `Note: could not load ${gaps.join(", ")} (partial failure). Retry for a complete picture.`);
+	return lines.join("\n");
+}
+function formatStep(step) {
+	const num = step.stepNumber ?? "?";
+	const name = step.stepName ?? "(unnamed)";
+	const bits = [];
+	if (step.status) bits.push(step.status);
+	if (step.assignedUser?.name) bits.push(step.assignedUser.name);
+	else if (step.assignedTeam?.name) bits.push(`team ${step.assignedTeam.name}`);
+	if (step.completedDate) bits.push(`done ${step.completedDate}`);
+	if (step.blockedReason) bits.push(`blocked: ${step.blockedReason}`);
+	return `Step ${num}: ${name}${bits.length > 0 ? ` — ${bits.join(" · ")}` : ""}`;
+}
+function formatNote(note) {
+	const pinPrefix = (note.pinnedLevel ?? 0) > 0 ? "[pinned] " : "";
+	const dateStr = note.date ?? note.createdDate ?? "";
+	const author = note.noteFromUser?.name ?? "(unknown)";
+	const stepCtx = note.stepName ? ` [step: ${note.stepName}]` : "";
+	const text = (note.text ?? "").replace(/\s+/g, " ").trim();
+	return `${pinPrefix}${dateStr} — ${author}${stepCtx}: ${text.length > 200 ? `${text.slice(0, 200)}...` : text}`;
+}
+function formatCodeAndName(v) {
+	if (!v) return "(none)";
+	const name = v.name ?? "";
+	const code = v.code ?? "";
+	if (name && code) return `${name} (${code})`;
+	return name || code || "(none)";
+}
+function countCompleted(items) {
+	return items.filter((i) => i.isCompleted).length;
+}
+function sumBy(arr, fn) {
+	return arr.reduce((acc, cur) => acc + fn(cur), 0);
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-tasks.ts
-const statusEnum = z.enum([
+const statusEnum$1 = z.enum([
 	"NotStarted",
 	"InProgress",
 	"Blocked",
@@ -1194,7 +1500,7 @@ const dateRangeEnum = z.enum([
 	"CustomDateRange"
 ]);
 const dateBasisEnum = z.enum(["StartDate", "DueDate"]);
-const sortByEnum = z.enum([
+const sortByEnum$1 = z.enum([
 	"Name",
 	"DueDate",
 	"StartDate",
@@ -1205,7 +1511,7 @@ const sortByEnum = z.enum([
 const ListTasksInputSchema = {
 	user: z.array(z.string()).optional().describe("Filter by assigned user codes. For 'my tasks' use the current user's code from the startup context. For another team member's tasks, pass their code. Omit to see tasks across all users (useful for practice managers)."),
 	client: z.array(z.string()).optional().describe("Filter by client codes — tasks belonging to these specific clients only."),
-	status: z.array(statusEnum).optional().describe("Filter by task status. Typical: ['NotStarted', 'InProgress'] to exclude completed/skipped. Leave empty for all statuses. IMPORTANT: if the query includes NotStarted (the default for new tasks), you must ALSO provide one of: dateRange, isOverdue=true, or restrict status to non-NotStarted values only — otherwise the API rejects the call to prevent unbounded queries."),
+	status: z.array(statusEnum$1).optional().describe("Filter by task status. Typical: ['NotStarted', 'InProgress'] to exclude completed/skipped. Leave empty for all statuses. IMPORTANT: if the query includes NotStarted (the default for new tasks), you must ALSO provide one of: dateRange, isOverdue=true, or restrict status to non-NotStarted values only — otherwise the API rejects the call to prevent unbounded queries."),
 	isOverdue: z.boolean().optional().describe("Set true to return only overdue tasks (DueDate before today, not completed/skipped). When true, no date range is required. Useful for sidestepping the NotStarted + date-range requirement."),
 	dateRange: dateRangeEnum.optional().describe("Preset date range. Use 'Today' for today's tasks, 'Next7Days' for 'due this week', 'Last30Days' for recent activity. If 'CustomDateRange', also provide startDate and/or endDate. REQUIRED when querying NotStarted tasks unless you pass isOverdue=true."),
 	startDate: z.string().optional().describe("Start of custom date range (YYYY-MM-DD). Used when dateRange='CustomDateRange'. Prefer specifying both startDate and endDate with a narrow window for performance — broad ranges strain the API. If startDate > endDate the API swaps them silently. Maximum allowed total range is 2 years."),
@@ -1217,29 +1523,36 @@ const ListTasksInputSchema = {
 	savedFilter: z.string().optional().describe("Apply a user-saved filter by its code. Other filter parameters override fields from the saved filter."),
 	includeProjected: z.boolean().optional().describe("Set true to include projected (virtual, not-yet-materialised) tasks in the results. Projected tasks are always NotStarted. Useful for 'what's coming up' queries."),
 	includeWorkflowSteps: z.boolean().optional().describe("Set true for Agenda Mode: returns both tasks AND their workflow steps as individual rows. Each step row has its parent task's properties plus step-specific details. Useful for 'what's the next action on X' or when workflow step granularity matters."),
-	sortBy: sortByEnum.optional().describe("Field to sort by. Defaults to StartDate. Use 'DueDate' for 'what's due soonest' ordering. Combine with sortDesc for 'oldest/newest' ordering."),
+	sortBy: sortByEnum$1.optional().describe("Field to sort by. Defaults to StartDate. Use 'DueDate' for 'what's due soonest' ordering. Combine with sortDesc for 'oldest/newest' ordering."),
 	sortDesc: z.boolean().optional().describe("Sort in descending order. Defaults to ascending."),
-	limit: z.number().int().min(1).max(50).optional().describe("Maximum number of tasks per page. Default 10, max 50."),
+	limit: z.number().int().min(0).max(50).optional().describe("Maximum number of tasks per page. Default 10, max 50. Pass 0 to return only the total count without any task 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("Pagination offset. Default 0.")
 };
 function formatTask(t) {
 	const code = t.code ?? "(no code)";
-	return `- ${t.name ?? "(unnamed)"} (${code})${t.isOverdue ? " [OVERDUE]" : ""}${t.dueDate ? ` · due ${t.dueDate}` : ""}${t.primaryClient ? ` · ${t.primaryClient.name}` : t.clients?.[0] ? ` · ${t.clients[0].name}` : ""}${t.assignedUser?.name ? ` · ${t.assignedUser.name}` : ""}${t.status && t.status !== "NotStarted" ? ` · ${t.status}` : ""}`;
+	return `- ${t.name ?? "(unnamed)"} (${code})${t.isOverdue ? " [OVERDUE]" : ""}${t.dueDate ? ` · due ${t.dueDate}` : ""}${t.primaryClient ? ` · ${t.primaryClient.name}` : t.clients?.[0] ? ` · ${t.clients[0].name}` : ""}${t.assignedUser?.name ? ` · ${t.assignedUser.name}` : ""}${t.status && t.status !== "NotStarted" ? ` · ${t.status}` : ""}${t.workflow ? ` · workflow ${t.workflowStepsComplete ?? 0}/${t.workflowSteps ?? 0}` : ""}`;
 }
 async function handleListTasks(api, args) {
 	try {
 		const query = args;
 		const result = await api.listTasks(query);
 		const items = result.data ?? [];
+		const total = result.totalCount ?? items.length;
+		if (args.limit === 0) {
+			const desc = describeFilters$1(args);
+			return { content: [{
+				type: "text",
+				text: desc ? `Total: ${total} task${total === 1 ? "" : "s"} matching ${desc}.` : `Total: ${total} task${total === 1 ? "" : "s"}.`
+			}] };
+		}
 		if (items.length === 0) {
-			const desc = describeFilters(args);
+			const desc = describeFilters$1(args);
 			return { content: [{
 				type: "text",
 				text: desc ? `No tasks match ${desc}.` : "No tasks found."
 			}] };
 		}
-		const total = result.totalCount ?? items.length;
-		const desc = describeFilters(args);
+		const desc = describeFilters$1(args);
 		const lines = [
 			desc ? total > items.length ? `Found ${total} tasks matching ${desc} (showing ${items.length}):` : `Found ${items.length} task${items.length === 1 ? "" : "s"} matching ${desc}:` : total > items.length ? `Showing ${items.length} of ${total} tasks:` : `${items.length} task${items.length === 1 ? "" : "s"}:`,
 			"",
@@ -1263,7 +1576,7 @@ async function handleListTasks(api, args) {
 		};
 	}
 }
-function describeFilters(args) {
+function describeFilters$1(args) {
 	const parts = [];
 	if (args.user?.length) parts.push(`user ${args.user.join(",")}`);
 	if (args.client?.length) parts.push(`client ${args.client.join(",")}`);
@@ -1275,6 +1588,101 @@ function describeFilters(args) {
 	return parts.join(", ");
 }
 //#endregion
+//#region ../mcp-core/src/tools/list-users.ts
+const statusEnum = z.enum([
+	"Created",
+	"Invited",
+	"Active",
+	"Disabled",
+	"Declined",
+	"Deleted"
+]);
+const systemRoleEnum = z.enum([
+	"Admin",
+	"StandardUser",
+	"Viewer"
+]);
+const sortByEnum = z.enum([
+	"LastName",
+	"FirstName",
+	"Email"
+]);
+const ListUsersInputSchema = {
+	search: z.string().min(3, "Search must be at least 3 characters when provided").optional().describe("Free-text search across user code, first name, last name, and email. Minimum 3 characters. Use for 'find Jane' when the name isn't in the startup roster (large teams, non-active users)."),
+	status: statusEnum.optional().describe("Filter by a single user status. Use 'Active' for currently-working members, 'Invited' for pending invitations, 'Disabled' for offboarded users, 'Deleted' for removed users. Note: this is a single value, not an array."),
+	systemRole: systemRoleEnum.optional().describe("Filter by system role. Admin = full access, StandardUser = normal access, Viewer = read-only. Single value."),
+	isClientManager: z.boolean().optional().describe("Set true to return only users flagged as client managers; false to exclude them."),
+	isPartner: z.boolean().optional().describe("Set true to return only users flagged as partners; false to exclude them. Use for 'list partners' queries."),
+	isAssociate: z.boolean().optional().describe("Set true to return only users flagged as associates; false to exclude them."),
+	sortBy: sortByEnum.optional().describe("Field to sort by. Defaults to LastName."),
+	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 users per page. Default 10, max 50. Pass 0 to return only the total count without any user data — use for 'how many users?' questions."),
+	offset: z.number().int().min(0).optional().describe("Pagination offset. Default 0.")
+};
+function formatUser(u) {
+	const code = u.code ?? "(no code)";
+	const display = u.displayName ?? [u.firstName, u.lastName].filter(Boolean).join(" ") ?? u.email ?? "(no name)";
+	const meta = [];
+	if (u.status && u.status !== "Active") meta.push(u.status);
+	if (u.email && u.email !== display) meta.push(u.email);
+	if (u.isSuperAdmin) meta.push("SuperAdmin");
+	return `- ${display} (${code})${meta.length > 0 ? ` — ${meta.join(" · ")}` : ""}`;
+}
+async function handleListUsers(api, args) {
+	try {
+		const query = args;
+		const result = await api.listUsers(query);
+		const items = result.data ?? [];
+		const total = result.totalCount ?? items.length;
+		if (args.limit === 0) {
+			const desc = describeFilters(args);
+			return { content: [{
+				type: "text",
+				text: desc ? `Total: ${total} user${total === 1 ? "" : "s"} matching ${desc}.` : `Total: ${total} user${total === 1 ? "" : "s"}.`
+			}] };
+		}
+		if (items.length === 0) {
+			const desc = describeFilters(args);
+			return { content: [{
+				type: "text",
+				text: desc ? `No users match ${desc}.` : "No users found."
+			}] };
+		}
+		const desc = describeFilters(args);
+		const lines = [
+			desc ? total > items.length ? `Found ${total} users matching ${desc} (showing ${items.length}):` : `Found ${items.length} user${items.length === 1 ? "" : "s"} matching ${desc}:` : total > items.length ? `Showing ${items.length} of ${total} users:` : `${items.length} user${items.length === 1 ? "" : "s"}:`,
+			"",
+			...items.map(formatUser)
+		];
+		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 users: ${error.message} (correlation: ${error.correlationId})` : `Error listing users: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+function describeFilters(args) {
+	const parts = [];
+	if (args.search) parts.push(`search "${args.search}"`);
+	if (args.status) parts.push(`status ${args.status}`);
+	if (args.systemRole) parts.push(`role ${args.systemRole}`);
+	if (args.isClientManager !== void 0) parts.push(`isClientManager=${args.isClientManager}`);
+	if (args.isPartner !== void 0) parts.push(`isPartner=${args.isPartner}`);
+	if (args.isAssociate !== void 0) parts.push(`isAssociate=${args.isAssociate}`);
+	return parts.join(", ");
+}
+//#endregion
 //#region ../mcp-core/src/server.ts
 async function buildServer(config) {
 	const api = new SodiumApiClient(config.context);
@@ -1298,7 +1706,7 @@ async function buildServer(config) {
 	}, () => handleGetPracticeDetails(api));
 	server.registerTool("list_clients", {
 		title: "List / search / filter clients",
-		description: "List clients with any combination of: search (code/name/internal reference, 3+ chars), status (Active/Inactive/Prospect/LostProspect), type (PrivateLimitedCompany/PublicLimitedCompany/LimitedLiabilityPartnership/Partnership/Individual/Trust/Charity/SoleTrader), manager/partner/associate user codes, service codes, a saved filter code, sort, and pagination. Use search for 'find ACME'-style queries. Use type for 'list limited companies' (pass PrivateLimitedCompany + PublicLimitedCompany). Use status: ['Active'] to exclude prospects/inactive. Returns up to 50 clients per page — paginate via offset for more. Follow up with get_client_summary for full detail on a specific client.",
+		description: "List clients with any combination of: search (code/name/internal reference, 3+ chars), status (Active/Inactive/Prospect/LostProspect), type (PrivateLimitedCompany/PublicLimitedCompany/LimitedLiabilityPartnership/Partnership/Individual/Trust/Charity/SoleTrader), manager/partner/associate user codes, service codes, a saved filter code, sort, and pagination. Use search for 'find ACME'-style queries. Use type for 'list limited companies' (pass PrivateLimitedCompany + PublicLimitedCompany). Use status: ['Active'] to exclude prospects/inactive. Returns up to 50 clients per page — paginate via offset for more. For 'how many X?' questions, pass limit=0 to get just the total count without fetching any client data. Follow up with get_client_summary for full detail on a specific client.",
 		inputSchema: ListClientsInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -1318,7 +1726,7 @@ async function buildServer(config) {
 	}, (args) => handleGetClientSummary(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.",
+		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.",
 		inputSchema: ListTasksInputSchema,
 		annotations: {
 			readOnlyHint: true,
@@ -1326,6 +1734,26 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListTasks(api, args));
+	server.registerTool("get_task_context", {
+		title: "Get full context for a single task",
+		description: "Get a consolidated view of one task by code: identity (name, code, status, overdue flag, start/due/statutory dates, time estimate, assignee), description, task-level checklist, workflow progress (groups and steps with status, assignee, and completion info — only if the task has a workflow attached), notes (pinned first, then newest first), and the parent client. Use this AFTER list_tasks identifies a task of interest, or when the user references a specific task by code. Tolerates partial failures — if notes or workflow steps can't be loaded, the task details are still returned with a note about what's missing. Only fails outright if the task itself can't be fetched (e.g. unknown code).",
+		inputSchema: GetTaskContextInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleGetTaskContext(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.",
+		inputSchema: ListUsersInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleListUsers(api, args));
 	return server;
 }
 //#endregion

package/package.json

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