@brixies-mcp/server 1.12.8 → 1.12.10

package/README.md

@@ -1,30 +1,21 @@
 # Brixies MCP
 
-Local stdio MCP connector for the Brixies layout library. Requires Node.js 22+ and an eligible Brixies account with its own API key.
+Local MCP server for the Brixies layout library. Requires Node.js 22+ and an active Brixies API key and membership.
 
-## Version 1.12.8 — staging evaluation
+## Run
 
-This release is intended for staging evaluation, not a production rollout. It retains the existing staging API fallback. Set BRIXIES_API_URL explicitly for your environment. A public connector does not grant access to the authenticated library.
-
-Once this version is published, configure your MCP client to launch:
-
-```text
-npx -y @brixies-mcp/server@1.12.8
+```sh
+npx -y --prefer-online @brixies-mcp/server@latest
 ```
 
-Set these in the MCP process environment:
-
-- BRIXIES_API_URL: the Brixies REST API base URL supplied for your environment.
-- BRIXIES_API_KEY: your personal Brixies key.
-
-Do not embed the key in command arguments or share your client configuration. Restart the MCP process after updating its version or credentials. No .env file is loaded automatically.
+Configure BRIXIES_API_URL and BRIXIES_API_KEY in your client's MCP process environment. The official API base URL is `https://brixies.co/wp-json/brixies/v1`. Keep the key private and out of chats and version control. Preserve existing MCP servers when editing client configuration.
 
-Test the connection by asking the assistant to consult your Brixies preferences without preparing a page or fetching layout JSON.
+## Version 1.12.10
 
-## Changes
+Uses the production API by default and reports the same version in npm and MCP. Authentication errors preserve the server’s reason without assuming that a revoked key expired. Recovery instructions apply to all supported assistants.
 
-Same catalog/delivery logic as 1.12.7. Adds an executable npm entry point, a runtime-file allowlist and version identification 1.12.8.
+## Version 1.12.9
 
-Only index.js, lib/transforms.js, package.json and README.md ship in the package. Dependencies are installed by npm. No WordPress plugins, layouts, API keys or customer records are bundled.
+Reads the recommended release from existing API response headers. Adds one update notice per MCP process when a newer stable version is recommended. It makes no extra requests and preserves tool payloads. Restart the MCP process to resolve latest; opening a new chat alone may not restart it. Existing pinned configurations must be changed manually once. Offline or missing version metadata never blocks ordinary tools.
 
-All rights reserved. No open-source license is granted for this connector. Third-party dependencies retain their own licenses.
+The API endpoint defaults to `https://brixies.co/wp-json/brixies/v1`. An explicit `BRIXIES_API_URL` overrides this default; use your staging API URL only for staging tests. This server runs locally via stdio. Releases are distributed through npm.

package/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createUpdateNotice } from "./lib/update-notice.js";
 import { applyBemRename, mergeSnippets, validateBemName, isBlockClass, bxClone } from "./lib/transforms.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -8,11 +9,12 @@ import postcss from "postcss";
 import { deflateRawSync } from "node:zlib";
 import selectorParser from "postcss-selector-parser";
 
-const MCP_VERSION = "1.12.8";
+const MCP_VERSION = "1.12.10";
+const updateNotice = createUpdateNotice(MCP_VERSION);
 const MANUAL_JSON_DELIVERY_INSTRUCTIONS = "For manual JSON delivery, use the complete JSON value after __BRICKS_JSON__ from this tool response as the authoritative base and deliver one complete JSON code block, excluding the marker and surrounding diagnostics. If the user has not explicitly requested content-text edits, reproduce that JSON exactly. If the user explicitly requests content-text edits, change only the requested user-facing text values (for example headings, paragraphs, button labels or form labels/placeholders) at the identified locations. Preserve existing fields, HTML tags, attributes and dynamic-data tokens within those values; edit only the requested literal text. Do not infer other edits. If a requested text target is ambiguous, ask which target to edit before changing it. Preserve every unrelated value, class definition, ID, reference, CSS rule, script, code signature, element order and structural relationship. Confirmed BEM renames must still be performed by the JSON tool using new_name/new_names, not by rewriting its output. Never reconstruct or summarize the JSON, truncate it, split a combined snippet, add duplicate keys, or append an empty globalClasses field. When editing text, prefer parsing the authoritative JSON, updating only the requested text values and serializing the complete object with correct JSON escaping; serialization whitespace may change, but unrelated values must not. Do not claim verbatim delivery if text was edited. If the complete result cannot be delivered reliably, report that limitation instead of supplying partial or invented JSON. A request for JSON or text personalization alone does not authorize creating pages/classes or importing through Bricks tools; use native import tools only when the user explicitly requests a site import.";
 
-// Set BRIXIES_API_URL explicitly outside staging.
-const BRIXIES_API = process.env.BRIXIES_API_URL || "https://brixies-fip1.1wp.site/wp-json/brixies/v1";
+// Production by default. Set BRIXIES_API_URL explicitly to test against staging.
+const BRIXIES_API = process.env.BRIXIES_API_URL || "https://brixies.co/wp-json/brixies/v1";
 const BRIXIES_API_KEY = process.env.BRIXIES_API_KEY || "";
 
 // Stable identifier for API logs and firewall rules.
@@ -158,6 +160,7 @@ async function apiPreparationRequest(recipe) {
       headers:{'X-Brixies-Key':BRIXIES_API_KEY,'User-Agent':USER_AGENT,'Accept':'application/json','Content-Type':'application/json'},
       body:JSON.stringify(recipe),
     });
+    updateNotice.observe(res.headers?.get('X-Brixies-MCP-Recommended-Version'));
     requestStats.http_statuses[res.status] = (requestStats.http_statuses[res.status] || 0) + 1;
     const data = await res.json().catch(() => null);
     if (!res.ok) {
@@ -278,7 +281,8 @@ async function apiRequest(path) {
   }
   clearTimeout(timer);
 
-  requestStats.http_statuses[res.status] = (requestStats.http_statuses[res.status] || 0) + 1;
+  updateNotice.observe(res.headers?.get('X-Brixies-MCP-Recommended-Version'));
+    requestStats.http_statuses[res.status] = (requestStats.http_statuses[res.status] || 0) + 1;
   if (res.status === 429) {
     let payload;
     try { payload = await res.json(); } catch { payload = {}; }
@@ -308,10 +312,13 @@ async function apiRequest(path) {
   if (res.status === 401) {
     return {
       ok: false,
+      status: 401,
       error:
-        `Your Brixies API key was rejected (${data.message || "invalid, expired or revoked"}). ` +
-        "Keys expire after 90 days. Check or regenerate your key on your Brixies account page, " +
-        "then update BRIXIES_API_KEY in your Claude Desktop config and restart Claude Desktop.",
+        `Your Brixies API key was rejected. Server response: ${data.message || "Authentication failed; the server did not specify the cause."} ` +
+        "Do not infer expiration unless the server explicitly reports it. " +
+        "Check or regenerate your key at https://brixies.co/account/api-key/, " +
+        "then update BRIXIES_API_KEY in your assistant's local MCP configuration and restart the Brixies MCP connection. " +
+        "Do not paste your API key into the chat.",
     };
   }
   if (res.status === 403) {
@@ -342,6 +349,14 @@ const server = new McpServer({
 }, { instructions: SERVER_INSTRUCTIONS });
 
 
+function defineBrixiesTool(...args) {
+  const callback = args.pop();
+  return server.tool(...args, async (...input) => {
+    const result = await callback(...input);
+    return updateNotice.attach(result);
+  });
+}
+
 const preferenceFrameworkSchema = z.enum(['ACSS', 'Core Framework', 'ATF', 'Vanilla', 'all']).optional().describe('Explicit user choice only; omit to use account preference. all means all frameworks.');
 const preferenceVersionSchema = z.enum(['3', '4']).optional().describe('Explicit ACSS version for this request only. Omit to use account preference. ACSS 4 conversion requires Brixies API 1.4.0 or newer.');
 async function resolveAccountPreferences(framework, acss_version) {
@@ -375,20 +390,20 @@ async function prepareBrixiesPage(input) {
   const result = await apiFetch('/preparations', {schema_version:1,...parsed.data});
   return result.ok ? textResult(JSON.stringify(result.data)) : errorContent(result.error);
 }
-server.tool('prepare_brixies_page',
+defineBrixiesTool('prepare_brixies_page',
   'Create a private, expiring Brixies web-copy link for 1–20 selected layouts/components. Uses account preferences unless overridden. Call after the user requests this selection; confirm any BEM renames. Returns only the link, ID, expiry and count, never Bricks JSON. Does not import into a site. Do not retry automatically.' + " " + ID_PRESENTATION_INSTRUCTIONS,
   preparationFields, prepareBrixiesPage);
 
-server.tool('get_brixies_request_diagnostics', 'Read local request counts since this MCP process started. Makes no API calls. Not account-wide quota, remaining allowance, or AI token usage.', {}, async () => textResult(JSON.stringify(getRequestDiagnostics())));
+defineBrixiesTool('get_brixies_request_diagnostics', 'Read local request counts since this MCP process started. Makes no API calls. Not account-wide quota, remaining allowance, or AI token usage.', {}, async () => textResult(JSON.stringify(getRequestDiagnostics())));
 
-server.tool('get_brixies_preferences', 'Read authenticated account preferences; optional overrides apply only to this request, never update the account.',
+defineBrixiesTool('get_brixies_preferences', 'Read authenticated account preferences; optional overrides apply only to this request, never update the account.',
  { framework: preferenceFrameworkSchema, acss_version: preferenceVersionSchema },
  async ({framework, acss_version}) => {
    const r = await resolveAccountPreferences(framework, acss_version);
    return r.ok ? textResult(JSON.stringify(r.data)) : errorContent(r.error);
  });
 
-server.tool(
+defineBrixiesTool(
   "search_brixies_layouts",
   "Search Brixies layouts by framework, category, elements, plugins, visual style, use case, complexity or keyword" + " " + ID_PRESENTATION_INSTRUCTIONS,
   {
@@ -448,7 +463,7 @@ server.tool(
   }
 );
 
-server.tool(
+defineBrixiesTool(
   "search_brixies_components",
   "Search Brixies components by framework, category, elements, plugins or keyword" + " " + ID_PRESENTATION_INSTRUCTIONS,
   {
@@ -499,7 +514,7 @@ server.tool(
   }
 );
 
-server.tool(
+defineBrixiesTool(
   "get_brixies_item_details",
   "Get full details of a specific Brixies layout or component by its ID" + " " + ID_PRESENTATION_INSTRUCTIONS,
   {
@@ -1069,7 +1084,7 @@ async function deliverJson({ ids, names, destination = 'manual', policies = [],
   } catch (error) { return textResult(friendlyCodeMessage(error.message), true); }
 }
 
-server.tool('get_brixies_item_json',
+defineBrixiesTool('get_brixies_item_json',
   'Brixies JSON: first omit new_name, propose BEM rename and wait for confirmation. Use destination=bricks_native_mcp only for an actual native Bricks MCP import; review code choices with the user and pass review_token on the second call. Manual delivery remains the default. For manual delivery, preserve __BRICKS_JSON__ exactly unless the user explicitly requests content-text edits; then change only those text values and preserve all structure, classes, IDs, CSS and unrelated values. Do not create pages/classes through Bricks tools for JSON-only requests.',
   {
     id: itemIdSchema,
@@ -1083,7 +1098,7 @@ server.tool('get_brixies_item_json',
   },
   ({ id, new_name, destination, code_policy, review_token, reuse_global_classes, framework, acss_version }) => deliverJson({ ids: [id], names: new_name === undefined ? undefined : [new_name], destination, policies: code_policy ? [code_policy] : [], review_token, reuse_global_classes, framework, acss_version })
 );
-server.tool('get_brixies_page_json',
+defineBrixiesTool('get_brixies_page_json',
   'Fetch and merge 2–10 layouts. First omit new_names and wait for user confirmation. Native Bricks imports require destination=bricks_native_mcp, review_token and optional code_policies per layout (default: keep original CSS). No partial page is returned on failure. For manual delivery, deliver the complete combined __BRICKS_JSON__ in one block, unchanged except for explicitly requested content-text edits. Preserve structure, classes, IDs, CSS and unrelated values. Do not create pages/classes through Bricks tools for JSON-only requests.',
   {
     ids: z.array(itemIdSchema).min(2).max(10),
@@ -1099,7 +1114,7 @@ server.tool('get_brixies_page_json',
 );
 
 
-server.tool(
+defineBrixiesTool(
   "recommend_brixies_page_structure",
   "Recommend a full page structure using real Brixies layouts. Searches each section type and returns only layouts that actually exist in the library." + " " + ID_PRESENTATION_INSTRUCTIONS,
   {
@@ -1172,7 +1187,7 @@ server.tool(
 const filtersCache = new Map();
 const FILTERS_CACHE_TTL_MS = 10 * 60 * 1000;
 
-server.tool(
+defineBrixiesTool(
   "get_brixies_filters",
   "Get available filter values for Brixies search: categories, elements, plugins, visual styles and use cases. Call this first when unsure about exact names.",
   {

package/lib/update-notice.js

@@ -0,0 +1,21 @@
+// Only release numbers are accepted; server-provided prose is never relayed.
+export function createUpdateNotice(current) {
+  const parse = value => typeof value === 'string' && /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/.test(value)
+    ? value.split('.').map(Number) : null;
+  const newer = (a, b) => { for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] > b[i]; } return false; };
+  const running = parse(current);
+  let recommended = null;
+  let announced = false;
+  return {
+    observe(value) {
+      const candidate = parse(value);
+      if (!announced && running && candidate && newer(candidate, running) && (!recommended || newer(candidate, parse(recommended)))) recommended = value;
+    },
+    attach(result) {
+      if (announced || !recommended || !result || !Array.isArray(result.content)) return result;
+      announced = true;
+      const text = `Brixies MCP update available: running ${current}; recommended ${recommended}. Briefly inform the user once. If configured with @latest, restart the Brixies MCP process to load the update. A new chat alone may not restart it. If pinned to a version, update the local configuration first. Do not claim the update has already been installed. Continue handling the original tool result.`;
+      return { ...result, content: [...result.content, { type: 'text', text }] };
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brixies-mcp/server",
-  "version": "1.12.8",
+  "version": "1.12.10",
   "type": "module",
   "description": "Brixies authenticated catalog MCP",
   "main": "index.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node test/migration.test.mjs && node test/rename.test.mjs && node test/requests.test.mjs && node test/preparations.test.mjs"
+    "test": "node test/migration.test.mjs && node test/rename.test.mjs && node test/requests.test.mjs && node test/preparations.test.mjs && node test/updates.test.mjs && node test/update-integration.test.mjs && node test/production.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
@@ -29,7 +29,7 @@
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public",
-    "tag": "next",
+    "tag": "latest",
     "registry": "https://registry.npmjs.org/"
   }
 }