midnight-mcp 0.2.3 → 0.2.5

package/README.md

@@ -104,11 +104,11 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ## What's Included
 
-### 27 Tools
+### 28 Tools
 
 | Category          | Tools                                                                                                                             | Description                                      |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| **Search**        | `search-compact`, `search-typescript`, `search-docs`                                                                              | Semantic search across Midnight codebase         |
+| **Search**        | `search-compact`, `search-typescript`, `search-docs`, `fetch-docs`                                                                | Semantic search + live docs fetching             |
 | **Analysis**      | `analyze-contract`, `explain-circuit`, `extract-contract-structure`                                                               | Static analysis with 15+ checks (P0-P2 severity) |
 | **Repository**    | `get-file`, `list-examples`, `get-latest-updates`                                                                                 | Access files and examples                        |
 | **Versioning**    | `get-version-info`, `check-breaking-changes`, `get-migration-guide`, `get-file-at-version`, `compare-syntax`, `get-latest-syntax` | Version tracking and migration                   |
@@ -123,7 +123,7 @@ All tools are prefixed with `midnight-` (e.g., `midnight-search-compact`).
 
 | Capability      | Feature                                         |
 | --------------- | ----------------------------------------------- |
-| **Tools**       | 27 tools with `listChanged` notifications       |
+| **Tools**       | 28 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-ZYCQLQEX.js";
+} from "./chunk-E5HAMXS3.js";
 import {
   setOutputFormat
-} from "./chunk-EBFMM2DS.js";
+} from "./chunk-6BPO5SRQ.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.3";
+var CURRENT_VERSION = "0.2.5";
 process.on("uncaughtException", (error) => {
   console.error("Uncaught exception:", error);
   process.exit(1);

package/dist/{chunk-EBFMM2DS.js → chunk-6BPO5SRQ.js}

@@ -1594,7 +1594,7 @@ async function checkGitHubAPI() {
 }
 async function checkVectorStore() {
   try {
-    const { vectorStore: vectorStore2 } = await import("./db-ILWTH42C.js");
+    const { vectorStore: vectorStore2 } = await import("./db-F27LE73N.js");
     if (vectorStore2) {
       return {
         status: "pass",
@@ -1898,7 +1898,9 @@ function pruneAllCaches() {
 setInterval(pruneAllCaches, 5 * 60 * 1e3);
 
 // src/utils/hosted-api.ts
-var API_TIMEOUT = 1e4;
+var API_TIMEOUT = 15e3;
+var MAX_RETRIES = 2;
+var RETRY_DELAY_MS = 1e3;
 function getActionableErrorMessage(status, endpoint, serverMessage) {
   const baseMessages = {
     400: `Bad request to ${endpoint}. Check your query parameters are valid.`,
@@ -1932,8 +1934,17 @@ async function parseApiError(response, endpoint) {
   );
   return new Error(actionableMessage);
 }
-async function apiRequest(endpoint, options = {}) {
-  const url = `${config.hostedApiUrl}${endpoint}`;
+function isRetryableError2(error) {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return error.name === "AbortError" || message.includes("timeout") || message.includes("network") || message.includes("econnreset") || message.includes("502") || message.includes("503") || message.includes("504") || message.includes("bad gateway") || message.includes("service unavailable") || message.includes("gateway timeout");
+  }
+  return false;
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function makeRequest(url, endpoint, options) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), API_TIMEOUT);
   try {
@@ -1953,21 +1964,54 @@ async function apiRequest(endpoint, options = {}) {
   } catch (error) {
     if (error instanceof Error && error.name === "AbortError") {
       throw new Error(
-        `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.`
+        `Request to ${endpoint} timed out after ${API_TIMEOUT / 1e3}s.`
       );
     }
-    if (error instanceof Error && error.message.includes("github.com/Olanetsoft")) {
-      throw error;
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function apiRequest(endpoint, options = {}) {
+  const url = `${config.hostedApiUrl}${endpoint}`;
+  let lastError = null;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      return await makeRequest(url, endpoint, options);
+    } catch (error) {
+      lastError = error;
+      if (!isRetryableError2(error)) {
+        break;
+      }
+      if (attempt === MAX_RETRIES) {
+        logger.warn(`Hosted API request failed after ${attempt + 1} attempts`, {
+          endpoint,
+          error: String(error)
+        });
+        break;
+      }
+      const delay = RETRY_DELAY_MS * Math.pow(2, attempt);
+      logger.debug(
+        `Retrying hosted API request in ${delay}ms (attempt ${attempt + 1}/${MAX_RETRIES + 1})`,
+        { endpoint }
+      );
+      await sleep2(delay);
+    }
+  }
+  if (lastError) {
+    if (lastError.message.includes("github.com/Olanetsoft")) {
+      throw lastError;
     }
-    if (error instanceof Error) {
+    if (lastError.message.includes("timed out")) {
       throw new Error(
-        `Failed to connect to hosted API: ${error.message}. Check your internet connection or set MIDNIGHT_LOCAL=true for local search.`
+        `Request to ${endpoint} timed out after ${MAX_RETRIES + 1} attempts. The hosted service may be slow or unavailable. Try a simpler query or set MIDNIGHT_LOCAL=true for local search.`
       );
     }
-    throw error;
-  } finally {
-    clearTimeout(timeout);
+    throw new Error(
+      `Failed to connect to hosted API after ${MAX_RETRIES + 1} attempts: ${lastError.message}. Check your internet connection or set MIDNIGHT_LOCAL=true for local search.`
+    );
   }
+  throw new Error("Unknown error in API request");
 }
 async function searchCompactHosted(query, limit = 10) {
   logger.debug("Searching Compact code via hosted API", { query });
@@ -2025,7 +2069,7 @@ function serialize(data) {
 }
 
 // src/utils/version.ts
-var CURRENT_VERSION = "0.2.3";
+var CURRENT_VERSION = "0.2.5";
 
 // src/db/vectorStore.ts
 var VectorStore = class {
@@ -2234,4 +2278,4 @@ export {
   serialize,
   CURRENT_VERSION
 };
-//# sourceMappingURL=chunk-EBFMM2DS.js.map
+//# sourceMappingURL=chunk-6BPO5SRQ.js.map

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

@@ -25,7 +25,7 @@ import {
   validateNumber,
   validateQuery,
   vectorStore
-} from "./chunk-EBFMM2DS.js";
+} from "./chunk-6BPO5SRQ.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 = {
@@ -429,6 +599,80 @@ USAGE GUIDANCE:
       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
   }
 ];
 
@@ -8483,6 +8727,20 @@ var INTENT_TO_TOOL = [
     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: [
@@ -8918,7 +9176,7 @@ var suggestToolOutputSchema = {
 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 27 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: {
@@ -9034,4 +9292,4 @@ export {
   startServer,
   startHttpServer
 };
-//# sourceMappingURL=chunk-ZYCQLQEX.js.map
+//# sourceMappingURL=chunk-E5HAMXS3.js.map

package/dist/db-F27LE73N.js

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

package/dist/index.js

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

package/package.json

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

package/dist/db-ILWTH42C.js

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