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

package/dist/index.js

@@ -775,6 +775,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 +891,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({
@@ -899,11 +929,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,7 +954,20 @@ 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
@@ -971,7 +1020,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 +1036,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 +1062,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 +1101,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("/")}`);
@@ -1162,7 +1218,7 @@ function formatTask$1(t) {
 }
 //#endregion
 //#region ../mcp-core/src/tools/list-tasks.ts
-const statusEnum = z.enum([
+const statusEnum$1 = z.enum([
 	"NotStarted",
 	"InProgress",
 	"Blocked",
@@ -1194,7 +1250,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 +1261,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,9 +1273,9 @@ 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) {
@@ -1231,15 +1287,22 @@ async function handleListTasks(api, args) {
 		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 +1326,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 +1338,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 +1456,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 +1476,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 +1484,16 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListTasks(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.2590",
   "description": "Sodium Practice Management MCP server — lets AI assistants interact with your Sodium tenant",
   "type": "module",
   "bin": {