midnight-mcp 0.2.2 → 0.2.4

package/dist/{chunk-S7G4OHA4.js → chunk-5DMOVW6Q.js}

@@ -25,7 +25,7 @@ import {
   validateNumber,
   validateQuery,
   vectorStore
-} from "./chunk-HOWO4K5A.js";
+} from "./chunk-KB6HV57P.js";
 
 // src/tools/search/schemas.ts
 import { z } from "zod";
@@ -48,6 +48,14 @@ var SearchDocsInputSchema = z.object({
   category: z.enum(["guides", "api", "concepts", "all"]).optional().default("all").describe("Filter by documentation category"),
   limit: z.number().optional().default(10)
 });
+var FetchDocsInputSchema = z.object({
+  path: z.string().describe(
+    "Documentation page path (e.g., '/develop/faq', '/getting-started/installation', '/compact')"
+  ),
+  extractSection: z.string().optional().describe(
+    "Optional: Extract only a specific section by heading (e.g., 'General questions')"
+  )
+});
 
 // src/tools/search/handlers.ts
 function validateSearchInput(query, limit) {
@@ -235,13 +243,16 @@ async function searchDocs(input) {
   );
   const cached = checkSearchCache(cacheKey);
   if (cached) return cached;
+  const freshnessHint = "For guaranteed freshness, use midnight-fetch-docs with the path from these results (e.g., /develop/faq)";
   const hostedResult = await tryHostedSearch(
     "docs",
     () => searchDocsHosted(sanitizedQuery, limit, input.category),
     cacheKey,
     warnings
   );
-  if (hostedResult) return hostedResult.result;
+  if (hostedResult) {
+    return { ...hostedResult.result, hint: freshnessHint };
+  }
   const filter = {
     language: "markdown"
   };
@@ -261,10 +272,169 @@ async function searchDocs(input) {
     })),
     totalResults: results.length,
     query: sanitizedQuery,
-    category: input.category
+    category: input.category,
+    hint: "For guaranteed freshness, use midnight-fetch-docs with the path from these results (e.g., /develop/faq)"
   };
   return finalizeResponse(response, cacheKey, warnings);
 }
+var DOCS_BASE_URL = "https://docs.midnight.network";
+var FETCH_TIMEOUT = 15e3;
+var KNOWN_DOC_PATHS = [
+  "/develop/faq",
+  "/develop/getting-help",
+  "/develop/tutorial/building",
+  "/develop/how-midnight-works",
+  "/getting-started/installation",
+  "/getting-started/create-mn-app",
+  "/getting-started/deploy-mn-app",
+  "/getting-started/interact-with-mn-app",
+  "/compact",
+  "/learn/what-is-midnight",
+  "/learn/glossary",
+  "/develop/reference/midnight-api",
+  "/relnotes/overview",
+  "/blog"
+];
+function extractContentFromHtml(html, extractSection) {
+  const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+  const title = titleMatch ? titleMatch[1].replace(" | Midnight Docs", "").trim() : "Unknown";
+  const lastUpdatedMatch = html.match(
+    /<time[^>]*datetime="([^"]+)"[^>]*itemprop="dateModified"/i
+  );
+  const lastUpdated = lastUpdatedMatch ? lastUpdatedMatch[1] : void 0;
+  const articleMatch = html.match(/<article[^>]*>([\s\S]*?)<\/article>/i);
+  const articleHtml = articleMatch ? articleMatch[1] : html;
+  const headings = [];
+  const headingRegex = /<h([1-6])[^>]*class="[^"]*anchor[^"]*"[^>]*id="([^"]*)"[^>]*>([^<]*(?:<[^/][^>]*>[^<]*<\/[^>]+>)*[^<]*)/gi;
+  let headingMatch;
+  while ((headingMatch = headingRegex.exec(articleHtml)) !== null) {
+    const text = headingMatch[3].replace(/<[^>]+>/g, "").replace(/\u200B/g, "").replace(/​/g, "").trim();
+    if (text) {
+      headings.push({
+        level: parseInt(headingMatch[1]),
+        text,
+        id: headingMatch[2]
+      });
+    }
+  }
+  let content = articleHtml.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<svg[^>]*>[\s\S]*?<\/svg>/gi, "").replace(/<nav[^>]*class="[^"]*breadcrumb[^"]*"[^>]*>[\s\S]*?<\/nav>/gi, "").replace(/<footer[^>]*>[\s\S]*?<\/footer>/gi, "").replace(/<a[^>]*class="[^"]*hash-link[^"]*"[^>]*>[\s\S]*?<\/a>/gi, "").replace(/<button[^>]*>[\s\S]*?<\/button>/gi, "");
+  content = content.replace(/<h1[^>]*>/gi, "\n# ").replace(/<\/h1>/gi, "\n").replace(/<h2[^>]*>/gi, "\n## ").replace(/<\/h2>/gi, "\n").replace(/<h3[^>]*>/gi, "\n### ").replace(/<\/h3>/gi, "\n").replace(/<h4[^>]*>/gi, "\n#### ").replace(/<\/h4>/gi, "\n").replace(/<p[^>]*>/gi, "\n").replace(/<\/p>/gi, "\n").replace(/<ul[^>]*>/gi, "\n").replace(/<\/ul>/gi, "\n").replace(/<ol[^>]*>/gi, "\n").replace(/<\/ol>/gi, "\n").replace(/<li[^>]*>/gi, "\u2022 ").replace(/<\/li>/gi, "\n").replace(/<pre[^>]*><code[^>]*>/gi, "\n```\n").replace(/<\/code><\/pre>/gi, "\n```\n").replace(/<code[^>]*>/gi, "`").replace(/<\/code>/gi, "`").replace(/<a[^>]*href="([^"]*)"[^>]*>([^<]*)<\/a>/gi, "$2 ($1)").replace(/<strong[^>]*>/gi, "**").replace(/<\/strong>/gi, "**").replace(/<em[^>]*>/gi, "_").replace(/<\/em>/gi, "_").replace(/<[^>]+>/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#x27;/g, "'").replace(/&nbsp;/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+  if (extractSection) {
+    const sectionLower = extractSection.toLowerCase();
+    const lines = content.split("\n");
+    const result = [];
+    let inSection = false;
+    let sectionLevel = 0;
+    for (const line of lines) {
+      const headerMatch = line.match(/^(#{1,4})\s+(.+)$/);
+      if (headerMatch) {
+        const level = headerMatch[1].length;
+        const headerText = headerMatch[2].toLowerCase();
+        if (headerText.includes(sectionLower)) {
+          inSection = true;
+          sectionLevel = level;
+          result.push(line);
+        } else if (inSection && level <= sectionLevel) {
+          break;
+        } else if (inSection) {
+          result.push(line);
+        }
+      } else if (inSection) {
+        result.push(line);
+      }
+    }
+    if (result.length > 0) {
+      content = result.join("\n").trim();
+    }
+  }
+  return { title, content, headings, lastUpdated };
+}
+async function fetchDocs(input) {
+  const { path: path2, extractSection } = input;
+  let normalizedPath = path2.startsWith("/") ? path2 : `/${path2}`;
+  normalizedPath = normalizedPath.replace(/\/$/, "");
+  if (/[<>"\s]/.test(normalizedPath)) {
+    return {
+      error: "Invalid path",
+      details: ["Path contains invalid characters"],
+      suggestion: `Use a clean path like '/develop/faq' or '/getting-started/installation'`
+    };
+  }
+  const url = `${DOCS_BASE_URL}${normalizedPath}`;
+  logger.debug("Fetching live documentation", { url, extractSection });
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "User-Agent": "midnight-mcp/1.0 (Documentation Fetcher)",
+        Accept: "text/html"
+      }
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      if (response.status === 404) {
+        return {
+          error: "Page not found",
+          path: normalizedPath,
+          suggestion: `Try one of these known paths: ${KNOWN_DOC_PATHS.slice(0, 5).join(", ")}`,
+          knownPaths: KNOWN_DOC_PATHS
+        };
+      }
+      return {
+        error: `Failed to fetch documentation: ${response.status} ${response.statusText}`,
+        path: normalizedPath,
+        suggestion: "Try again later or check if the URL is correct"
+      };
+    }
+    const html = await response.text();
+    if (!html.includes("<article") && !html.includes("<main")) {
+      return {
+        error: "Page returned but content not found",
+        path: normalizedPath,
+        suggestion: "The page may not have main content. Try a different path."
+      };
+    }
+    const { title, content, headings, lastUpdated } = extractContentFromHtml(
+      html,
+      extractSection
+    );
+    const MAX_CONTENT_LENGTH = 15e3;
+    const truncated = content.length > MAX_CONTENT_LENGTH;
+    const finalContent = truncated ? content.slice(0, MAX_CONTENT_LENGTH) + "\n\n[Content truncated...]" : content;
+    return {
+      title,
+      path: normalizedPath,
+      url,
+      content: finalContent,
+      headings: headings.length > 0 ? headings : void 0,
+      lastUpdated,
+      truncated,
+      contentLength: content.length,
+      note: extractSection ? `Extracted section matching: "${extractSection}"` : "Full page content"
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.name === "AbortError") {
+        return {
+          error: "Request timed out",
+          path: normalizedPath,
+          suggestion: "The documentation site may be slow. Try again or use midnight-search-docs for cached content."
+        };
+      }
+      return {
+        error: `Failed to fetch: ${error.message}`,
+        path: normalizedPath,
+        suggestion: "Check your network connection or try midnight-search-docs for cached content."
+      };
+    }
+    return {
+      error: "Unknown error fetching documentation",
+      path: normalizedPath
+    };
+  }
+}
 
 // src/tools/search/tools.ts
 var searchResultSchema = {
@@ -324,7 +494,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 +531,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 +568,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: {
@@ -414,6 +599,80 @@ var searchTools = [
       title: "Search Documentation"
     },
     handler: searchDocs
+  },
+  {
+    name: "midnight-fetch-docs",
+    description: `\u{1F310} LIVE FETCH: Retrieve latest documentation directly from docs.midnight.network (SSG-enabled).
+
+Unlike midnight-search-docs which uses pre-indexed content, this tool fetches LIVE documentation pages in real-time. Use when you need:
+\u2022 The absolute latest content (just updated docs)
+\u2022 A specific page you know the path to
+\u2022 Full page content rather than search snippets
+
+COMMON PATHS:
+\u2022 /develop/faq - Frequently asked questions
+\u2022 /getting-started/installation - Installation guide
+\u2022 /getting-started/create-mn-app - Create an MN app
+\u2022 /compact - Compact language reference
+\u2022 /develop/tutorial/building - Build guide
+\u2022 /develop/reference/midnight-api - API documentation
+\u2022 /learn/what-is-midnight - What is Midnight
+\u2022 /blog - Dev diaries
+
+USAGE GUIDANCE:
+\u2022 Use extractSection to get only a specific heading (e.g., "Developer questions")
+\u2022 Prefer midnight-search-docs for discovery, use this for known pages
+\u2022 Content is truncated at 15KB for token efficiency`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Documentation page path (e.g., '/develop/faq', '/getting-started/installation')"
+        },
+        extractSection: {
+          type: "string",
+          description: "Optional: Extract only a specific section by heading text"
+        }
+      },
+      required: ["path"]
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Page title" },
+        path: { type: "string", description: "Normalized path" },
+        url: { type: "string", description: "Full URL" },
+        content: { type: "string", description: "Extracted page content" },
+        headings: {
+          type: "array",
+          description: "Page headings/table of contents",
+          items: {
+            type: "object",
+            properties: {
+              level: { type: "number" },
+              text: { type: "string" },
+              id: { type: "string" }
+            }
+          }
+        },
+        lastUpdated: { type: "string", description: "Last update timestamp" },
+        truncated: {
+          type: "boolean",
+          description: "Whether content was truncated"
+        }
+      },
+      required: ["title", "path", "content"],
+      description: "Live documentation page content"
+    },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: true,
+      // Fetches from external URL
+      title: "\u{1F310} Fetch Live Docs",
+      category: "search"
+    },
+    handler: fetchDocs
   }
 ];
 
@@ -784,7 +1043,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 +1079,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 +7209,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 +8294,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 +8306,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 +8340,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 +8375,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 +8409,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 +8502,425 @@ 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"
+  },
+  {
+    patterns: [
+      "fetch docs",
+      "get docs",
+      "latest docs",
+      "live docs",
+      "docs page",
+      "faq",
+      "installation guide",
+      "getting started page"
+    ],
+    tool: "midnight-fetch-docs",
+    reason: "Fetch live documentation directly from docs.midnight.network"
+  },
+  // 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 +9011,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 +9144,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 28 tools into 7 logical groups.",
     inputSchema: {
       type: "object",
       properties: {
@@ -8276,6 +9230,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 +9292,4 @@ export {
   startServer,
   startHttpServer
 };
-//# sourceMappingURL=chunk-S7G4OHA4.js.map
+//# sourceMappingURL=chunk-5DMOVW6Q.js.map