oscar64-mcp-docs 1.0.4 → 1.0.6

package/dist/stdio.js

@@ -1454,7 +1454,67 @@ var StateUnavailableError = class extends Error {
   }
 };
 function isStateUnavailableError(error) {
-  return error instanceof StateUnavailableError;
+  if (error instanceof StateUnavailableError) return true;
+  if (!error || typeof error !== "object") return false;
+  const name = String(error.name ?? "");
+  const message = String(error.message ?? "");
+  return name === "StateUnavailableError" || /source state unavailable/i.test(message);
+}
+function unwrapCause(error) {
+  if (!error || typeof error !== "object") return void 0;
+  return error.cause;
+}
+function collectErrorSignals(error) {
+  const messages = [];
+  const codes = [];
+  let current = error;
+  for (let depth = 0; depth < 3 && current; depth += 1) {
+    if (typeof current === "object") {
+      const message = String(current.message ?? "").trim();
+      const code = String(current.code ?? "").trim();
+      if (message) messages.push(message);
+      if (code) codes.push(code);
+      current = unwrapCause(current);
+      continue;
+    }
+    messages.push(String(current));
+    break;
+  }
+  return { messages, codes };
+}
+function isOperationalOfflineError(error) {
+  if (isStateUnavailableError(error)) return true;
+  const { messages, codes } = collectErrorSignals(error);
+  const joined = messages.join(" | ").toLowerCase();
+  const upperCodes = codes.map((code) => code.toUpperCase());
+  const networkOrFsCodes = /* @__PURE__ */ new Set([
+    "EAI_AGAIN",
+    "ENOTFOUND",
+    "ENETUNREACH",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENOENT",
+    "ENOTDIR",
+    "EACCES",
+    "EPERM"
+  ]);
+  if (upperCodes.some((code) => networkOrFsCodes.has(code))) return true;
+  if (joined.includes("fetch failed")) return true;
+  if (joined.includes("http 4") || joined.includes("http 5")) return true;
+  if (joined.includes("timeout waiting for repo lock")) return true;
+  if (joined.includes("source state unavailable")) return true;
+  if (joined.includes("no such file or directory")) return true;
+  if (joined.includes("permission denied")) return true;
+  return false;
+}
+function toErrorHintSuffix(error) {
+  const { messages, codes } = collectErrorSignals(error);
+  const message = messages.find((value) => value.length > 0) ?? "";
+  const code = codes.find((value) => value.length > 0) ?? "";
+  const compact = [code, message].filter(Boolean).join(": ").slice(0, 220);
+  if (!compact) return "";
+  return ` Root cause: ${compact}`;
 }
 function getStateSnapshotSync() {
   return latestState;
@@ -1561,17 +1621,21 @@ var listIndexesTool = createTool({
   description: "List topic/tutorial/sample entries with concrete docs:// or code:// URIs.",
   inputSchema: listIndexesInputSchema,
   outputSchema: listIndexesOutputSchema,
-  execute: async ({ context }) => {
+  execute: async (input) => {
+    const context = input?.context ?? input;
     try {
       return await executeListIndexes(context);
     } catch (error) {
-      if (isStateUnavailableError(error)) {
+      if (process.env.OSCAR_MCP_DEBUG_ERRORS === "1") {
+        console.error("[oscar64-mcp-docs] list_indexes error:", error);
+      }
+      if (isOperationalOfflineError(error)) {
         return {
           ok: false,
           error: {
             code: "OFFLINE",
             message: "list_indexes unavailable while sources are offline.",
-            hint: "Ensure network access to GitHub or warm cache under ~/.cache/oscar-mcp, then retry.",
+            hint: `Ensure network access to GitHub or warm cache under ~/.cache/oscar-mcp, then retry.${toErrorHintSuffix(error)}`,
             recoverable: true
           }
         };
@@ -1595,7 +1659,7 @@ import { createTool as createTool2 } from "@mastra/core/tools";
 async function readResourceUriFromState(uri) {
   const state = await getStateSnapshot();
   const resources = makeResources(() => state);
-  const content = await resources.getResourceContent({ uri });
+  const content = await resources.getResourceContent({ uri, extra: {} });
   const toText = (item) => {
     if (typeof item?.text === "string") return item.text;
     if (typeof item?.blob === "string") return item.blob;
@@ -1721,17 +1785,21 @@ var readUriTool = createTool2({
   description: "Read text or binary content for supported resource/file URIs (typically from search results).",
   inputSchema: readUriInputSchema,
   outputSchema: readUriOutputSchema,
-  execute: async ({ context }) => {
+  execute: async (input) => {
+    const context = input?.context ?? input;
     try {
       return await executeReadUri(context);
     } catch (error) {
-      if (isStateUnavailableError(error)) {
+      if (process.env.OSCAR_MCP_DEBUG_ERRORS === "1") {
+        console.error("[oscar64-mcp-docs] read_uri error:", error);
+      }
+      if (isOperationalOfflineError(error)) {
         return {
           ok: false,
           error: {
             code: "OFFLINE",
             message: "read_uri unavailable while sources are offline.",
-            hint: "Ensure network access to GitHub or warm cache under ~/.cache/oscar-mcp, then retry.",
+            hint: `Ensure network access to GitHub or warm cache under ~/.cache/oscar-mcp, then retry.${toErrorHintSuffix(error)}`,
             recoverable: true
           }
         };
@@ -2137,17 +2205,21 @@ var searchTool = createTool3({
   description: "Unified search across manual and code sources with ranked results.",
   inputSchema: searchInputSchema,
   outputSchema: searchOutputSchema,
-  execute: async ({ context }) => {
+  execute: async (input) => {
+    const context = input?.context ?? input;
     try {
       return await executeSearch(context);
     } catch (error) {
-      if (isStateUnavailableError(error)) {
+      if (process.env.OSCAR_MCP_DEBUG_ERRORS === "1") {
+        console.error("[oscar64-mcp-docs] search error:", error);
+      }
+      if (isOperationalOfflineError(error)) {
         return {
           ok: false,
           error: {
             code: "OFFLINE",
             message: "Search unavailable while sources are offline.",
-            hint: "Ensure network access to GitHub or warm cache under ~/.cache/oscar-mcp, then retry.",
+            hint: `Ensure network access to GitHub or warm cache under ~/.cache/oscar-mcp, then retry.${toErrorHintSuffix(error)}`,
             recoverable: true
           }
         };

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "oscar64-mcp-docs",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "private": false,
   "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "files": [
     "dist",
     "README.md"
@@ -26,15 +29,15 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@mastra/core": "^1.9.0",
-    "@mastra/mcp": "^1.0.3",
+    "@mastra/core": "^1.10.0",
+    "@mastra/mcp": "^1.1.0",
     "adm-zip": "^0.5.16",
     "minisearch": "^7.1.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.5",
-    "mastra": "^1.3.6",
+    "mastra": "^1.3.7",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.6.3",