@teamix-evo/mcp 0.3.0 → 0.4.0

package/README.md

@@ -18,7 +18,7 @@
 | Group | Status | Tools | Naming |
 | --- | --- | --- | --- |
 | **registry** | ✅ shipping | `list_components` / `get_component_meta` / `find_components` | unprefixed (historical exception, see ADR 0011 §5) |
-| **design** | ✅ shipping | `design_list_principles` / `design_get_tokens` / `design_list_patterns` / `design_get_pattern` / `design_get_brand` | `<group>_<verb>_<noun>` |
+| **tokens** | ✅ shipping | `tokens_get` / `tokens_list` / `tokens_search` | `<group>_<verb>_<noun>` |
 | **skills** | ✅ shipping | `skills_list` / `skills_get` / `skills_find` | `<group>_<verb>_<noun>` |
 | **adr** | ✅ shipping | `adr_list` / `adr_get` / `adr_find` | `<group>_<verb>_<noun>` |
 | **scenario** | ⏸ v0.8 | `scenario_list` / `scenario_get_pack` | `<group>_<verb>_<noun>` |

package/dist/cli.js

@@ -40,10 +40,15 @@ function resolveManifestPath(startDir = process.cwd()) {
   }
   throw new Error(
     [
-      "Could not locate @teamix-evo/ui/manifest.json.",
-      `Tried env TEAMIX_EVO_UI_MANIFEST + walking up from ${startDir}.`,
-      "Either install @teamix-evo/ui in the consumer project, or set TEAMIX_EVO_UI_MANIFEST to an absolute path."
-    ].join(" ")
+      "Could not locate @teamix-evo/ui/manifest.json \u2014 the UI registry is not installed in this project.",
+      "",
+      "Fix one of:",
+      `  1. Install the package:  pnpm add @teamix-evo/ui   (or npm/yarn equivalent)`,
+      `  2. Point env at an existing manifest:  export TEAMIX_EVO_UI_MANIFEST=/abs/path/to/manifest.json`,
+      "",
+      `Searched: $TEAMIX_EVO_UI_MANIFEST, then walked up from ${startDir} looking for node_modules/@teamix-evo/ui/manifest.json (16 levels).`,
+      "Note: MCP currently has no online fallback \u2014 it does not fetch from the npm registry / unpkg."
+    ].join("\n")
   );
 }
 function loadManifest(path) {
@@ -238,11 +243,18 @@ import { z as z2 } from "zod";
 // src/adr-loader.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync } from "fs";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
 function resolveAdrRoot(startDir = process.cwd()) {
   const envPath = process.env.TEAMIX_EVO_ADR_ROOT;
   if (envPath && existsSync2(envPath)) {
     return envPath;
   }
+  try {
+    const here = dirname2(fileURLToPath(import.meta.url));
+    const bundled = join2(here, "data", "adr");
+    if (existsSync2(bundled)) return bundled;
+  } catch {
+  }
   let dir = resolve2(startDir);
   for (let i = 0; i < 16; i++) {
     const candidates = [
@@ -259,8 +271,8 @@ function resolveAdrRoot(startDir = process.cwd()) {
   throw new Error(
     [
       "Could not locate ADR directory.",
-      `Tried env TEAMIX_EVO_ADR_ROOT + walking up from ${startDir} for docs/adr/ or .teamix-evo/adr/.`,
-      "Either run from a teamix-evo monorepo, or set TEAMIX_EVO_ADR_ROOT to an absolute path."
+      `Tried env TEAMIX_EVO_ADR_ROOT, mcp-bundled snapshot, and walked up from ${startDir} for docs/adr/ or .teamix-evo/adr/.`,
+      "Either install @teamix-evo/mcp (carries ADR snapshot) or set TEAMIX_EVO_ADR_ROOT to an absolute path."
     ].join(" ")
   );
 }
@@ -544,8 +556,8 @@ function resolveSkillsRoot(startDir = process.cwd()) {
   throw new Error(
     [
       "Could not locate @teamix-evo/skills root.",
-      `Tried env TEAMIX_EVO_SKILLS_ROOT + walking up from ${startDir}.`,
-      "Either install @teamix-evo/skills or run from a monorepo, or set TEAMIX_EVO_SKILLS_ROOT to an absolute path."
+      `Tried env TEAMIX_EVO_SKILLS_ROOT and walked up from ${startDir} for packages/skills/ or node_modules/@teamix-evo/skills/.`,
+      "Install @teamix-evo/skills as a devDependency in your project (the scaffold adds it automatically)."
     ].join(" ")
   );
 }
@@ -795,20 +807,20 @@ function createSkillsGroup(opts = {}) {
   };
 }
 
-// src/groups/design.ts
+// src/groups/tokens.ts
 import { z as z4 } from "zod";
 
-// src/design-loader.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync3, statSync as statSync2 } from "fs";
+// src/tokens-loader.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 import { dirname as dirname4, join as join4, resolve as resolve4 } from "path";
-function resolveDesignRoot(startDir = process.cwd()) {
-  const envPath = process.env.TEAMIX_EVO_DESIGN_ROOT;
+function resolveTokensRoot(startDir = process.cwd()) {
+  const envPath = process.env.TEAMIX_EVO_TOKENS_ROOT;
   if (envPath && existsSync4(envPath)) {
     return envPath;
   }
   let dir = resolve4(startDir);
   for (let i = 0; i < 16; i++) {
-    const candidate = join4(dir, ".teamix-evo", "design");
+    const candidate = join4(dir, ".teamix-evo");
     if (existsSync4(candidate)) return candidate;
     const parent = dirname4(dir);
     if (parent === dir) break;
@@ -816,11 +828,11 @@ function resolveDesignRoot(startDir = process.cwd()) {
   }
   return null;
 }
-function loadDesign(rootDir) {
-  const root = rootDir ?? resolveDesignRoot();
+function loadTokens(rootDir) {
+  const root = rootDir ?? resolveTokensRoot();
   if (!root) return null;
   let variant = null;
-  const lockPath = join4(root, "pack.lock.json");
+  const lockPath = join4(root, "tokens-lock.json");
   if (existsSync4(lockPath)) {
     try {
       const raw = JSON.parse(readFileSync4(lockPath, "utf-8"));
@@ -831,47 +843,17 @@ function loadDesign(rootDir) {
   }
   return { rootDir: root, variant };
 }
-var PRINCIPLE_HEADING_RE = /^#{2,3}\s+(P\d+)\s*[·:]\s*(.+?)\s*$/;
-function readPrinciples(loaded) {
-  const filePath = join4(loaded.rootDir, "philosophy", "principles.md");
-  if (!existsSync4(filePath)) {
-    return {
-      principles: [],
-      sourcePath: null,
-      note: "philosophy/principles.md not found in this project. Run `teamix-evo design init <variant>` to install it."
-    };
-  }
-  const text = readFileSync4(filePath, "utf-8");
-  const lines = text.split(/\r?\n/);
-  const out = [];
-  for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(PRINCIPLE_HEADING_RE);
-    if (!m) continue;
-    let def = "";
-    for (let j = i + 1; j < lines.length && j < i + 8; j++) {
-      const candidate = lines[j].trim();
-      if (!candidate) continue;
-      if (/^#{1,6}\s/.test(candidate)) break;
-      def = candidate.replace(/^[*_>\s-]+/, "").trim();
-      break;
-    }
-    out.push({ id: m[1], name: m[2].trim(), oneLineDef: def });
-  }
-  return { principles: out, sourcePath: filePath };
-}
 function resolveTokensDir(loaded) {
   const projectRoot = dirname4(loaded.rootDir);
-  const lifted = join4(projectRoot, "tokens");
-  if (existsSync4(lifted)) return lifted;
-  const legacy = join4(loaded.rootDir, "foundations", "tokens");
-  if (existsSync4(legacy)) return legacy;
+  const rootTokens = join4(projectRoot, "tokens");
+  if (existsSync4(rootTokens)) return rootTokens;
   return null;
 }
 function readTokens(loaded) {
   const tokensDir = resolveTokensDir(loaded);
   const out = { sources: [] };
   if (!tokensDir) {
-    out.note = ".teamix-evo/tokens/ not found in this project (and no legacy foundations/tokens/).";
+    out.note = "tokens/ not found at project root.";
     return out;
   }
   const tryJson = (rel) => {
@@ -891,169 +873,186 @@ function readTokens(loaded) {
     return readFileSync4(fp, "utf-8");
   };
   out.base = tryJson("base.tokens.json");
-  out.semantic = tryJson("semantic.tokens.json");
   out.themeCss = tryText("tokens.theme.css");
   out.overridesCss = tryText("tokens.overrides.css");
   return out;
 }
-var VARIANT_PREFIX_RE = /^(cloud|opentrek|uni-manager|enterprise)-/i;
-function readPatternIndex(loaded) {
-  const patternsDir = join4(loaded.rootDir, "patterns");
-  if (!existsSync4(patternsDir)) return [];
+var W3C_KEYS = /* @__PURE__ */ new Set(["$value", "$type", "$description", "$extensions"]);
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function flattenTokens(base) {
+  if (!isPlainObject(base)) return [];
   const out = [];
-  for (const name of readdirSync3(patternsDir)) {
-    if (!name.endsWith(".md")) continue;
-    const fp = join4(patternsDir, name);
-    try {
-      if (!statSync2(fp).isFile()) continue;
-    } catch {
-      continue;
+  for (const [category, group] of Object.entries(base)) {
+    if (category.startsWith("$")) continue;
+    if (!isPlainObject(group)) continue;
+    for (const [name, leaf] of Object.entries(group)) {
+      if (name.startsWith("$")) continue;
+      if (!isPlainObject(leaf)) continue;
+      const type = typeof leaf.$type === "string" ? leaf.$type : void 0;
+      const values = {};
+      let description = typeof leaf.$description === "string" ? leaf.$description : void 0;
+      if (typeof leaf.$value === "string") {
+        values.default = leaf.$value;
+      }
+      for (const [modeKey, modeVal] of Object.entries(leaf)) {
+        if (W3C_KEYS.has(modeKey)) continue;
+        if (!isPlainObject(modeVal)) continue;
+        if (typeof modeVal.$value === "string") {
+          values[modeKey] = modeVal.$value;
+        }
+        if (!description && typeof modeVal.$description === "string") {
+          description = modeVal.$description;
+        }
+      }
+      if (Object.keys(values).length === 0) continue;
+      out.push({
+        category,
+        name,
+        ...type ? { type } : {},
+        values,
+        ...description ? { description } : {}
+      });
     }
-    const stem = name.replace(/\.md$/, "");
-    const text = readFileSync4(fp, "utf-8");
-    const titleMatch = text.match(/^#\s+(.+?)\s*$/m);
-    out.push({
-      id: stem,
-      title: titleMatch ? titleMatch[1] : stem,
-      sourcePath: fp,
-      variantSpecific: VARIANT_PREFIX_RE.test(stem)
-    });
   }
-  return out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
 }
-function readPatternContent(loaded, id) {
-  const stem = id.replace(/\.md$/, "");
-  const fp = join4(loaded.rootDir, "patterns", `${stem}.md`);
-  if (!existsSync4(fp)) return null;
+function listTokens(loaded) {
+  const snapshot = readTokens(loaded);
+  if (!snapshot.base) {
+    return {
+      variant: loaded.variant,
+      tokens: [],
+      sources: snapshot.sources,
+      note: snapshot.note ?? "base.tokens.json not found."
+    };
+  }
   return {
-    id: stem,
-    sourcePath: fp,
-    content: readFileSync4(fp, "utf-8")
+    variant: loaded.variant,
+    tokens: flattenTokens(snapshot.base),
+    sources: snapshot.sources
   };
 }
-function readBrand(loaded) {
-  const brandDir = join4(loaded.rootDir, "brand");
-  const out = {};
-  if (!existsSync4(brandDir)) {
-    out.note = "brand/ not present \u2014 this design variant does not ship brand-specific tone / voice / examples.";
-    return out;
+function searchTokens(loaded, query, limit = 20) {
+  const list = listTokens(loaded);
+  const q = query.trim().toLowerCase();
+  if (!q) {
+    return {
+      variant: list.variant,
+      query,
+      matches: [],
+      sources: list.sources,
+      note: "query is empty."
+    };
   }
-  for (const key of ["tone", "voice", "examples"]) {
-    const fp = join4(brandDir, `${key}.md`);
-    if (existsSync4(fp)) {
-      out[key] = { sourcePath: fp, content: readFileSync4(fp, "utf-8") };
-    }
+  if (list.note && list.tokens.length === 0) {
+    return {
+      variant: list.variant,
+      query,
+      matches: [],
+      sources: list.sources,
+      note: list.note
+    };
   }
-  return out;
+  const hits = list.tokens.filter((t) => {
+    if (t.category.toLowerCase().includes(q)) return true;
+    if (t.name.toLowerCase().includes(q)) return true;
+    if (t.description?.toLowerCase().includes(q)) return true;
+    return Object.values(t.values).some((v) => v.toLowerCase().includes(q));
+  });
+  hits.sort((a, b) => {
+    const c = a.category.localeCompare(b.category);
+    return c !== 0 ? c : a.name.localeCompare(b.name);
+  });
+  return {
+    variant: list.variant,
+    query,
+    matches: hits.slice(0, limit),
+    sources: list.sources
+  };
 }
 
-// src/groups/design.ts
+// src/groups/tokens.ts
 var EmptyInput = z4.object({});
-var GetPatternInput = z4.object({
-  id: z4.string().min(1)
+var SearchInput = z4.object({
+  query: z4.string().min(1),
+  limit: z4.number().int().min(1).max(100).optional()
 });
 var TOOLS4 = [
   {
-    name: "design_list_principles",
-    description: 'List the design principles defined by the consumer project\'s installed design variant. Reads `.teamix-evo/design/philosophy/principles.md` and parses headings of the form `## P1 \xB7 Name`. Returns id, display name, and a one-line definition for each. Use this when the user asks about "the four principles", "design philosophy", or to ground a design review in the variant\'s stated values. Returns `{ principles: [], note: "..." }` if the project hasn\'t installed a design pack.',
-    inputSchema: { type: "object", properties: {} }
-  },
-  {
-    name: "design_get_tokens",
-    description: "Fetch the consumer project's design tokens \u2014 parsed JSON from `.teamix-evo/tokens/base.tokens.json` and `semantic.tokens.json`, plus raw text of `tokens.theme.css` (variant theme) and `tokens.overrides.css` (user-owned overrides) when present. Use when AI needs to know what semantic colors / spacing / radii are available before writing component styles. JSON is for introspection; CSS is for copy-paste. Each tool result lists `sources` so you can cite paths.",
+    name: "tokens_get",
+    description: "Fetch the consumer project's design tokens \u2014 parsed JSON from `tokens/base.tokens.json`, plus raw text of `tokens.theme.css` (variant theme) and `tokens.overrides.css` (user-owned overrides) when present. Use when AI needs to know what semantic colors / spacing / radii are available before writing component styles. JSON is for introspection; CSS is for copy-paste. Each result lists `sources` so you can cite paths.",
     inputSchema: { type: "object", properties: {} }
   },
   {
-    name: "design_list_patterns",
-    description: "Index every pattern in `.teamix-evo/design/patterns/*.md` (page types, journeys, flows, plus variant-specific markers like `cloud-*`, `opentrek-*`, `uni-manager-*`). Returns `{ id, title, sourcePath, variantSpecific }` for each. Use this before `design_get_pattern` to discover which patterns exist. When both a baseline (`page-types`) and a variant-specific (`cloud-page-types`) entry are available, prefer the variant-specific one for projects that match.",
+    name: "tokens_list",
+    description: "List ALL design tokens as a flat array of entries `{ category, name, type, values, description }`. Categories come from top-level keys of base.tokens.json (e.g. `color`, `radius`, `spacing`). Each entry exposes resolved values keyed by mode (e.g. `light` / `dark` / `default`). Use this BEFORE writing styles to discover what semantic names are available \u2014 much cheaper than parsing the whole CSS file. Use `tokens_search` instead when you have a keyword.",
     inputSchema: { type: "object", properties: {} }
   },
   {
-    name: "design_get_pattern",
-    description: "Fetch the full markdown body of one pattern by id (filename stem, e.g. `page-types` or `cloud-page-types`). Use after `design_list_patterns` discovered the id. Returns the raw markdown plus `sourcePath`. Returns isError if the id does not exist \u2014 call `design_list_patterns` first to discover available ids.",
+    name: "tokens_search",
+    description: 'Substring match across token category / name / description / values (case-insensitive). Use when you remember a phrase ("primary" / "destructive" / "card-gap") but not the exact path. Returns up to `limit` matches (default 20). Combine with `tokens_get` if you need raw CSS text after locating an entry.',
     inputSchema: {
       type: "object",
       properties: {
-        id: {
-          type: "string",
-          description: 'Pattern id \u2014 filename stem under `patterns/`, e.g. "page-types", "cloud-page-types".'
+        query: { type: "string", description: "Free-text query." },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description: "Max matches to return (default 20)."
         }
       },
-      required: ["id"]
+      required: ["query"]
     }
-  },
-  {
-    name: "design_get_brand",
-    description: "Fetch the consumer project's variant-specific brand voice \u2014 `brand/tone.md`, `brand/voice.md`, `brand/examples.md`. Each is optional; the response contains only the files that exist. Some variants (like `_template` or `default`) ship no brand content \u2014 that's not an error, the response simply lists no entries. Use this when generating or reviewing user-facing copy, error messages, empty states, or onboarding text where brand voice matters.",
-    inputSchema: { type: "object", properties: {} }
   }
 ];
 var TOOL_NAMES4 = new Set(TOOLS4.map((t) => t.name));
-var NO_DESIGN_NOTE = ".teamix-evo/design/ not found in this project. Run `npx teamix-evo design init <variant>` to install a design pack.";
-function createDesignGroup(opts = {}) {
+var NO_TOKENS_NOTE = "tokens/ directory not found in this project. Run `npx teamix-evo tokens init <variant>` to install design tokens.";
+function createTokensGroup(opts = {}) {
   let cache = opts.loaded === void 0 ? void 0 : opts.loaded;
-  function getDesign() {
-    if (cache === void 0) cache = loadDesign(opts.rootDir);
+  function getLoaded() {
+    if (cache === void 0) cache = loadTokens(opts.rootDir);
     return cache;
   }
   return {
-    name: "design",
+    name: "tokens",
     tools: TOOLS4,
     async handle(name, args) {
       if (!TOOL_NAMES4.has(name)) return void 0;
-      const loaded = getDesign();
-      if (name === "design_list_principles") {
-        EmptyInput.parse(args ?? {});
-        if (!loaded) {
-          return jsonResult({ principles: [], sourcePath: null, note: NO_DESIGN_NOTE });
-        }
-        return jsonResult(readPrinciples(loaded));
-      }
-      if (name === "design_get_tokens") {
+      const loaded = getLoaded();
+      if (name === "tokens_get") {
         EmptyInput.parse(args ?? {});
         if (!loaded) {
-          return jsonResult({ sources: [], note: NO_DESIGN_NOTE });
+          return jsonResult({ sources: [], note: NO_TOKENS_NOTE });
         }
         return jsonResult(readTokens(loaded));
       }
-      if (name === "design_list_patterns") {
+      if (name === "tokens_list") {
         EmptyInput.parse(args ?? {});
         if (!loaded) {
-          return jsonResult({ patterns: [], note: NO_DESIGN_NOTE });
-        }
-        return jsonResult({
-          variant: loaded.variant,
-          patterns: readPatternIndex(loaded)
-        });
-      }
-      if (name === "design_get_pattern") {
-        const input = GetPatternInput.parse(args);
-        if (!loaded) {
-          return {
-            content: [{ type: "text", text: NO_DESIGN_NOTE }],
-            isError: true
-          };
-        }
-        const result = readPatternContent(loaded, input.id);
-        if (!result) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Pattern not found: ${input.id}. Use design_list_patterns to discover available ids.`
-              }
-            ],
-            isError: true
-          };
+          return jsonResult({
+            variant: null,
+            tokens: [],
+            sources: [],
+            note: NO_TOKENS_NOTE
+          });
         }
-        return jsonResult(result);
+        return jsonResult(listTokens(loaded));
       }
-      if (name === "design_get_brand") {
-        EmptyInput.parse(args ?? {});
+      if (name === "tokens_search") {
+        const parsed = SearchInput.parse(args ?? {});
         if (!loaded) {
-          return jsonResult({ note: NO_DESIGN_NOTE });
+          return jsonResult({
+            variant: null,
+            query: parsed.query,
+            matches: [],
+            sources: [],
+            note: NO_TOKENS_NOTE
+          });
         }
-        return jsonResult(readBrand(loaded));
+        return jsonResult(searchTokens(loaded, parsed.query, parsed.limit));
       }
       return void 0;
     }
@@ -1071,7 +1070,7 @@ function createServer(opts = {}) {
     createRegistryGroup(opts.registry),
     createAdrGroup(opts.adr),
     createSkillsGroup(opts.skills),
-    createDesignGroup(opts.design)
+    createTokensGroup(opts.tokens)
     // Future: createScenarioGroup(opts.scenario), // ADR 0011, v0.8
   ];
   const seen = /* @__PURE__ */ new Set();