@transcend-io/mcp-server-preferences 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# @transcend-io/mcp-server-preferences
+
+> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice.
+
+Transcend MCP Server for privacy preference management. Provides tools for querying, upserting, and deleting user privacy preference records and their identifiers.
+
+Requires **Node.js ≥ 22.12** (see `engines` in `package.json`).
+
+For local runs from this repository, copy [`secret.env.example`](../../../secret.env.example) to **`secret.env`** at the repo root (gitignored) and set your API key (see **Run from the monorepo**).
+
+## Install
+
+When the package is available on npm, install the CLI globally:
+
+```bash
+npm install -g @transcend-io/mcp-server-preferences
+```
+
+Until then, run from a checkout of this repository (see **Run from the monorepo** below).
+
+## Usage
+
+```bash
+# With TRANSCEND_API_KEY in the environment; from the monorepo use secret.env (see Run from the monorepo)
+TRANSCEND_API_KEY=your-api-key transcend-mcp-preferences
+```
+
+The process speaks MCP over **stdio** and is meant to be launched by an MCP client (for example Cursor or Claude Desktop), not used as an interactive shell.
+
+### MCP client configuration
+
+`npx` runs the package’s `transcend-mcp-preferences` binary (see `bin` in `package.json`).
+
+```json
+{
+  "mcpServers": {
+    "transcend-preferences": {
+      "command": "npx",
+      "args": ["-y", "@transcend-io/mcp-server-preferences"],
+      "env": {
+        "TRANSCEND_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+When developing in this repository, reuse the same variable names from root **`secret.env`** in the `env` block, or use your client’s env-file support if it has one.
+
+### Run from the monorepo
+
+1. **Credentials** — From the repository root, copy [`secret.env.example`](../../../secret.env.example) to **`secret.env`** and set `TRANSCEND_API_KEY` (and optional URL overrides).
+
+2. **Build and run** — `node ./dist/cli.mjs` matches the `transcend-mcp-preferences` `bin` (use `node` because `pnpm exec transcend-mcp-preferences` may not resolve this package’s own binary in a pnpm workspace):
+
+```bash
+# from the repository root
+pnpm exec turbo run build --filter="@transcend-io/mcp-server-preferences..."
+set -a && source ./secret.env && set +a
+pnpm -F @transcend-io/mcp-server-preferences exec node ./dist/cli.mjs
+```
+
+**Alternative:** `./scripts/mcp-run.sh ./packages/mcp/mcp-server-preferences/dist/cli.mjs` (sources `secret.env` when present; run after build).
+
+See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout and `pnpm --filter` workflows.
+
+### Environment variables
+
+| Variable                | Required | Default                                    | Description       |
+| ----------------------- | -------- | ------------------------------------------ | ----------------- |
+| `TRANSCEND_API_KEY`     | Yes      | —                                          | Transcend API key |
+| `TRANSCEND_API_URL`     | No       | `https://multi-tenant.sombra.transcend.io` | Sombra API URL    |
+| `TRANSCEND_GRAPHQL_URL` | No       | `https://api.transcend.io`                 | GraphQL API URL   |
+
+**Monorepo:** keep these in root **`secret.env`** (from [`secret.env.example`](../../../secret.env.example)); see **Run from the monorepo**.
+
+## Tools
+
+- `preferences_query` — Query preference records
+- `preferences_upsert` — Create or update a preference record
+- `preferences_delete` — Delete a preference record
+- `preferences_append_identifiers` — Append identifiers to a record
+- `preferences_update_identifiers` — Update identifiers on a record
+- `preferences_delete_identifiers` — Delete identifiers from a record
+
+## Related packages
+
+Also available as part of the unified [`@transcend-io/mcp-server`](../mcp-server/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { t as getPreferenceTools } from "./tools-8p4M7SP7.mjs";
+import { TranscendGraphQLBase, TranscendRestClient, createMCPServer } from "@transcend-io/mcp-server-core";
+//#region src/cli.ts
+createMCPServer({
+	name: "transcend-mcp-preferences",
+	version: "1.0.0",
+	getTools: getPreferenceTools,
+	createClients: (auth, sombraUrl, graphqlUrl) => ({
+		rest: new TranscendRestClient(auth, sombraUrl),
+		graphql: new TranscendGraphQLBase(auth, graphqlUrl)
+	})
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport {\n  createMCPServer,\n  TranscendGraphQLBase,\n  TranscendRestClient,\n} from '@transcend-io/mcp-server-core';\n\nimport { getPreferenceTools } from './tools/index.js';\n\ncreateMCPServer({\n  name: 'transcend-mcp-preferences',\n  version: '1.0.0',\n  getTools: getPreferenceTools,\n  createClients: (auth, sombraUrl, graphqlUrl) => ({\n    rest: new TranscendRestClient(auth, sombraUrl),\n    graphql: new TranscendGraphQLBase(auth, graphqlUrl),\n  }),\n});\n"],"mappings":";;;;AASA,gBAAgB;CACd,MAAM;CACN,SAAS;CACT,UAAU;CACV,gBAAgB,MAAM,WAAW,gBAAgB;EAC/C,MAAM,IAAI,oBAAoB,MAAM,UAAU;EAC9C,SAAS,IAAI,qBAAqB,MAAM,WAAW;EACpD;CACF,CAAC"}

package/dist/index.d.mts

@@ -0,0 +1,102 @@
+import { ToolClients, ToolDefinition, z } from "@transcend-io/mcp-server-core";
+
+//#region src/tools/index.d.ts
+declare function getPreferenceTools(clients: ToolClients): ToolDefinition[];
+//#endregion
+//#region src/tools/preferences_query.d.ts
+declare const IdentifierSchema: z.ZodObject<{
+  value: z.ZodString;
+  type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type IdentifierInput = z.infer<typeof IdentifierSchema>;
+declare const QueryPreferencesSchema: z.ZodObject<{
+  partition: z.ZodString;
+  identifiers: z.ZodArray<z.ZodObject<{
+    value: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type QueryPreferencesInput = z.infer<typeof QueryPreferencesSchema>;
+//#endregion
+//#region src/tools/preferences_upsert.d.ts
+declare const UpsertPreferencesPurposeSchema: z.ZodObject<{
+  purpose: z.ZodString;
+  enabled: z.ZodBoolean;
+}, z.core.$strip>;
+type UpsertPreferencesPurposeInput = z.infer<typeof UpsertPreferencesPurposeSchema>;
+declare const UpsertPreferencesRecordSchema: z.ZodObject<{
+  identifier: z.ZodString;
+  identifierType: z.ZodOptional<z.ZodString>;
+  purposes: z.ZodArray<z.ZodObject<{
+    purpose: z.ZodString;
+    enabled: z.ZodBoolean;
+  }, z.core.$strip>>;
+  confirmed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type UpsertPreferencesRecordInput = z.infer<typeof UpsertPreferencesRecordSchema>;
+declare const UpsertPreferencesSchema: z.ZodObject<{
+  partition: z.ZodString;
+  records: z.ZodArray<z.ZodObject<{
+    identifier: z.ZodString;
+    identifierType: z.ZodOptional<z.ZodString>;
+    purposes: z.ZodArray<z.ZodObject<{
+      purpose: z.ZodString;
+      enabled: z.ZodBoolean;
+    }, z.core.$strip>>;
+    confirmed: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type UpsertPreferencesInput = z.infer<typeof UpsertPreferencesSchema>;
+//#endregion
+//#region src/tools/preferences_delete.d.ts
+declare const DeletePreferencesSchema: z.ZodObject<{
+  partition: z.ZodString;
+  identifiers: z.ZodArray<z.ZodObject<{
+    value: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type DeletePreferencesInput = z.infer<typeof DeletePreferencesSchema>;
+//#endregion
+//#region src/tools/preferences_append_identifiers.d.ts
+declare const AppendIdentifiersSchema: z.ZodObject<{
+  partition: z.ZodString;
+  user_id: z.ZodString;
+  identifiers: z.ZodArray<z.ZodObject<{
+    value: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AppendIdentifiersInput = z.infer<typeof AppendIdentifiersSchema>;
+//#endregion
+//#region src/tools/preferences_update_identifiers.d.ts
+declare const UpdateIdentifiersItemSchema: z.ZodObject<{
+  oldValue: z.ZodString;
+  newValue: z.ZodString;
+  type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UpdateIdentifiersItemInput = z.infer<typeof UpdateIdentifiersItemSchema>;
+declare const UpdateIdentifiersSchema: z.ZodObject<{
+  partition: z.ZodString;
+  user_id: z.ZodString;
+  identifiers: z.ZodArray<z.ZodObject<{
+    oldValue: z.ZodString;
+    newValue: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type UpdateIdentifiersInput = z.infer<typeof UpdateIdentifiersSchema>;
+//#endregion
+//#region src/tools/preferences_delete_identifiers.d.ts
+declare const DeleteIdentifiersSchema: z.ZodObject<{
+  partition: z.ZodString;
+  user_id: z.ZodString;
+  identifiers: z.ZodArray<z.ZodObject<{
+    value: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type DeleteIdentifiersInput = z.infer<typeof DeleteIdentifiersSchema>;
+//#endregion
+export { type AppendIdentifiersInput, AppendIdentifiersSchema, type DeleteIdentifiersInput, DeleteIdentifiersSchema, type DeletePreferencesInput, DeletePreferencesSchema, type IdentifierInput, IdentifierSchema, type QueryPreferencesInput, QueryPreferencesSchema, type UpdateIdentifiersInput, type UpdateIdentifiersItemInput, UpdateIdentifiersItemSchema, UpdateIdentifiersSchema, type UpsertPreferencesInput, type UpsertPreferencesPurposeInput, UpsertPreferencesPurposeSchema, type UpsertPreferencesRecordInput, UpsertPreferencesRecordSchema, UpsertPreferencesSchema, getPreferenceTools };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/tools/index.ts","../src/tools/preferences_query.ts","../src/tools/preferences_upsert.ts","../src/tools/preferences_delete.ts","../src/tools/preferences_append_identifiers.ts","../src/tools/preferences_update_identifiers.ts","../src/tools/preferences_delete_identifiers.ts"],"mappings":";;;iBASgB,kBAAA,CAAmB,OAAA,EAAS,WAAA,GAAc,cAAA;;;cCP7C,gBAAA,EAAgB,CAAA,CAAA,SAAA;;;;KAIjB,eAAA,GAAkB,CAAA,CAAE,KAAA,QAAa,gBAAA;AAAA,cAEhC,sBAAA,EAAsB,CAAA,CAAA,SAAA;;;;;;;KAIvB,qBAAA,GAAwB,CAAA,CAAE,KAAA,QAAa,sBAAA;;;cCVtC,8BAAA,EAA8B,CAAA,CAAA,SAAA;;;;KAI/B,6BAAA,GAAgC,CAAA,CAAE,KAAA,QAAa,8BAAA;AAAA,cAE9C,6BAAA,EAA6B,CAAA,CAAA,SAAA;;;;;;;;;KAM9B,4BAAA,GAA+B,CAAA,CAAE,KAAA,QAAa,6BAAA;AAAA,cAE7C,uBAAA,EAAuB,CAAA,CAAA,SAAA;;;;;;;;;;;;KAIxB,sBAAA,GAAyB,CAAA,CAAE,KAAA,QAAa,uBAAA;;;cChBvC,uBAAA,EAAuB,CAAA,CAAA,SAAA;;;;;;;KAIxB,sBAAA,GAAyB,CAAA,CAAE,KAAA,QAAa,uBAAA;;;cCJvC,uBAAA,EAAuB,CAAA,CAAA,SAAA;;;;;;;;KAKxB,sBAAA,GAAyB,CAAA,CAAE,KAAA,QAAa,uBAAA;;;cCPvC,2BAAA,EAA2B,CAAA,CAAA,SAAA;;;;;KAK5B,0BAAA,GAA6B,CAAA,CAAE,KAAA,QAAa,2BAAA;AAAA,cAE3C,uBAAA,EAAuB,CAAA,CAAA,SAAA;;;;;;;;;KAOxB,sBAAA,GAAyB,CAAA,CAAE,KAAA,QAAa,uBAAA;;;cCZvC,uBAAA,EAAuB,CAAA,CAAA,SAAA;;;;;;;;KAKxB,sBAAA,GAAyB,CAAA,CAAE,KAAA,QAAa,uBAAA"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as UpdateIdentifiersItemSchema, c as DeletePreferencesSchema, d as QueryPreferencesSchema, i as UpsertPreferencesSchema, l as AppendIdentifiersSchema, n as UpsertPreferencesPurposeSchema, o as UpdateIdentifiersSchema, r as UpsertPreferencesRecordSchema, s as DeleteIdentifiersSchema, t as getPreferenceTools, u as IdentifierSchema } from "./tools-8p4M7SP7.mjs";
+export { AppendIdentifiersSchema, DeleteIdentifiersSchema, DeletePreferencesSchema, IdentifierSchema, QueryPreferencesSchema, UpdateIdentifiersItemSchema, UpdateIdentifiersSchema, UpsertPreferencesPurposeSchema, UpsertPreferencesRecordSchema, UpsertPreferencesSchema, getPreferenceTools };

package/dist/tools-8p4M7SP7.mjs

@@ -0,0 +1,239 @@
+import { createListResult, createToolResult, defineTool, z } from "@transcend-io/mcp-server-core";
+//#region src/tools/preferences_query.ts
+const IdentifierSchema = z.object({
+	value: z.string().describe("Identifier value"),
+	type: z.string().optional().describe("Identifier type (optional)")
+});
+const QueryPreferencesSchema = z.object({
+	partition: z.string().describe("Partition/organization context"),
+	identifiers: z.array(IdentifierSchema).describe("Array of identifier objects to query")
+});
+function createPreferencesQueryTool(clients) {
+	const { rest } = clients;
+	return defineTool({
+		name: "preferences_query",
+		description: "Query consent preferences for multiple users by their identifiers",
+		category: "Preference Management",
+		readOnly: true,
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true
+		},
+		zodSchema: QueryPreferencesSchema,
+		handler: async ({ partition, identifiers }) => {
+			const result = await rest.queryPreferences({
+				partition,
+				identifiers: identifiers.map((id) => ({
+					value: id.value,
+					type: id.type
+				}))
+			});
+			return createListResult(result, { totalCount: result.length });
+		}
+	});
+}
+//#endregion
+//#region src/tools/preferences_append_identifiers.ts
+const AppendIdentifiersSchema = z.object({
+	partition: z.string().describe("Partition/organization context"),
+	user_id: z.string().describe("User ID to append identifiers to"),
+	identifiers: z.array(IdentifierSchema).describe("Array of identifier objects to append")
+});
+function createPreferencesAppendIdentifiersTool(clients) {
+	const { rest } = clients;
+	return defineTool({
+		name: "preferences_append_identifiers",
+		description: "Append additional identifiers to an existing user preference record",
+		category: "Preference Management",
+		readOnly: false,
+		confirmationHint: "Appends identifiers to the user preference record",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		},
+		zodSchema: AppendIdentifiersSchema,
+		handler: async ({ partition, user_id, identifiers }) => {
+			return createToolResult(true, {
+				...await rest.appendIdentifiers(partition, user_id, identifiers.map((id) => ({
+					value: id.value,
+					type: id.type
+				}))),
+				identifiersAdded: identifiers.length,
+				message: "Identifiers appended successfully"
+			});
+		}
+	});
+}
+//#endregion
+//#region src/tools/preferences_delete.ts
+const DeletePreferencesSchema = z.object({
+	partition: z.string().describe("Partition/organization context"),
+	identifiers: z.array(IdentifierSchema).describe("Array of identifier objects to delete")
+});
+function createPreferencesDeleteTool(clients) {
+	const { rest } = clients;
+	return defineTool({
+		name: "preferences_delete",
+		description: "Delete consent preferences for specified users",
+		category: "Preference Management",
+		readOnly: false,
+		confirmationHint: "Deletes preference data for the identifiers",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false
+		},
+		zodSchema: DeletePreferencesSchema,
+		handler: async ({ partition, identifiers }) => {
+			const result = await rest.deletePreferences(partition, identifiers.map((id) => ({
+				value: id.value,
+				type: id.type
+			})));
+			return createToolResult(true, {
+				...result,
+				message: `Successfully deleted ${result.count} preference records`
+			});
+		}
+	});
+}
+//#endregion
+//#region src/tools/preferences_delete_identifiers.ts
+const DeleteIdentifiersSchema = z.object({
+	partition: z.string().describe("Partition/organization context"),
+	user_id: z.string().describe("User ID to delete identifiers from"),
+	identifiers: z.array(IdentifierSchema).describe("Array of identifier objects to delete")
+});
+function createPreferencesDeleteIdentifiersTool(clients) {
+	const { rest } = clients;
+	return defineTool({
+		name: "preferences_delete_identifiers",
+		description: "Delete specific identifiers from a user preference record",
+		category: "Preference Management",
+		readOnly: false,
+		confirmationHint: "Deletes identifiers from the user preference record",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false
+		},
+		zodSchema: DeleteIdentifiersSchema,
+		handler: async ({ partition, user_id, identifiers }) => {
+			return createToolResult(true, {
+				...await rest.deleteIdentifiers(partition, user_id, identifiers.map((id) => ({
+					value: id.value,
+					type: id.type
+				}))),
+				identifiersDeleted: identifiers.length,
+				message: "Identifiers deleted successfully"
+			});
+		}
+	});
+}
+//#endregion
+//#region src/tools/preferences_update_identifiers.ts
+const UpdateIdentifiersItemSchema = z.object({
+	oldValue: z.string().describe("Old identifier value"),
+	newValue: z.string().describe("New identifier value"),
+	type: z.string().optional().describe("Identifier type (optional)")
+});
+const UpdateIdentifiersSchema = z.object({
+	partition: z.string().describe("Partition/organization context"),
+	user_id: z.string().describe("User ID to update identifiers for"),
+	identifiers: z.array(UpdateIdentifiersItemSchema).describe("Array of identifier update objects with old and new values")
+});
+function createPreferencesUpdateIdentifiersTool(clients) {
+	const { rest } = clients;
+	return defineTool({
+		name: "preferences_update_identifiers",
+		description: "Update existing identifiers for a user (e.g., when email changes)",
+		category: "Preference Management",
+		readOnly: false,
+		confirmationHint: "Updates identifiers for the user preference record",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		},
+		zodSchema: UpdateIdentifiersSchema,
+		handler: async ({ partition, user_id, identifiers }) => {
+			return createToolResult(true, {
+				...await rest.updateIdentifiers(partition, user_id, identifiers.map((id) => ({
+					oldValue: id.oldValue,
+					newValue: id.newValue,
+					type: id.type
+				}))),
+				identifiersUpdated: identifiers.length,
+				message: "Identifiers updated successfully"
+			});
+		}
+	});
+}
+//#endregion
+//#region src/tools/preferences_upsert.ts
+const UpsertPreferencesPurposeSchema = z.object({
+	purpose: z.string().describe("Purpose slug"),
+	enabled: z.boolean().describe("Whether consent is granted")
+});
+const UpsertPreferencesRecordSchema = z.object({
+	identifier: z.string().describe("User identifier"),
+	identifierType: z.string().optional().describe("Identifier type (optional)"),
+	purposes: z.array(UpsertPreferencesPurposeSchema).describe("Array of purpose consent settings"),
+	confirmed: z.boolean().optional().describe("Whether consent was explicitly confirmed")
+});
+const UpsertPreferencesSchema = z.object({
+	partition: z.string().describe("Partition/organization context"),
+	records: z.array(UpsertPreferencesRecordSchema).describe("Array of preference records to upsert")
+});
+function createPreferencesUpsertTool(clients) {
+	const { rest } = clients;
+	return defineTool({
+		name: "preferences_upsert",
+		description: "Batch upsert consent preference records for multiple users",
+		category: "Preference Management",
+		readOnly: false,
+		confirmationHint: "Creates or updates preference records for users",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		},
+		zodSchema: UpsertPreferencesSchema,
+		handler: async ({ partition, records }) => {
+			const result = await rest.upsertPreferences({
+				partition,
+				records: records.map((record) => ({
+					identifier: record.identifier,
+					identifierType: record.identifierType,
+					purposes: record.purposes.map((p) => ({
+						purpose: p.purpose,
+						enabled: p.enabled
+					})),
+					confirmed: record.confirmed
+				}))
+			});
+			return createToolResult(true, {
+				...result,
+				recordsProcessed: records.length,
+				message: `Successfully upserted ${result.count} preference records`
+			});
+		}
+	});
+}
+//#endregion
+//#region src/tools/index.ts
+function getPreferenceTools(clients) {
+	return [
+		createPreferencesQueryTool(clients),
+		createPreferencesUpsertTool(clients),
+		createPreferencesDeleteTool(clients),
+		createPreferencesAppendIdentifiersTool(clients),
+		createPreferencesUpdateIdentifiersTool(clients),
+		createPreferencesDeleteIdentifiersTool(clients)
+	];
+}
+//#endregion
+export { UpdateIdentifiersItemSchema as a, DeletePreferencesSchema as c, QueryPreferencesSchema as d, UpsertPreferencesSchema as i, AppendIdentifiersSchema as l, UpsertPreferencesPurposeSchema as n, UpdateIdentifiersSchema as o, UpsertPreferencesRecordSchema as r, DeleteIdentifiersSchema as s, getPreferenceTools as t, IdentifierSchema as u };
+
+//# sourceMappingURL=tools-8p4M7SP7.mjs.map

package/dist/tools-8p4M7SP7.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-8p4M7SP7.mjs","names":[],"sources":["../src/tools/preferences_query.ts","../src/tools/preferences_append_identifiers.ts","../src/tools/preferences_delete.ts","../src/tools/preferences_delete_identifiers.ts","../src/tools/preferences_update_identifiers.ts","../src/tools/preferences_upsert.ts","../src/tools/index.ts"],"sourcesContent":["import { createListResult, defineTool, z, type ToolClients } from '@transcend-io/mcp-server-core';\n\nexport const IdentifierSchema = z.object({\n  value: z.string().describe('Identifier value'),\n  type: z.string().optional().describe('Identifier type (optional)'),\n});\nexport type IdentifierInput = z.infer<typeof IdentifierSchema>;\n\nexport const QueryPreferencesSchema = z.object({\n  partition: z.string().describe('Partition/organization context'),\n  identifiers: z.array(IdentifierSchema).describe('Array of identifier objects to query'),\n});\nexport type QueryPreferencesInput = z.infer<typeof QueryPreferencesSchema>;\n\nexport function createPreferencesQueryTool(clients: ToolClients) {\n  const { rest } = clients;\n  return defineTool({\n    name: 'preferences_query',\n    description: 'Query consent preferences for multiple users by their identifiers',\n    category: 'Preference Management',\n    readOnly: true,\n    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },\n    zodSchema: QueryPreferencesSchema,\n    handler: async ({ partition, identifiers }) => {\n      const result = await rest.queryPreferences({\n        partition,\n        identifiers: identifiers.map((id) => ({\n          value: id.value,\n          type: id.type,\n        })),\n      });\n\n      return createListResult(result, {\n        totalCount: result.length,\n      });\n    },\n  });\n}\n","import { createToolResult, defineTool, z, type ToolClients } from '@transcend-io/mcp-server-core';\n\nimport { IdentifierSchema } from './preferences_query.js';\n\nexport const AppendIdentifiersSchema = z.object({\n  partition: z.string().describe('Partition/organization context'),\n  user_id: z.string().describe('User ID to append identifiers to'),\n  identifiers: z.array(IdentifierSchema).describe('Array of identifier objects to append'),\n});\nexport type AppendIdentifiersInput = z.infer<typeof AppendIdentifiersSchema>;\n\nexport function createPreferencesAppendIdentifiersTool(clients: ToolClients) {\n  const { rest } = clients;\n  return defineTool({\n    name: 'preferences_append_identifiers',\n    description: 'Append additional identifiers to an existing user preference record',\n    category: 'Preference Management',\n    readOnly: false,\n    confirmationHint: 'Appends identifiers to the user preference record',\n    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },\n    zodSchema: AppendIdentifiersSchema,\n    handler: async ({ partition, user_id, identifiers }) => {\n      const result = await rest.appendIdentifiers(\n        partition,\n        user_id,\n        identifiers.map((id) => ({\n          value: id.value,\n          type: id.type,\n        })),\n      );\n\n      return createToolResult(true, {\n        ...result,\n        identifiersAdded: identifiers.length,\n        message: 'Identifiers appended successfully',\n      });\n    },\n  });\n}\n","import { createToolResult, defineTool, z, type ToolClients } from '@transcend-io/mcp-server-core';\n\nimport { IdentifierSchema } from './preferences_query.js';\n\nexport const DeletePreferencesSchema = z.object({\n  partition: z.string().describe('Partition/organization context'),\n  identifiers: z.array(IdentifierSchema).describe('Array of identifier objects to delete'),\n});\nexport type DeletePreferencesInput = z.infer<typeof DeletePreferencesSchema>;\n\nexport function createPreferencesDeleteTool(clients: ToolClients) {\n  const { rest } = clients;\n  return defineTool({\n    name: 'preferences_delete',\n    description: 'Delete consent preferences for specified users',\n    category: 'Preference Management',\n    readOnly: false,\n    confirmationHint: 'Deletes preference data for the identifiers',\n    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },\n    zodSchema: DeletePreferencesSchema,\n    handler: async ({ partition, identifiers }) => {\n      const result = await rest.deletePreferences(\n        partition,\n        identifiers.map((id) => ({\n          value: id.value,\n          type: id.type,\n        })),\n      );\n\n      return createToolResult(true, {\n        ...result,\n        message: `Successfully deleted ${result.count} preference records`,\n      });\n    },\n  });\n}\n","import { createToolResult, defineTool, z, type ToolClients } from '@transcend-io/mcp-server-core';\n\nimport { IdentifierSchema } from './preferences_query.js';\n\nexport const DeleteIdentifiersSchema = z.object({\n  partition: z.string().describe('Partition/organization context'),\n  user_id: z.string().describe('User ID to delete identifiers from'),\n  identifiers: z.array(IdentifierSchema).describe('Array of identifier objects to delete'),\n});\nexport type DeleteIdentifiersInput = z.infer<typeof DeleteIdentifiersSchema>;\n\nexport function createPreferencesDeleteIdentifiersTool(clients: ToolClients) {\n  const { rest } = clients;\n  return defineTool({\n    name: 'preferences_delete_identifiers',\n    description: 'Delete specific identifiers from a user preference record',\n    category: 'Preference Management',\n    readOnly: false,\n    confirmationHint: 'Deletes identifiers from the user preference record',\n    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },\n    zodSchema: DeleteIdentifiersSchema,\n    handler: async ({ partition, user_id, identifiers }) => {\n      const result = await rest.deleteIdentifiers(\n        partition,\n        user_id,\n        identifiers.map((id) => ({\n          value: id.value,\n          type: id.type,\n        })),\n      );\n\n      return createToolResult(true, {\n        ...result,\n        identifiersDeleted: identifiers.length,\n        message: 'Identifiers deleted successfully',\n      });\n    },\n  });\n}\n","import { createToolResult, defineTool, z, type ToolClients } from '@transcend-io/mcp-server-core';\n\nexport const UpdateIdentifiersItemSchema = z.object({\n  oldValue: z.string().describe('Old identifier value'),\n  newValue: z.string().describe('New identifier value'),\n  type: z.string().optional().describe('Identifier type (optional)'),\n});\nexport type UpdateIdentifiersItemInput = z.infer<typeof UpdateIdentifiersItemSchema>;\n\nexport const UpdateIdentifiersSchema = z.object({\n  partition: z.string().describe('Partition/organization context'),\n  user_id: z.string().describe('User ID to update identifiers for'),\n  identifiers: z\n    .array(UpdateIdentifiersItemSchema)\n    .describe('Array of identifier update objects with old and new values'),\n});\nexport type UpdateIdentifiersInput = z.infer<typeof UpdateIdentifiersSchema>;\n\nexport function createPreferencesUpdateIdentifiersTool(clients: ToolClients) {\n  const { rest } = clients;\n  return defineTool({\n    name: 'preferences_update_identifiers',\n    description: 'Update existing identifiers for a user (e.g., when email changes)',\n    category: 'Preference Management',\n    readOnly: false,\n    confirmationHint: 'Updates identifiers for the user preference record',\n    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },\n    zodSchema: UpdateIdentifiersSchema,\n    handler: async ({ partition, user_id, identifiers }) => {\n      const result = await rest.updateIdentifiers(\n        partition,\n        user_id,\n        identifiers.map((id) => ({\n          oldValue: id.oldValue,\n          newValue: id.newValue,\n          type: id.type,\n        })),\n      );\n\n      return createToolResult(true, {\n        ...result,\n        identifiersUpdated: identifiers.length,\n        message: 'Identifiers updated successfully',\n      });\n    },\n  });\n}\n","import { createToolResult, defineTool, z, type ToolClients } from '@transcend-io/mcp-server-core';\n\nexport const UpsertPreferencesPurposeSchema = z.object({\n  purpose: z.string().describe('Purpose slug'),\n  enabled: z.boolean().describe('Whether consent is granted'),\n});\nexport type UpsertPreferencesPurposeInput = z.infer<typeof UpsertPreferencesPurposeSchema>;\n\nexport const UpsertPreferencesRecordSchema = z.object({\n  identifier: z.string().describe('User identifier'),\n  identifierType: z.string().optional().describe('Identifier type (optional)'),\n  purposes: z.array(UpsertPreferencesPurposeSchema).describe('Array of purpose consent settings'),\n  confirmed: z.boolean().optional().describe('Whether consent was explicitly confirmed'),\n});\nexport type UpsertPreferencesRecordInput = z.infer<typeof UpsertPreferencesRecordSchema>;\n\nexport const UpsertPreferencesSchema = z.object({\n  partition: z.string().describe('Partition/organization context'),\n  records: z.array(UpsertPreferencesRecordSchema).describe('Array of preference records to upsert'),\n});\nexport type UpsertPreferencesInput = z.infer<typeof UpsertPreferencesSchema>;\n\nexport function createPreferencesUpsertTool(clients: ToolClients) {\n  const { rest } = clients;\n  return defineTool({\n    name: 'preferences_upsert',\n    description: 'Batch upsert consent preference records for multiple users',\n    category: 'Preference Management',\n    readOnly: false,\n    confirmationHint: 'Creates or updates preference records for users',\n    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },\n    zodSchema: UpsertPreferencesSchema,\n    handler: async ({ partition, records }) => {\n      const result = await rest.upsertPreferences({\n        partition,\n        records: records.map((record) => ({\n          identifier: record.identifier,\n          identifierType: record.identifierType,\n          purposes: record.purposes.map((p) => ({\n            purpose: p.purpose,\n            enabled: p.enabled,\n          })),\n          confirmed: record.confirmed,\n        })),\n      });\n\n      return createToolResult(true, {\n        ...result,\n        recordsProcessed: records.length,\n        message: `Successfully upserted ${result.count} preference records`,\n      });\n    },\n  });\n}\n","import type { ToolDefinition, ToolClients } from '@transcend-io/mcp-server-core';\n\nimport { createPreferencesAppendIdentifiersTool } from './preferences_append_identifiers.js';\nimport { createPreferencesDeleteTool } from './preferences_delete.js';\nimport { createPreferencesDeleteIdentifiersTool } from './preferences_delete_identifiers.js';\nimport { createPreferencesQueryTool } from './preferences_query.js';\nimport { createPreferencesUpdateIdentifiersTool } from './preferences_update_identifiers.js';\nimport { createPreferencesUpsertTool } from './preferences_upsert.js';\n\nexport function getPreferenceTools(clients: ToolClients): ToolDefinition[] {\n  return [\n    createPreferencesQueryTool(clients),\n    createPreferencesUpsertTool(clients),\n    createPreferencesDeleteTool(clients),\n    createPreferencesAppendIdentifiersTool(clients),\n    createPreferencesUpdateIdentifiersTool(clients),\n    createPreferencesDeleteIdentifiersTool(clients),\n  ];\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@transcend-io/mcp-server-preferences",
+  "version": "0.1.0",
+  "description": "Transcend MCP Server — Preference Management tools.",
+  "homepage": "https://github.com/transcend-io/tools/tree/main/packages/mcp/mcp-server-preferences",
+  "license": "Apache-2.0",
+  "author": "Transcend Inc.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/transcend-io/tools.git",
+    "directory": "packages/mcp/mcp-server-preferences"
+  },
+  "bin": {
+    "transcend-mcp-preferences": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "@transcend-io/source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check:exports": "attw --pack . --ignore-rules cjs-resolves-to-esm",
+    "check:publint": "publint --level warning --strict --pack pnpm"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "catalog:",
+    "@transcend-io/mcp-server-core": "workspace:*",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "catalog:",
+    "@types/node": "catalog:",
+    "publint": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}