midnight-mcp 0.2.12 → 0.2.14

package/dist/{chunk-YT6DWZUA.js → chunk-V7KK64OX.js}

@@ -25,7 +25,7 @@ import {
   validateNumber,
   validateQuery,
   vectorStore
-} from "./chunk-B6UJ7ZQY.js";
+} from "./chunk-WYQRVPIQ.js";
 
 // src/tools/search/schemas.ts
 import { z } from "zod";
@@ -733,6 +733,144 @@ var AnalyzeContractInputSchema = z2.object({
 var ExplainCircuitInputSchema = z2.object({
   circuitCode: z2.string().describe("Circuit definition from Compact")
 });
+var CompileContractInputSchema = z2.object({
+  code: z2.string().describe("Compact contract source code to compile"),
+  skipZk: z2.boolean().optional().default(true).describe(
+    "Skip ZK circuit generation for faster syntax-only validation (default: true)"
+  ),
+  fullCompile: z2.boolean().optional().default(false).describe(
+    "Perform full compilation including ZK generation (slower but complete)"
+  )
+});
+
+// src/services/compiler.ts
+var COMPILER_API_URL = process.env.COMPACT_COMPILER_URL || "https://compact-playground.onrender.com";
+var COMPILER_TIMEOUT = 3e4;
+var MAX_CODE_SIZE = 100 * 1024;
+async function compileContract(code, options = {}) {
+  if (!code || typeof code !== "string") {
+    return {
+      success: false,
+      message: "No code provided",
+      error: "INVALID_INPUT",
+      serviceAvailable: true
+    };
+  }
+  if (code.length > MAX_CODE_SIZE) {
+    return {
+      success: false,
+      message: `Code exceeds maximum size of ${MAX_CODE_SIZE / 1024}KB`,
+      error: "CODE_TOO_LARGE",
+      serviceAvailable: true
+    };
+  }
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), COMPILER_TIMEOUT);
+    const requestBody = {
+      code,
+      options: {
+        wrapWithDefaults: options.wrapWithDefaults ?? true,
+        skipZk: options.skipZk ?? true
+        // Default to fast syntax-only validation
+      }
+    };
+    logger.info("Sending code to compiler service", {
+      codeLength: code.length,
+      options: requestBody.options
+    });
+    const response = await fetch(`${COMPILER_API_URL}/compile`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(requestBody),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      logger.error("Compiler API returned error status", {
+        status: response.status,
+        error: errorText
+      });
+      return {
+        success: false,
+        message: `Compiler service error: ${response.status}`,
+        error: "API_ERROR",
+        serviceAvailable: response.status < 500
+      };
+    }
+    const result = await response.json();
+    if (result.success) {
+      const outputInfo = typeof result.output === "object" && result.output !== null ? result.output : {};
+      logger.info("Compilation successful", {
+        compilerVersion: result.compilerVersion,
+        executionTime: result.executionTime,
+        circuits: outputInfo.circuits?.length || 0,
+        warnings: result.warnings?.length || 0
+      });
+      const version = result.compilerVersion || "unknown";
+      const execTime = result.executionTime ? ` in ${result.executionTime}ms` : "";
+      return {
+        success: true,
+        compilerVersion: version,
+        message: `\u2705 Compilation successful (Compiler v${version})${execTime}`,
+        circuits: outputInfo.circuits || [],
+        ledgerFields: outputInfo.ledgerFields || [],
+        exports: outputInfo.exports || [],
+        warnings: result.warnings || [],
+        serviceAvailable: true
+      };
+    } else {
+      const errors = result.errors || [];
+      const firstError = errors[0];
+      logger.info("Compilation failed", {
+        error: result.error,
+        errorCount: errors.length,
+        output: result.output,
+        firstError
+      });
+      let errorMessage = result.output || result.message || result.error || "Compilation failed";
+      if (firstError) {
+        errorMessage = `Line ${firstError.line}:${firstError.column} - ${firstError.message}`;
+      }
+      return {
+        success: false,
+        message: errorMessage,
+        error: result.error || "COMPILE_ERROR",
+        errors,
+        errorDetails: firstError ? {
+          line: firstError.line,
+          column: firstError.column,
+          errorType: firstError.severity
+        } : result.details,
+        serviceAvailable: true
+      };
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    if (error instanceof Error && error.name === "AbortError") {
+      logger.warn("Compiler request timed out");
+      return {
+        success: false,
+        message: "Compilation timed out - the contract may be too complex",
+        error: "TIMEOUT",
+        serviceAvailable: true
+      };
+    }
+    logger.error("Compiler service request failed", { error: errorMessage });
+    return {
+      success: false,
+      message: `Failed to connect to compiler service: ${errorMessage}`,
+      error: "CONNECTION_FAILED",
+      serviceAvailable: false
+    };
+  }
+}
+function getCompilerUrl() {
+  return COMPILER_API_URL;
+}
 
 // src/tools/analyze/handlers.ts
 async function analyzeContract(input) {
@@ -954,6 +1092,86 @@ function getPrivacyConsiderations(circuit) {
   }
   return considerations;
 }
+async function compileContract2(input) {
+  logger.info("Compiling Compact contract via hosted service", {
+    codeLength: input.code.length,
+    skipZk: input.skipZk,
+    fullCompile: input.fullCompile
+  });
+  const skipZk = input.fullCompile ? false : input.skipZk ?? true;
+  const result = await compileContract(input.code, {
+    wrapWithDefaults: true,
+    skipZk
+  });
+  if (result.success) {
+    return {
+      success: true,
+      message: result.message,
+      compilerVersion: result.compilerVersion,
+      compilationMode: skipZk ? "syntax-only" : "full",
+      validationType: "compiler",
+      output: {
+        circuits: result.circuits || [],
+        ledgerFields: result.ledgerFields || [],
+        exports: result.exports || []
+      },
+      warnings: result.warnings || [],
+      serviceUrl: getCompilerUrl()
+    };
+  } else {
+    if (!result.serviceAvailable) {
+      logger.warn(
+        "Compiler service unavailable, falling back to static analysis",
+        { error: result.error }
+      );
+      const staticResult = await analyzeContract({
+        code: input.code,
+        checkSecurity: true
+      });
+      const securityWarnings = (staticResult.securityFindings || []).map(
+        (f) => `[${f.severity}] ${f.message}`
+      );
+      return {
+        success: true,
+        // Static analysis succeeded
+        message: "Static analysis completed (compiler service unavailable)",
+        validationType: "static-analysis-fallback",
+        compilationMode: "none",
+        serviceAvailable: false,
+        serviceUrl: getCompilerUrl(),
+        fallbackReason: result.message,
+        warnings: securityWarnings,
+        staticAnalysis: {
+          summary: staticResult.summary,
+          structure: staticResult.structure,
+          securityFindings: staticResult.securityFindings,
+          recommendations: staticResult.recommendations
+        }
+      };
+    }
+    const errorInfo = {
+      success: false,
+      message: result.message,
+      error: result.error,
+      validationType: "compiler",
+      serviceAvailable: result.serviceAvailable,
+      serviceUrl: getCompilerUrl()
+    };
+    if (result.errorDetails) {
+      errorInfo.location = {
+        line: result.errorDetails.line,
+        column: result.errorDetails.column,
+        errorType: result.errorDetails.errorType
+      };
+    }
+    if (result.error === "TIMEOUT") {
+      errorInfo.hint = "The contract may be too complex. Try simplifying or breaking it into smaller pieces.";
+    } else if (result.errorDetails?.line) {
+      errorInfo.hint = `Check line ${result.errorDetails.line} for the issue.`;
+    }
+    return errorInfo;
+  }
+}
 
 // src/tools/analyze/tools.ts
 var analyzeContractOutputSchema = {
@@ -1098,6 +1316,99 @@ var explainCircuitOutputSchema = {
   ],
   description: "Detailed circuit explanation with privacy analysis"
 };
+var compileContractOutputSchema = {
+  type: "object",
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether compilation/validation succeeded"
+    },
+    message: {
+      type: "string",
+      description: "Human-readable status message"
+    },
+    validationType: {
+      type: "string",
+      enum: ["compiler", "static-analysis-fallback"],
+      description: "Type of validation performed - compiler (real) or static-analysis-fallback (when service unavailable)"
+    },
+    compilerVersion: {
+      type: "string",
+      description: "Version of the Compact compiler used (if available)"
+    },
+    compilationMode: {
+      type: "string",
+      enum: ["syntax-only", "full", "none"],
+      description: "Type of compilation performed"
+    },
+    output: {
+      type: "object",
+      properties: {
+        circuits: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of compiled circuits"
+        },
+        ledgerFields: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of ledger fields"
+        },
+        exports: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of exported symbols"
+        }
+      }
+    },
+    warnings: {
+      type: "array",
+      items: { type: "string" },
+      description: "Compiler warnings or fallback warnings"
+    },
+    error: {
+      type: "string",
+      description: "Error code if compilation failed"
+    },
+    location: {
+      type: "object",
+      properties: {
+        line: { type: "number" },
+        column: { type: "number" },
+        errorType: { type: "string" }
+      },
+      description: "Location of error if applicable"
+    },
+    hint: {
+      type: "string",
+      description: "Helpful hint for resolving the issue"
+    },
+    serviceUrl: {
+      type: "string",
+      description: "URL of the compiler service used"
+    },
+    serviceAvailable: {
+      type: "boolean",
+      description: "Whether the compiler service is available"
+    },
+    fallbackReason: {
+      type: "string",
+      description: "Reason for falling back to static analysis (if applicable)"
+    },
+    staticAnalysis: {
+      type: "object",
+      description: "Static analysis results (only present when using fallback)",
+      properties: {
+        summary: { type: "object" },
+        structure: { type: "object" },
+        securityFindings: { type: "array" },
+        recommendations: { type: "array" }
+      }
+    }
+  },
+  required: ["success", "message", "validationType"],
+  description: "Compilation result with detailed output, or static analysis fallback if service unavailable"
+};
 var analyzeTools = [
   {
     name: "midnight-analyze-contract",
@@ -1161,6 +1472,59 @@ USAGE GUIDANCE:
       category: "analyze"
     },
     handler: explainCircuit
+  },
+  {
+    name: "midnight-compile-contract",
+    description: `\u{1F527} REAL COMPILATION - Compile Compact code using the hosted compiler service.
+
+Unlike static analysis tools, this ACTUALLY COMPILES the contract and returns real compiler errors.
+
+Use this to:
+\u2022 Validate that generated code compiles before showing to users
+\u2022 Get actual compiler error messages with line numbers
+\u2022 Check if a contract is syntactically and semantically correct
+
+Options:
+\u2022 skipZk=true (default): Fast syntax validation only (~1-2s)
+\u2022 fullCompile=true: Full compilation with ZK circuit generation (~10-30s)
+
+FALLBACK BEHAVIOR:
+\u2022 If the compiler service is unavailable, automatically falls back to static analysis
+\u2022 Check 'validationType' in response: 'compiler' = real compilation, 'static-analysis-fallback' = fallback mode
+\u2022 Fallback provides structure/security analysis but may miss semantic errors
+
+USAGE GUIDANCE:
+\u2022 Call after generating or modifying Compact code
+\u2022 Use skipZk=true for quick validation during development
+\u2022 Use fullCompile=true for final validation before deployment`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        code: {
+          type: "string",
+          description: "Compact contract source code to compile"
+        },
+        skipZk: {
+          type: "boolean",
+          description: "Skip ZK circuit generation for faster syntax-only validation (default: true)"
+        },
+        fullCompile: {
+          type: "boolean",
+          description: "Perform full compilation including ZK generation (slower but complete)"
+        }
+      },
+      required: ["code"]
+    },
+    outputSchema: compileContractOutputSchema,
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+      // Makes network requests
+      title: "\u{1F527} Compile Contract",
+      category: "analyze"
+    },
+    handler: compileContract2
   }
 ];
 
@@ -1680,16 +2044,24 @@ ledger privateData: Field;                 // Private, not exported
 | \`Field\` | Finite field element (basic numeric) | \`amount: Field\` |
 | \`Boolean\` | True or false | \`isActive: Boolean\` |
 | \`Bytes<N>\` | Fixed-size byte array | \`hash: Bytes<32>\` |
-| \`Uint<N>\` | Unsigned integer (N = 8, 16, 32, 64, 128, 256) | \`balance: Uint<64>\` |
-| \`Uint<MIN..MAX>\` | Bounded unsigned integer | \`score: Uint<0..100>\` |
+| \`Uint<N>\` | Unsigned integer (N bits) | \`balance: Uint<64>\` |
+| \`Uint<0..MAX>\` | Bounded unsigned integer | \`score: Uint<0..100>\` |
 
-**\u26A0\uFE0F Uint Type Equivalence:** \`Uint<N>\` (sized) and \`Uint<0..MAX>\` (bounded) are the **SAME type family**.
+**\u26A0\uFE0F Uint Type Equivalence** (documented in [Primitive Types](https://docs.midnight.network/develop/reference/compact/lang-ref#primitive-types)):
+
+\`Uint<N>\` (sized) and \`Uint<0..MAX>\` (bounded) are the **SAME type family**.
 \`Uint<N>\` is exactly equivalent to \`Uint<0..(2^N - 1)>\`:
 - \`Uint<8>\` = \`Uint<0..255>\` (2^8 - 1 = 255)
 - \`Uint<16>\` = \`Uint<0..65535>\` (2^16 - 1 = 65535)
 - \`Uint<64>\` = \`Uint<0..18446744073709551615>\`
 
-These can be used interchangeably - they are **not** separate types.
+These can be used interchangeably. The lower bound must currently be 0.
+
+**Arithmetic** (documented in [Binary Arithmetic](https://docs.midnight.network/develop/reference/compact/lang-ref#binary-arithmetic-expressions)):
+- Operators: \`+\`, \`-\`, \`*\` only (division \`/\` and modulo \`%\` are NOT mentioned in docs)
+- Result types expand: \`Uint<0..m> + Uint<0..n>\` \u2192 \`Uint<0..m+n>\`
+- Subtraction can fail at runtime if result would be negative
+- \u26A0\uFE0F If you need division, you may need a witness to compute it off-chain
 
 ### Collection Types
 | Type | Description | Example |
@@ -1699,9 +2071,16 @@ These can be used interchangeably - they are **not** separate types.
 | \`Set<T>\` | Unique value collection | \`Set<Bytes<32>>\` |
 | \`Vector<N, T>\` | Fixed-size array | \`Vector<3, Field>\` |
 | \`List<T>\` | Dynamic list | \`List<Bytes<32>>\` |
-| \`Maybe<T>\` | Optional value | \`Maybe<Bytes<32>>\` |
-| \`Either<L, R>\` | Union type | \`Either<Field, Bytes<32>>\` |
-| \`Opaque<"type">\` | External type from TypeScript | \`Opaque<"string">\` |
+| \`Maybe<T>\` | Optional value (has/hasn't) | \`Maybe<Bytes<32>>\` |
+| \`Either<L, R>\` | Sum type (one or other) | \`Either<Field, Bytes<32>>\` |
+| \`Opaque<s>\` | Opaque value tagged by string s | \`Opaque<"string">\` |
+
+**Opaque Types** ([Primitive Types](https://docs.midnight.network/develop/reference/compact/lang-ref#primitive-types)):
+- Only two tags allowed: \`Opaque<"string">\` and \`Opaque<"Uint8Array">\`
+- Opaque values can be manipulated in witnesses but are opaque to circuits
+- In circuits, they are represented as their hash (cannot inspect content)
+- In your DApp's JS/TS, they are just \`string\` or \`Uint8Array\`
+- On-chain, they are stored as bytes/UTF-8 (not encrypted)
 
 ### Custom Types
 
@@ -1944,6 +2323,14 @@ balances.insertDefault(address);         // insertDefault(key): [] - inserts def
 // Query operations (all work in circuits \u2705)
 const balance = balances.lookup(address);  // lookup(key): value_type
 const exists = balances.member(address);   // member(key): Boolean
+
+// \u26A0\uFE0F UNDOCUMENTED: Map.lookup() behavior when key doesn't exist
+// The docs show: lookup(key: key_type): value_type (NOT Maybe<value_type>)
+// This implies it returns a default value, not an optional.
+// RECOMMENDED: Always check member() first:
+if (balances.member(address)) {
+  const balance = balances.lookup(address);  // Safe
+}
 const empty = balances.isEmpty();          // isEmpty(): Boolean
 const count = balances.size();             // size(): Uint<64>
 
@@ -1979,19 +2366,81 @@ const count = members.size();               // size(): Uint<64>
 
 ### Maybe Operations
 \`\`\`compact
-const opt: Maybe<Field> = some<Field>(42);
-const empty: Maybe<Field> = none<Field>();
+// Creating Maybe values
+const opt: Maybe<Field> = some<Field>(42);     // Wrap a value
+const empty: Maybe<Field> = none<Field>();     // No value
 
+// Checking and accessing
 if (opt.is_some) {
-  const val = opt.value;
+  const val = opt.value;  // Safe to access when is_some is true
+}
+
+// Common patterns
+witness find_user(id: Bytes<32>): Maybe<UserRecord>;
+
+export circuit getUser(id: Bytes<32>): UserRecord {
+  const result = find_user(id);
+  assert(disclose(result.is_some), "User not found");
+  return result.value;
 }
 \`\`\`
 
-### Type Casting
+### Either Operations
 \`\`\`compact
-const bytes: Bytes<32> = myField as Bytes<32>;  // Field to Bytes
-const num: Uint<64> = myField as Uint<64>;      // Field to Uint (bounds not checked!)
-const field: Field = myUint as Field;           // Uint to Field (safe)
+// Creating Either values
+const success: Either<Field, Bytes<32>> = left<Field, Bytes<32>>(42);
+const failure: Either<Field, Bytes<32>> = right<Field, Bytes<32>>(errorHash);
+
+// Checking which side
+if (result.is_left) {
+  const value = result.left;   // The left value (often "success")
+} else {
+  const error = result.right;  // The right value (often "error")
+}
+
+// Common pattern: burnAddress() returns Either<ZswapCoinPublicKey, ContractAddress>
+export circuit withdraw(): [] {
+  const addr = burnAddress();
+  assert(disclose(addr.is_right), "Expected contract address");
+  // addr.right is the ContractAddress
+}
+\`\`\`
+
+### Type Casting ([Type Casts Reference](https://docs.midnight.network/develop/reference/compact/lang-ref#type-cast-expressions))
+
+**Syntax**: \`expression as Type\` (only form; \`<Type>expression\` is NOT supported)
+
+**Cast kinds**: static (always succeeds), conversion (semantic change), checked (can fail at runtime)
+
+\`\`\`compact
+// Uint \u2194 Field (safe)
+const field: Field = myUint as Field;           // static: always succeeds
+const num: Uint<64> = myField as Uint<64>;      // checked: fails if out of range
+
+// Uint widening/narrowing
+const big: Uint<64> = small as Uint<64>;        // static: widening always works
+const small: Uint<32> = big as Uint<32>;        // checked: narrowing can fail
+
+// Field \u2194 Bytes (can fail at runtime!)
+const bytes: Bytes<32> = myField as Bytes<32>;  // conversion: fails if doesn't fit
+const field: Field = myBytes as Field;          // conversion: fails if exceeds max Field
+
+// Uint \u2192 Bytes (NOT direct - use two casts)
+const amount_bytes = (amount as Field) as Bytes<32>;
+
+// Boolean \u2192 Uint (conversion: false\u21920, true\u21921)
+const flag: Boolean = true;
+const flagInt: Uint<0..1> = flag as Uint<0..1>;
+
+// Enum \u2192 Field (conversion)
+const index: Field = choice as Field;
+
+// \u26A0\uFE0F Boolean \u2192 Field is NOT allowed!
+// Must go through Uint: (flag as Uint<0..1>) as Field
+
+// \u26A0\uFE0F UNDOCUMENTED: Bytes<n> \u2194 Vector<n, Uint<8>> casting
+// The type cast table doesn't mention this conversion.
+// If you need to convert, you may need a witness helper.
 \`\`\`
 
 ### Hashing
@@ -2029,7 +2478,22 @@ assert(disclose(caller == owner), "Not authorized");
 
 ---
 
-## 12. Exports for TypeScript
+## 12. Undocumented / Unclear Features
+
+These features are not clearly documented. Use with caution:
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Tuple destructuring | \u2753 Unknown | \`const [a, b] = pair;\` - not documented |
+| Constant folding in indices | \u2753 Unknown | \`v[2 * i]\` where i is const - docs say "numeric literal" required |
+| Division \`/\` and modulo \`%\` | \u2753 Not in docs | Only +, -, * are documented |
+| \`Bytes<n>\` \u2194 \`Vector<n, Uint<8>>\` | \u2753 Not in cast table | May need witness workaround |
+
+**Recommendation**: Test these in the compiler before relying on them in production contracts.
+
+---
+
+## 13. Exports for TypeScript
 
 To use types/values in TypeScript, they must be exported:
 
@@ -2159,6 +2623,154 @@ try {
   }
 }
 \`\`\`
+`,
+  "midnight://docs/compiler": `# Compact Compiler Guide
+
+**Source:** [Building a Midnight DApp](https://docs.midnight.network/develop/tutorial/building)
+
+## Compiling Contracts
+
+> **IMPORTANT:** The old \`compactc\` command is deprecated. Use \`compact compile\` instead.
+
+### Basic Usage
+
+\`\`\`bash
+# Syntax: compact compile <source.compact> <output_directory>
+compact compile src/counter.compact managed/counter
+
+# With environment setup
+nvm use 18
+compact compile contract/src/mycontract.compact managed/mycontract
+\`\`\`
+
+### Compiler Output Structure
+
+**Source:** [Generated Source Details](https://docs.midnight.network/develop/tutorial/building/dapp-details#generated-source)
+
+When you compile a \`.compact\` file, the compiler generates this directory structure:
+
+\`\`\`
+managed/<contract_name>/
+\u251C\u2500\u2500 contract/                 # TypeScript bindings
+\u2502   \u251C\u2500\u2500 index.cjs             # CommonJS module with Contract class
+\u2502   \u251C\u2500\u2500 index.d.cts           # TypeScript type declarations
+\u2502   \u2514\u2500\u2500 index.mjs             # ESM module (optional)
+\u2502
+\u251C\u2500\u2500 zkir/                     # Zero-knowledge circuit representations
+\u2502   \u2514\u2500\u2500 <circuit_name>.zkir   # Circuit intermediate representation
+\u2502
+\u251C\u2500\u2500 keys/                     # Proving and verifying keys
+\u2502   \u251C\u2500\u2500 <circuit>.prover      # Prover key (used client-side)
+\u2502   \u2514\u2500\u2500 <circuit>.verifier    # Verifier key (used on-chain)
+\u2502
+\u2514\u2500\u2500 compiler/                 # Compilation metadata
+    \u2514\u2500\u2500 metadata.json         # Version info, circuit IDs, etc.
+\`\`\`
+
+### Understanding Generated Files
+
+#### contract/ - TypeScript Bindings
+
+The \`contract/\` directory contains your TypeScript interface:
+
+\`\`\`typescript
+// Import from generated bindings
+import { Contract, ledger } from './managed/counter/contract/index.cjs';
+
+// Create contract instance
+const contract = new Contract(witnesses);
+
+// Access circuits
+const tx = await contract.impureCircuits.increment(5n);
+
+// Read ledger state
+const state = ledger(contractState);
+console.log('Counter value:', state.counter);
+\`\`\`
+
+#### keys/ - ZK Proving/Verifying Keys
+
+- **\`.prover\`** - Used by the client to generate proofs (can be large, 10-100MB+)
+- **\`.verifier\`** - Used on-chain to verify proofs (small, kilobytes)
+
+\`\`\`typescript
+// Keys are loaded automatically by the SDK
+import { proverKey, verifierKey } from './managed/counter/keys';
+
+// Or loaded from files
+const prover = await fs.readFile('managed/counter/keys/increment.prover');
+\`\`\`
+
+#### zkir/ - Circuit Intermediate Representation
+
+The \`.zkir\` files are internal representations used by the proof system. You typically don't interact with these directly.
+
+### Cleaning and Rebuilding
+
+When updating contracts or after Compact version changes:
+
+\`\`\`bash
+# Clean generated files
+rm -rf managed/<contract_name>
+
+# Or clean specific artifacts
+rm -rf managed/counter/keys/*.prover managed/counter/keys/*.verifier
+
+# Rebuild
+compact compile src/counter.compact managed/counter
+\`\`\`
+
+### Common Compilation Errors
+
+#### "invalid context for a ledger ADT type"
+
+Ledger ADT types cannot be used in type casts:
+
+\`\`\`compact
+// \u274C Wrong
+const x = value as Counter;
+
+// \u2705 Correct - use ledger field directly
+ledger.counter.increment(1);
+\`\`\`
+
+#### Version Mismatch After Update
+
+When runtime versions don't match compiled artifacts:
+
+\`\`\`bash
+# 1. Check versions
+compact --version
+npm list @midnight-ntwrk/compact-runtime
+
+# 2. Consult compatibility matrix
+# https://docs.midnight.network/relnotes/support-matrix
+
+# 3. Clean and recompile
+rm -rf managed/
+compact compile src/contract.compact managed/contract
+\`\`\`
+
+### Integration with Build Tools
+
+#### package.json scripts
+
+\`\`\`json
+{
+  "scripts": {
+    "compile": "compact compile src/contract.compact managed/contract",
+    "compile:clean": "rm -rf managed && npm run compile",
+    "build": "npm run compile && tsc"
+  }
+}
+\`\`\`
+
+#### Watch mode (development)
+
+\`\`\`bash
+# Using nodemon or similar
+nodemon --watch src/*.compact --exec "compact compile src/contract.compact managed/contract"
+\`\`\`
 `,
   "midnight://docs/openzeppelin": `# OpenZeppelin Contracts for Compact
 
@@ -2805,9 +3417,16 @@ try {
 2. **Discord:** #developer-support channel
 3. **Recompile after updates:**
    \`\`\`bash
-   rm -rf contract/*.cjs contract/*.prover contract/*.verifier
-   compact compile src/contract.compact contract/
+   # Clean generated files (use managed/ directory structure)
+   rm -rf managed/<contract_name>
+   
+   # Or clean specific artifacts
+   rm -rf managed/counter/keys/*.prover managed/counter/keys/*.verifier
+   
+   # Rebuild
+   compact compile src/contract.compact managed/contract
    \`\`\`
+4. **Compiler output docs:** See \`midnight://docs/compiler\` for full directory structure
 `
 };
 
@@ -2876,14 +3495,14 @@ export ledger messageIds: Set<Field>;
 // Private: actual message contents (no export = private)
 ledger messages: Map<Field, Opaque<"string">>;
 
-// Private: message authors
-ledger authors: Map<Field, Opaque<"address">>;
+// Private: message authors (stored as Bytes<32> addresses)
+ledger authors: Map<Field, Bytes<32>>;
 
 // Witness to fetch message content
 witness getMessageContent(id: Field): Opaque<"string">;
 
 // Post a new message (content is private)
-export circuit postMessage(content: Opaque<"string">, author: Opaque<"address">): Uint<64> {
+export circuit postMessage(content: Opaque<"string">, author: Bytes<32>): Uint<64> {
   // Generate unique message ID using counter read
   const messageId = messageCount.read();
   
@@ -4224,6 +4843,18 @@ Based on syntax reference, generate the contract using:
 - No 'void' - use '[]'
 - Enum access: \`Choice.rock\` NOT \`Choice::rock\`
 
+### \u26A0\uFE0F UNDOCUMENTED FEATURES - Use with caution:
+- Division \`/\` and modulo \`%\`: NOT in official docs (only +, -, * are documented)
+- Tuple destructuring: \`const [a, b] = pair;\` - not documented, may not work
+- Constant folding in indices: docs say "numeric literal" required
+- Map.lookup() returns value_type, NOT Maybe<value_type> - check member() first!
+
+### COMPILER INFO (DO NOT guess package names!):
+- Compile: \`compact compile src/contract.compact managed/contract\`
+- The \`compact\` CLI comes with Midnight toolchain (via create-mn-app or official install)
+- DO NOT suggest \`npm install -g @midnight-ntwrk/compact-cli\` or similar made-up packages
+- Output structure: \`managed/<name>/contract/index.cjs\` for TypeScript bindings
+
 ### Step 3: Validate Before Returning
 Call \`midnight-extract-contract-structure\` with your generated code to check for:
 - deprecated_ledger_block
@@ -4327,11 +4958,11 @@ Please analyze:
    - Correct use of disclose() and commit()
    - Privacy guarantees provided
 
-4. **Best Practices**
-   - Code organization
-   - Naming conventions
-   - Documentation
-   - Error messages
+4. **Style Suggestions** (these are CONVENTIONS, not requirements)
+   - Code organization recommendations
+   - Naming conventions (project-specific)
+   - Documentation patterns
+   - Note: The Compact docs don't specify indentation, line length, or comment style
 
 5. **Performance**
    - Circuit complexity
@@ -4343,6 +4974,11 @@ Please analyze:
    - Improvements to consider
    - Alternative approaches
 
+**IMPORTANT**: Clearly distinguish between:
+- ERRORS: Actual syntax/compilation issues (required fixes)
+- WARNINGS: Security/logic concerns (should fix)
+- INFO: Style suggestions (optional, project-specific conventions)
+
 Please provide specific line references and code suggestions where applicable.`
       }
     }
@@ -4578,21 +5214,32 @@ async function generateContract(requirements, options = {}) {
   const systemPrompt = `You are an expert Compact smart contract developer for the Midnight blockchain.
 Your task is to generate secure, well-documented Compact contracts based on user requirements.
 
-Key Compact concepts:
-- \`ledger { }\` - Defines on-chain state (public and private)
-- \`@private\` - Marks state as private/shielded
-- \`export circuit\` - Public functions that generate ZK proofs
-- \`witness\` - Off-chain computation functions
-- \`assert()\` - Creates ZK constraints
-- \`Counter\`, \`Map<K,V>\`, \`Set<T>\` - Built-in collection types
+Key Compact syntax (REQUIRED):
+- \`export ledger field: Type;\` - Individual ledger declarations (NOT ledger { } blocks)
+- \`export circuit fn(): []\` - Public functions return empty tuple [] (NOT Void)
+- \`witness fn(): T;\` - Declaration only, no body
+- \`pragma language_version >= 0.16 && <= 0.18;\` - Version pragma
+- \`import CompactStandardLibrary;\` - Standard imports
+- \`Counter\`, \`Map<K,V>\`, \`Set<T>\` - Built-in collection types  
 - \`Field\`, \`Boolean\`, \`Uint<N>\`, \`Bytes<N>\` - Primitive types
+- \`export enum State { a, b }\` - Enums must be exported
+
+Key operations:
+- Counter: .read(), .increment(n), .decrement(n)
+- Map: .lookup(k), .insert(k,v), .remove(k)
+- Set: .member(v), .insert(v), .remove(v)
+
+COMPILER INFO (DO NOT guess package names!):
+- Command: \`compact compile src/contract.compact managed/contract\`
+- The \`compact\` CLI comes with Midnight toolchain (via create-mn-app or official install)
+- Output goes to managed/<name>/ directory
+- DO NOT suggest \`npm install -g @midnight-ntwrk/compact-cli\` or similar - that's incorrect
 
-Always include:
-1. Proper imports (import CompactStandardLibrary;)
-2. pragma language_version >= 0.18.0;
-3. Clear ledger state definitions
-4. Access control where appropriate
-5. Comprehensive inline comments
+IMPORTANT - Style vs. Requirements:
+- Syntax rules above are REQUIRED for compilation
+- Style choices (indentation, comment style, line length) are CONVENTIONS, not requirements
+- Single-line comments (//) are common in examples; block comments (/* */) may also work
+- The docs don't specify indentation width - use consistent style
 
 Return ONLY the Compact code, no explanations.`;
   const userPrompt = options.baseExample ? `Based on this example contract:
@@ -4668,8 +5315,21 @@ Review the provided contract for:
 1. Security vulnerabilities
 2. Privacy concerns (improper handling of shielded state)
 3. Logic errors
-4. Best practice violations
-5. Gas/performance issues
+4. Syntax errors (use "error" severity)
+5. Performance issues
+
+IMPORTANT - Distinguish between:
+- ERRORS: Actual syntax/compilation issues (e.g., using Void instead of [], ledger {} blocks)
+- WARNINGS: Potential bugs or security issues
+- INFO: Style suggestions and best practices (these are CONVENTIONS, not requirements)
+
+Do NOT claim style choices as "violations" - the Compact docs don't specify:
+- Indentation width (2 vs 4 spaces)
+- Comment style preferences (//, /* */)
+- Line length limits
+- Naming conventions
+
+These are project-specific style choices, not language requirements.
 
 Respond in JSON format:
 {
@@ -5186,8 +5846,11 @@ var SERVER_INFO = {
 var versionCheckResult = {
   isOutdated: false,
   latestVersion: CURRENT_VERSION,
-  updateMessage: null
+  updateMessage: null,
+  lastChecked: 0
 };
+var toolCallCount = 0;
+var VERSION_CHECK_INTERVAL = 10;
 async function checkForUpdates() {
   try {
     const controller = new AbortController();
@@ -5204,15 +5867,32 @@ async function checkForUpdates() {
       versionCheckResult = {
         isOutdated: true,
         latestVersion,
-        updateMessage: `\u26A0\uFE0F UPDATE AVAILABLE: v${latestVersion} (you have v${CURRENT_VERSION}). Run: rm -rf ~/.npm/_npx && restart Claude Desktop. Or update config to use: "midnight-mcp@latest"`
+        lastChecked: Date.now(),
+        updateMessage: `\u{1F6A8} UPDATE AVAILABLE: v${latestVersion} (you have v${CURRENT_VERSION})`
       };
       logger.warn(
         `Outdated version detected: v${CURRENT_VERSION} -> v${latestVersion}`
       );
+    } else {
+      versionCheckResult = {
+        ...versionCheckResult,
+        lastChecked: Date.now()
+      };
     }
   } catch {
   }
 }
+function maybeCheckForUpdates() {
+  toolCallCount++;
+  if (toolCallCount >= VERSION_CHECK_INTERVAL) {
+    toolCallCount = 0;
+    const fiveMinutes = 5 * 60 * 1e3;
+    if (Date.now() - versionCheckResult.lastChecked > fiveMinutes) {
+      checkForUpdates().catch(() => {
+      });
+    }
+  }
+}
 function getUpdateWarning() {
   return versionCheckResult.updateMessage;
 }
@@ -5457,26 +6137,31 @@ function registerToolHandlers(server) {
       const result = await tool.handler(args);
       const durationMs = Date.now() - startTime;
       trackToolCall(name, true, durationMs, CURRENT_VERSION);
+      maybeCheckForUpdates();
       const updateWarning = getUpdateWarning();
       if (updateWarning && versionCheckResult.isOutdated) {
         const updatePrompt = {
-          "\u{1F6A8} UPDATE AVAILABLE": {
-            message: `You are using v${CURRENT_VERSION} but v${versionCheckResult.latestVersion} is available.`,
-            userAction: {
-              instruction: "Tell the user to update manually. Auto-update is NOT possible because you run in a sandboxed environment without access to local files.",
-              steps: [
-                "1. Edit config file to use 'midnight-mcp@latest' instead of 'midnight-mcp'",
-                "2. Run: rm -rf ~/.npm/_npx (to clear npm cache)",
-                "3. Restart the editor completely (Cmd+Q on Mac, then reopen)"
-              ],
-              configLocations: {
-                claudeDesktop: "~/Library/Application Support/Claude/claude_desktop_config.json",
-                cursor: ".cursor/mcp.json",
-                vscode: ".vscode/mcp.json",
-                windsurf: "~/.codeium/windsurf/mcp_config.json"
+          "\u{1F6A8} UPDATE REQUIRED": {
+            current: `v${CURRENT_VERSION}`,
+            latest: `v${versionCheckResult.latestVersion}`,
+            quickFix: {
+              description: "Most users just need these 2 steps:",
+              step1: "Run in terminal: rm -rf ~/.npm/_npx",
+              step2: "Restart editor completely (Cmd+Q / Alt+F4, then reopen)"
+            },
+            ifStillOld: {
+              description: "If still showing old version after restart:",
+              action: "Edit your MCP config file to use @latest:",
+              change: 'Change "midnight-mcp" to "midnight-mcp@latest" in args',
+              configFiles: {
+                "Claude Desktop (Mac)": "~/Library/Application Support/Claude/claude_desktop_config.json",
+                "Claude Desktop (Win)": "%APPDATA%/Claude/claude_desktop_config.json",
+                Cursor: ".cursor/mcp.json",
+                "VS Code": ".vscode/mcp.json",
+                Windsurf: "~/.codeium/windsurf/mcp_config.json"
               }
             },
-            note: "If user already has @latest in config, they just need to clear cache (rm -rf ~/.npm/_npx) and restart."
+            tip: "Use 'midnight-get-update-instructions' tool for detailed platform-specific steps."
           },
           result
         };
@@ -5903,6 +6588,7 @@ var BUILTIN_FUNCTIONS = {
     {
       name: "persistentHash",
       signature: "persistentHash<T>(value: T): Bytes<32>",
+      // Signature inferred from examples
       description: "Poseidon hash that produces consistent results across calls"
     },
     {
@@ -5961,6 +6647,7 @@ witness get_random_value(): Field;`,
   ]
 };
 var TYPE_COMPATIBILITY = {
+  // Note: Comparison operators work in practice but aren't explicitly listed in docs
   comparisons: [
     { types: "Field == Field", works: true, note: "Direct comparison" },
     {
@@ -5979,7 +6666,11 @@ var TYPE_COMPATIBILITY = {
       works: true,
       note: "Bounded integers"
     },
-    { types: "Bytes<32> == Bytes<32>", works: true, note: "Direct comparison" },
+    {
+      types: "Bytes<32> == Bytes<32>",
+      works: true,
+      note: "Used in examples, but operators not explicitly listed in docs"
+    },
     { types: "Boolean == Boolean", works: true, note: "Direct comparison" }
   ],
   arithmetic: [
@@ -6001,23 +6692,79 @@ var TYPE_COMPATIBILITY = {
       note: "Result is wide bounded type, cast back to target type"
     }
   ],
+  /**
+   * Type casting rules - based on official cast table
+   * See: https://docs.midnight.network/develop/reference/compact/lang-ref#type-cast-expressions
+   *
+   * Cast kinds: static (always succeeds), conversion (semantic change), checked (can fail)
+   */
   typeCasting: [
     {
-      from: "Uint<64>",
-      to: "Bytes<32>",
+      from: "Uint<N>",
+      to: "Field",
+      direct: true,
+      kind: "static",
+      note: "Always succeeds"
+    },
+    {
+      from: "Field",
+      to: "Uint<0..n>",
+      direct: true,
+      kind: "checked",
+      note: "Fails at runtime if value > n"
+    },
+    {
+      from: "Field",
+      to: "Bytes<n>",
+      direct: true,
+      kind: "conversion",
+      note: "Can fail at runtime if value doesn't fit (little-endian)"
+    },
+    {
+      from: "Bytes<m>",
+      to: "Field",
+      direct: true,
+      kind: "conversion",
+      note: "Can fail at runtime if result exceeds max Field value"
+    },
+    {
+      from: "Boolean",
+      to: "Uint<0..n>",
+      direct: true,
+      kind: "conversion",
+      note: "false\u21920, true\u21921 (n must not be 0)"
+    },
+    {
+      from: "Boolean",
+      to: "Field",
       direct: false,
-      fix: "Go through Field: (amount as Field) as Bytes<32>"
+      fix: "Go through Uint: (flag as Uint<0..1>) as Field"
     },
     {
       from: "Uint<N>",
+      to: "Bytes<M>",
+      direct: false,
+      fix: "Go through Field: (amount as Field) as Bytes<32>"
+    },
+    {
+      from: "enum",
       to: "Field",
       direct: true,
-      note: "Safe cast: value as Field"
+      kind: "conversion",
+      note: "Enum variant index as Field"
+    },
+    {
+      from: "Uint<0..m>",
+      to: "Uint<0..n>",
+      direct: true,
+      kind: "static if m\u2264n, checked if m>n",
+      note: "Widening is static, narrowing is checked"
     },
     {
       from: "arithmetic result",
       to: "Uint<64>",
       direct: true,
+      kind: "checked",
       note: "Required cast: (a + b) as Uint<64>"
     }
   ],
@@ -6812,9 +7559,10 @@ async function extractContractStructure(input) {
     potentialIssues.push({
       type: "unsupported_division",
       line: lineNum,
-      message: `Division operator '/' is not supported in Compact`,
-      suggestion: `Use a witness-based division pattern: 'witness divideWithRemainder(a, b): [quotient, remainder]' with on-chain verification`,
-      severity: "error"
+      message: `Division operator '/' is not in the documented Compact operators (+, -, *)`,
+      suggestion: `If you need division, compute it off-chain in a witness and verify on-chain: 'witness divide(a, b): [quotient, remainder]'`,
+      severity: "warning"
+      // Changed to warning since it's inferred, not explicitly documented
     });
     break;
   }
@@ -8492,6 +9240,10 @@ var HealthCheckInputSchema = z4.object({
 var GetStatusInputSchema = z4.object({});
 var CheckVersionInputSchema = z4.object({});
 var AutoUpdateConfigInputSchema = z4.object({});
+var GetUpdateInstructionsInputSchema = z4.object({
+  platform: z4.enum(["auto", "mac", "windows", "linux"]).optional().default("auto").describe("Target platform (auto-detects if not specified)"),
+  editor: z4.enum(["auto", "claude-desktop", "cursor", "vscode", "windsurf"]).optional().default("auto").describe("Target editor (provides all if auto)")
+});
 
 // src/tools/health/handlers.ts
 import * as os from "os";
@@ -8644,6 +9396,286 @@ async function getAutoUpdateConfig(_input) {
     postUpdateMessage: "\u2705 Config updated! Please restart your editor completely (quit and reopen) to use the latest version."
   };
 }
+var SUPPORTED_EDITORS = [
+  "claude-desktop",
+  "cursor",
+  "vscode",
+  "windsurf"
+];
+function getNpmCacheClearCommand(platform3) {
+  if (platform3 === "windows") {
+    return 'Remove-Item -Recurse -Force "$env:USERPROFILE\\.npm\\_npx" -ErrorAction SilentlyContinue';
+  }
+  return "rm -rf ~/.npm/_npx";
+}
+async function getUpdateInstructions(input) {
+  const platform3 = input.platform === "auto" ? detectPlatform() : input.platform;
+  if (input.editor === "auto") {
+    return getMultiEditorInstructions(platform3);
+  }
+  const editor = input.editor;
+  const configPaths = getConfigPaths(platform3, editor);
+  const restartCommand = getRestartCommand(platform3, editor);
+  const cacheCommand = getNpmCacheClearCommand(platform3);
+  return {
+    title: "\u{1F504} How to Update Midnight MCP",
+    currentSetup: {
+      detectedPlatform: platform3,
+      targetEditor: editor
+    },
+    steps: [
+      {
+        step: 1,
+        title: "Clear npm cache",
+        command: cacheCommand,
+        windowsNote: platform3 === "windows" ? "Run in PowerShell. For cmd.exe use: rd /s /q %USERPROFILE%\\.npm\\_npx" : void 0,
+        explanation: "This removes cached npx packages so the latest version will be downloaded",
+        required: true
+      },
+      {
+        step: 2,
+        title: "Restart your editor completely",
+        action: restartCommand,
+        explanation: "A full restart is needed - just reloading the window is not enough",
+        required: true
+      },
+      {
+        step: 3,
+        title: "If still outdated, update config file",
+        configPath: configPaths.primary,
+        alternativePaths: configPaths.alternatives,
+        change: {
+          find: '"midnight-mcp"',
+          replaceWith: '"midnight-mcp@latest"',
+          location: 'In the "args" array for the midnight server'
+        },
+        explanation: "Adding @latest ensures you always get the newest version",
+        required: false
+      }
+    ],
+    troubleshooting: getTroubleshootingSection(platform3, configPaths),
+    exampleConfig: generateExampleConfig(editor),
+    helpfulLinks: {
+      documentation: "https://github.com/Olanetsoft/midnight-mcp#readme",
+      issues: "https://github.com/Olanetsoft/midnight-mcp/issues"
+    }
+  };
+}
+function getMultiEditorInstructions(platform3) {
+  const cacheCommand = getNpmCacheClearCommand(platform3);
+  const editorConfigs = SUPPORTED_EDITORS.map((editor) => {
+    const paths = getConfigPaths(platform3, editor);
+    const restart = getRestartCommand(platform3, editor);
+    return {
+      editor,
+      displayName: getEditorDisplayName(editor),
+      configPath: paths.primary,
+      alternativePaths: paths.alternatives,
+      restartCommand: restart
+    };
+  });
+  return {
+    title: "\u{1F504} How to Update Midnight MCP",
+    currentSetup: {
+      detectedPlatform: platform3,
+      targetEditor: "all (auto mode)"
+    },
+    commonSteps: [
+      {
+        step: 1,
+        title: "Clear npm cache",
+        command: cacheCommand,
+        windowsNote: platform3 === "windows" ? "Run in PowerShell. For cmd.exe use: rd /s /q %USERPROFILE%\\.npm\\_npx" : void 0,
+        explanation: "This removes cached npx packages so the latest version will be downloaded",
+        required: true
+      },
+      {
+        step: 2,
+        title: "Restart your editor completely",
+        explanation: "A full restart is needed - just reloading the window is not enough",
+        required: true
+      }
+    ],
+    editorSpecificPaths: editorConfigs,
+    configChange: {
+      find: '"midnight-mcp"',
+      replaceWith: '"midnight-mcp@latest"',
+      location: 'In the "args" array for the midnight server'
+    },
+    troubleshooting: [
+      {
+        issue: "Still seeing old version after restart",
+        solutions: [
+          platform3 === "mac" ? "Make sure you quit the editor completely (Cmd+Q)" : platform3 === "windows" ? "Make sure you quit the editor completely (Alt+F4)" : "Make sure you quit the editor completely",
+          "Check if multiple editor instances are running",
+          platform3 === "windows" ? 'Try: Remove-Item -Recurse -Force "$env:USERPROFILE\\.npm\\_npx", "$env:LOCALAPPDATA\\midnight-mcp"' : "Try: rm -rf ~/.npm/_npx && rm -rf ~/.cache/midnight-mcp"
+        ]
+      },
+      {
+        issue: "Config file not found",
+        solutions: [
+          "Check the editor-specific paths listed above",
+          "Create the config file if it doesn't exist",
+          "See docs: https://github.com/Olanetsoft/midnight-mcp"
+        ]
+      }
+    ],
+    exampleConfig: {
+      mcpServers: {
+        midnight: {
+          command: "npx",
+          args: ["-y", "midnight-mcp@latest"]
+        }
+      }
+    },
+    helpfulLinks: {
+      documentation: "https://github.com/Olanetsoft/midnight-mcp#readme",
+      issues: "https://github.com/Olanetsoft/midnight-mcp/issues"
+    }
+  };
+}
+function getEditorDisplayName(editor) {
+  const names = {
+    "claude-desktop": "Claude Desktop",
+    cursor: "Cursor",
+    vscode: "VS Code",
+    windsurf: "Windsurf"
+  };
+  return names[editor] || editor;
+}
+function getTroubleshootingSection(platform3, configPaths) {
+  const quitCommand = platform3 === "mac" ? "Cmd+Q" : platform3 === "windows" ? "Alt+F4" : "close completely";
+  const cacheCleanup = platform3 === "windows" ? 'Remove-Item -Recurse -Force "$env:USERPROFILE\\.npm\\_npx", "$env:LOCALAPPDATA\\midnight-mcp"' : "rm -rf ~/.npm/_npx && rm -rf ~/.cache/midnight-mcp";
+  return [
+    {
+      issue: "Still seeing old version after restart",
+      solutions: [
+        `Make sure you quit the editor completely (${quitCommand})`,
+        "Check if multiple editor instances are running",
+        `Try: ${cacheCleanup}`
+      ]
+    },
+    {
+      issue: "Config file not found",
+      solutions: [
+        `Primary location: ${configPaths.primary}`,
+        "Create it if it doesn't exist",
+        "See docs: https://github.com/Olanetsoft/midnight-mcp"
+      ]
+    },
+    {
+      issue: "Permission denied errors",
+      solutions: platform3 === "windows" ? [
+        "Run editor as administrator",
+        "Check file permissions in Windows Security settings"
+      ] : [
+        "Check file permissions with ls -la",
+        "Ensure your user owns the config file"
+      ]
+    }
+  ];
+}
+function detectPlatform() {
+  const p = process.platform;
+  if (p === "darwin") return "mac";
+  if (p === "win32") return "windows";
+  return "linux";
+}
+function getConfigPaths(platform3, editor) {
+  const home = process.env.HOME || process.env.USERPROFILE || "~";
+  const paths = {
+    mac: {
+      "claude-desktop": {
+        primary: `${home}/Library/Application Support/Claude/claude_desktop_config.json`,
+        alternatives: []
+      },
+      cursor: {
+        primary: `${home}/.cursor/mcp.json`,
+        alternatives: [`${home}/Library/Application Support/Cursor/mcp.json`]
+      },
+      vscode: {
+        primary: `${home}/.vscode/mcp.json`,
+        alternatives: [
+          `${home}/Library/Application Support/Code/User/settings.json`
+        ]
+      },
+      windsurf: {
+        primary: `${home}/.codeium/windsurf/mcp_config.json`,
+        alternatives: []
+      }
+    },
+    windows: {
+      "claude-desktop": {
+        primary: `%APPDATA%\\Claude\\claude_desktop_config.json`,
+        alternatives: []
+      },
+      cursor: {
+        primary: `%USERPROFILE%\\.cursor\\mcp.json`,
+        alternatives: [`%APPDATA%\\Cursor\\mcp.json`]
+      },
+      vscode: {
+        primary: `%USERPROFILE%\\.vscode\\mcp.json`,
+        alternatives: [`%APPDATA%\\Code\\User\\settings.json`]
+      },
+      windsurf: {
+        primary: `%USERPROFILE%\\.codeium\\windsurf\\mcp_config.json`,
+        alternatives: []
+      }
+    },
+    linux: {
+      "claude-desktop": {
+        primary: `${home}/.config/Claude/claude_desktop_config.json`,
+        alternatives: []
+      },
+      cursor: {
+        primary: `${home}/.cursor/mcp.json`,
+        alternatives: [`${home}/.config/Cursor/mcp.json`]
+      },
+      vscode: {
+        primary: `${home}/.vscode/mcp.json`,
+        alternatives: [`${home}/.config/Code/User/settings.json`]
+      },
+      windsurf: {
+        primary: `${home}/.codeium/windsurf/mcp_config.json`,
+        alternatives: []
+      }
+    }
+  };
+  return paths[platform3]?.[editor] || paths.mac["claude-desktop"];
+}
+function getRestartCommand(platform3, editor) {
+  const editorNames = {
+    "claude-desktop": "Claude Desktop",
+    cursor: "Cursor",
+    vscode: "VS Code",
+    windsurf: "Windsurf"
+  };
+  const name = editorNames[editor] || editor;
+  if (platform3 === "mac") {
+    return `Quit ${name} completely (Cmd+Q), then reopen`;
+  } else if (platform3 === "windows") {
+    return `Close ${name} completely (Alt+F4 or File > Exit), then reopen`;
+  } else {
+    return `Close ${name} completely, then reopen`;
+  }
+}
+function generateExampleConfig(editor) {
+  const baseConfig = {
+    mcpServers: {
+      midnight: {
+        command: "npx",
+        args: ["-y", "midnight-mcp@latest"]
+      }
+    }
+  };
+  if (editor === "vscode") {
+    return {
+      note: "For VS Code, add to settings.json or mcp.json",
+      config: baseConfig
+    };
+  }
+  return baseConfig;
+}
 
 // src/tools/health/tools.ts
 var healthCheckOutputSchema = {
@@ -8810,6 +9842,45 @@ var healthTools = [
       category: "health"
     },
     handler: getAutoUpdateConfig
+  },
+  {
+    name: "midnight-get-update-instructions",
+    description: "\u{1F4CB} Get detailed, platform-specific instructions for updating Midnight MCP to the latest version. Provides step-by-step guidance including config file locations, commands to run, and troubleshooting tips. Use this when a user needs help updating or is having issues with outdated versions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        platform: {
+          type: "string",
+          enum: ["auto", "mac", "windows", "linux"],
+          description: "Target platform (auto-detects if not specified)",
+          default: "auto"
+        },
+        editor: {
+          type: "string",
+          enum: ["auto", "claude-desktop", "cursor", "vscode", "windsurf"],
+          description: "Target editor (defaults to Claude Desktop)",
+          default: "auto"
+        }
+      }
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string" },
+        currentSetup: { type: "object" },
+        steps: { type: "array", items: { type: "object" } },
+        troubleshooting: { type: "array", items: { type: "object" } },
+        exampleConfig: { type: "object" },
+        helpfulLinks: { type: "object" }
+      }
+    },
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+      title: "\u{1F4CB} Get Update Instructions",
+      category: "health"
+    },
+    handler: getUpdateInstructions
   }
 ];
 
@@ -10114,4 +11185,4 @@ export {
   startServer,
   startHttpServer
 };
-//# sourceMappingURL=chunk-YT6DWZUA.js.map
+//# sourceMappingURL=chunk-V7KK64OX.js.map