midnight-mcp 0.1.22 → 0.1.24

package/README.md

@@ -15,11 +15,13 @@ MCP server that gives AI assistants access to Midnight blockchain—search contr
 ```json
 {
   "mcpServers": {
-    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp"] }
+    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp@latest"] }
   }
 }
 ```
 
+> **💡 Tip:** Using `@latest` ensures you always get the newest version with all features. If tools seem missing, run `rm -rf ~/.npm/_npx` and restart Claude Desktop.
+
 **Cursor** — One-click install:
 
 [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=midnight&config=eyJjb21tYW5kIjoibnB4IC15IG1pZG5pZ2h0LW1jcCJ9)
@@ -73,19 +75,23 @@ Restart your editor after adding the config. **No API keys required.**
 
 ## Features
 
-**23 Tools** — Search, analyze, version tracking, AI generation, compound operations
-
-| Category      | Tools                                                                                                                                                                                   |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Search        | `midnight-search-compact`, `midnight-search-typescript`, `midnight-search-docs`                                                                                                         |
-| Analysis      | `midnight-analyze-contract`, `midnight-explain-circuit`                                                                                                                                 |
-| Repository    | `midnight-get-file`, `midnight-list-examples`, `midnight-get-latest-updates`                                                                                                            |
-| Versioning    | `midnight-get-version-info`, `midnight-check-breaking-changes`, `midnight-get-migration-guide`, `midnight-get-file-at-version`, `midnight-compare-syntax`, `midnight-get-latest-syntax` |
-| AI Generation | `midnight-generate-contract`, `midnight-review-contract`, `midnight-document-contract` _(requires sampling)_                                                                            |
-| Compound      | `midnight-upgrade-check`, `midnight-get-repo-context` _(saves 50-70% tokens)_                                                                                                           |
-| Discovery     | `midnight-list-tool-categories`, `midnight-list-category-tools`, `midnight-health-check`, `midnight-get-status`                                                                         |
-
-> **Tip:** Use compound tools (`midnight-upgrade-check`, `midnight-get-repo-context`) for efficient multi-step operations in a single call.
+**24 Tools** — Search, analyze, validate, version tracking, AI generation, compound operations
+
+| Category       | Tools                                                                                                                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Search         | `midnight-search-compact`, `midnight-search-typescript`, `midnight-search-docs`                                                                                                         |
+| Analysis       | `midnight-analyze-contract`, `midnight-explain-circuit`                                                                                                                                 |
+| **Validation** | `midnight-validate-contract` ⭐, `midnight-extract-contract-structure`                                                                                                                  |
+| Repository     | `midnight-get-file`, `midnight-list-examples`, `midnight-get-latest-updates`                                                                                                            |
+| Versioning     | `midnight-get-version-info`, `midnight-check-breaking-changes`, `midnight-get-migration-guide`, `midnight-get-file-at-version`, `midnight-compare-syntax`, `midnight-get-latest-syntax` |
+| AI Generation  | `midnight-generate-contract`, `midnight-review-contract`, `midnight-document-contract` _(requires sampling)_                                                                            |
+| Compound       | `midnight-upgrade-check`, `midnight-get-repo-context` _(saves 50-70% tokens)_                                                                                                           |
+| Health         | `midnight-health-check`, `midnight-get-status`, `midnight-check-version` 🔄                                                                                                             |
+| Discovery      | `midnight-list-tool-categories`, `midnight-list-category-tools`                                                                                                                         |
+
+> **⭐ Key Tool:** `midnight-validate-contract` compiles code using the **real Compact compiler** - essential for verifying contracts actually work before deployment.
+>
+> **🔄 New:** `midnight-check-version` tells you if you're running the latest version with update instructions.
 
 **9 Embedded Resources** — Quick references available offline: Compact syntax, SDK API, OpenZeppelin contracts, tokenomics, wallet integration, common errors
 

package/dist/tools/analyze.js

@@ -377,7 +377,11 @@ const explainCircuitOutputSchema = {
 export const analyzeTools = [
     {
         name: "midnight-analyze-contract",
-        description: "Analyze a Compact smart contract for structure, patterns, and potential security issues. Returns detailed breakdown of circuits, witnesses, ledger state, and recommendations.",
+        description: "⚠️ STATIC ANALYSIS ONLY - Analyze contract structure and patterns. " +
+            "🚫 THIS DOES NOT COMPILE THE CONTRACT. Cannot catch: sealed field rules, disclose() requirements, semantic errors. " +
+            "👉 ALWAYS call 'midnight-validate-contract' FIRST to verify the code actually compiles. " +
+            "Use this for: understanding structure, security pattern analysis, recommendations. " +
+            "NEVER claim a contract 'works' or 'compiles' based on this tool alone.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/health.d.ts

@@ -11,8 +11,10 @@ export declare const HealthCheckInputSchema: z.ZodObject<{
     detailed?: boolean | undefined;
 }>;
 export declare const GetStatusInputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const CheckVersionInputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 export type HealthCheckInput = z.infer<typeof HealthCheckInputSchema>;
 export type GetStatusInput = z.infer<typeof GetStatusInputSchema>;
+export type CheckVersionInput = z.infer<typeof CheckVersionInputSchema>;
 /**
  * Perform health check on the MCP server
  */
@@ -64,5 +66,30 @@ export declare function getStatus(_input: GetStatusInput): Promise<{
         metadata: import("../utils/cache.js").CacheStats;
     };
 }>;
+/**
+ * Check if current version is up to date with npm
+ */
+export declare function checkVersion(_input: CheckVersionInput): Promise<{
+    currentVersion: string;
+    latestVersion: string;
+    isUpToDate: boolean;
+    error: string;
+    message?: undefined;
+    updateInstructions?: undefined;
+    newFeatures?: undefined;
+} | {
+    currentVersion: string;
+    latestVersion: string;
+    isUpToDate: boolean;
+    message: string;
+    updateInstructions: {
+        step1: string;
+        step2: string;
+        step3: string;
+        alternative: string;
+    } | null;
+    newFeatures: string[] | null;
+    error?: undefined;
+}>;
 export declare const healthTools: ExtendedToolDefinition[];
 //# sourceMappingURL=health.d.ts.map

package/dist/tools/health.js

@@ -4,6 +4,8 @@
 import { z } from "zod";
 import { getHealthStatus, getQuickHealthStatus, getRateLimitStatus, formatRateLimitStatus, } from "../utils/index.js";
 import { searchCache, fileCache, metadataCache } from "../utils/cache.js";
+// Current version - should match package.json
+const CURRENT_VERSION = "0.1.24";
 // Schema definitions
 export const HealthCheckInputSchema = z.object({
     detailed: z
@@ -13,6 +15,7 @@ export const HealthCheckInputSchema = z.object({
         .describe("Include detailed checks (slower but more comprehensive)"),
 });
 export const GetStatusInputSchema = z.object({});
+export const CheckVersionInputSchema = z.object({});
 /**
  * Perform health check on the MCP server
  */
@@ -61,6 +64,56 @@ export async function getStatus(_input) {
         },
     };
 }
+/**
+ * Check if current version is up to date with npm
+ */
+export async function checkVersion(_input) {
+    try {
+        const response = await fetch("https://registry.npmjs.org/midnight-mcp/latest");
+        if (!response.ok) {
+            return {
+                currentVersion: CURRENT_VERSION,
+                latestVersion: "unknown",
+                isUpToDate: true, // Assume up to date if we can't check
+                error: "Could not fetch latest version from npm",
+            };
+        }
+        const data = (await response.json());
+        const latestVersion = data.version;
+        const isUpToDate = CURRENT_VERSION === latestVersion;
+        return {
+            currentVersion: CURRENT_VERSION,
+            latestVersion,
+            isUpToDate,
+            message: isUpToDate
+                ? "✅ You are running the latest version!"
+                : `⚠️ UPDATE AVAILABLE: v${latestVersion} (you have v${CURRENT_VERSION})`,
+            updateInstructions: isUpToDate
+                ? null
+                : {
+                    step1: "Clear npx cache: rm -rf ~/.npm/_npx (macOS/Linux) or del /s /q %LocalAppData%\\npm-cache\\_npx (Windows)",
+                    step2: "Restart Claude Desktop completely (Cmd+Q / Alt+F4, then reopen)",
+                    step3: "Or update config to use: npx -y midnight-mcp@latest (forces latest)",
+                    alternative: "You can also install globally: npm install -g midnight-mcp@latest",
+                },
+            newFeatures: isUpToDate
+                ? null
+                : [
+                    "midnight-validate-contract - Compile with REAL Compact compiler",
+                    "midnight-extract-contract-structure - Static analysis with 10 pre-compilation checks",
+                    "Pre-compilation detection: division operator, Counter.value, overflow, disclose() requirements",
+                ],
+        };
+    }
+    catch (error) {
+        return {
+            currentVersion: CURRENT_VERSION,
+            latestVersion: "unknown",
+            isUpToDate: true,
+            error: `Failed to check version: ${error instanceof Error ? error.message : "Unknown error"}`,
+        };
+    }
+}
 // Output schemas for health tools
 const healthCheckOutputSchema = {
     type: "object",
@@ -160,5 +213,47 @@ export const healthTools = [
         },
         handler: getStatus,
     },
+    {
+        name: "midnight-check-version",
+        description: "🔄 Check if you're running the latest version of midnight-mcp. " +
+            "Compares your installed version against npm registry and provides update instructions if outdated. " +
+            "Use this if tools seem missing or you want to ensure you have the latest features like midnight-validate-contract.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                currentVersion: {
+                    type: "string",
+                    description: "Your installed version",
+                },
+                latestVersion: { type: "string", description: "Latest version on npm" },
+                isUpToDate: {
+                    type: "boolean",
+                    description: "Whether you have the latest",
+                },
+                message: { type: "string", description: "Status message" },
+                updateInstructions: {
+                    type: "object",
+                    description: "How to update if outdated",
+                },
+                newFeatures: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "New features in latest version",
+                },
+            },
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+            title: "🔄 Check for Updates",
+            category: "health",
+        },
+        handler: checkVersion,
+    },
 ];
 //# sourceMappingURL=health.js.map

package/dist/tools/index.d.ts

@@ -4,8 +4,8 @@ export { analyzeTools, analyzeContract, explainCircuit } from "./analyze.js";
 export type { AnalyzeContractInput, ExplainCircuitInput } from "./analyze.js";
 export { repositoryTools, getFile, listExamples, getLatestUpdates, } from "./repository.js";
 export type { GetFileInput, ListExamplesInput, GetLatestUpdatesInput, } from "./repository.js";
-export { healthTools, healthCheck, getStatus } from "./health.js";
-export type { HealthCheckInput, GetStatusInput } from "./health.js";
+export { healthTools, healthCheck, getStatus, checkVersion } from "./health.js";
+export type { HealthCheckInput, GetStatusInput, CheckVersionInput, } from "./health.js";
 export { generationTools, generationHandlers } from "./generation.js";
 export { metaTools, listToolCategories, listCategoryTools } from "./meta.js";
 export type { ExtendedToolDefinition, ToolAnnotations, OutputSchema, } from "../types/index.js";

package/dist/tools/index.js

@@ -1,7 +1,7 @@
 export { searchTools, searchCompact, searchTypeScript, searchDocs, } from "./search.js";
 export { analyzeTools, analyzeContract, explainCircuit } from "./analyze.js";
 export { repositoryTools, getFile, listExamples, getLatestUpdates, } from "./repository.js";
-export { healthTools, healthCheck, getStatus } from "./health.js";
+export { healthTools, healthCheck, getStatus, checkVersion } from "./health.js";
 export { generationTools, generationHandlers } from "./generation.js";
 export { metaTools, listToolCategories, listCategoryTools } from "./meta.js";
 // Combined tool list for MCP server

package/dist/tools/repository/tools.js

@@ -358,7 +358,13 @@ export const repositoryTools = [
     // ============================================================================
     {
         name: "midnight-validate-contract",
-        description: "🔍 PRIMARY VERIFICATION: Compile and validate a Compact contract using the ACTUAL Compact compiler. **ALWAYS use this tool first** when verifying contract code - it catches real compilation errors that static analysis cannot detect. Returns detailed error messages with line numbers, suggested fixes, and actionable guidance. If the compiler is not installed, it will provide installation instructions. Accepts either source code directly OR a file path to a .compact file. For contracts you generate, ALWAYS validate with this tool before presenting to the user.",
+        description: "� REQUIRED - ALWAYS CALL THIS FIRST: Compile a Compact contract using the REAL compiler. " +
+            "⚠️ CRITICAL: You MUST call this tool BEFORE telling the user a contract works or is correct. " +
+            "Static analysis tools like 'extract-contract-structure' or 'analyze-contract' CANNOT verify compilation - they miss semantic errors like: " +
+            "(1) sealed fields require constructor, (2) constructor params need disclose(), (3) export circuits cannot modify sealed fields. " +
+            "This tool runs the ACTUAL Compact compiler and returns real errors with line numbers. " +
+            "If compiler not installed, it provides installation instructions. " +
+            "WORKFLOW: Generate code → Call this tool → Fix errors → Repeat until success → THEN present to user.",
         inputSchema: {
             type: "object",
             properties: {
@@ -454,7 +460,12 @@ export const repositoryTools = [
     },
     {
         name: "midnight-extract-contract-structure",
-        description: "📋 STATIC ANALYSIS (not verification): Extract the structure of a Compact contract and detect common issues. Returns circuits, witnesses, ledger items, types, structs, enums, and **potentialIssues** (module-level const, stdlib collisions, sealed+export conflicts). **WARNING: This does NOT verify compilation** - use 'midnight-validate-contract' for actual compiler verification. Use this tool for: (1) understanding contract structure, (2) quick pre-checks before compilation, (3) fallback analysis when compiler unavailable. Do NOT claim a contract 'compiles correctly' based only on this tool.",
+        description: "⚠️ STATIC ANALYSIS ONLY - NOT A COMPILER: Extracts contract structure (circuits, witnesses, ledger) and detects common patterns. " +
+            "🚫 THIS TOOL CANNOT VERIFY COMPILATION. It will NOT catch: sealed field rules, disclose() requirements, type mismatches, or semantic errors. " +
+            "✅ USE FOR: Understanding structure, quick pattern checks, fallback when compiler unavailable. " +
+            "❌ NEVER USE TO: Verify a contract works, claim code 'compiles correctly', or validate before presenting to user. " +
+            "👉 ALWAYS call 'midnight-validate-contract' FIRST to actually compile the code. " +
+            "Detects: module-level const, stdlib collisions, sealed+export conflicts, missing disclose(), Counter.value access, division operator.",
         inputSchema: {
             type: "object",
             properties: {

package/package.json

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