midnight-mcp 0.1.14 → 0.1.16

package/dist/resources/content/docs-content.js

@@ -15,9 +15,13 @@ export const EMBEDDED_DOCS = {
 
 A curated syntax reference for Compact - Midnight's smart contract language.
 
+> **Version Note**: This reference is for Compact 0.16+ (current). Some older examples may use deprecated syntax like \`Cell<T>\` wrappers - see "Common Pitfalls" section below.
+
 ## Basic Structure
 
 \`\`\`compact
+pragma language_version >= 0.14.0;
+
 include "std";
 
 ledger {
@@ -145,11 +149,124 @@ export circuit revealSecret(): Field {
 }
 \`\`\`
 
+### Disclosure in Conditionals (IMPORTANT)
+When using witness values in if/else conditions, you MUST explicitly disclose the comparison result:
+
+\`\`\`compact
+// ❌ WRONG - compiler error: "potential witness-value disclosure must be declared"
+witness getSecret(): Field { return 42; }
+export circuit checkValue(guess: Field): Boolean {
+  const secret = getSecret();
+  if (guess == secret) {  // ERROR: implicit disclosure
+    return true;
+  }
+  return false;
+}
+
+// ✅ CORRECT - wrap comparison in disclose()
+export circuit checkValue(guess: Field): Boolean {
+  const secret = getSecret();
+  if (disclose(guess == secret)) {  // Explicitly acknowledge disclosure
+    return true;
+  }
+  return false;
+}
+
+// ✅ Multiple comparisons
+export circuit giveHint(guess: Field): Hint {
+  const secret = getSecret();
+  if (disclose(guess == secret)) {
+    return Hint.correct;
+  } else if (disclose(guess > secret)) {
+    return Hint.too_high;
+  } else {
+    return Hint.too_low;
+  }
+}
+\`\`\`
+
+**Why?** When you branch on a comparison involving private (witness) values, the boolean result becomes observable on-chain. Compact requires explicit acknowledgment via \`disclose()\` to prevent accidental privacy leaks.
+
 ### Assertions
 \`\`\`compact
 assert(condition);                    // Basic assertion
 assert(condition, "Error message");   // With message
 \`\`\`
+
+## Common Pitfalls & Solutions
+
+### 1. Cell<T> Wrapper (Deprecated)
+\`\`\`compact
+// ❌ OLD SYNTAX (pre-0.15) - causes "unbound identifier Cell"
+export ledger myValue: Cell<Field>;
+myValue.write(42);
+const x = myValue.read();
+
+// ✅ CURRENT SYNTAX (0.16+) - direct declaration
+export ledger myValue: Field;
+myValue = 42;
+const x = myValue;
+\`\`\`
+
+### 2. Opaque String Assignment
+\`\`\`compact
+// ❌ WRONG - cannot assign string literals to Opaque
+export ledger message: Opaque<"string">;
+export circuit setMessage(): Void {
+  message = "hello";  // ERROR!
+}
+
+// ✅ CORRECT - use enum for fixed values
+export enum Status { pending, approved, rejected }
+export ledger status: Status;
+export circuit setStatus(): Void {
+  status = Status.approved;  // Works!
+}
+
+// ✅ Or receive Opaque from parameter/witness
+export circuit setMessage(msg: Opaque<"string">): Void {
+  message = msg;  // msg comes from TypeScript
+}
+\`\`\`
+
+### 3. Counter vs Field
+\`\`\`compact
+// Counter has special methods
+export ledger count: Counter;
+count.increment(1);
+count.decrement(1);
+const val = count.value();
+
+// Field uses direct assignment
+export ledger amount: Field;
+amount = amount + 1;
+const val = amount;
+\`\`\`
+
+### 4. Map Initialization
+\`\`\`compact
+// Maps don't need initialization
+export ledger balances: Map<Bytes<32>, Field>;
+
+// Access with .member()
+const balance = balances.member(address);
+balances.insert(address, 100);
+\`\`\`
+
+### 5. Boolean Returns with Witnesses
+\`\`\`compact
+// ❌ WRONG - returns private boolean without disclosure
+export circuit isOwner(): Boolean {
+  const caller = getCaller();  // witness
+  return caller == owner;      // ERROR: undisclosed
+}
+
+// ✅ CORRECT - disclose the result
+export circuit isOwner(): Boolean {
+  const caller = getCaller();
+  return disclose(caller == owner);
+}
+\`\`\`
 `,
     "midnight://docs/sdk-api": `# Midnight TypeScript SDK Quick Reference
 

package/dist/tools/repository/handlers.d.ts

@@ -157,11 +157,24 @@ export declare function compareSyntax(input: CompareSyntaxInput): Promise<{
  * This is the source of truth for writing valid, compilable contracts
  */
 export declare function getLatestSyntax(input: GetLatestSyntaxInput): Promise<{
+    repository: string;
+    version: string;
+    syntaxReference: string;
+    sections: string[];
+    pitfalls: string[];
+    note: string;
+    warning?: undefined;
+    syntaxFiles?: undefined;
+    examplePaths?: undefined;
+} | {
     repository: string;
     version: string;
     warning: string;
     syntaxFiles: never[];
     examplePaths: string[];
+    syntaxReference?: undefined;
+    sections?: undefined;
+    pitfalls?: undefined;
     note?: undefined;
 } | {
     repository: string;
@@ -171,6 +184,9 @@ export declare function getLatestSyntax(input: GetLatestSyntaxInput): Promise<{
         content: string;
     }[];
     note: string;
+    syntaxReference?: undefined;
+    sections?: undefined;
+    pitfalls?: undefined;
     warning?: undefined;
     examplePaths?: undefined;
 }>;

package/dist/tools/repository/handlers.js

@@ -6,6 +6,7 @@ import { githubClient } from "../../pipeline/index.js";
 import { releaseTracker } from "../../pipeline/releases.js";
 import { logger, DEFAULT_REPOSITORIES, SelfCorrectionHints, } from "../../utils/index.js";
 import { REPO_ALIASES, EXAMPLES } from "./constants.js";
+import { EMBEDDED_DOCS } from "../../resources/content/docs-content.js";
 /**
  * Resolve repository name alias to owner/repo
  */
@@ -301,6 +302,36 @@ export async function getLatestSyntax(input) {
     // Ensure repo defaults to compact if undefined/empty
     const repoName = input?.repo || "compact";
     logger.debug("Getting latest syntax reference", { repo: repoName });
+    // For Compact language, always return our curated reference first
+    // This is more reliable than fetching from GitHub and includes pitfalls/patterns
+    if (repoName === "compact" || repoName === "midnight-compact") {
+        const compactReference = EMBEDDED_DOCS["midnight://docs/compact-reference"];
+        if (compactReference) {
+            return {
+                repository: "midnightntwrk/compact",
+                version: "0.16+ (current)",
+                syntaxReference: compactReference,
+                sections: [
+                    "Basic Structure",
+                    "Data Types",
+                    "Circuits",
+                    "Witnesses",
+                    "State Management",
+                    "Common Patterns",
+                    "Disclosure in Conditionals (IMPORTANT)",
+                    "Common Pitfalls & Solutions",
+                ],
+                pitfalls: [
+                    "Cell<T> wrapper deprecated in 0.15+ - use direct type",
+                    'Cannot assign string literals to Opaque<"string"> - use enum or parameters',
+                    "Must disclose() comparisons used in if/else conditions",
+                    "Counter uses .increment()/.value(), Field uses direct assignment",
+                    "Boolean returns from witnesses need disclose()",
+                ],
+                note: "This is the curated syntax reference for Compact 0.16+. Includes common pitfalls and correct patterns.",
+            };
+        }
+    }
     const resolved = resolveRepo(repoName);
     if (!resolved) {
         throw new Error(`Unknown repository: ${repoName}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midnight-mcp",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Model Context Protocol Server for Midnight Blockchain Development",
   "type": "module",
   "main": "dist/index.js",