@hayodev/crystallize-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HayoDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,304 @@
+# Crystallize MCP
+
+[![npm version](https://img.shields.io/npm/v/@hayodev/crystallize-mcp.svg)](https://npmjs.org/package/@hayodev/crystallize-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@hayodev/crystallize-mcp.svg)](https://npmjs.org/package/@hayodev/crystallize-mcp)
+[![license](https://img.shields.io/npm/l/@hayodev/crystallize-mcp.svg)](https://github.com/HayoDev/crystallize-mcp/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@hayodev/crystallize-mcp.svg)](https://npmjs.org/package/@hayodev/crystallize-mcp)
+
+MCP server for [Crystallize](https://crystallize.com) headless commerce. Gives AI agents read access to your catalogue, products, shapes, orders, customers, and tenant config — with deep links back to the Crystallize UI.
+
+Works with Claude Code, Claude Desktop, Cursor, Windsurf, Copilot, and any MCP-compatible client.
+
+## Getting started
+
+Standard MCP config (works in any client):
+
+```json
+{
+  "mcpServers": {
+    "crystallize": {
+      "command": "npx",
+      "args": ["-y", "@hayodev/crystallize-mcp@latest"],
+      "env": {
+        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant"
+      }
+    }
+  }
+}
+```
+
+Add `CRYSTALLIZE_ACCESS_TOKEN_ID` and `CRYSTALLIZE_ACCESS_TOKEN_SECRET` to the `env` block for PIM tools (shapes, orders, customers). See [Authentication](#authentication).
+
+<details>
+<summary>Claude Code</summary>
+
+```bash
+claude mcp add crystallize \
+  -e CRYSTALLIZE_TENANT_IDENTIFIER=your-tenant \
+  -e CRYSTALLIZE_ACCESS_TOKEN_ID=your-token-id \
+  -e CRYSTALLIZE_ACCESS_TOKEN_SECRET=your-token-secret \
+  -- npx -y @hayodev/crystallize-mcp@latest
+```
+
+Use `--scope project` to write to `.mcp.json` (shared with your team) or `--scope user` for personal use across all projects.
+
+Or run the guided setup wizard, which can optionally store tokens in the OS keychain instead of plain text:
+
+```bash
+npx @hayodev/crystallize-mcp --setup
+```
+
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Run the guided wizard — it writes directly to `claude_desktop_config.json` and can store tokens in the macOS Keychain so they never appear in the config file:
+
+```bash
+npx @hayodev/crystallize-mcp --setup --global
+```
+
+Or add the standard config manually to `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Add the standard config to your Cursor MCP settings (`~/.cursor/mcp.json` or the project-level `.cursor/mcp.json`).
+
+</details>
+
+<details>
+<summary>VS Code / GitHub Copilot</summary>
+
+Add the standard config to `.vscode/mcp.json` in your project root.
+
+```json
+{
+  "servers": {
+    "crystallize": {
+      "command": "npx",
+      "args": ["-y", "@hayodev/crystallize-mcp@latest"],
+      "env": {
+        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant",
+        "CRYSTALLIZE_ACCESS_TOKEN_ID": "your-token-id",
+        "CRYSTALLIZE_ACCESS_TOKEN_SECRET": "your-token-secret"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Add the standard config to `~/.codeium/windsurf/mcp_config.json`.
+
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+Add the standard config to `~/.gemini/settings.json`.
+
+</details>
+
+<details>
+<summary>JetBrains AI Assistant</summary>
+
+Add the standard config to `.junie/mcp.json` in your project root.
+
+</details>
+
+<details>
+<summary>Warp</summary>
+
+Add the standard config to `~/.warp/mcp.json`.
+
+</details>
+
+<details>
+<summary>Raycast</summary>
+
+Open "Install MCP Server" in Raycast and fill in:
+
+- **Command**: `npx`
+- **Arguments**: `-y @hayodev/crystallize-mcp@latest`
+- **Environment**: add `CRYSTALLIZE_TENANT_IDENTIFIER` and your token vars
+
+Or copy the standard config JSON above before opening the command — Raycast will auto-fill the form.
+
+</details>
+
+<details>
+<summary>From source</summary>
+
+```bash
+git clone https://github.com/HayoDev/crystallize-mcp.git
+cd crystallize-mcp
+npm install && npm run build
+npx . --setup --local   # writes .mcp.json pointing to local build
+```
+
+Or point your MCP client directly at the built entry point:
+
+```json
+{
+  "mcpServers": {
+    "crystallize": {
+      "command": "node",
+      "args": ["/path/to/crystallize-mcp/build/src/bin/crystallize-mcp.js"],
+      "env": {
+        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## Tools (12)
+
+### Catalogue (4 tools)
+
+| Tool                   | Description                                          |
+| ---------------------- | ---------------------------------------------------- |
+| `browse_catalogue`     | Traverse the item tree by path                       |
+| `get_item`             | Fetch an item by path or ID with full component data |
+| `search_catalogue`     | Keyword search across all items                      |
+| `get_product_variants` | List variants with pricing and stock                 |
+
+### Discovery (3 tools)
+
+| Tool                    | Description                                                           |
+| ----------------------- | --------------------------------------------------------------------- |
+| `list_discovery_shapes` | List all shapes with their queryable fields                           |
+| `browse_shape`          | Browse items of a shape with filters, pagination, and field selection |
+| `get_shape_fields`      | Detailed field info for a specific shape                              |
+
+### Shapes & Tenant (3 tools, requires auth)
+
+| Tool              | Description                                  |
+| ----------------- | -------------------------------------------- |
+| `list_shapes`     | All shapes with component summaries          |
+| `get_shape`       | Full component definition for a shape        |
+| `get_tenant_info` | Tenant configuration and available languages |
+
+### Orders (2 tools, requires auth)
+
+| Tool          | Description                                           |
+| ------------- | ----------------------------------------------------- |
+| `list_orders` | List orders for a customer with pagination            |
+| `get_order`   | Full order details — cart, payments, customer, totals |
+
+### Customers (2 tools, requires auth)
+
+| Tool             | Description                                                  |
+| ---------------- | ------------------------------------------------------------ |
+| `list_customers` | Search and list customers with pagination                    |
+| `get_customer`   | Full customer profile — addresses, meta, external references |
+
+## Authentication
+
+Catalogue and Discovery tools work without auth — just set `CRYSTALLIZE_TENANT_IDENTIFIER`.
+
+For PIM tools (shapes, tenant info, orders, customers), create an access token at:
+`https://app.crystallize.com/{tenant}/en/settings/access-tokens`
+
+> **Note:** Crystallize tokens inherit permissions from the user who created them. To restrict an agent to read-only access, generate the token under a user with a read-only role. See [Crystallize Roles](https://crystallize.com/docs/configuration/roles).
+
+### Environment variables
+
+| Variable                          | Required | Description                                                                        |
+| --------------------------------- | -------- | ---------------------------------------------------------------------------------- |
+| `CRYSTALLIZE_TENANT_IDENTIFIER`   | Yes      | Your tenant identifier from `app.crystallize.com/{tenant}`                         |
+| `CRYSTALLIZE_ACCESS_TOKEN_ID`     | No       | Access token ID for PIM API                                                        |
+| `CRYSTALLIZE_ACCESS_TOKEN_SECRET` | No       | Access token secret (paired with token ID)                                         |
+| `CRYSTALLIZE_STATIC_AUTH_TOKEN`   | No       | Static auth token (alternative to ID/secret pair)                                  |
+| `CRYSTALLIZE_ACCESS_MODE`         | No       | `read` (default), `write`, or `admin` — controls which tools are registered        |
+| `CRYSTALLIZE_PII_MODE`            | No       | `full` (default), `masked`, or `none` — controls PII in customer/order responses   |
+| `CRYSTALLIZE_AUDIT_LOG`           | No       | Path to write an audit log — `~` is expanded (e.g. `~/.crystallize-mcp/audit.log`) |
+
+### PII mode (opt-in)
+
+By default all customer and order data is returned as-is (`full`). Set `CRYSTALLIZE_PII_MODE` to opt in to data minimisation:
+
+| Mode     | Behaviour                                                                                                                                                                          |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `full`   | Default — all fields returned unchanged                                                                                                                                            |
+| `masked` | Emails → `h***@example.com`, phones → `***-1234`, addresses → city + country only                                                                                                  |
+| `none`   | Contact/PII fields stripped — names, emails, phones, addresses, meta, and external references removed. Non-contact data (order lines, payment types, totals) may still be present. |
+
+Applies to `list_customers`, `get_customer`, `list_orders`, and `get_order`. No effect on catalogue or shape tools.
+
+Relevant for teams handling real customer data, GDPR Article 25 compliance (data minimisation by design), or environments where the AI doesn't need raw contact details to do its job. A common pattern is `masked` on production and `full` on dev.
+
+### Audit log (opt-in)
+
+Set `CRYSTALLIZE_AUDIT_LOG` to an absolute file path to enable structured logging of every tool call:
+
+```json
+{
+  "ts": "2026-04-03T14:38:41Z",
+  "tool": "list_customers",
+  "params": { "first": 10 },
+  "result": "ok",
+  "tenant": "hageland-prod"
+}
+```
+
+One JSON line per call — timestamp, tool name, params, result (`ok`/`error`), and tenant. Response content is never logged.
+
+> **Note:** Params are logged as-is and may contain PII — for example, a `searchTerm` of `hani@example.com` or a `customerIdentifier`. Treat the audit log file as sensitive data and restrict access accordingly. Param scrubbing is on the roadmap but not yet implemented.
+
+Easy to pipe into log aggregators (Datadog, CloudWatch, Splunk) — but ensure your pipeline handles the file with appropriate access controls.
+
+### Keychain storage (optional)
+
+The setup wizard (`npx @hayodev/crystallize-mcp --setup`) can store tokens in the OS keychain (macOS Keychain, Windows Credential Manager, or libsecret on Linux) so they never appear as plain text in config files. This is particularly useful for:
+
+- **Claude Desktop users** — config is written to a JSON file with no CLI equivalent for secret management
+- **Shared `.mcp.json`** — when your project config is committed to git, keychain storage keeps tokens out of the repository
+
+When tokens are in the keychain, the config only needs `CRYSTALLIZE_TENANT_IDENTIFIER` — credentials are resolved automatically at startup.
+
+Note: CLI-based MCP clients (`claude mcp add`, Cursor, Copilot, etc.) store env vars as plain text in their config files and do not integrate with the OS keychain directly. If plain text env vars in a local config file are acceptable for your setup, the wizard's keychain option is not needed.
+
+### Access mode
+
+`CRYSTALLIZE_ACCESS_MODE` controls which tools the MCP server registers at startup:
+
+- **`read`** (default) — read-only tools only
+- **`write`** — includes tools that can create/update content (Phase 3)
+- **`admin`** — full access including webhooks and tenant config (Phase 3)
+
+## Deep links
+
+Every response includes clickable links to the Crystallize UI:
+
+- Items → `app.crystallize.com/@{tenant}/{language}/catalogue/{type}/{itemId}`
+- Shapes → `app.crystallize.com/@{tenant}/{language}/settings/shapes/{identifier}`
+- Orders → `app.crystallize.com/@{tenant}/{language}/orders/{orderId}`
+
+The language segment is automatically set from the tenant's default language, bootstrapped at server startup — no configuration needed. Tools that accept a `language` parameter (catalogue, search) use the requested language in both the API call and the generated link.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev          # build + start
+npm run lint         # oxlint
+npm run format       # oxlint --fix + oxfmt
+npm run typecheck    # tsc --noEmit
+npm run test         # build + node --test
+```
+
+## License
+
+MIT

package/build/src/audit.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Audit logger — writes one JSON line per tool call to a configured file.
+ *
+ * Never logs response content — only what was requested and the shape of the result.
+ */
+export interface AuditEntry {
+    ts: string;
+    tool: string;
+    params: Record<string, unknown>;
+    result: 'ok' | 'error';
+    tenant: string;
+}
+export declare class AuditLogger {
+    private readonly path;
+    private enabled;
+    constructor(path: string);
+    log(entry: AuditEntry): void;
+}
+/** Return a non-content status string for the audit log. */
+export declare function summariseResult(result: {
+    isError?: boolean;
+}): 'ok' | 'error';
+//# sourceMappingURL=audit.d.ts.map

package/build/src/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/audit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAQ;gBAEX,IAAI,EAAE,MAAM;IAUxB,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAW7B;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,OAAO,CAE7E"}

package/build/src/audit.js

@@ -0,0 +1,38 @@
+/**
+ * Audit logger — writes one JSON line per tool call to a configured file.
+ *
+ * Never logs response content — only what was requested and the shape of the result.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class AuditLogger {
+    path;
+    enabled = true;
+    constructor(path) {
+        this.path = path;
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        catch {
+            // Audit logging should never crash the server
+            this.enabled = false;
+        }
+    }
+    log(entry) {
+        if (!this.enabled) {
+            return;
+        }
+        try {
+            appendFileSync(this.path, JSON.stringify(entry) + '\n');
+        }
+        catch {
+            // Audit logging should never crash the server
+            this.enabled = false;
+        }
+    }
+}
+/** Return a non-content status string for the audit log. */
+export function summariseResult(result) {
+    return result.isError ? 'error' : 'ok';
+}
+//# sourceMappingURL=audit.js.map

package/build/src/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/audit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,MAAM,OAAO,WAAW;IACL,IAAI,CAAS;IACtB,OAAO,GAAG,IAAI,CAAC;IAEvB,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC;YACH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,8CAA8C;YAC9C,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IAED,GAAG,CAAC,KAAiB;QACnB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,8CAA8C;YAC9C,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;CACF;AAED,4DAA4D;AAC5D,MAAM,UAAU,eAAe,CAAC,MAA6B;IAC3D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACzC,CAAC"}

package/build/src/bin/crystallize-mcp.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Crystallize MCP Server — CLI entry point.
+ *
+ * Usage:
+ *   crystallize-mcp              Start the MCP server (stdio transport)
+ *   crystallize-mcp --setup           Interactive setup for Claude Code (.mcp.json)
+ *   crystallize-mcp --setup --global  Setup for Claude Desktop
+ *   crystallize-mcp --setup --local   Setup pointing at local build (for development)
+ */
+export {};
+//# sourceMappingURL=crystallize-mcp.d.ts.map

package/build/src/bin/crystallize-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crystallize-mcp.d.ts","sourceRoot":"","sources":["../../../src/bin/crystallize-mcp.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG"}

package/build/src/bin/crystallize-mcp.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Crystallize MCP Server — CLI entry point.
+ *
+ * Usage:
+ *   crystallize-mcp              Start the MCP server (stdio transport)
+ *   crystallize-mcp --setup           Interactive setup for Claude Code (.mcp.json)
+ *   crystallize-mcp --setup --global  Setup for Claude Desktop
+ *   crystallize-mcp --setup --local   Setup pointing at local build (for development)
+ */
+// Handle --setup before importing heavy deps
+if (process.argv.includes('--setup')) {
+    import('./setup.js').catch((err) => {
+        console.error('Setup failed:', err);
+        process.exit(1);
+    });
+}
+else {
+    startServer().catch((error) => {
+        console.error('Failed to start Crystallize MCP server:', error);
+        process.exit(1);
+    });
+}
+async function startServer() {
+    const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const { createCrystallizeMcpServer } = await import('../index.js');
+    const { CrystallizeClient } = await import('../client.js');
+    const crystallize = await CrystallizeClient.fromEnvOrKeychain();
+    const { server, client } = createCrystallizeMcpServer(crystallize);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`Crystallize MCP server running`);
+    console.error(`  Tenant: ${client.config.tenantIdentifier}`);
+    console.error(`  Access mode: ${client.config.accessMode}`);
+    console.error(`  Language: ${client.config.defaultLanguage ?? 'en (fallback)'}`);
+    console.error(`  PII mode: ${client.config.piiMode}`);
+    if (client.config.auditLog) {
+        console.error(`  Audit log: ${client.config.auditLog}`);
+    }
+    console.error(`  Auth: ${client.config.accessTokenId ? 'token' : client.config.staticAuthToken ? 'static' : 'none (public catalogue only)'}`);
+}
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+export {};
+//# sourceMappingURL=crystallize-mcp.js.map

package/build/src/bin/crystallize-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crystallize-mcp.js","sourceRoot":"","sources":["../../../src/bin/crystallize-mcp.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG;AAEH,6CAA6C;AAC7C,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;IACrC,MAAM,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC1C,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACrC,OAAO,CAAC,KAAK,CAAC,yCAAyC,EAAE,KAAK,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,WAAW;IACxB,MAAM,EAAE,oBAAoB,EAAE,GAC5B,MAAM,MAAM,CAAC,2CAA2C,CAAC,CAAC;IAC5D,MAAM,EAAE,0BAA0B,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACnE,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;IAE3D,MAAM,WAAW,GAAG,MAAM,iBAAiB,CAAC,iBAAiB,EAAE,CAAC;IAChE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,0BAA0B,CAAC,WAAW,CAAC,CAAC;IAEnE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAChD,OAAO,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,KAAK,CAAC,kBAAkB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAC5D,OAAO,CAAC,KAAK,CACX,eAAe,MAAM,CAAC,MAAM,CAAC,eAAe,IAAI,eAAe,EAAE,CAClE,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,eAAe,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,gBAAgB,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,CAAC,KAAK,CACX,WAAW,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,8BAA8B,EAAE,CAC/H,CAAC;AACJ,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/build/src/bin/setup.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Interactive setup for crystallize-mcp.
+ *
+ * Usage:
+ *   npx crystallize-mcp --setup
+ *   npx crystallize-mcp --setup --global
+ *
+ * Generates the MCP config for Claude Desktop or Claude Code.
+ */
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/build/src/bin/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/bin/setup.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG"}

package/build/src/bin/setup.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * Interactive setup for crystallize-mcp.
+ *
+ * Usage:
+ *   npx crystallize-mcp --setup
+ *   npx crystallize-mcp --setup --global
+ *
+ * Generates the MCP config for Claude Desktop or Claude Code.
+ */
+import { createInterface } from 'node:readline';
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { homedir } from 'node:os';
+import { isKeychainAvailable, writeCredentials } from '../credentials.js';
+const rl = createInterface({ input: process.stdin, output: process.stderr });
+function ask(question, defaultValue) {
+    const suffix = defaultValue ? ` (${defaultValue})` : '';
+    return new Promise(res => {
+        rl.question(`${question}${suffix}: `, answer => {
+            res(answer.trim() || defaultValue || '');
+        });
+    });
+}
+async function main() {
+    const isGlobal = process.argv.includes('--global');
+    const isLocal = process.argv.includes('--local');
+    console.error('\n🔧 Crystallize MCP Setup\n');
+    console.error('This will generate the MCP configuration for your Crystallize tenant.\n');
+    // Tenant identifier (required)
+    const tenant = await ask('Tenant identifier (from app.crystallize.com/{tenant})');
+    if (!tenant) {
+        console.error('\n❌ Tenant identifier is required.');
+        process.exit(1);
+    }
+    // Tenant ID (MongoDB UUID — find it at app.crystallize.com/{tenant}/en/settings/tenant)
+    const tenantId = await ask('Tenant ID (UUID from Settings → Tenant info, optional)');
+    // Auth tokens (optional)
+    console.error('\nAuth tokens are optional. Without them, you can still browse the public');
+    console.error('catalogue and use the Discovery API. Add tokens for PIM access (shapes, tenant info).\n');
+    const wantsAuth = await ask('Add auth tokens? (y/n)', 'n');
+    let tokenId = '';
+    let tokenSecret = '';
+    let staticToken = '';
+    if (wantsAuth.toLowerCase() === 'y') {
+        console.error('\nCreate tokens at: https://app.crystallize.com/' +
+            tenant +
+            '/en/settings/access-tokens\n');
+        const authType = await ask('Auth type: (1) Token ID + Secret  (2) Static token', '1');
+        if (authType === '2') {
+            staticToken = await ask('Static auth token');
+        }
+        else {
+            tokenId = await ask('Access Token ID');
+            tokenSecret = await ask('Access Token Signature Secret');
+        }
+    }
+    // Access mode
+    const accessMode = await ask('Access mode: read / write / admin', 'read');
+    // Keychain offer — only if tokens were entered and keychain is reachable
+    const hasSecrets = tokenId || tokenSecret || staticToken;
+    let useKeychain = false;
+    if (hasSecrets) {
+        const keychainAvailable = await isKeychainAvailable();
+        if (keychainAvailable) {
+            console.error('\n🔑 OS keychain detected (Keychain / Credential Manager / libsecret).');
+            const answer = await ask('Store tokens in OS keychain instead of config file? (recommended) y/n', 'y');
+            useKeychain = answer.toLowerCase() !== 'n';
+        }
+        else {
+            console.error('\n⚠️  OS keychain not available — tokens will be written to the config file.');
+        }
+    }
+    // Store to keychain if chosen
+    if (useKeychain && hasSecrets) {
+        await writeCredentials({
+            accessTokenId: tokenId || undefined,
+            accessTokenSecret: tokenSecret || undefined,
+            staticAuthToken: staticToken || undefined,
+        });
+        console.error('✅ Tokens saved to OS keychain.');
+    }
+    // Build env config — omit secrets if stored in keychain
+    const env = {
+        CRYSTALLIZE_TENANT_IDENTIFIER: tenant,
+    };
+    if (tenantId) {
+        env.CRYSTALLIZE_TENANT_ID = tenantId;
+    }
+    if (!useKeychain) {
+        if (tokenId) {
+            env.CRYSTALLIZE_ACCESS_TOKEN_ID = tokenId;
+        }
+        if (tokenSecret) {
+            env.CRYSTALLIZE_ACCESS_TOKEN_SECRET = tokenSecret;
+        }
+        if (staticToken) {
+            env.CRYSTALLIZE_STATIC_AUTH_TOKEN = staticToken;
+        }
+    }
+    if (accessMode !== 'read') {
+        env.CRYSTALLIZE_ACCESS_MODE = accessMode;
+    }
+    // Build MCP config entry
+    const mcpEntry = isLocal
+        ? {
+            command: 'node',
+            args: [resolvePath(process.cwd(), 'build/src/bin/crystallize-mcp.js')],
+            env,
+        }
+        : {
+            command: 'npx',
+            args: ['-y', '@hayodev/crystallize-mcp@latest'],
+            env,
+        };
+    if (isGlobal) {
+        // Claude Desktop config
+        const configPath = process.platform === 'darwin'
+            ? resolvePath(homedir(), 'Library/Application Support/Claude/claude_desktop_config.json')
+            : resolvePath(homedir(), 'AppData/Roaming/Claude/claude_desktop_config.json');
+        let config = {};
+        if (existsSync(configPath)) {
+            try {
+                config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            }
+            catch {
+                // start fresh
+            }
+        }
+        const servers = (config.mcpServers ?? {});
+        servers.crystallize = mcpEntry;
+        config.mcpServers = servers;
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+        console.error(`\n✅ Added to Claude Desktop config: ${configPath}`);
+    }
+    else {
+        // Local .mcp.json for Claude Code
+        const configPath = resolvePath(process.cwd(), '.mcp.json');
+        let config = {};
+        if (existsSync(configPath)) {
+            try {
+                config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            }
+            catch {
+                // start fresh
+            }
+        }
+        const servers = (config.mcpServers ?? {});
+        servers.crystallize = mcpEntry;
+        config.mcpServers = servers;
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+        console.error(`\n✅ Created ${configPath}`);
+    }
+    console.error('\nDone! The crystallize MCP server is now configured.');
+    console.error(`Tenant: ${tenant}`);
+    if (hasSecrets) {
+        const authType = tokenId ? 'token pair' : 'static token';
+        const storage = useKeychain ? 'OS keychain' : 'config file';
+        console.error(`Auth: ${authType} (stored in ${storage})`);
+    }
+    else {
+        console.error('Auth: none (public catalogue only)');
+    }
+    console.error(`Mode: ${accessMode}\n`);
+    rl.close();
+}
+main().catch((err) => {
+    console.error('Setup failed:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=setup.js.map

package/build/src/bin/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/bin/setup.ts"],"names":[],"mappings":"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"}