mcp-docs-service 0.3.5 → 0.3.7

package/cursor-wrapper.cjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Cursor Wrapper
+ *
+ * This script is a wrapper for the MCP Docs Service that ensures proper stdio handling for Cursor.
+ * It redirects all console.log output to stderr to avoid interfering with the JSON communication.
+ */
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// Create a debug log file
+const logDir = path.join(
+  process.env.HOME || process.env.USERPROFILE,
+  ".mcp-docs-service"
+);
+try {
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+} catch (err) {
+  // Ignore errors creating log directory
+}
+
+const logFile = path.join(logDir, "cursor-debug.log");
+try {
+  fs.writeFileSync(
+    logFile,
+    `MCP Cursor Wrapper called at ${new Date().toISOString()}\n`
+  );
+} catch (err) {
+  // Ignore errors writing to log file
+}
+
+// Helper function to log to the file
+const logToFile = (message) => {
+  try {
+    fs.appendFileSync(logFile, `${message}\n`);
+  } catch (err) {
+    // Ignore errors writing to log file
+  }
+};
+
+// Log debug information
+logToFile(`Process arguments: ${JSON.stringify(process.argv)}`);
+logToFile(`Working directory: ${process.cwd()}`);
+logToFile(`Script directory: ${__dirname}`);
+
+// Find the path to the actual service script
+const servicePath = path.resolve(path.join(__dirname, "dist", "index.js"));
+logToFile(`Service path: ${servicePath}`);
+
+// Check if the service script exists
+if (!fs.existsSync(servicePath)) {
+  logToFile(`ERROR: Service script not found at ${servicePath}`);
+  console.error(`ERROR: Service script not found at ${servicePath}`);
+  process.exit(1);
+}
+
+// Get command line arguments, skipping the first two (node and script path)
+const args = process.argv.slice(2);
+logToFile(`Command line arguments: ${JSON.stringify(args)}`);
+
+// Set environment variables
+const env = {
+  ...process.env,
+  MCP_CURSOR_WRAPPER: "true",
+  // Redirect console.log to stderr
+  NODE_OPTIONS: `${process.env.NODE_OPTIONS || ""} --redirect-warnings=stderr`,
+};
+
+// Create a child process with piped stdio
+// This is critical for Cursor - we need to control stdin/stdout directly
+const child = spawn("node", [servicePath, ...args], {
+  stdio: ["pipe", "pipe", "pipe"],
+  env,
+});
+
+// Redirect child's stderr to our stderr
+child.stderr.on("data", (data) => {
+  process.stderr.write(data);
+
+  // Also log to file for debugging
+  try {
+    logToFile(`STDERR: ${data.toString()}`);
+  } catch (err) {
+    // Ignore errors
+  }
+});
+
+// Pipe our stdin directly to child's stdin
+process.stdin.pipe(child.stdin);
+
+// Pipe child's stdout directly to our stdout
+// This is the critical part - we don't want to modify the JSON communication
+child.stdout.pipe(process.stdout);
+
+// Handle process exit
+child.on("exit", (code) => {
+  logToFile(`Child process exited with code ${code}`);
+  process.exit(code || 0);
+});
+
+// Handle errors
+child.on("error", (err) => {
+  logToFile(`Error spawning child process: ${err.message}`);
+  console.error(`Error spawning MCP Docs Service: ${err.message}`);
+  process.exit(1);
+});

package/dist/index.js

@@ -15,6 +15,20 @@ import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { createTwoFilesPatch } from "diff";
 import { glob } from "glob";
+// Setup logging to avoid interfering with MCP protocol
+// When running under Cursor, we need to redirect console.log to stderr
+const isCursorWrapper = process.env.MCP_CURSOR_WRAPPER === "true";
+const isInspector = process.env.MCP_INSPECTOR === "true";
+// Create a safe logging function that won't interfere with MCP protocol
+const safeLog = (...args) => {
+    // When running under Cursor, redirect all logs to stderr
+    if (isCursorWrapper) {
+        console.error(...args);
+    }
+    else {
+        console.log(...args);
+    }
+};
 // Command line argument parsing
 const args = process.argv.slice(2);
 let docsDir = path.join(process.cwd(), "docs");
@@ -42,7 +56,7 @@ docsDir = path.normalize(docsDir);
 try {
     const stats = await fs.stat(docsDir);
     if (!stats.isDirectory()) {
-        console.error(`Error: ${docsDir} is not a directory`);
+        safeLog(`Error: ${docsDir} is not a directory`);
         process.exit(1);
     }
 }
@@ -51,7 +65,7 @@ catch (error) {
     if (createDir) {
         try {
             await fs.mkdir(docsDir, { recursive: true });
-            console.log(`Created docs directory: ${docsDir}`);
+            safeLog(`Created docs directory: ${docsDir}`);
             // Create a sample README.md
             const readmePath = path.join(docsDir, "README.md");
             try {
@@ -68,22 +82,22 @@ description: Project documentation
 This is the documentation directory for your project.
 `;
                 await fs.writeFile(readmePath, content);
-                console.log(`Created sample README.md in ${docsDir}`);
+                safeLog(`Created sample README.md in ${docsDir}`);
             }
         }
         catch (error) {
-            console.error(`Error creating docs directory: ${error}`);
+            safeLog(`Error creating docs directory: ${error}`);
             process.exit(1);
         }
     }
     else {
-        console.error(`Error: Docs directory does not exist: ${docsDir}`);
-        console.error(`Use --create-dir to create it automatically`);
+        safeLog(`Error: Docs directory does not exist: ${docsDir}`);
+        safeLog(`Use --create-dir to create it automatically`);
         process.exit(1);
     }
 }
-console.log("MCP Documentation Service initialized with docs directory:", docsDir);
-console.log("Directory will be created if it doesn't exist");
+safeLog("MCP Documentation Service initialized with docs directory:", docsDir);
+safeLog("Directory will be created if it doesn't exist");
 // Schema definitions
 const ReadDocumentArgsSchema = z.object({
     path: z
@@ -438,7 +452,7 @@ async function checkDocumentationHealth(basePath) {
 // Server setup
 const server = new Server({
     name: "mcp-docs-service",
-    version: "0.3.5",
+    version: "0.3.7",
 }, {
     capabilities: {
         tools: {},
@@ -670,11 +684,11 @@ if (runHealthCheck) {
 async function runServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.log("MCP Documentation Management Service started.");
-    console.log("Using docs directory:", docsDir);
-    console.log("Reading from stdin, writing results to stdout...");
+    safeLog("MCP Documentation Management Service started.");
+    safeLog("Using docs directory:", docsDir);
+    safeLog("Reading from stdin, writing results to stdout...");
 }
 runServer().catch((error) => {
-    console.error("Fatal error running server:", error);
+    safeLog("Fatal error running server:", error);
     process.exit(1);
 });

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "mcp-docs-service",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "MCP Documentation Service - A Model Context Protocol implementation for documentation management",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "mcp-docs-service": "dist/index.js"
+    "mcp-docs-service": "dist/index.js",
+    "mcp-docs-service-cursor": "cursor-wrapper.cjs"
   },
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "cursor-wrapper.cjs"
   ],
   "scripts": {
     "build": "tsc",

package/dist/cli/bin.d.ts

@@ -1,8 +0,0 @@
-#!/usr/bin/env node
-/**
- * MCP Docs Service CLI
- *
- * This is the entry point for the CLI version of the MCP Docs Service.
- * It simply imports and runs the main service.
- */
-import "../index.js";

package/dist/cli/bin.js

@@ -1,133 +0,0 @@
-#!/usr/bin/env node
-/**
- * MCP Docs Service CLI
- *
- * This is the entry point for the CLI version of the MCP Docs Service.
- * It simply imports and runs the main service.
- */
-import path from "path";
-import fs from "fs";
-import { fileURLToPath } from "url";
-// Get the current directory
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-// Check if we're running under MCP Inspector
-const isMCPInspector = process.env.MCP_INSPECTOR === "true" ||
-    process.argv.some((arg) => arg.includes("modelcontextprotocol/inspector"));
-// Create a logging function that respects MCP Inspector mode
-const log = (...args) => {
-    if (!isMCPInspector) {
-        console.log(...args);
-    }
-};
-const errorLog = (...args) => {
-    console.error(...args);
-};
-// Parse command line arguments
-const args = process.argv.slice(2);
-log("CLI Arguments:", JSON.stringify(args));
-let docsDir = path.join(process.cwd(), "docs");
-let createDir = false;
-let healthCheck = false;
-let showHelp = false;
-// MCP Inspector specific handling
-// When run through MCP Inspector, it might pass arguments in a different format
-if (isMCPInspector) {
-    log("Detected MCP Inspector environment");
-    // Try to find a valid docs directory in all arguments
-    // This is a more aggressive approach but should work with various argument formats
-    for (const arg of process.argv) {
-        if (arg.endsWith("/docs") || arg.includes("/docs ")) {
-            const potentialPath = arg.split(" ")[0];
-            log("Found potential docs path in MCP Inspector args:", potentialPath);
-            if (fs.existsSync(potentialPath)) {
-                docsDir = path.resolve(potentialPath);
-                log("Using docs directory from MCP Inspector:", docsDir);
-                break;
-            }
-        }
-    }
-    // If we couldn't find a valid docs directory, use the default
-    log("Using docs directory:", docsDir);
-}
-else {
-    // Standard argument parsing
-    for (let i = 0; i < args.length; i++) {
-        log(`Processing arg[${i}]:`, args[i]);
-        if (args[i] === "--docs-dir" && i + 1 < args.length) {
-            docsDir = path.resolve(args[i + 1]);
-            log("Setting docs dir from --docs-dir flag:", docsDir);
-            i++; // Skip the next argument
-        }
-        else if (args[i] === "--create-dir") {
-            createDir = true;
-        }
-        else if (args[i] === "--health-check") {
-            healthCheck = true;
-        }
-        else if (args[i] === "--help" || args[i] === "-h") {
-            showHelp = true;
-        }
-        else if (!args[i].startsWith("--")) {
-            // Handle positional argument as docs directory
-            const potentialPath = path.resolve(args[i]);
-            log("Potential positional path:", potentialPath);
-            log("Path exists?", fs.existsSync(potentialPath));
-            if (fs.existsSync(potentialPath)) {
-                docsDir = potentialPath;
-                log("Setting docs dir from positional argument:", docsDir);
-            }
-            else {
-                log("Path doesn't exist, not using as docs dir:", potentialPath);
-            }
-        }
-    }
-}
-log("Final docs dir:", docsDir);
-// Show help if requested
-if (showHelp) {
-    console.log(`
-MCP Docs Service - Documentation Management Service
-
-Usage:
-  mcp-docs-service [options]
-  mcp-docs-service <docs-directory> [options]
-
-Options:
-  --docs-dir <path>   Specify the docs directory (default: ./docs)
-  --create-dir        Create the docs directory if it doesn't exist
-  --health-check      Run a health check on the documentation
-  --help, -h          Show this help message
-  `);
-    process.exit(0);
-}
-// Create docs directory if it doesn't exist and --create-dir is specified
-if (createDir) {
-    try {
-        if (!fs.existsSync(docsDir)) {
-            fs.mkdirSync(docsDir, { recursive: true });
-            log(`Created docs directory: ${docsDir}`);
-        }
-    }
-    catch (error) {
-        errorLog(`Error creating docs directory: ${error}`);
-        process.exit(1);
-    }
-}
-// Ensure the docs directory exists
-if (!fs.existsSync(docsDir)) {
-    errorLog(`Error: Docs directory does not exist: ${docsDir}`);
-    errorLog(`Use --create-dir to create it automatically`);
-    process.exit(1);
-}
-// Add the docs directory to process.argv so it's available to the main service
-process.argv.push(docsDir);
-// Add health check flag to process.argv if specified
-if (healthCheck) {
-    process.argv.push("--health-check");
-}
-// Import the main service
-import "../index.js";
-// The main service will handle the CLI arguments and execution
-// No additional code needed here as the main index.ts already has CLI functionality
-//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":"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"}

package/dist/handlers/docs.d.ts

@@ -1,26 +0,0 @@
-import { ToolResponse } from "../types/tools.js";
-/**
- * Reads a markdown document and extracts its content and metadata
- */
-export declare function readDocument(docPath: string, allowedDirectories: string[]): Promise<ToolResponse>;
-/**
- * Lists all markdown documents in a directory
- */
-export declare function listDocuments(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
-/**
- * Gets the structure of the documentation directory
- */
-export declare function getStructure(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
-/**
- * Gets the navigation structure for the documentation
- */
-export declare function getNavigation(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
-/**
- * Checks the health of documentation
- */
-export declare function checkDocumentationHealth(basePath: string, options: {
-    checkLinks?: boolean;
-    checkMetadata?: boolean;
-    checkOrphans?: boolean;
-    requiredMetadataFields?: string[];
-}, allowedDirectories: string[]): Promise<ToolResponse>;