sqlew 3.5.3 → 3.6.1

package/dist/index.js

@@ -6,8 +6,9 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { initializeDatabase, closeDatabase, setConfigValue, getAllConfig } from './database.js';
+import { initializeDatabase, closeDatabase, setConfigValue, getAllConfig, getAdapter } from './database.js';
 import { CONFIG_KEYS } from './constants.js';
+import { loadConfigFile } from './config/loader.js';
 import { setDecision, getContext, getDecision, searchByTags, getVersions, searchByLayer, quickSetDecision, searchAdvanced, setDecisionBatch, hasUpdates, setFromTemplate, createTemplate, listTemplates, hardDeleteDecision, addDecisionContextAction, listDecisionContextsAction, decisionHelp, decisionExample } from './tools/context.js';
 import { sendMessage, getMessages, markRead, sendMessageBatch, messageHelp, messageExample } from './tools/messaging.js';
 import { recordFileChange, getFileChanges, checkFileLock, recordFileChangeBatch, fileHelp, fileExample } from './tools/files.js';
@@ -16,6 +17,11 @@ import { getLayerSummary, clearOldData, getStats, getActivityLog, flushWAL, stat
 import { getConfig, updateConfig, configHelp, configExample } from './tools/config.js';
 import { createTask, updateTask, getTask, listTasks, moveTask, linkTask, archiveTask, batchCreateTasks, addDependency, removeDependency, getDependencies, watchFiles, getPrunedFiles, linkPrunedFile, taskHelp, taskExample, watcherStatus } from './tools/tasks.js';
 import { FileWatcher } from './watcher/index.js';
+import { trackAndReturnHelp } from './utils/help-tracking.js';
+import { queryHelpAction, queryHelpParams, queryHelpTool, queryHelpUseCase, queryHelpListUseCases, queryHelpNextActions } from './tools/help-queries.js';
+import { initDebugLogger, closeDebugLogger, debugLog, debugLogToolCall, debugLogToolResponse } from './utils/debug-logger.js';
+import { handleToolError, handleInitializationError, setupGlobalErrorHandlers } from './utils/error-handler.js';
+import { ensureSqlewDirectory } from './config/example-generator.js';
 // Parse command-line arguments
 const args = process.argv.slice(2);
 const parsedArgs = {};
@@ -46,6 +52,12 @@ for (let i = 0; i < args.length; i++) {
     else if (arg === '--autodelete-file-history-days' && i + 1 < args.length) {
         parsedArgs.autodeleteFileHistoryDays = parseInt(args[++i], 10);
     }
+    else if (arg.startsWith('--debug-log=')) {
+        parsedArgs.debugLogPath = arg.split('=')[1];
+    }
+    else if (arg === '--debug-log' && i + 1 < args.length) {
+        parsedArgs.debugLogPath = args[++i];
+    }
     else if (!arg.startsWith('--')) {
         // Backward compatibility: first non-flag argument is dbPath
         if (!parsedArgs.dbPath) {
@@ -53,33 +65,12 @@ for (let i = 0; i < args.length; i++) {
         }
     }
 }
-const dbPath = parsedArgs.dbPath;
-// Initialize database
+// Load config file and determine database path
+// Priority: CLI --db-path > config file > default
+const fileConfig = loadConfigFile();
+const dbPath = parsedArgs.dbPath || fileConfig.database?.path;
+// Initialize database (will be set after async init completes)
 let db;
-try {
-    db = initializeDatabase(dbPath);
-    // Apply CLI config overrides if provided
-    if (parsedArgs.autodeleteIgnoreWeekend !== undefined) {
-        setConfigValue(db, CONFIG_KEYS.AUTODELETE_IGNORE_WEEKEND, parsedArgs.autodeleteIgnoreWeekend ? '1' : '0');
-    }
-    if (parsedArgs.autodeleteMessageHours !== undefined) {
-        setConfigValue(db, CONFIG_KEYS.AUTODELETE_MESSAGE_HOURS, String(parsedArgs.autodeleteMessageHours));
-    }
-    if (parsedArgs.autodeleteFileHistoryDays !== undefined) {
-        setConfigValue(db, CONFIG_KEYS.AUTODELETE_FILE_HISTORY_DAYS, String(parsedArgs.autodeleteFileHistoryDays));
-    }
-    // Display current config
-    const config = getAllConfig(db);
-    const ignoreWeekend = config[CONFIG_KEYS.AUTODELETE_IGNORE_WEEKEND] === '1';
-    const messageHours = config[CONFIG_KEYS.AUTODELETE_MESSAGE_HOURS];
-    const fileHistoryDays = config[CONFIG_KEYS.AUTODELETE_FILE_HISTORY_DAYS];
-    console.error('✓ MCP Shared Context Server initialized');
-    console.error(`  Auto-delete config: messages=${messageHours}h, file_history=${fileHistoryDays}d, ignore_weekend=${ignoreWeekend}`);
-}
-catch (error) {
-    console.error('✗ Failed to initialize database:', error);
-    process.exit(1);
-}
 // Create MCP server
 const server = new Server({
     name: 'mcp-sqlew',
@@ -100,55 +91,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 Context Management - Store decisions with metadata (tags, layers, versions, scopes)
 
 Use action: "help" for detailed documentation.
-Use action: "example" for comprehensive usage examples.`,
+Use action: "example" for comprehensive usage examples.
+Use action: "use_case" for practical scenarios and when-to-use guidance.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         action: {
                             type: 'string',
                             description: 'Action',
-                            enum: ['set', 'get', 'list', 'search_tags', 'search_layer', 'versions', 'quick_set', 'search_advanced', 'set_batch', 'has_updates', 'set_from_template', 'create_template', 'list_templates', 'hard_delete', 'add_decision_context', 'list_decision_contexts', 'help', 'example']
-                        },
-                        key: { type: 'string' },
-                        value: { type: ['string', 'number'] },
-                        agent: { type: 'string' },
-                        layer: { type: 'string', enum: ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting'] },
-                        version: { type: 'string' },
-                        status: { type: 'string', enum: ['active', 'deprecated', 'draft'] },
-                        tags: { type: 'array', items: { type: 'string' } },
-                        scopes: { type: 'array', items: { type: 'string' } },
-                        scope: { type: 'string' },
-                        tag_match: { type: 'string', enum: ['AND', 'OR'] },
-                        include_tags: { type: 'boolean' },
-                        layers: { type: 'array', items: { type: 'string' } },
-                        tags_all: { type: 'array', items: { type: 'string' } },
-                        tags_any: { type: 'array', items: { type: 'string' } },
-                        exclude_tags: { type: 'array', items: { type: 'string' } },
-                        updated_after: { type: 'string' },
-                        updated_before: { type: 'string' },
-                        decided_by: { type: 'array', items: { type: 'string' } },
-                        statuses: { type: 'array', items: { type: 'string', enum: ['active', 'deprecated', 'draft'] } },
-                        search_text: { type: 'string' },
-                        sort_by: { type: 'string', enum: ['updated', 'key', 'version'] },
-                        sort_order: { type: 'string', enum: ['asc', 'desc'] },
-                        limit: { type: 'number' },
-                        offset: { type: 'number' },
-                        decisions: { type: 'array' },
-                        atomic: { type: 'boolean' },
-                        agent_name: { type: 'string' },
-                        since_timestamp: { type: 'string' },
-                        template: { type: 'string' },
-                        name: { type: 'string' },
-                        defaults: { type: 'object' },
-                        required_fields: { type: 'array', items: { type: 'string' } },
-                        created_by: { type: 'string' },
-                        rationale: { type: 'string' },
-                        alternatives_considered: { type: ['array', 'string'] },
-                        tradeoffs: { type: ['object', 'string'] },
-                        decision_key: { type: 'string' },
-                        related_task_id: { type: 'number' },
-                        related_constraint_id: { type: 'number' },
-                        include_context: { type: 'boolean' },
+                            enum: ['set', 'get', 'list', 'search_tags', 'search_layer', 'versions', 'quick_set', 'search_advanced', 'set_batch', 'has_updates', 'set_from_template', 'create_template', 'list_templates', 'hard_delete', 'add_decision_context', 'list_decision_contexts', 'help', 'example', 'use_case']
+                        }
                     },
                     required: ['action'],
                 },
@@ -160,26 +112,16 @@ Use action: "example" for comprehensive usage examples.`,
 Agent Messaging - Send messages between agents with priority levels and read tracking
 
 Use action: "help" for detailed documentation.
-Use action: "example" for comprehensive usage examples.`,
+Use action: "example" for comprehensive usage examples.
+Use action: "use_case" for practical scenarios and when-to-use guidance.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', description: 'Action (use "help" for usage)', enum: ['send', 'get', 'mark_read', 'send_batch', 'help', 'example'] },
-                        agent_name: { type: 'string' },
-                        from_agent: { type: 'string' },
-                        to_agent: { type: ['string', 'null'] },
-                        msg_type: { type: 'string', enum: ['decision', 'warning', 'request', 'info'] },
-                        message: { type: 'string' },
-                        priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'], default: 'medium' },
-                        payload: { type: 'object' },
-                        message_ids: { type: 'array', items: { type: 'number' } },
-                        unread_only: { type: 'boolean', default: false },
-                        msg_type_filter: { type: 'string', enum: ['decision', 'warning', 'request', 'info'] },
-                        priority_filter: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
-                        limit: { type: 'number', default: 50 },
-                        // send_batch parameters
-                        messages: { type: 'array', description: 'Array of messages for batch operation (max: 50)' },
-                        atomic: { type: 'boolean', description: 'Atomic mode - all succeed or all fail (default: true)' },
+                        action: {
+                            type: 'string',
+                            description: 'Action',
+                            enum: ['send', 'get', 'mark_read', 'send_batch', 'help', 'example', 'use_case']
+                        }
                     },
                     required: ['action'],
                 },
@@ -191,22 +133,16 @@ Use action: "example" for comprehensive usage examples.`,
 File Change Tracking - Track file changes with layer classification and lock detection
 
 Use action: "help" for detailed documentation.
-Use action: "example" for comprehensive usage examples.`,
+Use action: "example" for comprehensive usage examples.
+Use action: "use_case" for practical scenarios and when-to-use guidance.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', description: 'Action (use "help" for usage)', enum: ['record', 'get', 'check_lock', 'record_batch', 'help', 'example'] },
-                        file_path: { type: 'string' },
-                        agent_name: { type: 'string' },
-                        change_type: { type: 'string', enum: ['created', 'modified', 'deleted'] },
-                        layer: { type: 'string', enum: ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting'] },
-                        description: { type: 'string' },
-                        since: { type: 'string' },
-                        limit: { type: 'number' },
-                        lock_duration: { type: 'number' },
-                        // record_batch parameters
-                        file_changes: { type: 'array', description: 'Array of file changes for batch operation (max: 50)' },
-                        atomic: { type: 'boolean', description: 'Atomic mode - all succeed or all fail (default: true)' },
+                        action: {
+                            type: 'string',
+                            description: 'Action',
+                            enum: ['record', 'get', 'check_lock', 'record_batch', 'help', 'example', 'use_case']
+                        }
                     },
                     required: ['action'],
                 },
@@ -218,20 +154,16 @@ Use action: "example" for comprehensive usage examples.`,
 Constraint Management - Manage architectural rules and requirements
 
 Use action: "help" for detailed documentation.
-Use action: "example" for comprehensive usage examples.`,
+Use action: "example" for comprehensive usage examples.
+Use action: "use_case" for practical scenarios and when-to-use guidance.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', description: 'Action (use "help" for usage)', enum: ['add', 'get', 'deactivate', 'help', 'example'] },
-                        constraint_id: { type: 'number' },
-                        category: { type: 'string', enum: ['performance', 'architecture', 'security'] },
-                        constraint_text: { type: 'string' },
-                        priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'], default: 'medium' },
-                        layer: { type: 'string', enum: ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting'] },
-                        tags: { type: 'array', items: { type: 'string' } },
-                        created_by: { type: 'string' },
-                        active_only: { type: 'boolean', default: true },
-                        limit: { type: 'number', default: 50 },
+                        action: {
+                            type: 'string',
+                            description: 'Action',
+                            enum: ['add', 'get', 'deactivate', 'help', 'example', 'use_case']
+                        }
                     },
                     required: ['action'],
                 },
@@ -243,17 +175,16 @@ Use action: "example" for comprehensive usage examples.`,
 Statistics & Utilities - View stats, activity logs, manage data cleanup, and WAL checkpoints
 
 Use action: "help" for detailed documentation.
-Use action: "example" for comprehensive usage examples.`,
+Use action: "example" for comprehensive usage examples.
+Use action: "use_case" for practical scenarios and when-to-use guidance.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', description: 'Action (use "help" for usage)', enum: ['layer_summary', 'db_stats', 'clear', 'activity_log', 'flush', 'help', 'example'] },
-                        messages_older_than_hours: { type: 'number' },
-                        file_changes_older_than_days: { type: 'number' },
-                        since: { type: 'string', description: 'Time filter (e.g., "5m", "1h", "2d" or ISO timestamp)' },
-                        agent_names: { type: 'array', items: { type: 'string' }, description: 'Filter by agents' },
-                        actions: { type: 'array', items: { type: 'string' }, description: 'Filter by action types' },
-                        limit: { type: 'number', description: 'Max results (default: 100)' },
+                        action: {
+                            type: 'string',
+                            description: 'Action',
+                            enum: ['layer_summary', 'db_stats', 'clear', 'activity_log', 'flush', 'help_action', 'help_params', 'help_tool', 'help_use_case', 'help_list_use_cases', 'help_next_actions', 'help', 'example', 'use_case']
+                        }
                     },
                     required: ['action'],
                 },
@@ -265,14 +196,16 @@ Use action: "example" for comprehensive usage examples.`,
 Configuration - Manage auto-deletion settings with weekend-aware retention
 
 Use action: "help" for detailed documentation.
-Use action: "example" for comprehensive usage examples.`,
+Use action: "example" for comprehensive usage examples.
+Use action: "use_case" for practical scenarios and when-to-use guidance.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', description: 'Action (use "help" for usage)', enum: ['get', 'update', 'help', 'example'] },
-                        ignoreWeekend: { type: 'boolean' },
-                        messageRetentionHours: { type: 'number', minimum: 1, maximum: 168 },
-                        fileHistoryRetentionDays: { type: 'number', minimum: 1, maximum: 90 },
+                        action: {
+                            type: 'string',
+                            description: 'Action',
+                            enum: ['get', 'update', 'help', 'example', 'use_case']
+                        }
                     },
                     required: ['action'],
                 },
@@ -284,40 +217,16 @@ Use action: "example" for comprehensive usage examples.`,
 Kanban Task Watcher - AI-optimized task management with auto-stale detection
 
 Use action: "help" for detailed documentation.
-Use action: "example" for comprehensive usage examples.`,
+Use action: "example" for comprehensive usage examples.
+Use action: "use_case" for practical scenarios and when-to-use guidance.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', description: 'Action (use "help" for usage)', enum: ['create', 'update', 'get', 'list', 'move', 'link', 'archive', 'batch_create', 'add_dependency', 'remove_dependency', 'get_dependencies', 'watch_files', 'watcher', 'help', 'example'] },
-                        task_id: { type: 'number' },
-                        title: { type: 'string' },
-                        description: { type: 'string' },
-                        acceptance_criteria: { type: 'string' },
-                        notes: { type: 'string' },
-                        priority: { type: 'number', minimum: 1, maximum: 4 },
-                        assigned_agent: { type: 'string' },
-                        created_by_agent: { type: 'string' },
-                        layer: { type: 'string', enum: ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting'] },
-                        tags: { type: 'array', items: { type: 'string' } },
-                        status: { type: 'string', enum: ['todo', 'in_progress', 'waiting_review', 'blocked', 'done', 'archived'] },
-                        new_status: { type: 'string', enum: ['todo', 'in_progress', 'waiting_review', 'blocked', 'done', 'archived'] },
-                        link_type: { type: 'string', enum: ['decision', 'constraint', 'file'] },
-                        target_id: { type: ['string', 'number'] },
-                        link_relation: { type: 'string' },
-                        limit: { type: 'number', default: 50 },
-                        offset: { type: 'number', default: 0 },
-                        // watch_files parameters (v3.4.1)
-                        watch_files: { type: 'array', items: { type: 'string' }, description: 'Array of file paths to watch for auto-tracking' },
-                        file_path: { type: 'string', description: 'Single file path (for watch_files action)' },
-                        file_paths: { type: 'array', items: { type: 'string' }, description: 'Array of file paths (for watch_files action)' },
-                        // batch_create parameters
-                        tasks: { type: 'array', description: 'Array of tasks for batch operation (max: 50)' },
-                        atomic: { type: 'boolean', description: 'Atomic mode - all succeed or all fail (default: true)' },
-                        // dependency parameters (v3.2.0)
-                        blocker_task_id: { type: 'number' },
-                        blocked_task_id: { type: 'number' },
-                        include_dependencies: { type: 'boolean' },
-                        include_dependency_counts: { type: 'boolean' },
+                        action: {
+                            type: 'string',
+                            description: 'Action',
+                            enum: ['create', 'update', 'get', 'list', 'move', 'link', 'archive', 'batch_create', 'add_dependency', 'remove_dependency', 'get_dependencies', 'watch_files', 'watcher', 'help', 'example', 'use_case']
+                        }
                     },
                     required: ['action'],
                 },
@@ -329,34 +238,37 @@ Use action: "example" for comprehensive usage examples.`,
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const params = args;
+    const action = params.action || 'N/A';
+    // Debug logging: Tool call
+    debugLogToolCall(name, action, params);
     try {
         let result;
         switch (name) {
             case 'decision':
                 switch (params.action) {
                     case 'set':
-                        result = setDecision(params);
+                        result = await setDecision(params);
                         break;
                     case 'get':
-                        result = getDecision(params);
+                        result = await getDecision(params);
                         break;
                     case 'list':
-                        result = getContext(params);
+                        result = await getContext(params);
                         break;
                     case 'search_tags':
-                        result = searchByTags({ tags: params.tags, match_mode: params.tag_match, status: params.status, layer: params.layer });
+                        result = await searchByTags({ tags: params.tags, match_mode: params.tag_match, status: params.status, layer: params.layer });
                         break;
                     case 'search_layer':
-                        result = searchByLayer({ layer: params.layer, status: params.status, include_tags: params.include_tags });
+                        result = await searchByLayer({ layer: params.layer, status: params.status, include_tags: params.include_tags });
                         break;
                     case 'versions':
-                        result = getVersions(params);
+                        result = await getVersions(params);
                         break;
                     case 'quick_set':
-                        result = quickSetDecision(params);
+                        result = await quickSetDecision(params);
                         break;
                     case 'search_advanced':
-                        result = searchAdvanced({
+                        result = await searchAdvanced({
                             layers: params.layers,
                             tags_all: params.tags_all,
                             tags_any: params.tags_any,
@@ -374,34 +286,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         });
                         break;
                     case 'set_batch':
-                        result = setDecisionBatch({ decisions: params.decisions, atomic: params.atomic });
+                        result = await setDecisionBatch({ decisions: params.decisions, atomic: params.atomic });
                         break;
                     case 'has_updates':
-                        result = hasUpdates({ agent_name: params.agent_name, since_timestamp: params.since_timestamp });
+                        result = await hasUpdates({ agent_name: params.agent_name, since_timestamp: params.since_timestamp });
                         break;
                     case 'set_from_template':
-                        result = setFromTemplate(params);
+                        result = await setFromTemplate(params);
                         break;
                     case 'create_template':
-                        result = createTemplate(params);
+                        result = await createTemplate(params);
                         break;
                     case 'list_templates':
-                        result = listTemplates(params);
+                        result = await listTemplates(params);
                         break;
                     case 'hard_delete':
-                        result = hardDeleteDecision(params);
+                        result = await hardDeleteDecision(params);
                         break;
                     case 'add_decision_context':
-                        result = addDecisionContextAction(params);
+                        result = await addDecisionContextAction(params);
                         break;
                     case 'list_decision_contexts':
-                        result = listDecisionContextsAction(params);
+                        result = await listDecisionContextsAction(params);
                         break;
                     case 'help':
-                        result = decisionHelp();
+                        const helpContent = decisionHelp();
+                        trackAndReturnHelp('decision', 'help', JSON.stringify(helpContent));
+                        result = helpContent;
                         break;
                     case 'example':
-                        result = decisionExample();
+                        const exampleContent = decisionExample();
+                        trackAndReturnHelp('decision', 'example', JSON.stringify(exampleContent));
+                        result = exampleContent;
+                        break;
+                    case 'use_case':
+                        result = await queryHelpListUseCases(getAdapter(), {
+                            category: params.category,
+                            complexity: params.complexity,
+                            limit: params.limit,
+                            offset: params.offset
+                        });
                         break;
                     default: throw new Error(`Unknown action: ${params.action}`);
                 }
@@ -409,22 +333,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'message':
                 switch (params.action) {
                     case 'send':
-                        result = sendMessage(params);
+                        result = await sendMessage(params);
                         break;
                     case 'get':
-                        result = getMessages(params);
+                        result = await getMessages(params);
                         break;
                     case 'mark_read':
-                        result = markRead(params);
+                        result = await markRead(params);
                         break;
                     case 'send_batch':
-                        result = sendMessageBatch({ messages: params.messages, atomic: params.atomic });
+                        result = await sendMessageBatch({ messages: params.messages, atomic: params.atomic });
                         break;
                     case 'help':
-                        result = messageHelp();
+                        const msgHelpContent = messageHelp();
+                        trackAndReturnHelp('message', 'help', JSON.stringify(msgHelpContent));
+                        result = msgHelpContent;
                         break;
                     case 'example':
-                        result = messageExample();
+                        const msgExampleContent = messageExample();
+                        trackAndReturnHelp('message', 'example', JSON.stringify(msgExampleContent));
+                        result = msgExampleContent;
+                        break;
+                    case 'use_case':
+                        result = await queryHelpListUseCases(getAdapter(), {
+                            category: params.category,
+                            complexity: params.complexity,
+                            limit: params.limit,
+                            offset: params.offset
+                        });
                         break;
                     default: throw new Error(`Unknown action: ${params.action}`);
                 }
@@ -432,22 +368,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'file':
                 switch (params.action) {
                     case 'record':
-                        result = recordFileChange(params);
+                        result = await recordFileChange(params);
                         break;
                     case 'get':
-                        result = getFileChanges(params);
+                        result = await getFileChanges(params);
                         break;
                     case 'check_lock':
-                        result = checkFileLock(params);
+                        result = await checkFileLock(params);
                         break;
                     case 'record_batch':
-                        result = recordFileChangeBatch({ file_changes: params.file_changes, atomic: params.atomic });
+                        result = await recordFileChangeBatch({ file_changes: params.file_changes, atomic: params.atomic });
                         break;
                     case 'help':
-                        result = fileHelp();
+                        const fileHelpContent = fileHelp();
+                        trackAndReturnHelp('file', 'help', JSON.stringify(fileHelpContent));
+                        result = fileHelpContent;
                         break;
                     case 'example':
-                        result = fileExample();
+                        const fileExampleContent = fileExample();
+                        trackAndReturnHelp('file', 'example', JSON.stringify(fileExampleContent));
+                        result = fileExampleContent;
+                        break;
+                    case 'use_case':
+                        result = await queryHelpListUseCases(getAdapter(), {
+                            category: params.category,
+                            complexity: params.complexity,
+                            limit: params.limit,
+                            offset: params.offset
+                        });
                         break;
                     default: throw new Error(`Unknown action: ${params.action}`);
                 }
@@ -455,19 +403,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'constraint':
                 switch (params.action) {
                     case 'add':
-                        result = addConstraint(params);
+                        result = await addConstraint(params);
                         break;
                     case 'get':
-                        result = getConstraints(params);
+                        result = await getConstraints(params);
                         break;
                     case 'deactivate':
-                        result = deactivateConstraint(params);
+                        result = await deactivateConstraint(params);
                         break;
                     case 'help':
-                        result = constraintHelp();
+                        const constraintHelpContent = constraintHelp();
+                        trackAndReturnHelp('constraint', 'help', JSON.stringify(constraintHelpContent));
+                        result = constraintHelpContent;
                         break;
                     case 'example':
-                        result = constraintExample();
+                        const constraintExampleContent = constraintExample();
+                        trackAndReturnHelp('constraint', 'example', JSON.stringify(constraintExampleContent));
+                        result = constraintExampleContent;
+                        break;
+                    case 'use_case':
+                        result = await queryHelpListUseCases(getAdapter(), {
+                            category: params.category,
+                            complexity: params.complexity,
+                            limit: params.limit,
+                            offset: params.offset
+                        });
                         break;
                     default: throw new Error(`Unknown action: ${params.action}`);
                 }
@@ -475,16 +435,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'stats':
                 switch (params.action) {
                     case 'layer_summary':
-                        result = getLayerSummary();
+                        result = await getLayerSummary();
                         break;
                     case 'db_stats':
-                        result = getStats();
+                        result = await getStats();
                         break;
                     case 'clear':
-                        result = clearOldData(params);
+                        result = await clearOldData(params);
                         break;
                     case 'activity_log':
-                        result = getActivityLog({
+                        result = await getActivityLog({
                             since: params.since,
                             agent_names: params.agent_names,
                             actions: params.actions,
@@ -492,13 +452,73 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         });
                         break;
                     case 'flush':
-                        result = flushWAL();
+                        result = await flushWAL();
+                        break;
+                    case 'help_action':
+                        if (!params.target_tool || !params.target_action) {
+                            result = { error: 'Parameters "target_tool" and "target_action" are required' };
+                        }
+                        else {
+                            result = await queryHelpAction(getAdapter(), params.target_tool, params.target_action);
+                        }
+                        break;
+                    case 'help_params':
+                        if (!params.target_tool || !params.target_action) {
+                            result = { error: 'Parameters "target_tool" and "target_action" are required' };
+                        }
+                        else {
+                            result = await queryHelpParams(getAdapter(), params.target_tool, params.target_action);
+                        }
+                        break;
+                    case 'help_tool':
+                        if (!params.tool) {
+                            result = { error: 'Parameter "tool" is required' };
+                        }
+                        else {
+                            result = await queryHelpTool(getAdapter(), params.tool);
+                        }
+                        break;
+                    case 'help_use_case':
+                        if (!params.use_case_id) {
+                            result = { error: 'Parameter "use_case_id" is required' };
+                        }
+                        else {
+                            result = await queryHelpUseCase(getAdapter(), params.use_case_id);
+                        }
+                        break;
+                    case 'help_list_use_cases':
+                        result = await queryHelpListUseCases(getAdapter(), {
+                            category: params.category,
+                            complexity: params.complexity,
+                            limit: params.limit,
+                            offset: params.offset
+                        });
+                        break;
+                    case 'help_next_actions':
+                        if (!params.target_tool || !params.target_action) {
+                            result = { error: 'Parameters "target_tool" and "target_action" are required' };
+                        }
+                        else {
+                            result = await queryHelpNextActions(getAdapter(), params.target_tool, params.target_action);
+                        }
                         break;
                     case 'help':
-                        result = statsHelp();
+                        const statsHelpContent = statsHelp();
+                        trackAndReturnHelp('stats', 'help', JSON.stringify(statsHelpContent));
+                        result = statsHelpContent;
                         break;
                     case 'example':
-                        result = statsExample();
+                        const statsExampleContent = statsExample();
+                        trackAndReturnHelp('stats', 'example', JSON.stringify(statsExampleContent));
+                        result = statsExampleContent;
+                        break;
+                    case 'use_case':
+                        result = await queryHelpListUseCases(getAdapter(), {
+                            category: params.category,
+                            complexity: params.complexity,
+                            limit: params.limit,
+                            offset: params.offset
+                        });
                         break;
                     default: throw new Error(`Unknown action: ${params.action}`);
                 }
@@ -506,16 +526,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'config':
                 switch (params.action) {
                     case 'get':
-                        result = getConfig();
+                        result = await getConfig();
                         break;
                     case 'update':
-                        result = updateConfig(params);
+                        result = await updateConfig(params);
                         break;
                     case 'help':
-                        result = configHelp();
+                        const configHelpContent = configHelp();
+                        trackAndReturnHelp('config', 'help', JSON.stringify(configHelpContent));
+                        result = configHelpContent;
                         break;
                     case 'example':
-                        result = configExample();
+                        const configExampleContent = configExample();
+                        trackAndReturnHelp('config', 'example', JSON.stringify(configExampleContent));
+                        result = configExampleContent;
+                        break;
+                    case 'use_case':
+                        result = await queryHelpListUseCases(getAdapter(), {
+                            category: params.category,
+                            complexity: params.complexity,
+                            limit: params.limit,
+                            offset: params.offset
+                        });
                         break;
                     default: throw new Error(`Unknown action: ${params.action}`);
                 }
@@ -523,55 +555,67 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'task':
                 switch (params.action) {
                     case 'create':
-                        result = createTask(params);
+                        result = await createTask(params);
                         break;
                     case 'update':
-                        result = updateTask(params);
+                        result = await updateTask(params);
                         break;
                     case 'get':
-                        result = getTask(params);
+                        result = await getTask(params);
                         break;
                     case 'list':
                         result = await listTasks(params);
                         break;
                     case 'move':
-                        result = moveTask(params);
+                        result = await moveTask(params);
                         break;
                     case 'link':
-                        result = linkTask(params);
+                        result = await linkTask(params);
                         break;
                     case 'archive':
-                        result = archiveTask(params);
+                        result = await archiveTask(params);
                         break;
                     case 'batch_create':
-                        result = batchCreateTasks({ tasks: params.tasks, atomic: params.atomic });
+                        result = await batchCreateTasks({ tasks: params.tasks, atomic: params.atomic });
                         break;
                     case 'add_dependency':
-                        result = addDependency(params);
+                        result = await addDependency(params);
                         break;
                     case 'remove_dependency':
-                        result = removeDependency(params);
+                        result = await removeDependency(params);
                         break;
                     case 'get_dependencies':
-                        result = getDependencies(params);
+                        result = await getDependencies(params);
                         break;
                     case 'watch_files':
-                        result = watchFiles(params);
+                        result = await watchFiles(params);
                         break;
                     case 'get_pruned_files':
-                        result = getPrunedFiles(params);
+                        result = await getPrunedFiles(params);
                         break;
                     case 'link_pruned_file':
-                        result = linkPrunedFile(params);
+                        result = await linkPrunedFile(params);
                         break;
                     case 'watcher':
-                        result = watcherStatus(params);
+                        result = await watcherStatus(params);
                         break;
                     case 'help':
-                        result = taskHelp();
+                        const taskHelpContent = taskHelp();
+                        trackAndReturnHelp('task', 'help', JSON.stringify(taskHelpContent));
+                        result = taskHelpContent;
                         break;
                     case 'example':
-                        result = taskExample();
+                        const taskExampleContent = taskExample();
+                        trackAndReturnHelp('task', 'example', JSON.stringify(taskExampleContent));
+                        result = taskExampleContent;
+                        break;
+                    case 'use_case':
+                        result = await queryHelpListUseCases(getAdapter(), {
+                            category: params.category,
+                            complexity: params.complexity,
+                            limit: params.limit,
+                            offset: params.offset
+                        });
                         break;
                     default: throw new Error(`Unknown action: ${params.action}`);
                 }
@@ -579,61 +623,101 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
+        // Debug logging: Success
+        debugLogToolResponse(name, action, true, result);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        // Use centralized error handler
+        const { message, stack } = handleToolError(name, action, error, params);
+        debugLogToolResponse(name, action, false, undefined, { message, stack });
         return {
-            content: [{ type: 'text', text: JSON.stringify({ error: message }, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify({ error: message, stack: stack }, null, 2) }],
             isError: true,
         };
     }
 });
-// Handle graceful shutdown
-process.on('SIGINT', async () => {
-    console.error('\n✓ Shutting down MCP server...');
-    try {
-        const watcher = FileWatcher.getInstance();
-        await watcher.stop();
-    }
-    catch (error) {
-        // Ignore watcher errors during shutdown
-    }
-    closeDatabase();
-    process.exit(0);
-});
-process.on('SIGTERM', async () => {
-    console.error('\n✓ Shutting down MCP server...');
+// Setup centralized global error handlers
+setupGlobalErrorHandlers(() => {
+    debugLog('INFO', 'Shutting down gracefully');
     try {
         const watcher = FileWatcher.getInstance();
-        await watcher.stop();
+        watcher.stop();
     }
     catch (error) {
         // Ignore watcher errors during shutdown
     }
     closeDatabase();
-    process.exit(0);
+    closeDebugLogger();
 });
 // Start server with stdio transport
 async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error('✓ MCP Shared Context Server running on stdio');
-    // Start file watcher for auto-task-tracking
     try {
-        const watcher = FileWatcher.getInstance();
-        await watcher.start();
+        // 0. Ensure .sqlew directory and config template exist (first launch)
+        ensureSqlewDirectory();
+        // 1. Initialize database
+        const config = dbPath ? { connection: { filename: dbPath } } : undefined;
+        db = await initializeDatabase(config);
+        // Apply CLI config overrides if provided
+        if (parsedArgs.autodeleteIgnoreWeekend !== undefined) {
+            await setConfigValue(db, CONFIG_KEYS.AUTODELETE_IGNORE_WEEKEND, parsedArgs.autodeleteIgnoreWeekend ? '1' : '0');
+        }
+        if (parsedArgs.autodeleteMessageHours !== undefined) {
+            await setConfigValue(db, CONFIG_KEYS.AUTODELETE_MESSAGE_HOURS, String(parsedArgs.autodeleteMessageHours));
+        }
+        if (parsedArgs.autodeleteFileHistoryDays !== undefined) {
+            await setConfigValue(db, CONFIG_KEYS.AUTODELETE_FILE_HISTORY_DAYS, String(parsedArgs.autodeleteFileHistoryDays));
+        }
+        // Display current config
+        const configValues = await getAllConfig(db);
+        const ignoreWeekend = configValues[CONFIG_KEYS.AUTODELETE_IGNORE_WEEKEND] === '1';
+        const messageHours = configValues[CONFIG_KEYS.AUTODELETE_MESSAGE_HOURS];
+        const fileHistoryDays = configValues[CONFIG_KEYS.AUTODELETE_FILE_HISTORY_DAYS];
+        console.error('✓ MCP Shared Context Server initialized');
+        if (dbPath) {
+            const source = parsedArgs.dbPath ? 'CLI' : 'config file';
+            console.error(`  Database: ${dbPath} (from ${source})`);
+        }
+        console.error(`  Auto-delete config: messages=${messageHours}h, file_history=${fileHistoryDays}d, ignore_weekend=${ignoreWeekend}`);
+        // Initialize debug logger (priority: CLI arg > environment variable > config file)
+        const debugLogPath = parsedArgs.debugLogPath || process.env.SQLEW_DEBUG || fileConfig.debug?.log_path;
+        const debugLogLevel = fileConfig.debug?.log_level || 'info';
+        initDebugLogger(debugLogPath, debugLogLevel);
+        debugLog('INFO', 'MCP Shared Context Server initialized', {
+            dbPath,
+            autoDeleteConfig: { messageHours, fileHistoryDays, ignoreWeekend },
+            debugLogLevel: debugLogLevel
+        });
+        // 2. Connect MCP server
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error('✓ MCP Shared Context Server running on stdio');
+        // 3. Start file watcher for auto-task-tracking (after database is ready)
+        try {
+            const watcher = FileWatcher.getInstance();
+            await watcher.start();
+        }
+        catch (error) {
+            console.error('⚠ Failed to start file watcher:', error);
+            console.error('  (Auto task tracking will be disabled)');
+        }
     }
     catch (error) {
-        console.error('⚠ Failed to start file watcher:', error);
-        console.error('  (Auto task tracking will be disabled)');
+        // Use centralized initialization error handler
+        handleInitializationError(error);
+        closeDatabase();
+        closeDebugLogger();
+        process.exit(1);
     }
 }
 main().catch((error) => {
-    console.error('✗ Fatal error:', error);
+    // Use centralized initialization error handler
+    console.error('\n❌ FATAL ERROR:');
+    handleInitializationError(error);
     closeDatabase();
+    closeDebugLogger();
     process.exit(1);
 });
 //# sourceMappingURL=index.js.map