@hyperfixi/mcp-server 3.1.1 → 3.3.0

package/README.md

@@ -118,12 +118,12 @@ The **103** tools below, plus the **5** GRAIL tools above, total **108** defined
 
 ### Pattern Lookup (4)
 
-| Tool                    | Description                                                    |
-| ----------------------- | -------------------------------------------------------------- |
-| `get_examples`          | Get working code examples matching a task description          |
-| `search_patterns`       | Search pattern database by keyword or category                 |
-| `translate_hyperscript` | Translate keywords between 24 languages (pattern substitution) |
-| `get_pattern_stats`     | Get statistics about patterns and languages                    |
+| Tool                    | Description                                                                                |
+| ----------------------- | ------------------------------------------------------------------------------------------ |
+| `get_examples`          | Get working code examples matching a task description                                      |
+| `search_patterns`       | Search pattern database by keyword or category                                             |
+| `translate_hyperscript` | Translate between 24 languages (same engine as `translate_code`, without its verification) |
+| `get_pattern_stats`     | Get statistics about patterns and languages                                                |
 
 ### LSP Bridge (4)
 

package/dist/index.js

@@ -474,7 +474,7 @@ function simpleIntentRecognition(code) {
 var patternTools = [
   {
     name: "get_examples",
-    description: 'Get hyperscript code examples matching a natural language task description (e.g., "toggle a class on click"). Returns working code with quality scores. Best for generating new code by example.',
+    description: 'Get hyperscript code examples matching a natural language task description (e.g., "toggle a class on click"). Returns code verified to run on at least one engine, each tagged with `engine` (both = upstream _hyperscript and hyperfixi, hyperscript = upstream only, lokascript = hyperfixi only), plus quality scores. Best for generating new code by example.',
     inputSchema: {
       type: "object",
       properties: {
@@ -498,7 +498,7 @@ var patternTools = [
   },
   {
     name: "search_patterns",
-    description: "Search the pattern database by keyword or category filter (class-manipulation, visibility, async, validation, etc.). Unlike get_examples which takes task descriptions, this searches pattern names and content.",
+    description: "Search the pattern database by keyword, optionally within one category (events, dom-manipulation, class-manipulation, visibility, forms, async, etc.). Unlike get_examples which takes task descriptions, this searches pattern names and content.",
     inputSchema: {
       type: "object",
       properties: {
@@ -521,7 +521,7 @@ var patternTools = [
   },
   {
     name: "translate_hyperscript",
-    description: "Translate hyperscript keywords between any of 24 languages via pattern substitution. Preserves selectors and values. For higher-fidelity translation with grammar transformation, use translate_code instead.",
+    description: "Translate hyperscript between any of 24 languages with @lokascript/semantic (parse, then render in the target language's word order); selectors and values are preserved. Same engine as translate_code, which also returns a fidelity verification and name-collision warnings.",
     inputSchema: {
       type: "object",
       properties: {
@@ -576,7 +576,11 @@ async function handlePatternTool(name, args) {
                   examples: examples.map((ex) => ({
                     task: ex.prompt,
                     code: ex.completion,
-                    quality: ex.qualityScore
+                    quality: ex.qualityScore,
+                    // Which engine(s) are verified to run it (both | lokascript |
+                    // hyperscript) — patterns-reference never serves one that
+                    // runs on neither.
+                    engine: ex.engine
                   })),
                   count: examples.length,
                   language
@@ -599,11 +603,7 @@ async function handlePatternTool(name, args) {
         const ref = patternsRef.createPatternsReference({ readonly: true });
         let patterns;
         try {
-          if (category) {
-            patterns = await ref.getPatternsByCategory(category);
-          } else {
-            patterns = await ref.searchPatterns(query, { limit });
-          }
+          patterns = await ref.searchPatterns(query, { category, limit });
         } finally {
           ref.close();
         }
@@ -617,7 +617,7 @@ async function handlePatternTool(name, args) {
                     id: p.id,
                     title: p.title,
                     code: p.rawCode,
-                    category: p.feature
+                    category: p.category
                   })),
                   count: patterns.length,
                   query
@@ -920,7 +920,7 @@ function handleWithBuiltinExamples(name, args) {
                 builtinExamples: BUILTIN_EXAMPLES.length,
                 categories: [...new Set(BUILTIN_EXAMPLES.map((ex) => ex.category))],
                 supportedLanguages: ["en"],
-                note: "Install @hyperfixi/patterns-reference for 106 patterns, 1378 translations, 414 LLM examples"
+                note: "Install @hyperfixi/patterns-reference for the full pattern database: patterns, their translations in 24 languages, and LLM examples"
               },
               null,
               2
@@ -1255,6 +1255,11 @@ try {
   semanticPackage = await import("@lokascript/semantic");
 } catch {
 }
+var coreParse = null;
+try {
+  coreParse = (await import("@hyperfixi/core")).parse;
+} catch {
+}
 var cachedAnalyzer = null;
 function getSemanticAnalyzer() {
   if (!semanticPackage) return null;
@@ -1274,6 +1279,8 @@ function getSemanticAnalyzer() {
         if (result.tokensConsumed !== void 0) out.tokensConsumed = result.tokensConsumed;
         if (result.node) {
           out.command = { name: result.node.action, roles: result.node.roles };
+          const unconsumed = (result.node.diagnostics ?? []).filter((d) => d.code === "unconsumed-input" && d.message).map((d) => d.message);
+          if (unconsumed.length > 0) out.unconsumed = unconsumed;
         }
         if (result.error) out.errors = [result.error];
         return out;
@@ -1291,7 +1298,7 @@ function getSemanticAnalyzer() {
 var validationTools = [
   {
     name: "validate_hyperscript",
-    description: "Check hyperscript code for syntax errors and role warnings. Use as the FIRST validation step before returning code to users. For detailed line/column positions, use get_diagnostics instead.",
+    description: `Check hyperscript code for syntax errors and role warnings. Use as the FIRST validation step before returning code to users. English is also checked against hyperfixi's own parser (errors with source "core-parser"); tokens the semantic parser could not bind are warned as UNCONSUMED_INPUT, and a translation of that code drops them. It checks one snippet on its own, so it cannot tell whether a translation kept every clause: use score_fidelity (or translate_code's verification) for that. For detailed line/column positions, use get_diagnostics instead.`,
     inputSchema: {
       type: "object",
       properties: {
@@ -1626,6 +1633,7 @@ function validateHyperscript(code, language) {
   const validCommands = getValidCommandsForLanguage(language);
   const eventKeywords = getEventHandlerKeywords(language);
   let semanticInfo = null;
+  let semanticEvent;
   const analyzer = getSemanticAnalyzer();
   if (analyzer) {
     try {
@@ -1648,6 +1656,28 @@ function validateHyperscript(code, language) {
           errors.push({ message: err, source: "semantic-parser" });
         }
       }
+      const ev = result2.command?.roles?.get("event");
+      const evName = ev?.value ?? ev?.raw;
+      if (result2.command?.name === "on" && typeof evName === "string") semanticEvent = evName;
+      for (const msg of result2.unconsumed ?? []) {
+        warnings.push({
+          code: "UNCONSUMED_INPUT",
+          message: `Semantic parser ${msg.replace(/^body clause /, "left part of the body unbound: ")}`,
+          suggestion: "translate_code and the semantic IR drop these tokens. Rephrase with an explicit command or role marker (e.g. `call me.click()`), or check the translation's verification.referenceComplete.",
+          source: "semantic-parser"
+        });
+      }
+      if (language !== "en" && result2.confidence >= 0.5) {
+        const findings = semanticPackage?.findNameCollisions?.(code, language) ?? [];
+        for (const finding of findings) {
+          warnings.push({
+            code: "NAME_COLLISION",
+            message: finding.message,
+            suggestion: finding.rename ? `Rename \`${finding.name}\` to \`${finding.rename}\` in the ${finding.occurrences.length} place(s) the parse reads it as the variable.` : `Rename \`${finding.name}\`.`,
+            source: "semantic-parser"
+          });
+        }
+      }
       if (result2.confidence > 0 && result2.confidence < 0.5) {
         warnings.push({
           message: `Low parsing confidence (${(result2.confidence * 100).toFixed(0)}%)`,
@@ -1760,7 +1790,7 @@ function validateHyperscript(code, language) {
     });
   }
   const eventPattern = new RegExp(
-    `(?:^|\\n|;|\\bthen\\b)\\s*(${eventKeywords.join("|")})\\s+(\\w+)`,
+    `(?:^|\\n|;|\\bthen\\b)\\s*(${eventKeywords.join("|")})\\s+([\\w:.-]+)`,
     "gim"
   );
   const eventMatches = code.matchAll(eventPattern);
@@ -1814,16 +1844,29 @@ function validateHyperscript(code, language) {
     "window",
     "document"
   ];
-  for (const match of eventMatches) {
-    const event = match[2].toLowerCase();
-    if (!validEvents.includes(event) && !event.includes(".") && !targetKeywords.includes(event)) {
+  const judged = semanticEvent ? [semanticEvent.toLowerCase().split("[")[0]] : [...eventMatches].map((m) => m[2].toLowerCase());
+  for (const event of judged) {
+    if (!validEvents.includes(event) && !event.includes(".") && !event.includes(":") && !targetKeywords.includes(event)) {
       warnings.push({
         message: `Unknown event type: ${event}`,
         suggestion: `Did you mean one of: ${validEvents.slice(0, 5).join(", ")}...?`
       });
     }
   }
-  const commandPattern = new RegExp(`\\b(${validCommands.slice(0, 30).join("|")})\\b`, "gi");
+  if (coreParse && (language === "en" || language.startsWith("en-"))) {
+    try {
+      for (const err of coreParse(code).errors ?? []) {
+        errors.push({
+          message: err.message,
+          source: "core-parser",
+          suggestion: "hyperfixi's parser rejects this, so hyperfixi cannot run it as written (get_diagnostics gives the position)."
+        });
+      }
+    } catch (e) {
+      errors.push({ message: e instanceof Error ? e.message : String(e), source: "core-parser" });
+    }
+  }
+  const commandPattern = new RegExp(`\\b(${validCommands.join("|")})\\b`, "gi");
   const commandMatches = code.match(commandPattern);
   if (!semanticInfo?.usedSemanticParsing) {
     const toggleVariants = ["toggle"];
@@ -5541,7 +5584,7 @@ var compilationTools = [
   },
   {
     name: "translate_code",
-    description: 'Translate hyperscript between any of 24 languages via full semantic parsing \u2014 deterministic grammar transformation (SVO/SOV/VSO word order), not LLM translation. Every result carries a `verification` report (the output scored against the source via score_fidelity): verification.faithful === true is the claim "this rendering is structurally exact", so present it alongside the translation when showing code to a user for review. Higher fidelity than translate_hyperscript; preferred for production translations.',
+    description: 'Translate hyperscript between any of 24 languages via full semantic parsing \u2014 deterministic grammar transformation (SVO/SOV/VSO word order), not LLM translation. Every result carries a `verification` report (the output scored against the source via score_fidelity): verification.faithful === true is the claim "this rendering is structurally exact", so present it alongside the translation when showing code to a user for review. A variable the target language reads as a pronoun or another value word (tl `ako` is `me`) comes back as a NAME_COLLISION warning with a rename: rename it in the source and translate again. Higher fidelity than translate_hyperscript; preferred for production translations.',
     inputSchema: {
       type: "object",
       properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/mcp-server",
-  "version": "3.1.1",
+  "version": "3.3.0",
   "description": "Model Context Protocol server for HyperFixi hyperscript development",
   "type": "module",
   "main": "dist/index.js",
@@ -13,7 +13,7 @@
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "dev:watch": "tsx watch src/index.ts",
-    "pretest": "../../scripts/ensure-fresh.sh ../compilation-service ../semantic ../framework ../intent ../planner",
+    "pretest": "../../scripts/ensure-fresh.sh ../compilation-service ../semantic ../framework ../intent ../planner ../patterns-reference",
     "test": "vitest",
     "typecheck": "tsc --noEmit",
     "service:setup": "echo 'Copy com.lokascript.mcp-server.plist.example to com.lokascript.mcp-server.plist and update paths, then run service:install'",
@@ -37,22 +37,22 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@hyperfixi/patterns-reference": "^3.1.1",
-    "@lokascript/compilation-service": "^3.1.1",
+    "@hyperfixi/patterns-reference": "^3.3.0",
+    "@lokascript/compilation-service": "^3.3.0",
     "@lokascript/domains": "^3.0.0",
-    "@lokascript/framework": "^3.1.1",
-    "@lokascript/planner": "^3.1.1",
-    "@lokascript/semantic": "^3.1.1",
-    "@modelcontextprotocol/server": "^2.0.0",
-    "yaml": "^2.8.3"
+    "@lokascript/framework": "^3.3.0",
+    "@lokascript/planner": "^3.3.0",
+    "@lokascript/semantic": "^3.3.0",
+    "@modelcontextprotocol/server": "^2.1.0",
+    "yaml": "^2.9.1"
   },
   "peerDependencies": {
-    "@hyperfixi/core": "^3.1.1",
-    "@hyperfixi/patterns-reference": "^3.1.1",
-    "@hyperfixi/server-bridge": "^3.1.1",
-    "@lokascript/compilation-service": "^3.1.1",
-    "@lokascript/framework": "^3.1.1",
-    "@lokascript/semantic": "^3.1.1"
+    "@hyperfixi/core": "^3.3.0",
+    "@hyperfixi/patterns-reference": "^3.3.0",
+    "@hyperfixi/server-bridge": "^3.3.0",
+    "@lokascript/compilation-service": "^3.3.0",
+    "@lokascript/framework": "^3.3.0",
+    "@lokascript/semantic": "^3.3.0"
   },
   "peerDependenciesMeta": {
     "@lokascript/compilation-service": {
@@ -75,17 +75,17 @@
     }
   },
   "devDependencies": {
-    "@hyperfixi/core": "^3.1.1",
-    "@hyperfixi/patterns-reference": "^3.1.1",
-    "@hyperfixi/server-bridge": "^3.1.1",
-    "@lokascript/compilation-service": "^3.1.1",
-    "@lokascript/framework": "^3.1.1",
-    "@lokascript/semantic": "^3.1.1",
-    "@types/node": "^26.1.2",
+    "@hyperfixi/core": "^3.3.0",
+    "@hyperfixi/patterns-reference": "^3.3.0",
+    "@hyperfixi/server-bridge": "^3.3.0",
+    "@lokascript/compilation-service": "^3.3.0",
+    "@lokascript/framework": "^3.3.0",
+    "@lokascript/semantic": "^3.3.0",
+    "@types/node": "^26.6.3",
     "tsup": "^8.0.0",
-    "tsx": "^4.23.1",
+    "tsx": "^4.23.15",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.5"
+    "vitest": "^5.0.2"
   },
   "files": [
     "dist",