@hayodev/crystallize-mcp 0.1.1

package/build/src/tools/shapes.js

@@ -0,0 +1,194 @@
+/**
+ * Shape & tenant tools — inspect shapes, components, and tenant configuration.
+ */
+import { z } from 'zod';
+export function shapeTools(client) {
+    return [
+        {
+            name: 'list_shapes',
+            description: 'List all shapes defined in the tenant. Returns shape names, identifiers, types, and component counts with deep links to the Crystallize UI.',
+            schema: {},
+            handler: async () => {
+                const query = `
+          query ListShapes($tenantId: ID!) {
+            shape {
+              getMany(tenantId: $tenantId) {
+                identifier
+                name
+                type
+                components {
+                  id
+                  name
+                  type
+                }
+              }
+            }
+          }
+        `;
+                const data = await client.api.pimApi(query, {
+                    tenantId: client.config.tenantId,
+                });
+                const shapes = data.shape
+                    .getMany;
+                if (!shapes?.length) {
+                    return {
+                        content: [
+                            { type: 'text', text: 'No shapes found in this tenant.' },
+                        ],
+                    };
+                }
+                const lines = [
+                    `${shapes.length} shape(s) in tenant "${client.config.tenantIdentifier}":\n`,
+                ];
+                for (const shape of shapes) {
+                    lines.push(`${shape.name} (${shape.identifier}) [${shape.type}]`);
+                    lines.push(`  Components: ${shape.components?.length ?? 0}`);
+                    if (shape.components?.length) {
+                        const componentList = shape.components
+                            .map(c => `${c.id} (${c.type})`)
+                            .join(', ');
+                        lines.push(`  ${componentList}`);
+                    }
+                    lines.push(`  Link: ${client.shapeLink(shape.identifier)}`);
+                    lines.push('');
+                }
+                return {
+                    content: [{ type: 'text', text: lines.join('\n') }],
+                };
+            },
+        },
+        {
+            name: 'get_shape',
+            description: 'Get the full component definition for a shape. Shows all components with their types, descriptions, and configuration. Useful for understanding what data a shape expects.',
+            schema: {
+                identifier: z
+                    .string()
+                    .describe('Shape identifier, e.g. "product" or "blog-post"'),
+            },
+            handler: async (params) => {
+                const { identifier } = params;
+                const query = `
+          query GetShape($identifier: String!, $tenantId: ID!) {
+            shape {
+              get(identifier: $identifier, tenantId: $tenantId) {
+                identifier
+                name
+                type
+                components {
+                  id
+                  name
+                  type
+                  description
+                  config {
+                    ... on ComponentConfig {
+                      min
+                      max
+                    }
+                  }
+                }
+                variantComponents {
+                  id
+                  name
+                  type
+                  description
+                }
+              }
+            }
+          }
+        `;
+                const data = await client.api.pimApi(query, {
+                    identifier,
+                    tenantId: client.config.tenantId,
+                });
+                const shape = data.shape
+                    .get;
+                if (!shape) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Shape "${identifier}" not found. Use list_shapes to see available shapes.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const lines = [
+                    `${shape.name} (${shape.identifier}) [${shape.type}]`,
+                    `Link: ${client.shapeLink(shape.identifier)}`,
+                    '',
+                ];
+                if (shape.components?.length) {
+                    lines.push(`Item Components (${shape.components.length}):`);
+                    for (const comp of shape.components) {
+                        lines.push(`  ${comp.id} — ${comp.name} [${comp.type}]`);
+                        if (comp.description) {
+                            lines.push(`    ${comp.description}`);
+                        }
+                    }
+                    lines.push('');
+                }
+                if (shape.variantComponents?.length) {
+                    lines.push(`Variant Components (${shape.variantComponents.length}):`);
+                    for (const comp of shape.variantComponents) {
+                        lines.push(`  ${comp.id} — ${comp.name} [${comp.type}]`);
+                        if (comp.description) {
+                            lines.push(`    ${comp.description}`);
+                        }
+                    }
+                }
+                return {
+                    content: [{ type: 'text', text: lines.join('\n') }],
+                };
+            },
+        },
+        {
+            name: 'get_tenant_info',
+            description: 'Get tenant configuration including name, identifier, available languages, and default language.',
+            schema: {},
+            handler: async () => {
+                const query = `
+          query GetTenant($identifier: String!) {
+            tenant {
+              get(identifier: $identifier) {
+                id
+                identifier
+                name
+                defaults {
+                  language
+                  currency
+                }
+                availableLanguages {
+                  code
+                  name
+                }
+              }
+            }
+          }
+        `;
+                const data = await client.api.pimApi(query, {
+                    identifier: client.config.tenantIdentifier,
+                });
+                const tenant = data.tenant.get;
+                const lines = [
+                    `${tenant.name}`,
+                    `  Identifier: ${tenant.identifier}`,
+                    `  ID: ${tenant.id}`,
+                    `  Default language: ${tenant.defaults?.language ?? 'en'}`,
+                    `  Default currency: ${tenant.defaults?.currency ?? 'n/a'}`,
+                    `  UI: https://app.crystallize.com/${tenant.identifier}`,
+                ];
+                if (tenant.availableLanguages?.length) {
+                    const langs = tenant.availableLanguages
+                        .map(l => `${l.name} (${l.code})`)
+                        .join(', ');
+                    lines.push(`  Languages: ${langs}`);
+                }
+                return {
+                    content: [{ type: 'text', text: lines.join('\n') }],
+                };
+            },
+        },
+    ];
+}
+//# sourceMappingURL=shapes.js.map

package/build/src/tools/shapes.js.map

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

package/build/src/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared types for crystallize-mcp.
+ */
+import type { z, ZodRawShape } from 'zod';
+/** Access mode controls which tools are registered. */
+export type AccessMode = 'read' | 'write' | 'admin';
+/** MCP tool result content block. */
+export interface TextContent {
+    type: 'text';
+    text: string;
+}
+/** MCP tool result — uses index signature to satisfy MCP SDK. */
+export interface ToolResult {
+    [key: string]: unknown;
+    content: TextContent[];
+    isError?: boolean;
+}
+/** A complete tool definition — schema, handler, and metadata. */
+export interface ToolDefinition<T extends ZodRawShape = ZodRawShape> {
+    name: string;
+    description: string;
+    schema: T;
+    /** Minimum access mode required to use this tool. Defaults to 'read'. */
+    mode?: AccessMode;
+    handler: (params: z.objectOutputType<T, z.ZodTypeAny>) => Promise<ToolResult>;
+}
+/** PII masking mode for customer/order data. */
+export type PiiMode = 'full' | 'masked' | 'none';
+/** Crystallize environment configuration. */
+export interface CrystallizeConfig {
+    tenantIdentifier: string;
+    tenantId?: string;
+    accessTokenId?: string;
+    accessTokenSecret?: string;
+    staticAuthToken?: string;
+    accessMode: AccessMode;
+    defaultLanguage?: string;
+    piiMode?: PiiMode;
+    auditLog?: string;
+}
+/** Error categories for actionable error messages. */
+export type ErrorCategory = 'auth' | 'not_found' | 'rate_limit' | 'permission' | 'validation' | 'unknown';
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAE1C,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpD,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC;IACV,yEAAyE;IACzE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAC/E;AAED,gDAAgD;AAChD,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sDAAsD;AACtD,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,SAAS,CAAC"}

package/build/src/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for crystallize-mcp.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/build/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@hayodev/crystallize-mcp",
+  "version": "0.1.1",
+  "description": "Crystallize MCP — headless commerce tools for AI agents. Browse catalogue, search products, inspect shapes, manage orders via Model Context Protocol.",
+  "type": "module",
+  "main": "build/src/index.js",
+  "bin": {
+    "crystallize-mcp": "build/src/bin/crystallize-mcp.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HayoDev/crystallize-mcp.git"
+  },
+  "homepage": "https://github.com/HayoDev/crystallize-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/HayoDev/crystallize-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "build/src",
+    "LICENSE",
+    "!*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf build",
+    "start": "node build/src/bin/crystallize-mcp.js",
+    "dev": "npm run build && npm start",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxlint --fix && oxfmt --write .",
+    "check-format": "oxlint && oxfmt --check .",
+    "test": "npm run build && node --test build/tests/**/*.test.js",
+    "test:no-build": "node --test build/tests/**/*.test.js",
+    "prepare": "sh scripts/install-hooks.sh"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "crystallize",
+    "headless-commerce",
+    "ecommerce",
+    "pim",
+    "catalogue",
+    "graphql",
+    "model-context-protocol",
+    "ai-agents",
+    "ai-coding",
+    "claude",
+    "cursor",
+    "copilot"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "HayoDev",
+  "license": "MIT",
+  "dependencies": {
+    "@crystallize/js-api-client": "^4.0.0",
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.23.0"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.58.0",
+    "typescript": "^5.7.0"
+  }
+}