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

package/README.md

@@ -50,6 +50,7 @@ Then ask: *"give me a summary of my practice"*.
 - **`get_practice_details`** — consolidated practice overview (counts, connections, settings)
 - **`list_clients`** — list and filter clients by search, status, type, assignee, services, saved filters
 - **`get_client_summary`** — one-call composite: client identity + contacts + active services + overdue + upcoming tasks
+- **`list_tasks`** — list and filter tasks by user (including "my tasks"), client, status, date range, overdue, category, team — covers both individual and practice-manager workflows
 
 More tools land iteratively as the beta progresses.
 

package/dist/index.js

@@ -971,7 +971,7 @@ async function handleGetPracticeDetails(api) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-clients.ts
-const statusEnum = z.enum([
+const statusEnum$1 = z.enum([
 	"Active",
 	"Inactive",
 	"Prospect",
@@ -987,17 +987,17 @@ const typeEnum = z.enum([
 	"Charity",
 	"SoleTrader"
 ]);
-const sortByEnum = z.enum(["Name", "InternalReference"]);
+const sortByEnum$1 = 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).optional().describe("Filter by client status. Defaults to all statuses if omitted. Example: ['Active'] for active clients only."),
+	status: z.array(statusEnum$1).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.optional().describe("Field to sort by. Defaults to Name."),
+	sortBy: sortByEnum$1.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."),
 	offset: z.number().int().min(0).optional().describe("Number of records to skip for pagination. Default 0.")
@@ -1014,14 +1014,14 @@ async function handleListClients(api, args) {
 		const result = await api.listClients(query);
 		const items = result.data ?? [];
 		if (items.length === 0) {
-			const desc = describeFilters(args);
+			const desc = describeFilters$1(args);
 			return { content: [{
 				type: "text",
 				text: desc ? `No clients match ${desc}.` : "No clients found."
 			}] };
 		}
 		const total = result.totalCount ?? items.length;
-		const desc = describeFilters(args);
+		const desc = describeFilters$1(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 +1045,7 @@ async function handleListClients(api, args) {
 		};
 	}
 }
-function describeFilters(args) {
+function describeFilters$1(args) {
 	const parts = [];
 	if (args.search) parts.push(`search "${args.search}"`);
 	if (args.status?.length) parts.push(`status ${args.status.join("/")}`);
@@ -1145,22 +1145,136 @@ function format(input) {
 	lines.push("", "--- Tasks ---");
 	lines.push(`Overdue: ${overdueTasks.length}`);
 	if (overdueTasks.length > 0) {
-		for (const t of overdueTasks.slice(0, 5)) lines.push(`  - ${formatTask(t)}`);
+		for (const t of overdueTasks.slice(0, 5)) lines.push(`  - ${formatTask$1(t)}`);
 		if (overdueTasks.length > 5) lines.push(`  ... and ${overdueTasks.length - 5} more`);
 	}
 	lines.push(`Due in next 7 days: ${upcomingTasks.length}`);
 	if (upcomingTasks.length > 0) {
-		for (const t of upcomingTasks.slice(0, 5)) lines.push(`  - ${formatTask(t)}`);
+		for (const t of upcomingTasks.slice(0, 5)) lines.push(`  - ${formatTask$1(t)}`);
 		if (upcomingTasks.length > 5) lines.push(`  ... and ${upcomingTasks.length - 5} more`);
 	}
 	if (gaps.length > 0) lines.push("", `Note: could not load ${gaps.join(", ")} (partial failure). Retry for a complete picture.`);
 	return lines.join("\n");
 }
-function formatTask(t) {
+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}` : ""}`;
 }
 //#endregion
+//#region ../mcp-core/src/tools/list-tasks.ts
+const statusEnum = z.enum([
+	"NotStarted",
+	"InProgress",
+	"Blocked",
+	"Completed",
+	"Skipped"
+]);
+const dateRangeEnum = z.enum([
+	"Today",
+	"ThisWeek",
+	"NextWeek",
+	"Last7Days",
+	"Next7Days",
+	"Last30Days",
+	"Next30Days",
+	"PreviousMonth",
+	"ThisMonth",
+	"NextMonth",
+	"PreviousQuarter",
+	"ThisQuarter",
+	"NextQuarter",
+	"PreviousYear",
+	"ThisYear",
+	"NextYear",
+	"YearToDate",
+	"PreviousFinancialYear",
+	"ThisFinancialYear",
+	"NextFinancialYear",
+	"FinancialYearToDate",
+	"CustomDateRange"
+]);
+const dateBasisEnum = z.enum(["StartDate", "DueDate"]);
+const sortByEnum = z.enum([
+	"Name",
+	"DueDate",
+	"StartDate",
+	"Category",
+	"ClientName",
+	"AssignedUser"
+]);
+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."),
+	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."),
+	endDate: z.string().optional().describe("End of custom date range (YYYY-MM-DD). Used when dateRange='CustomDateRange'. Pair with startDate to define a narrow window — avoid open-ended ranges."),
+	dateBasis: dateBasisEnum.optional().describe("Which date field to apply the date range filter to. Use 'DueDate' for 'what's due when' questions; 'StartDate' (default) for 'what's been worked on'."),
+	category: z.array(z.string()).optional().describe("Filter by task category codes (e.g. tax, audit, compliance categories)."),
+	team: z.array(z.string()).optional().describe("Filter by team codes (if the practice uses teams to group users)."),
+	recurringTask: z.array(z.string()).optional().describe("Filter by recurring-task template codes — returns all instances generated from those templates."),
+	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."),
+	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."),
+	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}` : ""}`;
+}
+async function handleListTasks(api, args) {
+	try {
+		const query = args;
+		const result = await api.listTasks(query);
+		const items = result.data ?? [];
+		if (items.length === 0) {
+			const desc = describeFilters(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 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"}:`,
+			"",
+			...items.map(formatTask)
+		];
+		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 tasks: ${error.message} (correlation: ${error.correlationId})` : `Error listing tasks: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+}
+function describeFilters(args) {
+	const parts = [];
+	if (args.user?.length) parts.push(`user ${args.user.join(",")}`);
+	if (args.client?.length) parts.push(`client ${args.client.join(",")}`);
+	if (args.status?.length) parts.push(`status ${args.status.join("/")}`);
+	if (args.isOverdue) parts.push("overdue");
+	if (args.dateRange) parts.push(`date ${args.dateRange}${args.dateBasis ? ` (${args.dateBasis})` : ""}${args.dateRange === "CustomDateRange" && args.startDate && args.endDate ? ` ${args.startDate} to ${args.endDate}` : ""}`);
+	if (args.category?.length) parts.push(`category ${args.category.join(",")}`);
+	if (args.team?.length) parts.push(`team ${args.team.join(",")}`);
+	return parts.join(", ");
+}
+//#endregion
 //#region ../mcp-core/src/server.ts
 async function buildServer(config) {
 	const api = new SodiumApiClient(config.context);
@@ -1202,6 +1316,16 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (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.",
+		inputSchema: ListTasksInputSchema,
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		}
+	}, (args) => handleListTasks(api, args));
 	return server;
 }
 //#endregion

package/package.json

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