mcp-docs-service 0.2.13 → 0.2.15

package/CHANGELOG.md

@@ -2,7 +2,21 @@
 
 All notable changes to the MCP Docs Service will be documented in this file.
 
-## [0.2.13] - 2024-05-16
+## [0.2.15] - 2024-05-16
+
+### Added
+
+- Added `mcp-docs-npx` standalone wrapper for more reliable npx execution
+- Enhanced debugging capabilities with detailed logging in all wrapper scripts
+- Improved error handling and recovery in wrapper scripts
+
+### Fixed
+
+- Fixed issue with file access when running via npx
+- Improved robustness of path resolution in wrapper scripts
+- Enhanced error handling for edge cases
+
+## [0.2.14] - 2024-05-16
 
 ### Added
 
@@ -16,6 +30,12 @@ All notable changes to the MCP Docs Service will be documented in this file.
 - Improved robustness of docs directory resolution
 - Enhanced error handling for Cursor integration
 
+## [0.2.13] - 2024-05-16
+
+### Fixed
+
+- Fixed packaging issue with wrapper scripts
+
 ## [0.2.12] - 2024-05-15
 
 ### Fixed

package/cursor-wrapper.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * Cursor Wrapper for MCP Docs Service
+ *
+ * This script is designed to be used as the entry point for Cursor's MCP integration.
+ * It handles the arguments properly and forwards them to the actual MCP Docs Service.
+ */
+
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+// Wrap everything in a try/catch to catch any initialization errors
+try {
+  // Get the current directory
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  // Create a log file for debugging
+  const logFile = path.join(process.cwd(), "cursor-debug.log");
+  fs.writeFileSync(
+    logFile,
+    `Cursor wrapper called at ${new Date().toISOString()}\n`
+  );
+  fs.appendFileSync(logFile, `Arguments: ${JSON.stringify(process.argv)}\n`);
+  fs.appendFileSync(logFile, `Working directory: ${process.cwd()}\n`);
+  fs.appendFileSync(logFile, `Script directory: ${__dirname}\n`);
+  fs.appendFileSync(logFile, `Package structure:\n`);
+
+  // List files in the package directory to debug
+  try {
+    const files = fs.readdirSync(__dirname);
+    fs.appendFileSync(
+      logFile,
+      `Files in package dir: ${JSON.stringify(files)}\n`
+    );
+
+    // Check if dist directory exists
+    const distDir = path.join(__dirname, "dist");
+    if (fs.existsSync(distDir)) {
+      const distFiles = fs.readdirSync(distDir);
+      fs.appendFileSync(
+        logFile,
+        `Files in dist dir: ${JSON.stringify(distFiles)}\n`
+      );
+
+      // Check if cli directory exists
+      const cliDir = path.join(distDir, "cli");
+      if (fs.existsSync(cliDir)) {
+        const cliFiles = fs.readdirSync(cliDir);
+        fs.appendFileSync(
+          logFile,
+          `Files in cli dir: ${JSON.stringify(cliFiles)}\n`
+        );
+      } else {
+        fs.appendFileSync(logFile, `CLI directory not found: ${cliDir}\n`);
+      }
+    } else {
+      fs.appendFileSync(logFile, `Dist directory not found: ${distDir}\n`);
+    }
+  } catch (err) {
+    fs.appendFileSync(logFile, `Error listing files: ${err.message}\n`);
+  }
+
+  // Extract the docs directory from the arguments
+  // The docs directory is expected to be the last argument
+  let docsDir = path.join(process.cwd(), "docs");
+  const args = process.argv.slice(2);
+
+  fs.appendFileSync(logFile, `Processing args: ${JSON.stringify(args)}\n`);
+
+  if (args.length > 0) {
+    // Check if --docs-dir flag is used
+    const docsDirIndex = args.indexOf("--docs-dir");
+    if (docsDirIndex !== -1 && docsDirIndex + 1 < args.length) {
+      docsDir = args[docsDirIndex + 1];
+      fs.appendFileSync(logFile, `Found --docs-dir flag, using: ${docsDir}\n`);
+    } else {
+      // Otherwise, use the last argument if it looks like a path
+      const lastArg = args[args.length - 1];
+      if (!lastArg.startsWith("-")) {
+        docsDir = lastArg;
+        fs.appendFileSync(logFile, `Using last arg as docs dir: ${docsDir}\n`);
+      }
+    }
+  } else {
+    fs.appendFileSync(
+      logFile,
+      `No args provided, using default docs dir: ${docsDir}\n`
+    );
+  }
+
+  // Resolve the docs directory to an absolute path
+  docsDir = path.resolve(docsDir);
+  fs.appendFileSync(logFile, `Using docs directory: ${docsDir}\n`);
+
+  // Ensure the docs directory exists
+  if (!fs.existsSync(docsDir)) {
+    fs.appendFileSync(logFile, `Creating docs directory: ${docsDir}\n`);
+    try {
+      fs.mkdirSync(docsDir, { recursive: true });
+      fs.appendFileSync(logFile, `Successfully created docs directory\n`);
+    } catch (error) {
+      fs.appendFileSync(logFile, `Error creating docs directory: ${error}\n`);
+      console.error(`Error creating docs directory: ${error}`);
+      process.exit(1);
+    }
+  }
+
+  // Set up the arguments for the actual service
+  const serviceArgs = ["--docs-dir", docsDir];
+  fs.appendFileSync(
+    logFile,
+    `Service arguments: ${JSON.stringify(serviceArgs)}\n`
+  );
+
+  // Find the bin.js file
+  let binPath = path.join(__dirname, "dist", "cli", "bin.js");
+
+  // Check if the bin.js file exists
+  if (!fs.existsSync(binPath)) {
+    fs.appendFileSync(
+      logFile,
+      `bin.js not found at ${binPath}, searching...\n`
+    );
+
+    // Try to find bin.js in node_modules
+    const nodeModulesPath = path.join(
+      process.cwd(),
+      "node_modules",
+      "mcp-docs-service"
+    );
+    if (fs.existsSync(nodeModulesPath)) {
+      const potentialBinPath = path.join(
+        nodeModulesPath,
+        "dist",
+        "cli",
+        "bin.js"
+      );
+      if (fs.existsSync(potentialBinPath)) {
+        binPath = potentialBinPath;
+        fs.appendFileSync(
+          logFile,
+          `Found bin.js in node_modules: ${binPath}\n`
+        );
+      }
+    }
+  }
+
+  fs.appendFileSync(
+    logFile,
+    `Running service: ${binPath} ${serviceArgs.join(" ")}\n`
+  );
+
+  // Check if the bin file exists before trying to run it
+  if (!fs.existsSync(binPath)) {
+    fs.appendFileSync(logFile, `ERROR: bin.js not found at ${binPath}\n`);
+    console.error(
+      `ERROR: Could not find the MCP Docs Service binary at ${binPath}`
+    );
+    process.exit(1);
+  }
+
+  // Run the actual service
+  const child = spawn("node", [binPath, ...serviceArgs], {
+    stdio: "inherit",
+    env: { ...process.env, MCP_CURSOR_INTEGRATION: "true" },
+  });
+
+  child.on("exit", (code) => {
+    fs.appendFileSync(logFile, `Child process exited with code ${code}\n`);
+    process.exit(code);
+  });
+
+  // Handle errors
+  child.on("error", (err) => {
+    fs.appendFileSync(
+      logFile,
+      `Error spawning child process: ${err.message}\n`
+    );
+    console.error(`Error spawning MCP Docs Service: ${err.message}`);
+    process.exit(1);
+  });
+} catch (error) {
+  // Write to a fallback log file in case the main one couldn't be created
+  try {
+    fs.writeFileSync(
+      path.join(process.cwd(), "cursor-error.log"),
+      `Fatal error in cursor-wrapper.js: ${error.message}\n${error.stack}\n`
+    );
+  } catch (e) {
+    // Last resort, just log to console
+    console.error(`Fatal error in cursor-wrapper.js: ${error.message}`);
+    console.error(error.stack);
+  }
+  process.exit(1);
+}

package/mcp-inspector-wrapper.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Inspector Wrapper
+ *
+ * This script is a wrapper for the MCP Docs Service that handles the MCP Inspector's argument format.
+ * It extracts the docs directory from the arguments and passes it to the MCP Docs Service.
+ */
+
+import path from "path";
+import { spawn } from "child_process";
+import fs from "fs";
+import { fileURLToPath } from "url";
+
+// Wrap everything in a try/catch to catch any initialization errors
+try {
+  // Get the current directory
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  // Redirect logs to stderr instead of stdout to avoid interfering with JSON communication
+  const log = (...args) => {
+    console.error(...args);
+  };
+
+  // Create a log file for debugging
+  const logFile = path.join(process.cwd(), "inspector-debug.log");
+  fs.writeFileSync(
+    logFile,
+    `MCP Inspector Wrapper called at ${new Date().toISOString()}\n`
+  );
+
+  // Get all arguments
+  const args = process.argv.slice(2);
+  fs.appendFileSync(
+    logFile,
+    `MCP Inspector Wrapper - Arguments: ${JSON.stringify(args)}\n`
+  );
+  fs.appendFileSync(logFile, `Working directory: ${process.cwd()}\n`);
+  fs.appendFileSync(logFile, `Script directory: ${__dirname}\n`);
+  log("MCP Inspector Wrapper - Arguments:", args);
+
+  // List files in the package directory to debug
+  try {
+    const files = fs.readdirSync(__dirname);
+    fs.appendFileSync(
+      logFile,
+      `Files in package dir: ${JSON.stringify(files)}\n`
+    );
+
+    // Check if dist directory exists
+    const distDir = path.join(__dirname, "dist");
+    if (fs.existsSync(distDir)) {
+      const distFiles = fs.readdirSync(distDir);
+      fs.appendFileSync(
+        logFile,
+        `Files in dist dir: ${JSON.stringify(distFiles)}\n`
+      );
+
+      // Check if cli directory exists
+      const cliDir = path.join(distDir, "cli");
+      if (fs.existsSync(cliDir)) {
+        const cliFiles = fs.readdirSync(cliDir);
+        fs.appendFileSync(
+          logFile,
+          `Files in cli dir: ${JSON.stringify(cliFiles)}\n`
+        );
+      } else {
+        fs.appendFileSync(logFile, `CLI directory not found: ${cliDir}\n`);
+      }
+    } else {
+      fs.appendFileSync(logFile, `Dist directory not found: ${distDir}\n`);
+    }
+  } catch (err) {
+    fs.appendFileSync(logFile, `Error listing files: ${err.message}\n`);
+  }
+
+  // Find the docs directory in the arguments
+  let docsDir = path.join(process.cwd(), "docs");
+  let foundDocsDir = false;
+
+  // Look for a path ending with /docs
+  for (const arg of args) {
+    if (arg.endsWith("/docs") || arg.includes("/docs ")) {
+      const potentialPath = arg.split(" ")[0];
+      log("Found potential docs path:", potentialPath);
+      fs.appendFileSync(
+        logFile,
+        `Found potential docs path: ${potentialPath}\n`
+      );
+
+      if (fs.existsSync(potentialPath)) {
+        docsDir = potentialPath;
+        foundDocsDir = true;
+        log("Using docs directory:", docsDir);
+        fs.appendFileSync(logFile, `Using docs directory: ${docsDir}\n`);
+        break;
+      }
+    }
+  }
+
+  if (!foundDocsDir) {
+    log("No docs directory found in arguments, using default:", docsDir);
+    fs.appendFileSync(
+      logFile,
+      `No docs directory found in arguments, using default: ${docsDir}\n`
+    );
+
+    // Ensure the docs directory exists
+    if (!fs.existsSync(docsDir)) {
+      fs.appendFileSync(logFile, `Creating docs directory: ${docsDir}\n`);
+      try {
+        fs.mkdirSync(docsDir, { recursive: true });
+        fs.appendFileSync(logFile, `Successfully created docs directory\n`);
+      } catch (error) {
+        fs.appendFileSync(logFile, `Error creating docs directory: ${error}\n`);
+        log(`Error creating docs directory: ${error}`);
+        process.exit(1);
+      }
+    }
+  }
+
+  // Find the bin.js file
+  let binPath = path.join(__dirname, "dist", "cli", "bin.js");
+
+  // Check if the bin.js file exists
+  if (!fs.existsSync(binPath)) {
+    fs.appendFileSync(
+      logFile,
+      `bin.js not found at ${binPath}, searching...\n`
+    );
+
+    // Try to find bin.js in node_modules
+    const nodeModulesPath = path.join(
+      process.cwd(),
+      "node_modules",
+      "mcp-docs-service"
+    );
+    if (fs.existsSync(nodeModulesPath)) {
+      const potentialBinPath = path.join(
+        nodeModulesPath,
+        "dist",
+        "cli",
+        "bin.js"
+      );
+      if (fs.existsSync(potentialBinPath)) {
+        binPath = potentialBinPath;
+        fs.appendFileSync(
+          logFile,
+          `Found bin.js in node_modules: ${binPath}\n`
+        );
+      }
+    }
+  }
+
+  log("Spawning MCP Docs Service:", binPath, "--docs-dir", docsDir);
+  fs.appendFileSync(
+    logFile,
+    `Spawning MCP Docs Service: ${binPath} --docs-dir ${docsDir}\n`
+  );
+
+  // Check if the bin file exists before trying to run it
+  if (!fs.existsSync(binPath)) {
+    fs.appendFileSync(logFile, `ERROR: bin.js not found at ${binPath}\n`);
+    log(`ERROR: Could not find the MCP Docs Service binary at ${binPath}`);
+    process.exit(1);
+  }
+
+  // Set environment variable to indicate we're running under MCP Inspector
+  const env = { ...process.env, MCP_INSPECTOR: "true" };
+
+  // Spawn the process with stdio inheritance
+  // This ensures that the JSON communication between the MCP Inspector and the service
+  // is not interrupted by our logs
+  const child = spawn("node", [binPath, "--docs-dir", docsDir], {
+    stdio: "inherit",
+    env,
+  });
+
+  // Forward exit code
+  child.on("exit", (code) => {
+    fs.appendFileSync(logFile, `Child process exited with code ${code}\n`);
+    process.exit(code);
+  });
+
+  // Handle errors
+  child.on("error", (err) => {
+    fs.appendFileSync(
+      logFile,
+      `Error spawning child process: ${err.message}\n`
+    );
+    log(`Error spawning MCP Docs Service: ${err.message}`);
+    process.exit(1);
+  });
+} catch (error) {
+  // Write to a fallback log file in case the main one couldn't be created
+  try {
+    fs.writeFileSync(
+      path.join(process.cwd(), "inspector-error.log"),
+      `Fatal error in mcp-inspector-wrapper.js: ${error.message}\n${error.stack}\n`
+    );
+  } catch (e) {
+    // Last resort, just log to console
+    console.error(`Fatal error in mcp-inspector-wrapper.js: ${error.message}`);
+    console.error(error.stack);
+  }
+  process.exit(1);
+}

package/npx-wrapper.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+/**
+ * NPX Wrapper for MCP Docs Service
+ *
+ * This script is a standalone wrapper that can be used directly with npx.
+ * It doesn't require any additional files from the package and will download
+ * and run the MCP Docs Service directly.
+ */
+
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+// Wrap everything in a try/catch to catch any initialization errors
+try {
+  // Create a log file for debugging
+  const logFile = path.join(process.cwd(), "npx-debug.log");
+  fs.writeFileSync(
+    logFile,
+    `NPX wrapper called at ${new Date().toISOString()}\n`
+  );
+  fs.appendFileSync(logFile, `Arguments: ${JSON.stringify(process.argv)}\n`);
+  fs.appendFileSync(logFile, `Working directory: ${process.cwd()}\n`);
+
+  // Get the docs directory from arguments or use default
+  let docsDir = path.join(process.cwd(), "docs");
+  const args = process.argv.slice(2);
+
+  fs.appendFileSync(logFile, `Processing args: ${JSON.stringify(args)}\n`);
+
+  if (args.length > 0) {
+    // Check if --docs-dir flag is used
+    const docsDirIndex = args.indexOf("--docs-dir");
+    if (docsDirIndex !== -1 && docsDirIndex + 1 < args.length) {
+      docsDir = args[docsDirIndex + 1];
+      fs.appendFileSync(logFile, `Found --docs-dir flag, using: ${docsDir}\n`);
+    } else {
+      // Otherwise, use the last argument if it looks like a path
+      const lastArg = args[args.length - 1];
+      if (!lastArg.startsWith("-")) {
+        docsDir = lastArg;
+        fs.appendFileSync(logFile, `Using last arg as docs dir: ${docsDir}\n`);
+      }
+    }
+  } else {
+    fs.appendFileSync(
+      logFile,
+      `No args provided, using default docs dir: ${docsDir}\n`
+    );
+  }
+
+  // Resolve the docs directory to an absolute path
+  docsDir = path.resolve(docsDir);
+  fs.appendFileSync(logFile, `Using docs directory: ${docsDir}\n`);
+
+  // Ensure the docs directory exists
+  if (!fs.existsSync(docsDir)) {
+    fs.appendFileSync(logFile, `Creating docs directory: ${docsDir}\n`);
+    try {
+      fs.mkdirSync(docsDir, { recursive: true });
+      fs.appendFileSync(logFile, `Successfully created docs directory\n`);
+    } catch (error) {
+      fs.appendFileSync(logFile, `Error creating docs directory: ${error}\n`);
+      console.error(`Error creating docs directory: ${error}`);
+      process.exit(1);
+    }
+  }
+
+  // Install the MCP Docs Service if not already installed
+  const packageName = "mcp-docs-service";
+  fs.appendFileSync(logFile, `Checking if ${packageName} is installed...\n`);
+
+  // Run the MCP Docs Service
+  fs.appendFileSync(
+    logFile,
+    `Running MCP Docs Service with docs dir: ${docsDir}\n`
+  );
+
+  // Use npx to run the service directly
+  const npxArgs = ["-y", packageName, "--docs-dir", docsDir];
+  fs.appendFileSync(
+    logFile,
+    `Running npx with args: ${JSON.stringify(npxArgs)}\n`
+  );
+
+  const child = spawn("npx", npxArgs, {
+    stdio: "inherit",
+    env: { ...process.env, MCP_STANDALONE_WRAPPER: "true" },
+  });
+
+  child.on("exit", (code) => {
+    fs.appendFileSync(logFile, `Child process exited with code ${code}\n`);
+    process.exit(code);
+  });
+
+  child.on("error", (err) => {
+    fs.appendFileSync(
+      logFile,
+      `Error spawning child process: ${err.message}\n`
+    );
+    console.error(`Error running MCP Docs Service: ${err.message}`);
+    process.exit(1);
+  });
+} catch (error) {
+  // Write to a fallback log file in case the main one couldn't be created
+  try {
+    fs.writeFileSync(
+      path.join(process.cwd(), "npx-error.log"),
+      `Fatal error in npx-wrapper.js: ${error.message}\n${error.stack}\n`
+    );
+  } catch (e) {
+    // Last resort, just log to console
+    console.error(`Fatal error in npx-wrapper.js: ${error.message}`);
+    console.error(error.stack);
+  }
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-docs-service",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "MCP Documentation Management Service - A Model Context Protocol implementation for documentation management",
   "type": "module",
   "main": "dist/index.js",
@@ -8,7 +8,8 @@
   "bin": {
     "mcp-docs-service": "dist/cli/bin.js",
     "mcp-docs-inspector": "mcp-inspector-wrapper.js",
-    "mcp-docs-cursor": "cursor-wrapper.js"
+    "mcp-docs-cursor": "cursor-wrapper.js",
+    "mcp-docs-npx": "npx-wrapper.js"
   },
   "scripts": {
     "build": "tsc",
@@ -35,6 +36,7 @@
     "@modelcontextprotocol/sdk": "^0.5.0",
     "diff": "^7.0.0",
     "glob": "^11.0.1",
+    "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
     "minimatch": "^10.0.1",
     "zod-to-json-schema": "^3.23.5"
@@ -52,7 +54,8 @@
     "CHANGELOG.md",
     "LICENSE",
     "mcp-inspector-wrapper.js",
-    "cursor-wrapper.js"
+    "cursor-wrapper.js",
+    "npx-wrapper.js"
   ],
   "engines": {
     "node": ">=18"