@pasko70/pibo 1.0.0

package/dist/mcp/daemon.js

@@ -0,0 +1,327 @@
+/**
+ * MCP-CLI Daemon - Background worker that maintains persistent MCP connections
+ *
+ * This is spawned as a detached process and manages a Unix socket for IPC.
+ * It maintains the MCP server connection and forwards requests from CLI invocations.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { createServer } from 'node:net';
+import { dirname } from 'node:path';
+import { callTool, connectToServer, listTools, } from './client.js';
+import { debug, getConfigHash, getDaemonTimeoutMs, getPidPath, getSocketDir, getSocketPath, } from './config.js';
+// ============================================================================
+// PID File Management
+// ============================================================================
+/**
+ * Write PID file with config hash for stale detection
+ */
+export function writePidFile(serverName, configHash) {
+    const pidPath = getPidPath(serverName);
+    const dir = dirname(pidPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const content = {
+        pid: process.pid,
+        configHash,
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(pidPath, JSON.stringify(content), { mode: 0o600 });
+}
+/**
+ * Read PID file content
+ */
+export function readPidFile(serverName) {
+    const pidPath = getPidPath(serverName);
+    if (!existsSync(pidPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(pidPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove PID file
+ */
+export function removePidFile(serverName) {
+    const pidPath = getPidPath(serverName);
+    try {
+        if (existsSync(pidPath)) {
+            unlinkSync(pidPath);
+        }
+    }
+    catch {
+        // Ignore errors during cleanup
+    }
+}
+/**
+ * Remove socket file
+ */
+export function removeSocketFile(serverName) {
+    const socketPath = getSocketPath(serverName);
+    try {
+        if (existsSync(socketPath)) {
+            unlinkSync(socketPath);
+        }
+    }
+    catch {
+        // Ignore errors during cleanup
+    }
+}
+/**
+ * Check if a process is running
+ */
+export function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Kill a process by PID
+ */
+export function killProcess(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ============================================================================
+// Daemon Worker
+// ============================================================================
+/**
+ * Main daemon entry point - run as detached background process
+ */
+export async function runDaemon(serverName, config) {
+    const socketPath = getSocketPath(serverName);
+    const configHash = getConfigHash(config);
+    const timeoutMs = getDaemonTimeoutMs();
+    let idleTimer = null;
+    let mcpClient = null;
+    let server = null;
+    const activeConnections = new Set();
+    // Cleanup function
+    const cleanup = async () => {
+        debug(`[daemon:${serverName}] Shutting down...`);
+        if (idleTimer) {
+            clearTimeout(idleTimer);
+            idleTimer = null;
+        }
+        // Close all active socket connections
+        for (const conn of activeConnections) {
+            try {
+                conn.end();
+            }
+            catch {
+                // Ignore
+            }
+        }
+        activeConnections.clear();
+        // Close MCP connection
+        if (mcpClient) {
+            try {
+                await mcpClient.close();
+            }
+            catch {
+                // Ignore
+            }
+            mcpClient = null;
+        }
+        // Close socket server
+        if (server) {
+            try {
+                server.close();
+            }
+            catch {
+                // Ignore
+            }
+            server = null;
+        }
+        // Clean up files
+        removeSocketFile(serverName);
+        removePidFile(serverName);
+        debug(`[daemon:${serverName}] Cleanup complete`);
+    };
+    // Reset idle timer
+    const resetIdleTimer = () => {
+        if (idleTimer) {
+            clearTimeout(idleTimer);
+        }
+        idleTimer = setTimeout(async () => {
+            debug(`[daemon:${serverName}] Idle timeout reached, shutting down`);
+            await cleanup();
+            process.exit(0);
+        }, timeoutMs);
+    };
+    // Handle signals
+    process.on('SIGTERM', async () => {
+        await cleanup();
+        process.exit(0);
+    });
+    process.on('SIGINT', async () => {
+        await cleanup();
+        process.exit(0);
+    });
+    // Ensure socket dir exists
+    const socketDir = getSocketDir();
+    if (!existsSync(socketDir)) {
+        mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+    }
+    // Remove stale socket if exists
+    removeSocketFile(serverName);
+    // Write PID file
+    writePidFile(serverName, configHash);
+    // Connect to MCP server
+    try {
+        debug(`[daemon:${serverName}] Connecting to MCP server...`);
+        mcpClient = await connectToServer(serverName, config);
+        debug(`[daemon:${serverName}] Connected to MCP server`);
+    }
+    catch (error) {
+        console.error(`[daemon:${serverName}] Failed to connect:`, error.message);
+        await cleanup();
+        process.exit(1);
+    }
+    // Handle incoming request
+    const handleRequest = async (data) => {
+        resetIdleTimer();
+        let request;
+        try {
+            request = JSON.parse(data.toString());
+        }
+        catch {
+            return {
+                id: 'unknown',
+                success: false,
+                error: { code: 'INVALID_REQUEST', message: 'Invalid JSON' },
+            };
+        }
+        debug(`[daemon:${serverName}] Request: ${request.type} (${request.id})`);
+        if (!mcpClient) {
+            return {
+                id: request.id,
+                success: false,
+                error: { code: 'NOT_CONNECTED', message: 'MCP client not connected' },
+            };
+        }
+        try {
+            switch (request.type) {
+                case 'ping':
+                    return { id: request.id, success: true, data: 'pong' };
+                case 'listTools': {
+                    const tools = await listTools(mcpClient.client);
+                    return { id: request.id, success: true, data: tools };
+                }
+                case 'callTool': {
+                    if (!request.toolName) {
+                        return {
+                            id: request.id,
+                            success: false,
+                            error: { code: 'MISSING_TOOL', message: 'toolName required' },
+                        };
+                    }
+                    const result = await callTool(mcpClient.client, request.toolName, request.args ?? {});
+                    return { id: request.id, success: true, data: result };
+                }
+                case 'getInstructions': {
+                    const instructions = mcpClient.client.getInstructions();
+                    return { id: request.id, success: true, data: instructions };
+                }
+                case 'close':
+                    // Graceful shutdown requested
+                    setTimeout(async () => {
+                        await cleanup();
+                        process.exit(0);
+                    }, 100);
+                    return { id: request.id, success: true, data: 'closing' };
+                default:
+                    return {
+                        id: request.id,
+                        success: false,
+                        error: {
+                            code: 'UNKNOWN_TYPE',
+                            message: `Unknown request type: ${request.type}`,
+                        },
+                    };
+            }
+        }
+        catch (error) {
+            const err = error;
+            return {
+                id: request.id,
+                success: false,
+                error: { code: 'EXECUTION_ERROR', message: err.message },
+            };
+        }
+    };
+    // Start Unix socket server
+    try {
+        server = createServer((socket) => {
+            activeConnections.add(socket);
+            debug(`[daemon:${serverName}] Client connected`);
+            socket.on('data', async (data) => {
+                const response = await handleRequest(Buffer.isBuffer(data) ? data : Buffer.from(data));
+                socket.write(`${JSON.stringify(response)}\n`);
+            });
+            socket.on('close', () => {
+                activeConnections.delete(socket);
+                debug(`[daemon:${serverName}] Client disconnected`);
+            });
+            socket.on('error', (error) => {
+                debug(`[daemon:${serverName}] Socket error: ${error.message}`);
+                activeConnections.delete(socket);
+            });
+        });
+        await new Promise((resolve, reject) => {
+            server?.once('error', reject);
+            server?.listen(socketPath, () => {
+                server?.off('error', reject);
+                resolve();
+            });
+        });
+        debug(`[daemon:${serverName}] Listening on ${socketPath}`);
+        // Start idle timer
+        resetIdleTimer();
+        // Signal readiness by writing to stdout (parent will read this)
+        console.log('DAEMON_READY');
+    }
+    catch (error) {
+        console.error(`[daemon:${serverName}] Failed to start socket server:`, error.message);
+        await cleanup();
+        process.exit(1);
+    }
+}
+// ============================================================================
+// Entry point when run directly
+// ============================================================================
+// Check if running as daemon process
+if (process.argv[2] === '--daemon') {
+    const serverName = process.argv[3];
+    const configJson = process.argv[4];
+    if (!serverName || !configJson) {
+        console.error('Usage: daemon.ts --daemon <serverName> <configJson>');
+        process.exit(1);
+    }
+    let config;
+    try {
+        config = JSON.parse(configJson);
+    }
+    catch {
+        console.error('Invalid config JSON');
+        process.exit(1);
+    }
+    runDaemon(serverName, config).catch((error) => {
+        console.error('Daemon failed:', error);
+        process.exit(1);
+    });
+}

package/dist/mcp/errors.js

@@ -0,0 +1,287 @@
+/**
+ * Enhanced error handling with actionable messages for LLM recovery
+ *
+ * Each error includes:
+ * - What went wrong (error type)
+ * - Why it failed (details)
+ * - How to fix it (recovery suggestions)
+ */
+import { ErrorCode } from '../cli-errors.js';
+export { ErrorCode, formatCliError } from '../cli-errors.js';
+// ============================================================================
+// Config Errors
+// ============================================================================
+export function configNotFoundError(path) {
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'CONFIG_NOT_FOUND',
+        message: `Config file not found: ${path}`,
+        suggestion: `Create mcp_servers.json with: { "mcpServers": { "server-name": { "command": "..." } } }`,
+    };
+}
+export function configSearchError() {
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'CONFIG_NOT_FOUND',
+        message: 'No mcp_servers.json found in search paths',
+        details: 'Searched: ./mcp_servers.json, ~/.mcp_servers.json, ~/.config/mcp/mcp_servers.json',
+        suggestion: 'Create mcp_servers.json in current directory or use -c/--config to specify path',
+    };
+}
+export function configInvalidJsonError(path, parseError) {
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'CONFIG_INVALID_JSON',
+        message: `Invalid JSON in config file: ${path}`,
+        details: parseError,
+        suggestion: 'Check for syntax errors: missing commas, unquoted keys, trailing commas',
+    };
+}
+export function configMissingFieldError(path) {
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'CONFIG_MISSING_FIELD',
+        message: `Config file missing required "mcpServers" object`,
+        details: `File: ${path}`,
+        suggestion: 'Config must have structure: { "mcpServers": { ... } }',
+    };
+}
+// ============================================================================
+// Server Errors
+// ============================================================================
+export function serverNotFoundError(serverName, available) {
+    const availableList = available.length > 0 ? available.join(', ') : '(none)';
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'SERVER_NOT_FOUND',
+        message: `Server "${serverName}" not found in config`,
+        details: `Available servers: ${availableList}`,
+        suggestion: available.length > 0
+            ? `Use one of: ${available.map((s) => `pibo mcp info ${s}`).join(', ')}`
+            : `Add server to mcp_servers.json: { "mcpServers": { "${serverName}": { ... } } }`,
+    };
+}
+export function serverConnectionError(serverName, cause) {
+    // Detect common error patterns
+    let suggestion = 'Check server configuration and ensure the server process can start';
+    if (cause.includes('ENOENT') || cause.includes('not found')) {
+        suggestion =
+            'Command not found. Install the MCP server: npx -y @modelcontextprotocol/server-<name>';
+    }
+    else if (cause.includes('ECONNREFUSED')) {
+        suggestion =
+            'Server refused connection. Check if the server is running and URL is correct';
+    }
+    else if (cause.includes('ETIMEDOUT') || cause.includes('timeout')) {
+        suggestion =
+            'Connection timed out. Check network connectivity and server availability';
+    }
+    else if (cause.includes('401') || cause.includes('Unauthorized')) {
+        suggestion = 'Authentication required. Add Authorization header to config';
+    }
+    else if (cause.includes('403') || cause.includes('Forbidden')) {
+        suggestion = 'Access forbidden. Check credentials and permissions';
+    }
+    return {
+        code: ErrorCode.NETWORK_ERROR,
+        type: 'SERVER_CONNECTION_FAILED',
+        message: `Failed to connect to server "${serverName}"`,
+        details: cause,
+        suggestion,
+    };
+}
+// ============================================================================
+// Tool Errors
+// ============================================================================
+export function toolNotFoundError(toolName, serverName, availableTools) {
+    const toolList = availableTools?.slice(0, 5).join(', ') || '';
+    const moreCount = availableTools && availableTools.length > 5
+        ? ` (+${availableTools.length - 5} more)`
+        : '';
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'TOOL_NOT_FOUND',
+        message: `Tool "${toolName}" not found in server "${serverName}"`,
+        details: availableTools
+            ? `Available tools: ${toolList}${moreCount}`
+            : undefined,
+        suggestion: `Run 'pibo mcp info ${serverName}' to see all available tools`,
+    };
+}
+export function toolExecutionError(toolName, serverName, cause) {
+    let suggestion = 'Check tool arguments match the expected schema';
+    // Detect common MCP error patterns
+    if (cause.includes('validation') || cause.includes('invalid_type')) {
+        suggestion = `Run 'pibo mcp info ${serverName} ${toolName}' to see the input schema, then fix arguments`;
+    }
+    else if (cause.includes('required')) {
+        suggestion = `Missing required argument. Run 'pibo mcp info ${serverName} ${toolName}' to see required fields`;
+    }
+    else if (cause.includes('permission') || cause.includes('denied')) {
+        suggestion = 'Permission denied. Check file/resource permissions';
+    }
+    else if (cause.includes('not found') || cause.includes('ENOENT')) {
+        suggestion = 'Resource not found. Verify the path or identifier exists';
+    }
+    return {
+        code: ErrorCode.SERVER_ERROR,
+        type: 'TOOL_EXECUTION_FAILED',
+        message: `Tool "${toolName}" execution failed`,
+        details: cause,
+        suggestion,
+    };
+}
+export function toolDisabledError(toolName, serverName) {
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'TOOL_DISABLED',
+        message: `Tool "${toolName}" is disabled by configuration`,
+        details: `Server "${serverName}" has allowedTools/disabledTools filtering configured`,
+        suggestion: `Check your mcp_servers.json config. Remove "${toolName}" from disabledTools or add it to allowedTools.`,
+    };
+}
+// ============================================================================
+// Argument Errors
+// ============================================================================
+export function invalidTargetError(target) {
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'INVALID_TARGET',
+        message: `Invalid target format: "${target}"`,
+        details: 'Expected format: server/tool',
+        suggestion: `Use 'pibo mcp call <server> <tool> <json>', e.g. 'pibo mcp call github search_repos \'{"query":"mcp"}\''`,
+    };
+}
+export function invalidJsonArgsError(input, parseError) {
+    // Truncate long input
+    const truncated = input.length > 100 ? `${input.substring(0, 100)}...` : input;
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'INVALID_JSON_ARGUMENTS',
+        message: 'Invalid JSON in tool arguments',
+        details: parseError ? `Parse error: ${parseError}` : `Input: ${truncated}`,
+        suggestion: `Use valid JSON: '{"path": "./file.txt"}'. Run 'pibo mcp info <server> <tool>' for the schema.`,
+    };
+}
+export function unknownOptionError(option) {
+    // Provide context-aware suggestions for common mistakes
+    let suggestion;
+    const optionLower = option.toLowerCase().replace(/^-+/, '');
+    if (['server', 's'].includes(optionLower)) {
+        suggestion = `Server is a positional argument. Use 'pibo mcp info <server>'`;
+    }
+    else if (['tool', 't'].includes(optionLower)) {
+        suggestion = `Tool is a positional argument. Use 'pibo mcp call <server> <tool>'`;
+    }
+    else if (['args', 'arguments', 'a', 'input'].includes(optionLower)) {
+        suggestion = `Pass JSON directly: 'pibo mcp call <server> <tool> '{\"key\": \"value\"}''`;
+    }
+    else if (['pattern', 'p', 'search', 'query'].includes(optionLower)) {
+        suggestion = `Use 'pibo mcp grep \"*pattern*\"'`;
+    }
+    else if (['call', 'run', 'exec'].includes(optionLower)) {
+        suggestion = `Use 'call' as a subcommand, not option: 'pibo mcp call <server> <tool>'`;
+    }
+    else if (['info', 'list', 'get'].includes(optionLower)) {
+        suggestion = `Use 'info' as a subcommand, not option: 'pibo mcp info <server>'`;
+    }
+    else {
+        suggestion =
+            'Valid options: -c/--config, -j/--json, -d/--with-descriptions, -r/--raw';
+    }
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'UNKNOWN_OPTION',
+        message: `Unknown option: ${option}`,
+        suggestion,
+    };
+}
+export function missingArgumentError(command, argument) {
+    // Provide command-specific format examples
+    let suggestion;
+    switch (command) {
+        case 'call':
+            if (argument.includes('server')) {
+                suggestion = `Use 'pibo mcp call <server> <tool> '{\"key\": \"value\"}''`;
+            }
+            else {
+                suggestion = `Use 'pibo mcp call <server> <tool> '{\"key\": \"value\"}''`;
+            }
+            break;
+        case 'grep':
+            suggestion = `Use 'pibo mcp grep \"*pattern*\"'`;
+            break;
+        case '-c/--config':
+            suggestion = `Use 'pibo mcp -c /path/to/mcp_servers.json'`;
+            break;
+        default:
+            suggestion = `Run 'pibo mcp --help' for available commands`;
+    }
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'MISSING_ARGUMENT',
+        message: `Missing required argument for ${command}: ${argument}`,
+        suggestion,
+    };
+}
+// ============================================================================
+// Subcommand Errors
+// ============================================================================
+/**
+ * Error when user provides ambiguous command like "pibo mcp server tool"
+ */
+export function ambiguousCommandError(serverName, toolName, hasArgs) {
+    const cmd = hasArgs
+        ? `pibo mcp call ${serverName} ${toolName} '<json>'`
+        : `pibo mcp call ${serverName} ${toolName}`;
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'AMBIGUOUS_COMMAND',
+        message: 'Ambiguous command: did you mean to call a tool or view info?',
+        details: `Received: pibo mcp ${serverName} ${toolName}${hasArgs ? ' ...' : ''}`,
+        suggestion: `Use '${cmd}' to execute, or 'pibo mcp info ${serverName} ${toolName}' to view schema`,
+    };
+}
+/**
+ * Error when user uses unknown subcommand with smart suggestions
+ */
+export function unknownSubcommandError(subcommand) {
+    // Map common aliases to correct subcommands
+    const suggestions = {
+        run: 'call',
+        execute: 'call',
+        exec: 'call',
+        invoke: 'call',
+        list: 'info',
+        ls: 'info',
+        get: 'info',
+        show: 'info',
+        describe: 'info',
+        search: 'grep',
+        find: 'grep',
+        query: 'grep',
+    };
+    const suggested = suggestions[subcommand.toLowerCase()];
+    const validCommands = 'info, grep, call, config';
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'UNKNOWN_SUBCOMMAND',
+        message: `Unknown subcommand: "${subcommand}"`,
+        details: `Valid subcommands: ${validCommands}`,
+        suggestion: suggested
+            ? `Did you mean 'pibo mcp ${suggested}'?`
+            : `Use 'pibo mcp --help' to see available commands`,
+    };
+}
+/**
+ * Error when too many positional arguments provided
+ */
+export function tooManyArgumentsError(command, received, max) {
+    return {
+        code: ErrorCode.CLIENT_ERROR,
+        type: 'TOO_MANY_ARGUMENTS',
+        message: `Too many arguments for ${command}`,
+        details: `Received ${received} arguments, maximum is ${max}`,
+        suggestion: `Run 'pibo mcp --help' for correct usage`,
+    };
+}