@just-every/mcp-read-website-fast 0.1.9 → 0.1.11

package/README.md

@@ -86,7 +86,7 @@ Drop this into your client’s mcp.json (e.g. .vscode/mcp.json, ~/.cursor/mcp.js
 
 ### Available Tools
 
-- `read_website_fast` - Fetches a webpage and converts it to clean markdown
+- `read_website` - Fetches a webpage and converts it to clean markdown
   - Parameters:
     - `url` (required): The HTTP/HTTPS URL to fetch
     - `depth` (optional): Crawl depth (0 = single page)
@@ -144,6 +144,22 @@ npm run dev fetch https://example.com --output both
 npm run dev clear-cache
 ```
 
+## Auto-Restart Feature
+
+The MCP server includes automatic restart capability by default for improved reliability:
+
+- Automatically restarts the server if it crashes
+- Handles unhandled exceptions and promise rejections
+- Implements exponential backoff (max 10 attempts in 1 minute)
+- Logs all restart attempts for monitoring
+- Gracefully handles shutdown signals (SIGINT, SIGTERM)
+
+For development/debugging without auto-restart:
+```bash
+# Run directly without restart wrapper
+npm run serve:dev
+```
+
 ## Architecture
 
 ```
@@ -153,7 +169,9 @@ mcp/
 │   ├── parser/         # DOM parsing, Readability, Turndown conversion
 │   ├── cache/          # Disk-based caching with SHA-256 keys
 │   ├── utils/          # Logger, chunker utilities
-│   └── index.ts        # CLI entry point
+│   ├── index.ts        # CLI entry point
+│   ├── serve.ts        # MCP server entry point
+│   └── serve-restart.ts # Auto-restart wrapper
 ```
 
 ## Development

package/bin/mcp-read-website.js

@@ -18,7 +18,7 @@ async function main() {
   if (distExists) {
     // Use compiled JavaScript for production (fast startup)
     if (command === 'serve') {
-      const servePath = join(__dirname, '..', 'dist', 'serve.js');
+      const servePath = join(__dirname, '..', 'dist', 'serve-restart.js');
       await import(servePath);
     } else {
       const cliPath = join(__dirname, '..', 'dist', 'index.js');
@@ -30,7 +30,7 @@ async function main() {
       await import('tsx/esm');
       
       if (command === 'serve') {
-        const servePath = join(__dirname, '..', 'src', 'serve.ts');
+        const servePath = join(__dirname, '..', 'src', 'serve-restart.ts');
         await import(servePath);
       } else {
         const cliPath = join(__dirname, '..', 'src', 'index.ts');

package/dist/serve-restart.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/serve-restart.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAX_RESTART_ATTEMPTS = 10;
+const RESTART_WINDOW_MS = 60000;
+const INITIAL_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30000;
+let restartAttempts = [];
+let currentBackoff = INITIAL_BACKOFF_MS;
+const log = (level, message, ...args) => {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] [${level}] [restart-wrapper]`, message, ...args);
+};
+const cleanupRestartAttempts = () => {
+    const now = Date.now();
+    restartAttempts = restartAttempts.filter(timestamp => now - timestamp < RESTART_WINDOW_MS);
+};
+const shouldRestart = () => {
+    cleanupRestartAttempts();
+    if (restartAttempts.length >= MAX_RESTART_ATTEMPTS) {
+        log('ERROR', `Reached maximum restart attempts (${MAX_RESTART_ATTEMPTS}) within ${RESTART_WINDOW_MS}ms`);
+        return false;
+    }
+    return true;
+};
+const getBackoffDelay = () => {
+    const delay = Math.min(currentBackoff, MAX_BACKOFF_MS);
+    currentBackoff = Math.min(currentBackoff * 2, MAX_BACKOFF_MS);
+    return delay;
+};
+const resetBackoff = () => {
+    currentBackoff = INITIAL_BACKOFF_MS;
+};
+const startServer = () => {
+    log('INFO', 'Starting MCP server...');
+    const serverPath = join(__dirname, 'serve.js');
+    const child = spawn(process.execPath, [serverPath], {
+        stdio: 'inherit',
+        env: process.env,
+    });
+    let shuttingDown = false;
+    let restartTimer = null;
+    let startupTimer = setTimeout(() => {
+        log('INFO', 'Server started successfully');
+        resetBackoff();
+    }, 5000);
+    child.on('exit', (code, signal) => {
+        clearTimeout(startupTimer);
+        if (shuttingDown) {
+            log('INFO', 'Server stopped gracefully');
+            process.exit(0);
+            return;
+        }
+        if (code === 0) {
+            log('INFO', 'Server exited cleanly');
+            process.exit(0);
+            return;
+        }
+        log('WARN', `Server exited with code ${code}, signal ${signal}`);
+        if (!shouldRestart()) {
+            log('ERROR', 'Too many restart attempts, giving up');
+            process.exit(1);
+            return;
+        }
+        const backoffDelay = getBackoffDelay();
+        restartAttempts.push(Date.now());
+        log('INFO', `Restarting server in ${backoffDelay}ms (attempt ${restartAttempts.length}/${MAX_RESTART_ATTEMPTS})...`);
+        restartTimer = setTimeout(() => {
+            startServer();
+        }, backoffDelay);
+    });
+    child.on('error', (error) => {
+        log('ERROR', 'Failed to start server:', error);
+        process.exit(1);
+    });
+    const shutdown = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log('INFO', `Received ${signal}, shutting down...`);
+        if (restartTimer) {
+            clearTimeout(restartTimer);
+        }
+        child.kill(signal);
+        setTimeout(() => {
+            log('WARN', 'Force killing child process');
+            child.kill('SIGKILL');
+        }, 5000);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+};
+process.on('uncaughtException', (error) => {
+    log('ERROR', 'Uncaught exception in restart wrapper:', error);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    log('ERROR', 'Unhandled rejection in restart wrapper:', reason);
+    process.exit(1);
+});
+log('INFO', 'MCP server restart wrapper starting...');
+log('INFO', `Configuration: max attempts=${MAX_RESTART_ATTEMPTS}, window=${RESTART_WINDOW_MS}ms`);
+startServer();

package/dist/serve.js

@@ -1,13 +1,23 @@
 #!/usr/bin/env node
+console.error('[serve.ts] Process started, PID:', process.pid);
+console.error('[serve.ts] Node version:', process.version);
+console.error('[serve.ts] Current directory:', process.cwd());
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { logger, LogLevel } from './utils/logger.js';
+logger.setLevel(LogLevel.DEBUG);
+logger.info('MCP Server starting up...');
+logger.debug('Node version:', process.version);
+logger.debug('Working directory:', process.cwd());
+logger.debug('Environment:', { LOG_LEVEL: process.env.LOG_LEVEL });
 process.stdin.on('error', () => { });
 process.stdout.on('error', () => { });
 process.stderr.on('error', () => { });
 let fetchMarkdownModule;
 let fsPromises;
 let pathModule;
+logger.debug('Creating MCP server instance...');
 const server = new Server({
     name: 'read-website-fast',
     version: '0.1.0',
@@ -17,12 +27,13 @@ const server = new Server({
         resources: {},
     },
 });
+logger.info('MCP server instance created successfully');
 server.onerror = error => {
-    console.error('[MCP Server Error]', error);
+    logger.error('MCP Server Error:', error);
 };
 const READ_WEBSITE_TOOL = {
-    name: 'read_website_fast',
-    description: 'Quickly reads webpages and converts to markdown for fast, token efficient web scraping',
+    name: 'read_website',
+    description: 'Fast, token-efficient web content extraction - ideal for reading documentation, analyzing content, and gathering information from websites. Converts to clean Markdown while preserving links and structure.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -43,6 +54,13 @@ const READ_WEBSITE_TOOL = {
         },
         required: ['url'],
     },
+    annotations: {
+        title: 'Read Website',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 };
 const RESOURCES = [
     {
@@ -58,25 +76,44 @@ const RESOURCES = [
         description: 'Clear the cache directory',
     },
 ];
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [READ_WEBSITE_TOOL],
-}));
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    logger.debug('Received ListTools request');
+    const response = {
+        tools: [READ_WEBSITE_TOOL],
+    };
+    logger.debug('Returning tools:', response.tools.map(t => t.name));
+    return response;
+});
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    if (request.params.name !== 'read_website_fast') {
-        throw new Error(`Unknown tool: ${request.params.name}`);
+    logger.info('Received CallTool request:', request.params.name);
+    logger.debug('Request params:', JSON.stringify(request.params, null, 2));
+    if (request.params.name !== 'read_website') {
+        const error = `Unknown tool: ${request.params.name}`;
+        logger.error(error);
+        throw new Error(error);
     }
     try {
         if (!fetchMarkdownModule) {
+            logger.debug('Lazy loading fetchMarkdown module...');
             fetchMarkdownModule = await import('./internal/fetchMarkdown.js');
+            logger.info('fetchMarkdown module loaded successfully');
         }
         const args = request.params.arguments;
         if (!args.url || typeof args.url !== 'string') {
             throw new Error('URL parameter is required and must be a string');
         }
+        logger.info(`Processing read request for URL: ${args.url}`);
+        logger.debug('Read parameters:', {
+            url: args.url,
+            depth: args.depth,
+            respectRobots: args.respectRobots,
+        });
+        logger.debug('Calling fetchMarkdown...');
         const result = await fetchMarkdownModule.fetchMarkdown(args.url, {
             depth: args.depth ?? 0,
             respectRobots: args.respectRobots ?? true,
         });
+        logger.info('Content fetched successfully');
         if (result.error && result.markdown) {
             return {
                 content: [
@@ -95,14 +132,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
     catch (error) {
-        console.error('Tool execution error:', error);
+        logger.error('Error fetching content:', error.message);
+        logger.debug('Error stack:', error.stack);
+        logger.debug('Error details:', {
+            name: error.name,
+            code: error.code,
+            ...error,
+        });
         throw new Error(`Failed to fetch content: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
 });
-server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-    resources: RESOURCES,
-}));
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    logger.debug('Received ListResources request');
+    return {
+        resources: RESOURCES,
+    };
+});
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    logger.debug('Received ReadResource request:', request.params);
     const uri = request.params.uri;
     if (!fsPromises) {
         fsPromises = await import('fs/promises');
@@ -190,49 +237,84 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     throw new Error(`Unknown resource: ${uri}`);
 });
 async function runServer() {
-    const transport = new StdioServerTransport();
-    transport.onerror = error => {
-        console.error('[Transport Error]', error);
-    };
-    process.on('SIGINT', async () => {
-        console.error('Received SIGINT, shutting down gracefully...');
-        await server.close();
-        process.exit(0);
-    });
-    process.on('SIGTERM', async () => {
-        console.error('Received SIGTERM, shutting down gracefully...');
-        await server.close();
-        process.exit(0);
-    });
-    process.on('uncaughtException', error => {
-        console.error('Uncaught exception:', error);
-        if (error && error.message && error.message.includes('EPIPE')) {
-            console.error('Pipe error detected, keeping server alive');
-            return;
-        }
-        process.exit(1);
-    });
-    process.on('unhandledRejection', (reason, promise) => {
-        console.error('Unhandled rejection at:', promise, 'reason:', reason);
-    });
-    process.stdin.on('end', () => {
-        console.error('Stdin closed, shutting down...');
-        process.exit(0);
-    });
-    process.stdin.on('error', error => {
-        console.error('Stdin error:', error);
-    });
     try {
+        logger.info('Starting MCP server...');
+        logger.debug('Creating StdioServerTransport...');
+        const transport = new StdioServerTransport();
+        logger.debug('Transport created, connecting to server...');
+        transport.onerror = error => {
+            logger.error('Transport Error:', error);
+            if (error?.message?.includes('Connection closed')) {
+                logger.info('Connection closed by client');
+                process.exit(0);
+            }
+        };
+        const cleanup = async (signal) => {
+            logger.info(`Received ${signal}, shutting down gracefully...`);
+            try {
+                await server.close();
+                logger.info('Server closed successfully');
+                process.exit(0);
+            }
+            catch (error) {
+                logger.error('Error during cleanup:', error);
+                process.exit(1);
+            }
+        };
+        process.on('SIGINT', () => cleanup('SIGINT'));
+        process.on('SIGTERM', () => cleanup('SIGTERM'));
+        process.on('uncaughtException', error => {
+            logger.error('Uncaught exception:', error.message);
+            logger.error('Stack trace:', error.stack);
+            logger.debug('Full error object:', error);
+            if (error && error.message && error.message.includes('EPIPE')) {
+                logger.warn('Pipe error detected, keeping server alive');
+                return;
+            }
+            process.exit(1);
+        });
+        process.on('unhandledRejection', (reason, promise) => {
+            logger.error('Unhandled Rejection at:', promise);
+            logger.error('Rejection reason:', reason);
+            logger.debug('Full rejection details:', { reason, promise });
+        });
+        process.on('exit', code => {
+            logger.info(`Process exiting with code: ${code}`);
+        });
+        process.on('warning', warning => {
+            logger.warn('Process warning:', warning.message);
+            logger.debug('Warning details:', warning);
+        });
+        process.stdin.on('end', () => {
+            logger.info('Stdin closed, shutting down...');
+            setTimeout(() => process.exit(0), 100);
+        });
+        process.stdin.on('error', error => {
+            logger.warn('Stdin error:', error);
+        });
         await server.connect(transport);
-        console.error('read-website-fast MCP server running');
+        logger.info('MCP server connected and running successfully!');
+        logger.info('Ready to receive requests');
+        logger.debug('Server details:', {
+            name: 'read-website-fast',
+            version: '0.1.0',
+            pid: process.pid,
+        });
+        setInterval(() => {
+            logger.debug('Server heartbeat - still running...');
+        }, 30000);
         process.stdin.resume();
     }
     catch (error) {
-        console.error('Failed to start server:', error);
-        process.exit(1);
+        logger.error('Failed to start server:', error.message);
+        logger.debug('Startup error details:', error);
+        throw error;
     }
 }
+logger.info('Initializing MCP server...');
 runServer().catch(error => {
-    console.error('Server initialization error:', error);
+    logger.error('Fatal server error:', error.message);
+    logger.error('Stack trace:', error.stack);
+    logger.debug('Full error:', error);
     process.exit(1);
 });

package/dist/utils/logger.js

@@ -23,10 +23,10 @@ export class Logger {
                 console.error(prefix, message, ...args);
                 break;
             case LogLevel.WARN:
-                console.warn(prefix, message, ...args);
+                console.error(prefix, message, ...args);
                 break;
             default:
-                console.log(prefix, message, ...args);
+                console.error(prefix, message, ...args);
         }
     }
     error(message, ...args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@just-every/mcp-read-website-fast",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Markdown Content Preprocessor - Fetch web pages, extract content, convert to clean Markdown",
   "main": "dist/index.js",
   "bin": {
@@ -18,7 +18,7 @@
     "build:dev": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
-    "serve": "tsx src/serve.ts",
+    "serve": "node dist/serve-restart.js",
     "serve:dev": "tsx src/serve.ts",
     "test": "vitest",
     "test:deploy": "vitest run test/deployment.test.ts",
@@ -50,7 +50,7 @@
   "homepage": "https://github.com/just-every/mcp-read-website-fast#readme",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@modelcontextprotocol/sdk": "^1.12.3",
     "@mozilla/readability": "^0.6.0",
     "commander": "^14.0.0",
     "jsdom": "^26.1.0",