@sodiumhq/mcp-pm 0.1.0-beta.2590 → 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.
@@ -919,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})`;
@@ -972,7 +1083,7 @@ async function buildInstructions(api) {
 }
 //#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})`);
@@ -1006,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 {
@@ -1145,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),
@@ -1164,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)";
@@ -1214,7 +1325,146 @@ 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
@@ -1280,7 +1530,7 @@ const ListTasksInputSchema = {
 };
 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 {
@@ -1484,6 +1734,16 @@ 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.",

package/package.json

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