midnight-mcp 0.2.2 → 0.2.3

package/README.md

@@ -8,6 +8,33 @@
 
 MCP server that gives AI assistants access to Midnight blockchain—search contracts, analyze code, and explore documentation.
 
+## Requirements
+
+- **Node.js 20+** (LTS recommended)
+
+Check your version: `node --version`
+
+<details>
+<summary><strong>Using nvm?</strong> Click for Claude Desktop setup</summary>
+
+If you use nvm, Claude Desktop may not see your nvm-managed Node. Use this config instead:
+
+```json
+{
+  "mcpServers": {
+    "midnight": {
+      "command": "/bin/sh",
+      "args": [
+        "-c",
+        "source ~/.nvm/nvm.sh && nvm use 20 >/dev/null 2>&1 && npx -y midnight-mcp@latest"
+      ]
+    }
+  }
+}
+```
+
+</details>
+
 ## Quick Start
 
 ### Claude Desktop
@@ -71,33 +98,13 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 **No API keys required.** Restart your editor after adding the config.
 
-### Updating to Latest Version
-
-Using `midnight-mcp@latest` in your config ensures you get updates automatically on restart.
-
-**Already using an older version without `@latest`?** Update your config manually:
-
-```diff
-- "args": ["-y", "midnight-mcp"]
-+ "args": ["-y", "midnight-mcp@latest"]
-```
-
-**Then clear npm cache and restart:**
-
-```bash
-# Clear npx cache (required to fetch new version)
-rm -rf ~/.npm/_npx
-
-# Restart your editor (Cmd+Q on Mac, then reopen)
-```
-
-> **Note:** AI agents cannot auto-update your config because they run in a sandboxed environment without access to your local filesystem.
+> **Why `@latest`?** Unlike cached npx packages that never auto-update, `@latest` ensures you get new features and fixes on each restart. If upgrading from an older config without `@latest`, also clear your npx cache: `rm -rf ~/.npm/_npx`
 
 ---
 
 ## What's Included
 
-### 26 Tools
+### 27 Tools
 
 | Category          | Tools                                                                                                                             | Description                                      |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
@@ -108,7 +115,7 @@ rm -rf ~/.npm/_npx
 | **AI Generation** | `generate-contract`, `review-contract`, `document-contract`                                                                       | AI-powered code generation _(requires sampling)_ |
 | **Compound**      | `upgrade-check`, `get-repo-context`                                                                                               | Multi-step operations _(saves 50-70% tokens)_    |
 | **Health**        | `health-check`, `get-status`, `check-version`                                                                                     | Server status and version checking               |
-| **Discovery**     | `list-tool-categories`, `list-category-tools`                                                                                     | Explore available tools                          |
+| **Discovery**     | `list-tool-categories`, `list-category-tools`, `suggest-tool`                                                                     | Explore available tools and get recommendations  |
 
 All tools are prefixed with `midnight-` (e.g., `midnight-search-compact`).
 
@@ -116,7 +123,7 @@ All tools are prefixed with `midnight-` (e.g., `midnight-search-compact`).
 
 | Capability      | Feature                                         |
 | --------------- | ----------------------------------------------- |
-| **Tools**       | 26 tools with `listChanged` notifications       |
+| **Tools**       | 27 tools with `listChanged` notifications       |
 | **Resources**   | 9 embedded resources with subscription support  |
 | **Prompts**     | 5 workflow prompts                              |
 | **Logging**     | Client-controllable log level                   |

package/dist/bin.js

@@ -2,10 +2,10 @@
 import {
   startHttpServer,
   startServer
-} from "./chunk-S7G4OHA4.js";
+} from "./chunk-ZYCQLQEX.js";
 import {
   setOutputFormat
-} from "./chunk-HOWO4K5A.js";
+} from "./chunk-EBFMM2DS.js";
 
 // src/bin.ts
 import { config } from "dotenv";
@@ -13,7 +13,7 @@ import { resolve } from "path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 config({ path: resolve(process.cwd(), ".env") });
-var CURRENT_VERSION = "0.2.2";
+var CURRENT_VERSION = "0.2.3";
 process.on("uncaughtException", (error) => {
   console.error("Uncaught exception:", error);
   process.exit(1);

package/dist/{chunk-HOWO4K5A.js → chunk-EBFMM2DS.js}

@@ -1594,7 +1594,7 @@ async function checkGitHubAPI() {
 }
 async function checkVectorStore() {
   try {
-    const { vectorStore: vectorStore2 } = await import("./db-YDGUWI5K.js");
+    const { vectorStore: vectorStore2 } = await import("./db-ILWTH42C.js");
     if (vectorStore2) {
       return {
         status: "pass",
@@ -1899,6 +1899,39 @@ setInterval(pruneAllCaches, 5 * 60 * 1e3);
 
 // src/utils/hosted-api.ts
 var API_TIMEOUT = 1e4;
+function getActionableErrorMessage(status, endpoint, serverMessage) {
+  const baseMessages = {
+    400: `Bad request to ${endpoint}. Check your query parameters are valid.`,
+    401: `Authentication failed. If you have an API key configured, verify it's correct.`,
+    403: `Access denied to ${endpoint}. This resource may require authentication.`,
+    404: `Resource not found at ${endpoint}. Use midnight-list-examples to see available resources.`,
+    408: `Request timed out. The hosted service may be under heavy load - try again in a moment.`,
+    429: `Rate limited. Try again in a few minutes, or set MIDNIGHT_LOCAL=true for unlimited local search (requires ChromaDB + OpenAI API key).`,
+    500: `Server error. This is temporary - try again shortly or report at github.com/Olanetsoft/midnight-mcp/issues`,
+    502: `Bad gateway. The hosted API may be restarting - try again in 30 seconds.`,
+    503: `Service temporarily unavailable. The hosted API may be under maintenance - try again later or use MIDNIGHT_LOCAL=true for local mode.`,
+    504: `Gateway timeout. The request took too long - try a simpler query or try again later.`
+  };
+  const actionableMessage = baseMessages[status] || `API error (${status}). Try again or report at github.com/Olanetsoft/midnight-mcp/issues`;
+  if (serverMessage && !actionableMessage.includes(serverMessage)) {
+    return `${actionableMessage} Server said: "${serverMessage}"`;
+  }
+  return actionableMessage;
+}
+async function parseApiError(response, endpoint) {
+  let serverMessage;
+  try {
+    const errorData = await response.json();
+    serverMessage = errorData.error || errorData.message;
+  } catch {
+  }
+  const actionableMessage = getActionableErrorMessage(
+    response.status,
+    endpoint,
+    serverMessage
+  );
+  return new Error(actionableMessage);
+}
 async function apiRequest(endpoint, options = {}) {
   const url = `${config.hostedApiUrl}${endpoint}`;
   const controller = new AbortController();
@@ -1914,14 +1947,21 @@ async function apiRequest(endpoint, options = {}) {
       }
     });
     if (!response.ok) {
-      const errorData = await response.json().catch(() => ({ error: "Unknown error" }));
-      throw new Error(errorData.error || `API error: ${response.status}`);
+      throw await parseApiError(response, endpoint);
     }
     return await response.json();
   } catch (error) {
     if (error instanceof Error && error.name === "AbortError") {
       throw new Error(
-        "API request timed out. The hosted service may be unavailable."
+        `Request to ${endpoint} timed out after ${API_TIMEOUT / 1e3}s. The hosted service may be unavailable. Try again or set MIDNIGHT_LOCAL=true for local search.`
+      );
+    }
+    if (error instanceof Error && error.message.includes("github.com/Olanetsoft")) {
+      throw error;
+    }
+    if (error instanceof Error) {
+      throw new Error(
+        `Failed to connect to hosted API: ${error.message}. Check your internet connection or set MIDNIGHT_LOCAL=true for local search.`
       );
     }
     throw error;
@@ -1985,7 +2025,7 @@ function serialize(data) {
 }
 
 // src/utils/version.ts
-var CURRENT_VERSION = "0.2.2";
+var CURRENT_VERSION = "0.2.3";
 
 // src/db/vectorStore.ts
 var VectorStore = class {
@@ -2194,4 +2234,4 @@ export {
   serialize,
   CURRENT_VERSION
 };
-//# sourceMappingURL=chunk-HOWO4K5A.js.map
+//# sourceMappingURL=chunk-EBFMM2DS.js.map

package/dist/{chunk-S7G4OHA4.js → chunk-ZYCQLQEX.js}

@@ -25,7 +25,7 @@ import {
   validateNumber,
   validateQuery,
   vectorStore
-} from "./chunk-HOWO4K5A.js";
+} from "./chunk-EBFMM2DS.js";
 
 // src/tools/search/schemas.ts
 import { z } from "zod";
@@ -324,7 +324,12 @@ var searchToolAnnotations = {
 var searchTools = [
   {
     name: "midnight-search-compact",
-    description: "Semantic search across Compact smart contract code and patterns. Use this to find circuit definitions, witness functions, ledger declarations, and best practices for Midnight smart contracts.",
+    description: `Semantic search across Compact smart contract code and patterns. Use this to find circuit definitions, witness functions, ledger declarations, and best practices for Midnight smart contracts.
+
+USAGE GUIDANCE:
+\u2022 Call at most 2 times per question - if first search doesn't help, try different keywords
+\u2022 For comprehensive results, combine with midnight-search-docs
+\u2022 Use specific terms like "ledger", "circuit", "witness" for better matches`,
     inputSchema: {
       type: "object",
       properties: {
@@ -356,7 +361,12 @@ var searchTools = [
   },
   {
     name: "midnight-search-typescript",
-    description: "Search TypeScript SDK code, types, and API implementations. Use this to find how to use the Midnight JavaScript SDK, type definitions, and integration patterns.",
+    description: `Search TypeScript SDK code, types, and API implementations. Use this to find how to use the Midnight JavaScript SDK, type definitions, and integration patterns.
+
+USAGE GUIDANCE:
+\u2022 Call at most 2 times per question - refine keywords rather than repeating
+\u2022 For contract code, use midnight-search-compact instead
+\u2022 Include "type" or "interface" in query for type definitions`,
     inputSchema: {
       type: "object",
       properties: {
@@ -388,7 +398,12 @@ var searchTools = [
   },
   {
     name: "midnight-search-docs",
-    description: "Full-text search across official Midnight documentation. Use this to find guides, API documentation, and conceptual explanations about Midnight blockchain and the Compact language.",
+    description: `Full-text search across official Midnight documentation. Use this to find guides, API documentation, and conceptual explanations about Midnight blockchain and the Compact language.
+
+USAGE GUIDANCE:
+\u2022 Call at most 2 times per question - use different keywords if first search fails
+\u2022 For code examples, combine with midnight-search-compact or midnight-search-typescript
+\u2022 Use category filter to narrow results (guides, api, concepts)`,
     inputSchema: {
       type: "object",
       properties: {
@@ -784,7 +799,17 @@ var explainCircuitOutputSchema = {
 var analyzeTools = [
   {
     name: "midnight-analyze-contract",
-    description: "\u26A0\uFE0F STATIC ANALYSIS ONLY - Analyze contract structure and patterns. \u{1F6AB} THIS DOES NOT COMPILE THE CONTRACT. Cannot catch: sealed field rules, disclose() requirements, semantic errors. \u{1F449} Use 'midnight-extract-contract-structure' for pre-compilation checks. Use this for: understanding structure, security pattern analysis, recommendations. NEVER claim a contract 'works' or 'compiles' based on this tool alone.",
+    description: `\u26A0\uFE0F STATIC ANALYSIS ONLY - Analyze contract structure and patterns.
+\u{1F6AB} THIS DOES NOT COMPILE THE CONTRACT. Cannot catch: sealed field rules, disclose() requirements, semantic errors.
+\u{1F449} Use 'midnight-extract-contract-structure' for pre-compilation checks.
+
+Use this for: understanding structure, security pattern analysis, recommendations.
+NEVER claim a contract 'works' or 'compiles' based on this tool alone.
+
+USAGE GUIDANCE:
+\u2022 Call once per contract - results are deterministic
+\u2022 For security review, also use midnight-review-contract (requires sampling)
+\u2022 Run before making changes, not repeatedly during iteration`,
     inputSchema: {
       type: "object",
       properties: {
@@ -810,7 +835,12 @@ var analyzeTools = [
   },
   {
     name: "midnight-explain-circuit",
-    description: "Explain what a specific Compact circuit does in plain language, including its zero-knowledge proof implications and privacy considerations.",
+    description: `Explain what a specific Compact circuit does in plain language, including its zero-knowledge proof implications and privacy considerations.
+
+USAGE GUIDANCE:
+\u2022 Call once per circuit - explanations are deterministic
+\u2022 Provide complete circuit code including parameters and body
+\u2022 For full contract analysis, use midnight-analyze-contract first`,
     inputSchema: {
       type: "object",
       properties: {
@@ -6935,7 +6965,12 @@ function getInstallCommand(repoName, version) {
 var repositoryTools = [
   {
     name: "midnight-get-file",
-    description: "Retrieve a specific file from Midnight repositories. Use repository aliases like 'compact', 'midnight-js', 'counter', or 'bboard' for convenience.",
+    description: `Retrieve a specific file from Midnight repositories. Use repository aliases like 'compact', 'midnight-js', 'counter', or 'bboard' for convenience.
+
+USAGE GUIDANCE:
+\u2022 Use midnight-list-examples first if you're unsure which file to get
+\u2022 For searching across files, use midnight-search-* tools instead
+\u2022 Use 'ref' parameter to get specific versions (branch, tag, or commit)`,
     inputSchema: {
       type: "object",
       properties: {
@@ -8015,6 +8050,11 @@ var ListCategoryToolsInputSchema = z6.object({
   ]).describe("Category to list tools for"),
   includeSchemas: z6.boolean().optional().default(false).describe("Include input/output schemas")
 });
+var SuggestToolInputSchema = z6.object({
+  intent: z6.string().describe(
+    "What you want to accomplish (e.g., 'find example voting contract', 'check if my version is outdated', 'analyze my contract for security issues')"
+  )
+});
 var CATEGORY_INFO = {
   search: {
     description: "Semantic search across Midnight codebase - find code by meaning, not keywords",
@@ -8022,7 +8062,33 @@ var CATEGORY_INFO = {
       "Find example implementations",
       "Search for patterns",
       "Discover relevant code"
-    ]
+    ],
+    intentKeywords: [
+      // Core search verbs
+      "find",
+      "search",
+      "look for",
+      "locate",
+      "discover",
+      "explore",
+      // Question patterns
+      "example",
+      "how to",
+      "show me",
+      "where is",
+      "what is",
+      "can i see",
+      "give me",
+      // Code-specific
+      "pattern",
+      "implementation",
+      "code for",
+      "sample",
+      "snippet",
+      "reference",
+      "similar to"
+    ],
+    startWith: "midnight-search-compact"
   },
   analyze: {
     description: "Static analysis of Compact contracts - security, structure, patterns",
@@ -8030,7 +8096,34 @@ var CATEGORY_INFO = {
       "Security audit",
       "Code review",
       "Understand contract structure"
-    ]
+    ],
+    intentKeywords: [
+      // Analysis verbs
+      "analyze",
+      "check",
+      "inspect",
+      "examine",
+      "evaluate",
+      "assess",
+      // Security-related
+      "security",
+      "audit",
+      "vulnerability",
+      "vulnerabilities",
+      "safe",
+      "secure",
+      "risk",
+      // Understanding
+      "review",
+      "structure",
+      "explain",
+      "understand",
+      "what does",
+      "breakdown",
+      "how does",
+      "meaning of"
+    ],
+    startWith: "midnight-analyze-contract"
   },
   repository: {
     description: "Access repository files, examples, and recent updates",
@@ -8038,7 +8131,32 @@ var CATEGORY_INFO = {
       "Get specific files",
       "List examples",
       "Track repository changes"
-    ]
+    ],
+    intentKeywords: [
+      // File access
+      "get file",
+      "fetch",
+      "download",
+      "read file",
+      "open",
+      "source code",
+      "raw",
+      // Listing
+      "list",
+      "examples",
+      "show examples",
+      "available",
+      "what examples",
+      // Repository state
+      "recent",
+      "updates",
+      "changes",
+      "commits",
+      "history",
+      "modified",
+      "new files"
+    ],
+    startWith: "midnight-list-examples"
   },
   versioning: {
     description: "Version management, breaking changes, and migration assistance",
@@ -8047,15 +8165,92 @@ var CATEGORY_INFO = {
       "Plan upgrades",
       "Compare versions",
       "Get migration guides"
-    ]
+    ],
+    intentKeywords: [
+      // Version-related
+      "version",
+      "upgrade",
+      "update",
+      "migrate",
+      "migration",
+      // State checks
+      "breaking",
+      "outdated",
+      "latest",
+      "current",
+      "deprecated",
+      "old",
+      "new version",
+      // Comparison
+      "compare",
+      "diff",
+      "difference",
+      "changed between",
+      "what changed",
+      // Guidance
+      "syntax",
+      "correct syntax",
+      "reference"
+    ],
+    startWith: "midnight-upgrade-check"
   },
   generation: {
     description: "AI-powered code generation, review, and documentation (requires sampling)",
-    useCases: ["Generate contracts", "Review code", "Generate documentation"]
+    useCases: ["Generate contracts", "Review code", "Generate documentation"],
+    intentKeywords: [
+      // Creation verbs
+      "generate",
+      "create",
+      "write",
+      "build",
+      "make",
+      "scaffold",
+      "boilerplate",
+      // AI-specific
+      "ai",
+      "help me write",
+      "draft",
+      "produce",
+      // Documentation
+      "document",
+      "documentation",
+      "explain code",
+      "comment",
+      // Review
+      "improve",
+      "suggest fix",
+      "refactor"
+    ],
+    startWith: "midnight-generate-contract"
   },
   health: {
     description: "Server health checks and status monitoring",
-    useCases: ["Check API status", "Monitor rate limits", "Debug connectivity"]
+    useCases: ["Check API status", "Monitor rate limits", "Debug connectivity"],
+    intentKeywords: [
+      // Status checks
+      "health",
+      "status",
+      "working",
+      "alive",
+      "running",
+      "up",
+      // Problems
+      "rate limit",
+      "throttle",
+      "quota",
+      "error",
+      "issue",
+      "problem",
+      // Debugging
+      "debug",
+      "connection",
+      "connectivity",
+      "api",
+      "server",
+      "not working",
+      "broken"
+    ],
+    startWith: "midnight-health-check"
   },
   compound: {
     description: "Multi-step operations in a single call - saves tokens and reduces latency",
@@ -8063,9 +8258,411 @@ var CATEGORY_INFO = {
       "Full upgrade analysis",
       "Get complete repo context",
       "One-shot operations"
-    ]
+    ],
+    intentKeywords: [
+      // Completeness
+      "everything",
+      "all",
+      "complete",
+      "full",
+      "comprehensive",
+      "entire",
+      "whole",
+      // Starting points
+      "start",
+      "begin",
+      "setup",
+      "getting started",
+      "onboard",
+      "new project",
+      // Efficiency
+      "one shot",
+      "single call",
+      "efficient",
+      "quick",
+      "fast"
+    ],
+    startWith: "midnight-get-repo-context"
   }
 };
+var INTENT_TO_TOOL = [
+  // Examples & Getting Started
+  {
+    patterns: [
+      "counter",
+      "simple",
+      "beginner",
+      "start",
+      "hello world",
+      "basic",
+      "first contract",
+      "tutorial",
+      "starter"
+    ],
+    tool: "midnight-list-examples",
+    reason: "Lists all example contracts including the beginner-friendly counter"
+  },
+  {
+    patterns: [
+      "getting started",
+      "begin",
+      "first time",
+      "new to midnight",
+      "learn midnight",
+      "introduction",
+      "overview",
+      "onboarding",
+      "setup project"
+    ],
+    tool: "midnight-get-repo-context",
+    reason: "Get everything needed to start working (compound tool)"
+  },
+  // Domain-specific searches
+  {
+    patterns: [
+      "voting",
+      "governance",
+      "election",
+      "ballot",
+      "poll",
+      "referendum",
+      "proposal",
+      "dao"
+    ],
+    tool: "midnight-search-compact",
+    reason: "Search for voting/governance-related patterns and examples"
+  },
+  {
+    patterns: [
+      "token",
+      "transfer",
+      "balance",
+      "mint",
+      "burn",
+      "erc20",
+      "fungible",
+      "asset",
+      "coin"
+    ],
+    tool: "midnight-search-compact",
+    reason: "Search for token-related implementations"
+  },
+  {
+    patterns: [
+      "nft",
+      "non-fungible",
+      "collectible",
+      "unique",
+      "ownership",
+      "deed"
+    ],
+    tool: "midnight-search-compact",
+    reason: "Search for NFT and non-fungible token patterns"
+  },
+  {
+    patterns: ["auction", "bid", "bidding", "marketplace", "sale", "exchange"],
+    tool: "midnight-search-compact",
+    reason: "Search for auction and marketplace patterns"
+  },
+  {
+    patterns: [
+      "access control",
+      "permission",
+      "role",
+      "admin",
+      "owner",
+      "authorization",
+      "acl"
+    ],
+    tool: "midnight-search-compact",
+    reason: "Search for access control and permission patterns"
+  },
+  // Security & Analysis
+  {
+    patterns: [
+      "security",
+      "vulnerability",
+      "audit",
+      "safe",
+      "attack",
+      "exploit",
+      "risk",
+      "issue",
+      "bug"
+    ],
+    tool: "midnight-analyze-contract",
+    reason: "Performs security analysis on your contract code"
+  },
+  {
+    patterns: [
+      "circuit",
+      "zk",
+      "zero knowledge",
+      "proof",
+      "privacy",
+      "private",
+      "witness",
+      "constraint"
+    ],
+    tool: "midnight-explain-circuit",
+    reason: "Explains circuit logic and ZK implications"
+  },
+  // Version & Upgrade
+  {
+    patterns: [
+      "upgrade",
+      "update",
+      "outdated",
+      "new version",
+      "breaking",
+      "deprecat",
+      "migrate",
+      "migration guide"
+    ],
+    tool: "midnight-upgrade-check",
+    reason: "Complete upgrade analysis in one call (compound tool)"
+  },
+  {
+    patterns: [
+      "syntax",
+      "correct",
+      "how to write",
+      "format",
+      "proper way",
+      "right way",
+      "convention",
+      "best practice"
+    ],
+    tool: "midnight-get-latest-syntax",
+    reason: "Get authoritative syntax reference to avoid mistakes"
+  },
+  {
+    patterns: [
+      "what changed",
+      "changelog",
+      "release notes",
+      "difference between",
+      "compare versions"
+    ],
+    tool: "midnight-compare-syntax",
+    reason: "Compare syntax/features between versions"
+  },
+  // SDK & TypeScript
+  {
+    patterns: [
+      "sdk",
+      "typescript",
+      "javascript",
+      "api",
+      "integration",
+      "client",
+      "frontend",
+      "dapp",
+      "web3"
+    ],
+    tool: "midnight-search-typescript",
+    reason: "Search TypeScript SDK code and types"
+  },
+  {
+    patterns: ["type", "types", "interface", "typing", "definition"],
+    tool: "midnight-search-typescript",
+    reason: "Search TypeScript type definitions"
+  },
+  // Documentation
+  {
+    patterns: [
+      "docs",
+      "documentation",
+      "guide",
+      "tutorial",
+      "learn",
+      "concept",
+      "explanation",
+      "manual"
+    ],
+    tool: "midnight-search-docs",
+    reason: "Search official Midnight documentation"
+  },
+  // Code Generation
+  {
+    patterns: [
+      "generate",
+      "create contract",
+      "write contract",
+      "new contract",
+      "scaffold",
+      "template",
+      "boilerplate"
+    ],
+    tool: "midnight-generate-contract",
+    reason: "AI-powered contract generation (requires sampling)"
+  },
+  {
+    patterns: [
+      "review",
+      "check my code",
+      "is this correct",
+      "feedback",
+      "improve my",
+      "fix my"
+    ],
+    tool: "midnight-review-contract",
+    reason: "AI-powered code review (requires sampling)"
+  },
+  {
+    patterns: [
+      "document my",
+      "add comments",
+      "explain my code",
+      "generate docs"
+    ],
+    tool: "midnight-generate-documentation",
+    reason: "AI-powered documentation generation (requires sampling)"
+  },
+  // Health & Debugging
+  {
+    patterns: [
+      "not working",
+      "error",
+      "broken",
+      "failing",
+      "issue with server",
+      "api down"
+    ],
+    tool: "midnight-health-check",
+    reason: "Check server status and connectivity"
+  },
+  {
+    patterns: ["rate limit", "quota", "throttle", "429", "too many requests"],
+    tool: "midnight-health-check",
+    reason: "Check rate limit status and remaining quota"
+  },
+  {
+    patterns: ["server status", "api status", "is api up", "check server"],
+    tool: "midnight-get-status",
+    reason: "Get detailed server and API status information"
+  },
+  {
+    patterns: [
+      "mcp version",
+      "server version",
+      "what version am i using",
+      "installed version"
+    ],
+    tool: "midnight-check-version",
+    reason: "Check the current MCP server version"
+  },
+  {
+    patterns: [
+      "auto update",
+      "keep updated",
+      "automatic updates",
+      "stay current",
+      "update automatically"
+    ],
+    tool: "midnight-auto-update-config",
+    reason: "Configure automatic syntax updates"
+  },
+  // Repository & Files
+  {
+    patterns: [
+      "recent changes",
+      "latest commits",
+      "what's new",
+      "updates",
+      "modified",
+      "new features",
+      "repo activity"
+    ],
+    tool: "midnight-get-latest-updates",
+    reason: "See recent repository activity and changes"
+  },
+  {
+    patterns: ["read file", "get file", "show file", "file content", "source"],
+    tool: "midnight-get-file",
+    reason: "Fetch specific file content from repository"
+  },
+  {
+    patterns: [
+      "file from version",
+      "old version of file",
+      "file at version",
+      "historical file",
+      "previous version"
+    ],
+    tool: "midnight-get-file-at-version",
+    reason: "Get a file as it existed in a specific version"
+  },
+  // Version Comparison & Info
+  {
+    patterns: [
+      "what version",
+      "current version",
+      "latest version",
+      "version number",
+      "compact version"
+    ],
+    tool: "midnight-get-version-info",
+    reason: "Get version information for Midnight components"
+  },
+  {
+    patterns: [
+      "breaking changes",
+      "what broke",
+      "incompatible",
+      "api changes",
+      "deprecations"
+    ],
+    tool: "midnight-check-breaking-changes",
+    reason: "Check for breaking changes between versions"
+  },
+  {
+    patterns: [
+      "how to migrate",
+      "migration steps",
+      "upgrade guide",
+      "migration path",
+      "move to new version"
+    ],
+    tool: "midnight-get-migration-guide",
+    reason: "Get step-by-step migration guidance"
+  },
+  {
+    patterns: [
+      "compare syntax",
+      "syntax diff",
+      "syntax between versions",
+      "syntax comparison"
+    ],
+    tool: "midnight-compare-syntax",
+    reason: "Compare Compact syntax between two versions"
+  },
+  // Contract Structure
+  {
+    patterns: [
+      "extract structure",
+      "contract structure",
+      "parse contract",
+      "contract outline",
+      "functions in contract",
+      "contract anatomy"
+    ],
+    tool: "midnight-extract-contract-structure",
+    reason: "Extract and analyze contract structure (functions, state, etc.)"
+  },
+  // Meta/Discovery (fallback patterns)
+  {
+    patterns: [
+      "what tools",
+      "available tools",
+      "list tools",
+      "show tools",
+      "tool list"
+    ],
+    tool: "midnight-list-tool-categories",
+    reason: "Browse available tool categories"
+  }
+];
 
 // src/tools/meta/handlers.ts
 var _metaTools = [];
@@ -8156,6 +8753,76 @@ function generateCategorySuggestion(category) {
       return `Use these tools for ${CATEGORY_INFO[category]?.useCases[0] || "related operations"}.`;
   }
 }
+async function suggestTool(input) {
+  const intentLower = input.intent.toLowerCase();
+  const matchedTools = [];
+  for (const mapping of INTENT_TO_TOOL) {
+    const matchCount = mapping.patterns.filter(
+      (p) => intentLower.includes(p.toLowerCase())
+    ).length;
+    if (matchCount > 0) {
+      matchedTools.push({
+        tool: mapping.tool,
+        reason: mapping.reason,
+        confidence: matchCount >= 2 ? "high" : "medium"
+      });
+    }
+  }
+  const matchedCategories = [];
+  for (const [category, info] of Object.entries(CATEGORY_INFO)) {
+    const matchCount = info.intentKeywords.filter(
+      (k) => intentLower.includes(k.toLowerCase())
+    ).length;
+    if (matchCount > 0 && info.startWith) {
+      matchedCategories.push({
+        category,
+        startWith: info.startWith,
+        description: info.description,
+        confidence: matchCount >= 2 ? "medium" : "low"
+      });
+    }
+  }
+  const confidenceOrder = { high: 0, medium: 1, low: 2 };
+  matchedTools.sort(
+    (a, b) => confidenceOrder[a.confidence] - confidenceOrder[b.confidence]
+  );
+  if (matchedTools.length === 0 && matchedCategories.length === 0) {
+    return {
+      intent: input.intent,
+      suggestions: [],
+      fallback: {
+        tool: "midnight-list-tool-categories",
+        reason: "No specific match found. Start by exploring available tool categories."
+      },
+      tip: "Try rephrasing your intent with keywords like: search, analyze, generate, upgrade, version, security, example"
+    };
+  }
+  const seenTools = /* @__PURE__ */ new Set();
+  const suggestions = [];
+  for (const match of matchedTools) {
+    if (!seenTools.has(match.tool)) {
+      seenTools.add(match.tool);
+      suggestions.push(match);
+    }
+  }
+  for (const match of matchedCategories) {
+    if (!seenTools.has(match.startWith)) {
+      seenTools.add(match.startWith);
+      suggestions.push({
+        tool: match.startWith,
+        reason: `Recommended starting tool for ${match.category}: ${match.description}`,
+        confidence: match.confidence
+      });
+    }
+  }
+  const topSuggestions = suggestions.slice(0, 3);
+  return {
+    intent: input.intent,
+    suggestions: topSuggestions,
+    primaryRecommendation: topSuggestions[0],
+    tip: topSuggestions[0]?.confidence === "high" ? `Strong match! Use ${topSuggestions[0].tool} for this task.` : "Multiple tools may help. Consider the suggestions based on your specific needs."
+  };
+}
 
 // src/tools/meta/tools.ts
 var listCategoriesOutputSchema = {
@@ -8219,10 +8886,39 @@ var listCategoryToolsOutputSchema = {
   required: ["category", "tools"],
   description: "Tools within a specific category"
 };
+var suggestToolOutputSchema = {
+  type: "object",
+  properties: {
+    intent: { type: "string", description: "The original intent" },
+    suggestions: {
+      type: "array",
+      description: "Suggested tools ranked by relevance",
+      items: {
+        type: "object",
+        properties: {
+          tool: { type: "string", description: "Tool name" },
+          reason: { type: "string", description: "Why this tool is suggested" },
+          confidence: {
+            type: "string",
+            enum: ["high", "medium", "low"],
+            description: "Match confidence"
+          }
+        }
+      }
+    },
+    primaryRecommendation: {
+      type: "object",
+      description: "Top recommendation"
+    },
+    tip: { type: "string", description: "Helpful tip" }
+  },
+  required: ["intent", "suggestions"],
+  description: "Tool suggestions based on intent"
+};
 var metaTools = [
   {
     name: "midnight-list-tool-categories",
-    description: "\u{1F4CB} DISCOVERY TOOL: List available tool categories for progressive exploration. Use this FIRST to understand what capabilities are available, then drill into specific categories with midnight-list-category-tools. Reduces cognitive load by organizing 25 tools into 7 logical groups.",
+    description: "\u{1F4CB} DISCOVERY TOOL: List available tool categories for progressive exploration. Use this FIRST to understand what capabilities are available, then drill into specific categories with midnight-list-category-tools. Reduces cognitive load by organizing 27 tools into 7 logical groups.",
     inputSchema: {
       type: "object",
       properties: {
@@ -8276,6 +8972,41 @@ var metaTools = [
       category: "health"
     },
     handler: listCategoryTools
+  },
+  {
+    name: "midnight-suggest-tool",
+    description: `\u{1F3AF} SMART DISCOVERY: Describe what you want to do in natural language, and get tool recommendations.
+
+EXAMPLES:
+\u2022 "I want to find example voting contracts" \u2192 midnight-search-compact
+\u2022 "Check if my version is outdated" \u2192 midnight-upgrade-check
+\u2022 "Analyze my contract for security issues" \u2192 midnight-analyze-contract
+\u2022 "I'm new to Midnight and want to get started" \u2192 midnight-get-repo-context
+
+This tool matches your intent against known patterns and suggests the most appropriate tools with confidence levels.
+
+USAGE GUIDANCE:
+\u2022 Call once with your intent - no need to call repeatedly
+\u2022 More specific intents get better matches
+\u2022 Use the primaryRecommendation for the best match`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        intent: {
+          type: "string",
+          description: "What you want to accomplish (natural language description)"
+        }
+      },
+      required: ["intent"]
+    },
+    outputSchema: suggestToolOutputSchema,
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+      title: "\u{1F3AF} Suggest Tool",
+      category: "health"
+    },
+    handler: suggestTool
   }
 ];
 setMetaTools(metaTools);
@@ -8303,4 +9034,4 @@ export {
   startServer,
   startHttpServer
 };
-//# sourceMappingURL=chunk-S7G4OHA4.js.map
+//# sourceMappingURL=chunk-ZYCQLQEX.js.map

package/dist/db-ILWTH42C.js

@@ -0,0 +1,7 @@
+import {
+  vectorStore
+} from "./chunk-EBFMM2DS.js";
+export {
+  vectorStore
+};
+//# sourceMappingURL=db-ILWTH42C.js.map

package/dist/index.js

@@ -9,10 +9,10 @@ import {
   promptDefinitions,
   startHttpServer,
   startServer
-} from "./chunk-S7G4OHA4.js";
+} from "./chunk-ZYCQLQEX.js";
 import {
   logger
-} from "./chunk-HOWO4K5A.js";
+} from "./chunk-EBFMM2DS.js";
 export {
   allResources,
   allTools,

package/package.json

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

package/dist/db-YDGUWI5K.js

@@ -1,7 +0,0 @@
-import {
-  vectorStore
-} from "./chunk-HOWO4K5A.js";
-export {
-  vectorStore
-};
-//# sourceMappingURL=db-YDGUWI5K.js.map