@sodiumhq/mcp-pm 0.1.0-beta.2603 → 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
 
@@ -73,12 +80,16 @@ Then ask: *"give me a summary of my practice"*.
 **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.
@@ -835,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.
@@ -1250,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})`;
@@ -1261,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(),
@@ -1295,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;
@@ -2351,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
@@ -2489,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
@@ -2499,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
@@ -2517,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.2603",
+  "version": "0.1.0-beta.2611",
   "description": "Sodium Practice Management MCP server — lets AI assistants interact with your Sodium tenant",
   "type": "module",
   "bin": {