mcp-adr-analysis-server 2.1.9 → 2.1.19

package/dist/src/index.js

@@ -17,6 +17,12 @@ import { CONVERSATION_CONTEXT_SCHEMA } from './types/conversation-context.js';
 import { maskMcpResponse, createMaskingConfig, } from './utils/output-masking.js';
 import { loadConfig, validateProjectPath, createLogger, printConfigSummary, } from './utils/config.js';
 import { KnowledgeGraphManager } from './utils/knowledge-graph-manager.js';
+import { StateReinforcementManager } from './utils/state-reinforcement-manager.js';
+import { ConversationMemoryManager } from './utils/conversation-memory-manager.js';
+import { MemoryEntityManager } from './utils/memory-entity-manager.js';
+import { RootManager } from './utils/root-manager.js';
+import { ServerContextGenerator } from './utils/server-context-generator.js';
+import { createNoOpContext } from './types/tool-context.js';
 /**
  * Get version from package.json
  */
@@ -72,11 +78,23 @@ export class McpAdrAnalysisServer {
     config;
     logger;
     kgManager;
+    stateReinforcementManager;
+    conversationMemoryManager;
+    memoryEntityManager;
+    rootManager;
+    contextGenerator;
     constructor() {
         // Load and validate configuration
         this.config = loadConfig();
         this.logger = createLogger(this.config);
         this.kgManager = new KnowledgeGraphManager();
+        this.stateReinforcementManager = new StateReinforcementManager(this.kgManager);
+        this.conversationMemoryManager = new ConversationMemoryManager(this.kgManager);
+        this.memoryEntityManager = new MemoryEntityManager();
+        // Initialize root manager for file access control
+        this.rootManager = new RootManager(this.config.projectPath, this.config.adrDirectory);
+        // Initialize server context generator
+        this.contextGenerator = new ServerContextGenerator();
         // Print configuration summary
         printConfigSummary(this.config);
         // Note: Validation will be done during startup
@@ -113,9 +131,38 @@ export class McpAdrAnalysisServer {
     }
     /**
      * Setup MCP protocol handlers
+     *
+     * @description Configures all Model Context Protocol request handlers for the ADR Analysis Server.
+     * Implements the complete MCP specification including tools, resources, and prompts.
+     *
+     * @private
+     * @since 2.0.0
+     * @category MCP Protocol
      */
     setupHandlers() {
-        // Tools handler
+        /**
+         * List Tools Handler - MCP Protocol Endpoint
+         *
+         * @description Returns the complete catalog of available tools for ADR analysis,
+         * research, validation, and deployment operations. Each tool includes comprehensive
+         * input schemas and descriptions for client integration.
+         *
+         * @returns {Promise<{tools: Array}>} Complete tool catalog with schemas
+         *
+         * @example
+         * ```typescript
+         * // MCP Client usage
+         * const tools = await mcpClient.listTools();
+         * console.log(tools.tools.length); // 20+ available tools
+         *
+         * // Find specific tool
+         * const researchTool = tools.tools.find(t => t.name === 'perform_research');
+         * console.log(researchTool.description); // Tool description
+         * ```
+         *
+         * @mcp-endpoint
+         * @category Tools
+         */
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
             return {
                 tools: [
@@ -247,72 +294,6 @@ export class McpAdrAnalysisServer {
                             required: ['prdPath'],
                         },
                     },
-                    {
-                        name: 'generate_adr_todo',
-                        description: 'Generate TDD-focused todo.md from existing ADRs with JSON-first approach: creates structured JSON TODO and syncs to markdown',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                adrDirectory: {
-                                    type: 'string',
-                                    description: 'Directory containing ADR files (optional, uses configured ADR_DIRECTORY if not provided)',
-                                },
-                                scope: {
-                                    type: 'string',
-                                    enum: ['all', 'pending', 'in_progress'],
-                                    description: 'Scope of tasks to include',
-                                    default: 'all',
-                                },
-                                phase: {
-                                    type: 'string',
-                                    enum: ['both', 'test', 'production'],
-                                    description: 'TDD phase: both (default), test (mock test generation), production (implementation after tests)',
-                                    default: 'both',
-                                },
-                                linkAdrs: {
-                                    type: 'boolean',
-                                    description: 'Auto-detect and link ADR dependencies in task creation',
-                                    default: true,
-                                },
-                                includeRules: {
-                                    type: 'boolean',
-                                    description: 'Include architectural rules validation in TDD tasks',
-                                    default: true,
-                                },
-                                ruleSource: {
-                                    type: 'string',
-                                    enum: ['adrs', 'patterns', 'both'],
-                                    description: 'Source for architectural rules (only used if includeRules is true)',
-                                    default: 'both',
-                                },
-                                todoPath: {
-                                    type: 'string',
-                                    description: 'Path to TODO.md file (relative to project root)',
-                                    default: 'TODO.md',
-                                },
-                                preserveExisting: {
-                                    type: 'boolean',
-                                    description: 'Preserve existing TODO.md content by merging instead of overwriting',
-                                    default: true,
-                                },
-                                forceSyncToMarkdown: {
-                                    type: 'boolean',
-                                    description: 'Force sync JSON to markdown even if markdown is newer',
-                                    default: false,
-                                },
-                                intentId: {
-                                    type: 'string',
-                                    description: 'Link generated tasks to specific knowledge graph intent',
-                                },
-                                createJsonBackup: {
-                                    type: 'boolean',
-                                    description: 'Create backup of existing JSON TODO data before import',
-                                    default: true,
-                                },
-                                conversationContext: CONVERSATION_CONTEXT_SCHEMA,
-                            },
-                        },
-                    },
                     {
                         name: 'compare_adr_progress',
                         description: 'Compare TODO.md progress against ADRs and current environment to validate implementation status',
@@ -585,7 +566,7 @@ export class McpAdrAnalysisServer {
                     },
                     {
                         name: 'suggest_adrs',
-                        description: 'Suggest architectural decisions with advanced prompting techniques (Knowledge Generation + Reflexion)',
+                        description: 'Suggest architectural decisions with advanced prompting techniques (Knowledge Generation + Reflexion). TIP: Read @.mcp-server-context.md first for project history, patterns, and previous ADRs to ensure consistency.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -643,7 +624,7 @@ export class McpAdrAnalysisServer {
                     },
                     {
                         name: 'generate_adr_from_decision',
-                        description: 'Generate a complete ADR from decision data',
+                        description: 'Generate a complete ADR from decision data. TIP: Reference @.mcp-server-context.md to align with existing architectural patterns and decisions.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -689,7 +670,7 @@ export class McpAdrAnalysisServer {
                     },
                     {
                         name: 'generate_adr_bootstrap',
-                        description: 'Generate bootstrap.sh and validate_bootstrap.sh scripts to ensure deployed code follows ADR requirements',
+                        description: "Generate bootstrap.sh and validate_bootstrap.sh scripts to ensure deployed code follows ADR requirements. **CRITICAL**: Before generating scripts, use WebFetch to query the base code repository (e.g., https://github.com/validatedpatterns/common for OpenShift) and authoritative pattern documentation (e.g., https://play.validatedpatterns.io/). Merge the base repository code into your project and have bootstrap.sh call the pattern's scripts rather than generating everything from scratch. This ensures compliance with validated deployment patterns.",
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -733,6 +714,67 @@ export class McpAdrAnalysisServer {
                             },
                         },
                     },
+                    {
+                        name: 'bootstrap_validation_loop',
+                        description: '**GUIDED EXECUTION MODE**: This tool guides you through an interactive, step-by-step deployment validation workflow. It does NOT execute commands internally - instead, it tells YOU what commands to run and processes the results iteratively. **Workflow**: (1) First call with iteration=0: Detects platform (OpenShift/K8s/Docker), validates environment connection, and requests human approval for target platform. (2) Subsequent calls: After running each command and reporting back with output, the tool provides next steps. **Environment Validation**: Before deployment, the tool verifies connection to the target platform (e.g., `oc status` for OpenShift, `kubectl cluster-info` for K8s) and requires explicit human confirmation. **Validated Patterns Integration**: Automatically identifies base code repositories (e.g., validatedpatterns/common for OpenShift) and guides you to merge them into your project. **Deployment Cleanup**: Supports CI/CD-style workflows with deployment teardown/restart guidance. **Call this tool iteratively**, passing previous command output back each time.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to the project directory',
+                                    default: '.',
+                                },
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory where ADRs are stored',
+                                    default: 'docs/adrs',
+                                },
+                                targetEnvironment: {
+                                    type: 'string',
+                                    enum: ['development', 'staging', 'production', 'testing'],
+                                    description: 'Target deployment environment',
+                                    default: 'development',
+                                },
+                                maxIterations: {
+                                    type: 'number',
+                                    description: 'Maximum validation/fix iterations',
+                                    default: 5,
+                                },
+                                autoFix: {
+                                    type: 'boolean',
+                                    description: 'Whether to generate auto-fix suggestions in guidance',
+                                    default: true,
+                                },
+                                updateAdrsWithLearnings: {
+                                    type: 'boolean',
+                                    description: 'Update ADRs with deployment learnings (non-sensitive)',
+                                    default: true,
+                                },
+                                currentIteration: {
+                                    type: 'number',
+                                    description: 'Current iteration number (0 for initial call, then increment). Used to track workflow progress.',
+                                    default: 0,
+                                },
+                                previousExecutionOutput: {
+                                    type: 'string',
+                                    description: 'Output from the previous command execution. Paste the stdout/stderr from running the command that was recommended in the previous iteration.',
+                                    default: '',
+                                },
+                                previousExecutionSuccess: {
+                                    type: 'boolean',
+                                    description: 'Whether the previous command execution succeeded (exit code 0). Set to true if command succeeded, false if it failed.',
+                                    default: false,
+                                },
+                                deploymentCleanupRequested: {
+                                    type: 'boolean',
+                                    description: 'Set to true to request deployment cleanup/teardown guidance (for CI/CD workflows that need to delete and restart deployments).',
+                                    default: false,
+                                },
+                                conversationContext: CONVERSATION_CONTEXT_SCHEMA,
+                            },
+                        },
+                    },
                     {
                         name: 'discover_existing_adrs',
                         description: 'Discover and catalog existing ADRs in the project',
@@ -752,9 +794,53 @@ export class McpAdrAnalysisServer {
                             },
                         },
                     },
+                    {
+                        name: 'analyze_adr_timeline',
+                        description: 'Analyze ADR timeline with smart time tracking, adaptive thresholds, and actionable recommendations. Auto-detects project context (startup/growth/mature) and generates prioritized work queue based on staleness, implementation lag, and technical debt.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to the project directory',
+                                    default: '.',
+                                },
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory containing ADR files',
+                                    default: 'docs/adrs',
+                                },
+                                generateActions: {
+                                    type: 'boolean',
+                                    description: 'Generate actionable work items with priority and effort estimates',
+                                    default: true,
+                                },
+                                thresholdProfile: {
+                                    type: 'string',
+                                    enum: ['startup', 'growth', 'mature', 'maintenance', 'feature_development'],
+                                    description: 'Threshold profile for action generation (auto-detected if not specified)',
+                                },
+                                autoDetectContext: {
+                                    type: 'boolean',
+                                    description: 'Auto-detect project phase from git activity and ADR patterns',
+                                    default: true,
+                                },
+                                includeContent: {
+                                    type: 'boolean',
+                                    description: 'Include ADR content for better analysis',
+                                    default: true,
+                                },
+                                forceExtract: {
+                                    type: 'boolean',
+                                    description: 'Force timeline extraction even if ADRs have dates',
+                                    default: false,
+                                },
+                            },
+                        },
+                    },
                     {
                         name: 'review_existing_adrs',
-                        description: 'Review existing ADRs against actual code implementation with cloud/DevOps expertise',
+                        description: 'Review existing ADRs against actual code implementation with cloud/DevOps expertise. TIP: After review, call get_server_context to update @.mcp-server-context.md with findings.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -792,6 +878,69 @@ export class McpAdrAnalysisServer {
                             },
                         },
                     },
+                    {
+                        name: 'validate_adr',
+                        description: 'Validate an existing ADR against actual infrastructure reality using research-driven analysis. TIP: Compare findings against patterns in @.mcp-server-context.md for consistency checks.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                adrPath: {
+                                    type: 'string',
+                                    description: 'Path to the ADR file to validate (relative or absolute)',
+                                },
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to the project directory',
+                                    default: '.',
+                                },
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory containing ADR files',
+                                    default: 'docs/adrs',
+                                },
+                                includeEnvironmentCheck: {
+                                    type: 'boolean',
+                                    description: 'Include live environment verification in validation',
+                                    default: true,
+                                },
+                                confidenceThreshold: {
+                                    type: 'number',
+                                    description: 'Minimum research confidence threshold (0-1)',
+                                    default: 0.6,
+                                },
+                            },
+                            required: ['adrPath'],
+                        },
+                    },
+                    {
+                        name: 'validate_all_adrs',
+                        description: 'Validate all ADRs in a directory against actual infrastructure reality',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to the project directory',
+                                    default: '.',
+                                },
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory containing ADR files',
+                                    default: 'docs/adrs',
+                                },
+                                includeEnvironmentCheck: {
+                                    type: 'boolean',
+                                    description: 'Include live environment verification in validation',
+                                    default: true,
+                                },
+                                minConfidence: {
+                                    type: 'number',
+                                    description: 'Minimum research confidence for validation (0-1)',
+                                    default: 0.6,
+                                },
+                            },
+                        },
+                    },
                     {
                         name: 'incorporate_research',
                         description: 'Incorporate research findings into architectural decisions',
@@ -1204,95 +1353,255 @@ export class McpAdrAnalysisServer {
                         },
                     },
                     {
-                        name: 'analyze_deployment_progress',
-                        description: 'Analyze deployment progress and verify completion with outcome rules',
+                        name: 'perform_research',
+                        description: 'Perform research using cascading sources: project files → knowledge graph → environment resources → web search (fallback)',
                         inputSchema: {
                             type: 'object',
                             properties: {
-                                analysisType: {
+                                question: {
                                     type: 'string',
-                                    enum: ['tasks', 'cicd', 'progress', 'completion', 'comprehensive'],
-                                    description: 'Type of deployment analysis to perform',
-                                    default: 'comprehensive',
+                                    description: 'The research question to answer',
+                                },
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to project directory',
+                                    default: '.',
                                 },
                                 adrDirectory: {
                                     type: 'string',
                                     description: 'Directory containing ADR files',
                                     default: 'docs/adrs',
                                 },
-                                todoPath: {
-                                    type: 'string',
-                                    description: 'Path to TODO.md file for task identification',
-                                    default: 'TODO.md',
+                                confidenceThreshold: {
+                                    type: 'number',
+                                    description: 'Minimum confidence threshold (0-1) before suggesting web search',
+                                    default: 0.6,
+                                    minimum: 0,
+                                    maximum: 1,
                                 },
-                                cicdLogs: {
-                                    type: 'string',
-                                    description: 'CI/CD pipeline logs for analysis',
+                                performWebSearch: {
+                                    type: 'boolean',
+                                    description: 'Enable web search recommendations when confidence is low',
+                                    default: true,
                                 },
-                                pipelineConfig: {
+                            },
+                            required: ['question'],
+                        },
+                    },
+                    {
+                        name: 'llm_web_search',
+                        description: 'LLM-managed web search using Firecrawl for cross-platform support',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                query: {
                                     type: 'string',
-                                    description: 'CI/CD pipeline configuration',
+                                    description: 'The search query to execute',
                                 },
-                                deploymentTasks: {
-                                    type: 'array',
-                                    items: {
-                                        type: 'object',
-                                        properties: {
-                                            taskId: { type: 'string' },
-                                            taskName: { type: 'string' },
-                                            status: { type: 'string' },
-                                            progress: { type: 'number' },
-                                            category: { type: 'string' },
-                                            priority: { type: 'string' },
-                                            verificationCriteria: { type: 'array', items: { type: 'string' } },
-                                            expectedOutcome: { type: 'string' },
-                                        },
-                                    },
-                                    description: 'Deployment tasks for progress calculation',
+                                maxResults: {
+                                    type: 'number',
+                                    description: 'Maximum results to return',
+                                    default: 5,
+                                    minimum: 1,
+                                    maximum: 20,
                                 },
-                                outcomeRules: {
-                                    type: 'array',
-                                    items: {
-                                        type: 'object',
-                                        properties: {
-                                            ruleId: { type: 'string' },
-                                            description: { type: 'string' },
-                                            criteria: { type: 'array', items: { type: 'string' } },
-                                            verificationMethod: { type: 'string' },
-                                        },
-                                    },
-                                    description: 'Outcome rules for completion verification',
+                                includeContent: {
+                                    type: 'boolean',
+                                    description: 'Include full content in results',
+                                    default: true,
                                 },
-                                actualOutcomes: {
-                                    type: 'array',
-                                    items: {
-                                        type: 'object',
-                                        properties: {
-                                            taskId: { type: 'string' },
-                                            outcome: { type: 'string' },
-                                            evidence: { type: 'array', items: { type: 'string' } },
-                                            timestamp: { type: 'string' },
-                                        },
-                                    },
-                                    description: 'Actual deployment outcomes',
+                                llmInstructions: {
+                                    type: 'string',
+                                    description: 'LLM instructions for search optimization',
                                 },
-                                cicdStatus: {
-                                    type: 'object',
-                                    description: 'CI/CD pipeline status data',
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to project directory',
+                                    default: '.',
                                 },
-                                environmentStatus: {
-                                    type: 'object',
-                                    description: 'Environment status data',
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory containing ADR files',
+                                    default: 'docs/adrs',
                                 },
                             },
+                            required: ['query'],
                         },
                     },
                     {
-                        name: 'check_ai_execution_status',
-                        description: 'Check AI execution configuration and status for debugging prompt-only mode issues',
+                        name: 'llm_cloud_management',
+                        description: 'LLM-managed cloud provider operations with research-driven approach',
                         inputSchema: {
                             type: 'object',
-                            properties: {},
+                            properties: {
+                                provider: {
+                                    type: 'string',
+                                    enum: ['aws', 'azure', 'gcp', 'redhat', 'ubuntu', 'macos'],
+                                    description: 'Cloud provider to use',
+                                },
+                                action: {
+                                    type: 'string',
+                                    description: 'Action to perform',
+                                },
+                                parameters: {
+                                    type: 'object',
+                                    description: 'Action parameters',
+                                },
+                                llmInstructions: {
+                                    type: 'string',
+                                    description: 'LLM instructions for command generation',
+                                },
+                                researchFirst: {
+                                    type: 'boolean',
+                                    description: 'Research best approach first',
+                                    default: true,
+                                },
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to project directory',
+                                    default: '.',
+                                },
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory containing ADR files',
+                                    default: 'docs/adrs',
+                                },
+                            },
+                            required: ['provider', 'action', 'llmInstructions'],
+                        },
+                    },
+                    {
+                        name: 'llm_database_management',
+                        description: 'LLM-managed database operations with research-driven approach',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                database: {
+                                    type: 'string',
+                                    enum: ['postgresql', 'mongodb', 'redis', 'mysql', 'mariadb'],
+                                    description: 'Database type to use',
+                                },
+                                action: {
+                                    type: 'string',
+                                    description: 'Database action to perform',
+                                },
+                                parameters: {
+                                    type: 'object',
+                                    description: 'Action parameters',
+                                },
+                                llmInstructions: {
+                                    type: 'string',
+                                    description: 'LLM instructions for command generation',
+                                },
+                                researchFirst: {
+                                    type: 'boolean',
+                                    description: 'Research best approach first',
+                                    default: true,
+                                },
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to project directory',
+                                    default: '.',
+                                },
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory containing ADR files',
+                                    default: 'docs/adrs',
+                                },
+                            },
+                            required: ['database', 'action', 'llmInstructions'],
+                        },
+                    },
+                    {
+                        name: 'analyze_deployment_progress',
+                        description: 'Analyze deployment progress and verify completion with outcome rules',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                analysisType: {
+                                    type: 'string',
+                                    enum: ['tasks', 'cicd', 'progress', 'completion', 'comprehensive'],
+                                    description: 'Type of deployment analysis to perform',
+                                    default: 'comprehensive',
+                                },
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory containing ADR files',
+                                    default: 'docs/adrs',
+                                },
+                                todoPath: {
+                                    type: 'string',
+                                    description: 'Path to TODO.md file for task identification',
+                                    default: 'TODO.md',
+                                },
+                                cicdLogs: {
+                                    type: 'string',
+                                    description: 'CI/CD pipeline logs for analysis',
+                                },
+                                pipelineConfig: {
+                                    type: 'string',
+                                    description: 'CI/CD pipeline configuration',
+                                },
+                                deploymentTasks: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            taskId: { type: 'string' },
+                                            taskName: { type: 'string' },
+                                            status: { type: 'string' },
+                                            progress: { type: 'number' },
+                                            category: { type: 'string' },
+                                            priority: { type: 'string' },
+                                            verificationCriteria: { type: 'array', items: { type: 'string' } },
+                                            expectedOutcome: { type: 'string' },
+                                        },
+                                    },
+                                    description: 'Deployment tasks for progress calculation',
+                                },
+                                outcomeRules: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            ruleId: { type: 'string' },
+                                            description: { type: 'string' },
+                                            criteria: { type: 'array', items: { type: 'string' } },
+                                            verificationMethod: { type: 'string' },
+                                        },
+                                    },
+                                    description: 'Outcome rules for completion verification',
+                                },
+                                actualOutcomes: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            taskId: { type: 'string' },
+                                            outcome: { type: 'string' },
+                                            evidence: { type: 'array', items: { type: 'string' } },
+                                            timestamp: { type: 'string' },
+                                        },
+                                    },
+                                    description: 'Actual deployment outcomes',
+                                },
+                                cicdStatus: {
+                                    type: 'object',
+                                    description: 'CI/CD pipeline status data',
+                                },
+                                environmentStatus: {
+                                    type: 'object',
+                                    description: 'Environment status data',
+                                },
+                            },
+                        },
+                    },
+                    {
+                        name: 'check_ai_execution_status',
+                        description: 'Check AI execution configuration and status for debugging prompt-only mode issues',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {},
                             required: [],
                         },
                     },
@@ -1402,18 +1711,44 @@ export class McpAdrAnalysisServer {
                             required: ['developmentPhase'],
                         },
                     },
+                    {
+                        name: 'list_roots',
+                        description: 'List available file system roots that can be accessed. Use this to discover what directories are available before reading files.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {},
+                        },
+                    },
+                    {
+                        name: 'read_directory',
+                        description: 'List files and folders in a directory. Use this to explore the file structure within accessible roots.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                path: {
+                                    type: 'string',
+                                    description: 'Directory path to list (relative to project root or absolute within roots)',
+                                },
+                            },
+                            required: ['path'],
+                        },
+                    },
                     {
                         name: 'read_file',
                         description: 'Read contents of a file',
                         inputSchema: {
                             type: 'object',
                             properties: {
-                                path: {
+                                filePath: {
                                     type: 'string',
                                     description: 'Path to the file to read',
                                 },
+                                path: {
+                                    type: 'string',
+                                    description: 'Path to the file to read (alias for filePath)',
+                                },
                             },
-                            required: ['path'],
+                            required: [],
                         },
                     },
                     {
@@ -1448,200 +1783,6 @@ export class McpAdrAnalysisServer {
                             required: ['path'],
                         },
                     },
-                    {
-                        name: 'manage_todo_json',
-                        description: 'JSON-first TODO management with consistent LLM interactions, automatic scoring sync, and knowledge graph integration',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                operation: {
-                                    type: 'string',
-                                    enum: [
-                                        'create_task',
-                                        'update_task',
-                                        'bulk_update',
-                                        'get_tasks',
-                                        'get_analytics',
-                                        'import_adr_tasks',
-                                        'sync_knowledge_graph',
-                                        'sync_to_markdown',
-                                        'import_from_markdown',
-                                    ],
-                                    description: 'Operation to perform on TODO JSON backend',
-                                },
-                                projectPath: {
-                                    type: 'string',
-                                    description: 'Project root path (uses configured PROJECT_PATH if not provided)',
-                                },
-                                taskId: {
-                                    type: 'string',
-                                    description: 'Task ID for update operations',
-                                },
-                                title: {
-                                    type: 'string',
-                                    description: 'Task title for create operations',
-                                },
-                                description: {
-                                    type: 'string',
-                                    description: 'Task description',
-                                },
-                                priority: {
-                                    type: 'string',
-                                    enum: ['low', 'medium', 'high', 'critical'],
-                                    default: 'medium',
-                                    description: 'Task priority level',
-                                },
-                                assignee: {
-                                    type: 'string',
-                                    description: 'Task assignee',
-                                },
-                                dueDate: {
-                                    type: 'string',
-                                    description: 'Due date (ISO string format)',
-                                },
-                                category: {
-                                    type: 'string',
-                                    description: 'Task category',
-                                },
-                                tags: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Task tags',
-                                },
-                                dependencies: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Task dependencies (task IDs)',
-                                },
-                                intentId: {
-                                    type: 'string',
-                                    description: 'Link to knowledge graph intent',
-                                },
-                                linkedAdrs: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Related ADR files',
-                                },
-                                autoComplete: {
-                                    type: 'boolean',
-                                    default: false,
-                                    description: 'Auto-complete when criteria are met',
-                                },
-                                completionCriteria: {
-                                    type: 'string',
-                                    description: 'Auto-completion rules',
-                                },
-                                updates: {
-                                    type: 'object',
-                                    properties: {
-                                        title: { type: 'string' },
-                                        description: { type: 'string' },
-                                        status: {
-                                            type: 'string',
-                                            enum: ['pending', 'in_progress', 'completed', 'blocked', 'cancelled'],
-                                        },
-                                        priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
-                                        assignee: { type: 'string' },
-                                        dueDate: { type: 'string' },
-                                        progressPercentage: { type: 'number', minimum: 0, maximum: 100 },
-                                        notes: { type: 'string' },
-                                        tags: { type: 'array', items: { type: 'string' } },
-                                    },
-                                    description: 'Fields to update for update operations',
-                                },
-                                reason: {
-                                    type: 'string',
-                                    description: 'Reason for update (for changelog)',
-                                },
-                                filters: {
-                                    type: 'object',
-                                    properties: {
-                                        status: {
-                                            type: 'string',
-                                            enum: ['pending', 'in_progress', 'completed', 'blocked', 'cancelled'],
-                                        },
-                                        priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
-                                        assignee: { type: 'string' },
-                                        category: { type: 'string' },
-                                        hasDeadline: { type: 'boolean' },
-                                        overdue: { type: 'boolean' },
-                                        tags: { type: 'array', items: { type: 'string' } },
-                                    },
-                                    description: 'Filter criteria for get_tasks operation',
-                                },
-                                sortBy: {
-                                    type: 'string',
-                                    enum: ['priority', 'dueDate', 'createdAt', 'updatedAt'],
-                                    default: 'priority',
-                                    description: 'Sort field for get_tasks operation',
-                                },
-                                sortOrder: {
-                                    type: 'string',
-                                    enum: ['asc', 'desc'],
-                                    default: 'desc',
-                                    description: 'Sort order for get_tasks operation',
-                                },
-                                limit: {
-                                    type: 'number',
-                                    description: 'Maximum number of tasks to return',
-                                },
-                                timeframe: {
-                                    type: 'string',
-                                    enum: ['day', 'week', 'month', 'all'],
-                                    default: 'week',
-                                    description: 'Analysis timeframe for analytics',
-                                },
-                                includeVelocity: {
-                                    type: 'boolean',
-                                    default: true,
-                                    description: 'Include velocity metrics in analytics',
-                                },
-                                includeScoring: {
-                                    type: 'boolean',
-                                    default: true,
-                                    description: 'Include scoring metrics in analytics',
-                                },
-                                adrDirectory: {
-                                    type: 'string',
-                                    default: 'docs/adrs',
-                                    description: 'ADR directory path for imports',
-                                },
-                                preserveExisting: {
-                                    type: 'boolean',
-                                    default: true,
-                                    description: 'Keep existing tasks during imports',
-                                },
-                                autoLinkDependencies: {
-                                    type: 'boolean',
-                                    default: true,
-                                    description: 'Auto-detect task dependencies',
-                                },
-                                direction: {
-                                    type: 'string',
-                                    enum: ['to_kg', 'from_kg', 'bidirectional'],
-                                    default: 'bidirectional',
-                                    description: 'Knowledge graph sync direction',
-                                },
-                                force: {
-                                    type: 'boolean',
-                                    default: false,
-                                    description: 'Force operation even if conflicts exist',
-                                },
-                                mergeStrategy: {
-                                    type: 'string',
-                                    enum: ['overwrite', 'merge', 'preserve_json'],
-                                    default: 'merge',
-                                    description: 'Merge strategy for imports',
-                                },
-                                backupExisting: {
-                                    type: 'boolean',
-                                    default: true,
-                                    description: 'Create backup before destructive operations',
-                                },
-                            },
-                            required: ['operation'],
-                        },
-                    },
                     {
                         name: 'generate_deployment_guidance',
                         description: 'Generate deployment guidance and instructions from ADRs with environment-specific configurations',
@@ -2137,7 +2278,6 @@ export class McpAdrAnalysisServer {
                                     items: {
                                         type: 'string',
                                         enum: [
-                                            'manage_todo_json',
                                             'smart_git_push',
                                             'compare_adr_progress',
                                             'analyze_content_security',
@@ -2460,7 +2600,7 @@ export class McpAdrAnalysisServer {
                     },
                     {
                         name: 'interactive_adr_planning',
-                        description: 'Interactive guided ADR planning and creation tool - walks users through structured decision-making process with research integration, option evaluation, and automatic ADR generation',
+                        description: 'Interactive guided ADR planning and creation tool - walks users through structured decision-making process with research integration, option evaluation, and automatic ADR generation. TIP: Start by reading @.mcp-server-context.md to understand project context and previous decisions.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -2652,75 +2792,263 @@ export class McpAdrAnalysisServer {
                                     description: 'Maximum depth for relationship traversal (find_related action)',
                                     default: 2,
                                 },
-                                forceReload: {
+                                forceReload: {
+                                    type: 'boolean',
+                                    description: 'Force reload of ADRs (load_adrs action)',
+                                    default: false,
+                                },
+                            },
+                        },
+                    },
+                    {
+                        name: 'expand_analysis_section',
+                        description: 'Retrieve full analysis content from tiered responses. Expand entire analysis or specific sections stored in memory. Use this when a tool returns a summary with an expandable ID.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                expandableId: {
+                                    type: 'string',
+                                    description: 'ID of the expandable analysis (provided in tiered response)',
+                                },
+                                section: {
+                                    type: 'string',
+                                    description: 'Optional: Specific section to expand (omit to get full analysis). Available sections are listed in the tiered response.',
+                                },
+                                format: {
+                                    type: 'string',
+                                    enum: ['markdown', 'json'],
+                                    description: 'Output format (default: markdown)',
+                                    default: 'markdown',
+                                },
+                            },
+                            required: ['expandableId'],
+                        },
+                    },
+                    {
+                        name: 'tool_chain_orchestrator',
+                        description: 'AI-powered dynamic tool sequencing - intelligently analyze user requests and generate structured tool execution plans',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                userRequest: {
+                                    type: 'string',
+                                    description: 'User request to analyze and create tool execution plan for',
+                                },
+                                availableTools: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'List of available MCP tools to orchestrate',
+                                },
+                                executionMode: {
+                                    type: 'string',
+                                    enum: ['plan_only', 'plan_and_execute', 'validate_plan'],
+                                    description: 'Orchestration mode',
+                                    default: 'plan_only',
+                                },
+                                maxSteps: {
+                                    type: 'number',
+                                    description: 'Maximum number of steps in the execution plan',
+                                    default: 10,
+                                },
+                                allowParallel: {
+                                    type: 'boolean',
+                                    description: 'Allow parallel execution of independent steps',
+                                    default: true,
+                                },
+                                contextHints: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'Additional context hints for better plan generation',
+                                },
+                            },
+                            required: ['userRequest'],
+                        },
+                    },
+                    {
+                        name: 'expand_memory',
+                        description: 'Phase 3: Retrieve and expand stored content from a tiered response using its expandable ID',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                expandableId: {
+                                    type: 'string',
+                                    description: 'Expandable ID from a tiered response',
+                                },
+                                section: {
+                                    type: 'string',
+                                    description: 'Optional: specific section to expand',
+                                },
+                                includeContext: {
                                     type: 'boolean',
-                                    description: 'Force reload of ADRs (load_adrs action)',
-                                    default: false,
+                                    description: 'Include related conversation context and knowledge graph state',
+                                    default: true,
                                 },
                             },
+                            required: ['expandableId'],
                         },
                     },
                     {
-                        name: 'tool_chain_orchestrator',
-                        description: 'AI-powered dynamic tool sequencing - intelligently analyze user requests and generate structured tool execution plans',
+                        name: 'query_conversation_history',
+                        description: 'Phase 3: Search and retrieve conversation sessions based on filters',
                         inputSchema: {
                             type: 'object',
                             properties: {
-                                userRequest: {
+                                projectPath: {
                                     type: 'string',
-                                    description: 'User request to analyze and create tool execution plan for',
+                                    description: 'Filter by project path',
                                 },
-                                availableTools: {
+                                dateRange: {
+                                    type: 'object',
+                                    properties: {
+                                        start: { type: 'string', description: 'Start date (ISO 8601)' },
+                                        end: { type: 'string', description: 'End date (ISO 8601)' },
+                                    },
+                                    description: 'Filter by date range',
+                                },
+                                toolsUsed: {
                                     type: 'array',
                                     items: { type: 'string' },
-                                    description: 'List of available MCP tools to orchestrate',
+                                    description: 'Filter by tools used in the session',
                                 },
-                                executionMode: {
+                                keyword: {
                                     type: 'string',
-                                    enum: ['plan_only', 'plan_and_execute', 'validate_plan'],
-                                    description: 'Orchestration mode',
-                                    default: 'plan_only',
+                                    description: 'Search keyword in conversation turns',
                                 },
-                                maxSteps: {
+                                limit: {
                                     type: 'number',
-                                    description: 'Maximum number of steps in the execution plan',
+                                    description: 'Maximum number of sessions to return',
                                     default: 10,
                                 },
-                                allowParallel: {
+                            },
+                        },
+                    },
+                    {
+                        name: 'get_conversation_snapshot',
+                        description: 'Phase 3: Get current conversation context snapshot for resumption or analysis',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                recentTurnCount: {
+                                    type: 'number',
+                                    description: 'Number of recent turns to include',
+                                    default: 5,
+                                },
+                            },
+                        },
+                    },
+                    {
+                        name: 'get_memory_stats',
+                        description: 'Phase 3: Get statistics about stored conversation memory',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {},
+                        },
+                    },
+                    {
+                        name: 'get_server_context',
+                        description: "Generate a comprehensive context file showing the server's current state, memory, and capabilities. Creates .mcp-server-context.md that can be @ referenced in conversations for instant LLM awareness",
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                writeToFile: {
                                     type: 'boolean',
-                                    description: 'Allow parallel execution of independent steps',
+                                    description: 'Whether to write the context to .mcp-server-context.md file',
                                     default: true,
                                 },
-                                contextHints: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Additional context hints for better plan generation',
+                                outputPath: {
+                                    type: 'string',
+                                    description: 'Custom output path for the context file',
+                                },
+                                includeDetailed: {
+                                    type: 'boolean',
+                                    description: 'Include detailed information',
+                                    default: true,
+                                },
+                                maxRecentItems: {
+                                    type: 'number',
+                                    description: 'Maximum number of recent items to show',
+                                    default: 5,
                                 },
                             },
-                            required: ['userRequest'],
                         },
                     },
                 ],
             };
         });
-        // Tool execution handler
+        /**
+         * Call Tool Handler - MCP Protocol Endpoint
+         *
+         * @description Executes specific tools with provided arguments. This is the core
+         * execution endpoint that routes tool calls to their respective implementations.
+         * Includes comprehensive error handling, argument validation, and response masking.
+         *
+         * @param {CallToolRequest} request - MCP tool execution request
+         * @param {string} request.params.name - Tool name to execute
+         * @param {Object} request.params.arguments - Tool-specific arguments
+         *
+         * @returns {Promise<CallToolResult>} Tool execution result with content and metadata
+         *
+         * @throws {McpAdrError} When tool execution fails or arguments are invalid
+         *
+         * @example
+         * ```typescript
+         * // Execute research tool
+         * const result = await mcpClient.callTool('perform_research', {
+         *   question: 'What authentication methods are used?',
+         *   projectPath: '/path/to/project'
+         * });
+         *
+         * console.log(result.content); // Research findings
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Execute ADR validation
+         * const validation = await mcpClient.callTool('validate_adr', {
+         *   adrPath: 'docs/adrs/0001-auth-choice.md',
+         *   includeEnvironmentCheck: true
+         * });
+         *
+         * console.log(validation.isValid); // true/false
+         * console.log(validation.findings); // Validation issues
+         * ```
+         *
+         * @mcp-endpoint
+         * @category Tools
+         * @category Execution
+         */
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
+            // Create context for progress notifications and logging
+            const context = {
+                info: (message) => {
+                    this.logger.info(message);
+                    // Note: MCP progress notifications will be available in future SDK versions
+                    // For now, we log to server console for visibility
+                },
+                report_progress: (progress, total) => {
+                    const percentage = total ? Math.round((progress / total) * 100) : progress;
+                    this.logger.info(`Progress: ${percentage}%${total ? ` (${progress}/${total})` : ''}`);
+                },
+                warn: (message) => {
+                    this.logger.warn(message);
+                },
+                error: (message) => {
+                    this.logger.error(message);
+                },
+            };
             try {
                 let response;
                 const safeArgs = args || {};
                 switch (name) {
                     case 'analyze_project_ecosystem':
-                        response = await this.analyzeProjectEcosystem(safeArgs);
+                        response = await this.analyzeProjectEcosystem(safeArgs, context);
                         break;
                     case 'get_architectural_context':
                         response = await this.getArchitecturalContext(safeArgs);
                         break;
                     case 'generate_adrs_from_prd':
-                        response = await this.generateAdrsFromPrd(safeArgs);
-                        break;
-                    case 'generate_adr_todo':
-                        response = await this.generateAdrTodo(safeArgs);
+                        response = await this.generateAdrsFromPrd(safeArgs, context);
                         break;
                     case 'compare_adr_progress':
                         response = await this.compareAdrProgress(safeArgs);
@@ -2755,12 +3083,24 @@ export class McpAdrAnalysisServer {
                     case 'generate_adr_bootstrap':
                         response = await this.generateAdrBootstrap(safeArgs);
                         break;
+                    case 'bootstrap_validation_loop':
+                        response = await this.bootstrapValidationLoop(safeArgs);
+                        break;
                     case 'discover_existing_adrs':
-                        response = await this.discoverExistingAdrs(safeArgs);
+                        response = await this.discoverExistingAdrs(safeArgs, context);
+                        break;
+                    case 'analyze_adr_timeline':
+                        response = await this.analyzeAdrTimeline(safeArgs);
                         break;
                     case 'review_existing_adrs':
                         response = await this.reviewExistingAdrs(safeArgs);
                         break;
+                    case 'validate_adr':
+                        response = await this.validateAdr(safeArgs);
+                        break;
+                    case 'validate_all_adrs':
+                        response = await this.validateAllAdrs(safeArgs);
+                        break;
                     case 'incorporate_research':
                         response = await this.incorporateResearch(safeArgs);
                         break;
@@ -2785,6 +3125,18 @@ export class McpAdrAnalysisServer {
                     case 'generate_research_questions':
                         response = await this.generateResearchQuestions(safeArgs);
                         break;
+                    case 'perform_research':
+                        response = await this.performResearch(safeArgs, context);
+                        break;
+                    case 'llm_web_search':
+                        response = await this.llmWebSearch(safeArgs);
+                        break;
+                    case 'llm_cloud_management':
+                        response = await this.llmCloudManagement(safeArgs);
+                        break;
+                    case 'llm_database_management':
+                        response = await this.llmDatabaseManagement(safeArgs);
+                        break;
                     case 'analyze_deployment_progress':
                         response = await this.analyzeDeploymentProgress(safeArgs);
                         break;
@@ -2797,18 +3149,26 @@ export class McpAdrAnalysisServer {
                     case 'get_development_guidance':
                         response = await this.getDevelopmentGuidance(safeArgs);
                         break;
-                    case 'read_file':
-                        response = await this.readFile(safeArgs);
+                    case 'list_roots':
+                        response = await this.listRoots();
+                        break;
+                    case 'read_directory':
+                        response = await this.readDirectory(safeArgs);
                         break;
+                    case 'read_file': {
+                        // Map 'path' parameter to 'filePath' for compatibility
+                        const readFileArgs = safeArgs;
+                        response = await this.readFile({
+                            filePath: readFileArgs.filePath || readFileArgs.path || '',
+                        });
+                        break;
+                    }
                     case 'write_file':
                         response = await this.writeFile(safeArgs);
                         break;
                     case 'list_directory':
                         response = await this.listDirectory(safeArgs);
                         break;
-                    case 'manage_todo_json':
-                        response = await this.manageTodoJson(safeArgs);
-                        break;
                     case 'generate_deployment_guidance':
                         response = await this.generateDeploymentGuidance(safeArgs);
                         break;
@@ -2830,19 +3190,38 @@ export class McpAdrAnalysisServer {
                     case 'memory_loading':
                         response = await this.memoryLoading(safeArgs);
                         break;
+                    case 'expand_analysis_section':
+                        response = await this.expandAnalysisSection(safeArgs);
+                        break;
                     case 'interactive_adr_planning':
                         response = await this.interactiveAdrPlanning(safeArgs);
                         break;
                     case 'tool_chain_orchestrator':
                         response = await this.toolChainOrchestrator(safeArgs);
                         break;
+                    case 'expand_memory':
+                        response = await this.expandMemory(safeArgs);
+                        break;
+                    case 'query_conversation_history':
+                        response = await this.queryConversationHistory(safeArgs);
+                        break;
+                    case 'get_conversation_snapshot':
+                        response = await this.getConversationSnapshot(safeArgs);
+                        break;
+                    case 'get_memory_stats':
+                        response = await this.getMemoryStats();
+                        break;
+                    case 'get_server_context':
+                        response = await this.getServerContext(safeArgs);
+                        break;
                     default:
                         throw new McpAdrError(`Unknown tool: ${name}`, 'UNKNOWN_TOOL');
                 }
-                // Apply content masking to response
                 // Track tool execution in knowledge graph
                 await this.trackToolExecution(name, args, response, true);
-                return await this.applyOutputMasking(response);
+                // Apply state reinforcement (Phase 2: Context Decay Mitigation) and content masking
+                // Also record conversation turn (Phase 3: Structured External Memory)
+                return await this.enrichResponseWithStateReinforcement(response, name, args);
             }
             catch (error) {
                 // Track failed execution
@@ -2853,32 +3232,213 @@ export class McpAdrAnalysisServer {
                 throw new McpAdrError(`Tool execution failed: ${error instanceof Error ? error.message : String(error)}`, 'TOOL_EXECUTION_ERROR');
             }
         });
-        // Resources handler
+        /**
+         * List Resources Handler - MCP Protocol Endpoint
+         *
+         * @description Returns available resources for client access including the
+         * architectural knowledge graph and project analysis data. Resources provide
+         * read-only access to server-managed data structures.
+         *
+         * @returns {Promise<{resources: Array}>} Available resources with URIs and descriptions
+         *
+         * @example
+         * ```typescript
+         * // List available resources
+         * const resources = await mcpClient.listResources();
+         * console.log(resources.resources.length); // Available resources
+         *
+         * // Find knowledge graph resource
+         * const kgResource = resources.resources.find(r =>
+         *   r.uri === 'adr://architectural_knowledge_graph'
+         * );
+         * console.log(kgResource.name); // "Architectural Knowledge Graph"
+         * ```
+         *
+         * @mcp-endpoint
+         * @category Resources
+         */
         this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
             return {
                 resources: [
+                    // Existing resources (refactored to return data)
                     {
                         uri: 'adr://architectural_knowledge_graph',
                         name: 'Architectural Knowledge Graph',
-                        description: 'Complete architectural knowledge graph of the project',
+                        description: 'Complete architectural knowledge graph with technologies, patterns, and relationships',
                         mimeType: 'application/json',
                     },
                     {
                         uri: 'adr://analysis_report',
                         name: 'Analysis Report',
-                        description: 'Comprehensive project analysis report',
+                        description: 'Comprehensive project analysis report with metrics and recommendations',
                         mimeType: 'application/json',
                     },
                     {
                         uri: 'adr://adr_list',
                         name: 'ADR List',
-                        description: 'List of all Architectural Decision Records',
+                        description: 'List of all Architectural Decision Records with status and metadata',
+                        mimeType: 'application/json',
+                    },
+                    // NEW Phase 1 Resources
+                    {
+                        uri: 'adr://todo_list',
+                        name: 'Todo List',
+                        description: 'Current project task list with status, priorities, and dependencies',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://research_index',
+                        name: 'Research Index',
+                        description: 'Index of all research documents and findings with metadata',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://rule_catalog',
+                        name: 'Rule Catalog',
+                        description: 'Catalog of all architectural and validation rules from ADRs and code',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://rule_generation',
+                        name: 'Rule Generation',
+                        description: 'AI-powered rule generation from ADRs and code patterns. Supports query parameters: ?operation=generate|validate|create_set, ?source=adrs|patterns|both, ?knowledge=true|false, ?enhanced=true|false, ?format=json|yaml|both, ?comprehensive=true|false',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://project_status',
+                        name: 'Project Status',
+                        description: 'Current project status and health metrics aggregated from all sources',
+                        mimeType: 'application/json',
+                    },
+                    // NEW Phase 2 Templated Resources
+                    {
+                        uri: 'adr://adr/{id}',
+                        name: 'ADR by ID',
+                        description: 'Individual Architectural Decision Record by ID or title match',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://research/{topic}',
+                        name: 'Research by Topic',
+                        description: 'Research documents filtered by topic with full content',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://todo/{task_id}',
+                        name: 'Todo by Task ID',
+                        description: 'Individual task details by ID or title match with dependencies and history',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://rule/{rule_id}',
+                        name: 'Rule by ID',
+                        description: 'Individual architectural rule by ID or name match with violations and usage stats',
+                        mimeType: 'application/json',
+                    },
+                    // NEW Phase 3 Advanced Resources
+                    {
+                        uri: 'adr://deployment_status',
+                        name: 'Deployment Status',
+                        description: 'Current deployment state with health checks, build status, and readiness score',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://environment_analysis',
+                        name: 'Environment Analysis',
+                        description: 'System environment details including platform, dependencies, and capabilities',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://memory_snapshots',
+                        name: 'Memory Snapshots',
+                        description: 'Knowledge graph snapshots with statistics, insights, and relationship data',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://project_metrics',
+                        name: 'Project Metrics',
+                        description: 'Code metrics and quality scores including codebase stats, quality assessment, and git metrics',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://technology/{name}',
+                        name: 'Technology by Name',
+                        description: 'Individual technology analysis by name with usage, relationships, and adoption status',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://pattern/{name}',
+                        name: 'Pattern by Name',
+                        description: 'Individual pattern analysis by name with quality metrics, relationships, and examples',
+                        mimeType: 'application/json',
+                    },
+                    // NEW Phase 4 Final Resources
+                    {
+                        uri: 'adr://deployment_history',
+                        name: 'Deployment History',
+                        description: 'Historical deployment data with trends, failure analysis, and patterns. Supports query parameters: ?period=7d|30d|90d|1y|all, ?environment=production|staging|development|all, ?includeFailures=true|false, ?includeMetrics=true|false, ?format=summary|detailed',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://code_quality',
+                        name: 'Code Quality',
+                        description: 'Comprehensive code quality assessment with metrics, issues, and recommendations. Supports query parameters: ?scope=full|changes|critical, ?includeMetrics=true|false, ?includeRecommendations=true|false, ?threshold=0-100, ?format=summary|detailed',
+                        mimeType: 'application/json',
+                    },
+                    // NEW Phase 5 Validated Pattern Resources
+                    {
+                        uri: 'adr://validated_patterns',
+                        name: 'Validated Patterns Catalog',
+                        description: 'Complete catalog of validated deployment patterns for different platforms (OpenShift, Kubernetes, Docker, Node.js, Python, MCP, A2A) with bill of materials, deployment phases, validation checks, and authoritative sources',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://validated_pattern/{platform}',
+                        name: 'Validated Pattern by Platform',
+                        description: 'Individual validated pattern by platform type (openshift, kubernetes, docker, nodejs, python, mcp, a2a) with complete bill of materials, deployment phases, validation checks, health checks, and authoritative sources for LLM research',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://pattern_sources/{platform}',
+                        name: 'Pattern Authoritative Sources',
+                        description: 'Authoritative documentation and repository sources for a specific platform pattern, prioritized by importance with query instructions for LLMs',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'adr://pattern_base_code/{platform}',
+                        name: 'Pattern Base Code Repository',
+                        description: 'Base code repository information for a platform pattern including URL, integration instructions, required files, and script entrypoint',
                         mimeType: 'application/json',
                     },
                 ],
             };
         });
-        // Resource reading handler
+        /**
+         * Read Resource Handler - MCP Protocol Endpoint
+         *
+         * @description Reads specific resource content by URI. Provides access to
+         * architectural knowledge graphs, project analysis data, and other server-managed
+         * resources with appropriate content masking applied.
+         *
+         * @param {ReadResourceRequest} request - MCP resource read request
+         * @param {string} request.params.uri - Resource URI to read
+         *
+         * @returns {Promise<ReadResourceResult>} Resource content with metadata
+         *
+         * @throws {McpAdrError} When resource URI is invalid or access fails
+         *
+         * @example
+         * ```typescript
+         * // Read knowledge graph resource
+         * const kgData = await mcpClient.readResource(
+         *   'adr://architectural_knowledge_graph'
+         * );
+         * console.log(kgData.contents); // Knowledge graph JSON
+         * ```
+         *
+         * @mcp-endpoint
+         * @category Resources
+         */
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             const { uri } = request.params;
             try {
@@ -2892,7 +3452,31 @@ export class McpAdrAnalysisServer {
                 throw new McpAdrError(`Resource reading failed: ${error instanceof Error ? error.message : String(error)}`, 'RESOURCE_ERROR');
             }
         });
-        // Prompts handler
+        /**
+         * List Prompts Handler - MCP Protocol Endpoint
+         *
+         * @description Returns available prompt templates for ADR analysis, research,
+         * and architectural decision support. Prompts can be executed directly or
+         * used as templates for custom implementations.
+         *
+         * @returns {Promise<{prompts: Array}>} Available prompt templates with metadata
+         *
+         * @example
+         * ```typescript
+         * // List available prompts
+         * const prompts = await mcpClient.listPrompts();
+         * console.log(prompts.prompts.length); // Available prompt templates
+         *
+         * // Find ADR analysis prompt
+         * const adrPrompt = prompts.prompts.find(p =>
+         *   p.name === 'adr_analysis_prompt'
+         * );
+         * console.log(adrPrompt.description); // Prompt description
+         * ```
+         *
+         * @mcp-endpoint
+         * @category Prompts
+         */
         this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
             const { allPrompts } = await import('./prompts/index.js');
             return {
@@ -2903,7 +3487,47 @@ export class McpAdrAnalysisServer {
                 })),
             };
         });
-        // Prompt execution handler
+        /**
+         * Get Prompt Handler - MCP Protocol Endpoint
+         *
+         * @description Executes specific prompt templates with provided arguments.
+         * Returns formatted prompts ready for AI execution or further processing.
+         * Supports dynamic argument injection and template customization.
+         *
+         * @param {GetPromptRequest} request - MCP prompt execution request
+         * @param {string} request.params.name - Prompt template name
+         * @param {Object} request.params.arguments - Template-specific arguments
+         *
+         * @returns {Promise<GetPromptResult>} Formatted prompt with metadata
+         *
+         * @throws {McpAdrError} When prompt template is not found or arguments are invalid
+         *
+         * @example
+         * ```typescript
+         * // Execute ADR analysis prompt
+         * const prompt = await mcpClient.getPrompt('adr_analysis_prompt', {
+         *   adrPath: 'docs/adrs/0001-auth.md',
+         *   projectContext: 'microservices architecture'
+         * });
+         *
+         * console.log(prompt.messages); // Formatted prompt messages
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Execute research prompt
+         * const researchPrompt = await mcpClient.getPrompt('research_question_prompt', {
+         *   domain: 'authentication',
+         *   complexity: 'advanced'
+         * });
+         *
+         * console.log(researchPrompt.messages[0].content); // Research prompt
+         * ```
+         *
+         * @mcp-endpoint
+         * @category Prompts
+         * @category Execution
+         */
         this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
             try {
@@ -3071,18 +3695,17 @@ Verify these environment variables are set in your MCP configuration:
 5. **suggest_adrs** - Auto-suggest ADRs from implicit decisions
 6. **generate_adr_from_decision** - Create ADRs from specific decisions
 7. **discover_existing_adrs** - Intelligent ADR discovery and analysis
-8. **generate_adr_todo** - Create actionable task lists from ADRs
 
 ### 🔍 **Research & Documentation Tools** (AI-Powered ✅)
-9. **generate_research_questions** - Create context-aware research questions
-10. **incorporate_research** - Integrate research findings into decisions
-11. **create_research_template** - Generate research documentation templates
+8. **generate_research_questions** - Create context-aware research questions
+9. **incorporate_research** - Integrate research findings into decisions
+10. **create_research_template** - Generate research documentation templates
 
 ### 🛡️ **Security & Compliance Tools** (AI-Powered ✅)
-12. **generate_content_masking** - Intelligent content masking and protection
-13. **configure_custom_patterns** - Customize security and masking settings
-14. **apply_basic_content_masking** - Basic content masking (fallback)
-15. **validate_content_masking** - Validate masking effectiveness
+11. **generate_content_masking** - Intelligent content masking and protection
+12. **configure_custom_patterns** - Customize security and masking settings
+13. **apply_basic_content_masking** - Basic content masking (fallback)
+14. **validate_content_masking** - Validate masking effectiveness
 
 ### 🏗️ **Rule & Governance Tools** (AI-Powered ✅)
 16. **generate_rules** - Extract architectural rules from ADRs
@@ -3140,13 +3763,13 @@ Define how to measure success:
 1. analyze_project_ecosystem → 2. get_architectural_context → 3. suggest_adrs → 4. generate_adr_from_decision
 
 ### **Existing Project Analysis**
-1. discover_existing_adrs → 2. get_architectural_context → 3. generate_adr_todo → 4. validate_rules
+1. discover_existing_adrs → 2. get_architectural_context → 3. validate_rules
 
 ### **Security Audit**
 1. analyze_content_security → 2. generate_content_masking → 3. configure_custom_patterns → 4. validate_content_masking
 
 ### **PRD to Implementation**
-1. generate_adrs_from_prd → 2. generate_adr_todo → 3. analyze_deployment_progress
+1. generate_adrs_from_prd → 2. analyze_deployment_progress
 
 ### **Legacy Modernization**
 1. analyze_project_ecosystem → 2. get_architectural_context → 3. suggest_adrs → 4. generate_rules → 5. validate_rules
@@ -3194,7 +3817,7 @@ ${executionResult.content}
 ## Quick Reference: Available Tools
 
 **Core Analysis**: analyze_project_ecosystem, get_architectural_context, generate_adrs_from_prd, analyze_content_security
-**ADR Management**: suggest_adrs, generate_adr_from_decision, discover_existing_adrs, generate_adr_todo
+**ADR Management**: suggest_adrs, generate_adr_from_decision, discover_existing_adrs
 **Security**: generate_content_masking, configure_custom_patterns, validate_content_masking
 **Governance**: generate_rules, validate_rules, create_rule_set
 **Environment**: analyze_environment, analyze_deployment_progress
@@ -3237,7 +3860,10 @@ This guidance is tailored to your specific context and goals for maximum effecti
                 const { getAdrDirectoryPath } = await import('./utils/config.js');
                 const { discoverAdrsInDirectory } = await import('./utils/adr-discovery.js');
                 const absoluteAdrPath = getAdrDirectoryPath(this.config);
-                const discoveryResult = await discoverAdrsInDirectory(absoluteAdrPath, true, this.config.projectPath);
+                const discoveryResult = await discoverAdrsInDirectory(absoluteAdrPath, this.config.projectPath, {
+                    includeContent: true,
+                    includeTimeline: false,
+                });
                 // Filter ADRs to only those specified for implementation
                 const targetAdrs = discoveryResult.adrs.filter(adr => adrsToImplement.some((target) => adr.title.toLowerCase().includes(target.toLowerCase()) ||
                     adr.filename.toLowerCase().includes(target.toLowerCase())));
@@ -3432,7 +4058,6 @@ This development guidance works seamlessly with other MCP tools:
 - **analyze_content_security** → Security validation during development
 
 ### **Documentation Tools**
-- **generate_adr_todo** → Create implementation task lists
 - **discover_existing_adrs** → Reference existing architectural decisions
 
 ## Next Steps: From Architecture to Code
@@ -3463,7 +4088,8 @@ This guidance ensures your development work is **architecturally aligned**, **qu
             throw new McpAdrError(`Failed to generate development guidance: ${error instanceof Error ? error.message : String(error)}`, 'DEVELOPMENT_ERROR');
         }
     }
-    async analyzeProjectEcosystem(args) {
+    async analyzeProjectEcosystem(args, context) {
+        const ctx = context || createNoOpContext();
         // Use configured project path if not provided in args
         const projectPath = args.projectPath || this.config.projectPath;
         const { includePatterns, enhancedMode = true, knowledgeEnhancement = true, learningEnabled = true, technologyFocus = [], analysisDepth = 'comprehensive', includeEnvironment = true, recursiveDepth = 'comprehensive', analysisScope = [],
@@ -3473,9 +4099,38 @@ This guidance ensures your development work is **architecturally aligned**, **qu
         this.logger.info(`Analysis configuration - Depth: ${analysisDepth}, Recursive: ${recursiveDepth}, Environment: ${includeEnvironment}`);
         this.logger.info(`Enhancement features - Knowledge: ${knowledgeEnhancement}, Learning: ${learningEnabled}`);
         this.logger.info(`Analysis scope: ${analysisScope.length > 0 ? analysisScope.join(', ') : 'Full ecosystem analysis'}`);
+        ctx.info(`🌐 Starting comprehensive ecosystem analysis: ${projectPath}`);
+        ctx.report_progress(0, 100);
         try {
+            ctx.info('📊 Phase 1: Analyzing project structure');
+            ctx.report_progress(10, 100);
             // Import utilities dynamically to avoid circular dependencies
             const { analyzeProjectStructureCompat: analyzeProjectStructure } = await import('./utils/file-system.js');
+            // Initialize ADR knowledge base on first run
+            ctx.info('📚 Phase 1.5: Initializing ADR knowledge base');
+            ctx.report_progress(15, 100);
+            try {
+                const { initializeAdrKnowledgeBase, isAdrKnowledgeBaseInitialized } = await import('./utils/adr-knowledge-initializer.js');
+                const isInitialized = await isAdrKnowledgeBaseInitialized(this.kgManager);
+                if (!isInitialized) {
+                    this.logger.info('First run detected - initializing ADR knowledge base');
+                    const initResult = await initializeAdrKnowledgeBase(this.kgManager, this.config.adrDirectory, projectPath);
+                    if (initResult.success) {
+                        this.logger.info(`✅ ADR knowledge base initialized with ${initResult.adrsIndexed} ADRs`);
+                        ctx.info(`📚 Indexed ${initResult.adrsIndexed} existing ADRs to knowledge base`);
+                    }
+                    else {
+                        this.logger.warn(`ADR knowledge base initialization completed with errors: ${initResult.errors.join(', ')}`);
+                    }
+                }
+                else {
+                    this.logger.info('ADR knowledge base already initialized - skipping');
+                }
+            }
+            catch (error) {
+                this.logger.warn('Failed to initialize ADR knowledge base:', error);
+                // Don't fail the entire analysis if ADR initialization fails
+            }
             // Import advanced prompting utilities if enhanced mode is enabled
             let generateArchitecturalKnowledge = null;
             let executeWithReflexion = null;
@@ -3494,6 +4149,8 @@ This guidance ensures your development work is **architecturally aligned**, **qu
                 }
             }
             // Step 1: Generate technology-specific knowledge if enabled
+            ctx.info('🧠 Phase 2: Generating architectural knowledge');
+            ctx.report_progress(25, 100);
             let knowledgeContext = '';
             if (enhancedMode && knowledgeEnhancement && generateArchitecturalKnowledge) {
                 try {
@@ -3544,8 +4201,12 @@ ${memoryResult.prompt}
                 }
             }
             // Step 3: Generate base project analysis prompt with recursive depth
+            ctx.info('📁 Phase 3: Scanning project files and structure');
+            ctx.report_progress(40, 100);
             const baseProjectAnalysisPrompt = await analyzeProjectStructure(projectPath);
             // Step 4: Generate environment analysis if enabled
+            ctx.info('🔧 Phase 4: Analyzing environment and infrastructure');
+            ctx.report_progress(55, 100);
             let environmentAnalysisContext = '';
             if (includeEnvironment) {
                 try {
@@ -3579,6 +4240,8 @@ ${environmentResult.content[0].text}
                 }
             }
             // Step 5: Apply Reflexion execution if learning is enabled
+            ctx.info('🧪 Phase 5: Applying learning and reflexion');
+            ctx.report_progress(70, 100);
             let enhancedAnalysisPrompt = baseProjectAnalysisPrompt.prompt + environmentAnalysisContext;
             if (enhancedMode && learningEnabled && executeWithReflexion && createToolReflexionConfig) {
                 try {
@@ -3615,6 +4278,8 @@ ${environmentResult.content[0].text}
                     baseProjectAnalysisPrompt.prompt + knowledgeContext + environmentAnalysisContext;
             }
             // Execute the analysis with AI if enabled, otherwise return prompt
+            ctx.info('🤖 Phase 6: Executing AI-powered ecosystem analysis');
+            ctx.report_progress(85, 100);
             const { executeEcosystemAnalysisPrompt, formatMCPResponse } = await import('./utils/prompt-execution.js');
             const executionResult = await executeEcosystemAnalysisPrompt(enhancedAnalysisPrompt, baseProjectAnalysisPrompt.instructions, {
                 temperature: 0.1,
@@ -3640,6 +4305,8 @@ ${environmentResult.content[0].text}
                 this.logger.warn('Failed to record project structure to knowledge graph:', kgError);
                 // Don't fail the entire analysis if KG recording fails
             }
+            ctx.info('✅ Ecosystem analysis completed successfully');
+            ctx.report_progress(100, 100);
             // Return appropriate response based on execution result
             if (executionResult.isAIGenerated) {
                 // AI execution successful - return actual analysis results
@@ -4029,16 +4696,24 @@ This **outcome-focused approach** ensures architectural work delivers **measurab
             throw new McpAdrError(`Failed to get architectural context: ${error instanceof Error ? error.message : String(error)}`, 'ANALYSIS_ERROR');
         }
     }
-    async generateAdrsFromPrd(args) {
+    async generateAdrsFromPrd(args, context) {
+        const ctx = context || createNoOpContext();
         const { prdPath, enhancedMode = true, promptOptimization = true, knowledgeEnhancement = true, prdType = 'general', } = args;
         const outputDirectory = args['outputDirectory'] || this.config.adrDirectory;
         this.logger.info(`Generating enhanced ADRs from PRD: ${prdPath} to ${outputDirectory}`);
         this.logger.info(`Enhancement features - APE: ${promptOptimization}, Knowledge: ${knowledgeEnhancement}, Type: ${prdType}`);
+        ctx.info(`📝 Starting ADR generation from PRD: ${prdPath}`);
+        ctx.report_progress(0, 100);
         try {
+            ctx.info('📂 Phase 1: Validating PRD file');
+            ctx.report_progress(10, 100);
             const { readFileContentCompat: readFileContent, fileExistsCompat: fileExists } = await import('./utils/file-system.js');
             // Import advanced prompting utilities if enhanced mode is enabled
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             let generateArchitecturalKnowledge = null;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             let optimizePromptWithAPE = null;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             let createToolAPEConfig = null;
             if (enhancedMode) {
                 if (knowledgeEnhancement) {
@@ -4055,7 +4730,11 @@ This **outcome-focused approach** ensures architectural work delivers **measurab
             const fileExistsPrompt = await fileExists(prdPath);
             // Generate file content reading prompt
             const fileContentPrompt = await readFileContent(prdPath);
+            ctx.info('📚 Phase 2: Reading PRD content');
+            ctx.report_progress(25, 100);
             // Step 1: Generate domain-specific knowledge if enabled
+            ctx.info('🧠 Phase 3: Generating domain knowledge');
+            ctx.report_progress(40, 100);
             let knowledgeContext = '';
             if (enhancedMode && knowledgeEnhancement && generateArchitecturalKnowledge) {
                 try {
@@ -4086,8 +4765,12 @@ ${knowledgeResult.prompt}
                 }
             }
             // Step 2: Create base ADR generation prompt
+            ctx.info('📋 Phase 4: Creating base ADR prompts');
+            ctx.report_progress(60, 100);
             const baseAdrPrompt = this.createBaseAdrPrompt(prdPath, outputDirectory, knowledgeContext);
             // Step 3: Apply APE optimization if enabled
+            ctx.info('⚡ Phase 5: Optimizing prompts with APE');
+            ctx.report_progress(75, 100);
             let finalAdrPrompt = baseAdrPrompt;
             if (enhancedMode && promptOptimization && optimizePromptWithAPE && createToolAPEConfig) {
                 try {
@@ -4166,6 +4849,8 @@ For each generated ADR, create a file creation prompt using the following patter
 - Confirm all decisions are traceable back to PRD requirements with domain context
 `;
             // Execute the ADR generation with AI if enabled, otherwise return prompt
+            ctx.info('🤖 Phase 6: Executing AI-powered ADR generation');
+            ctx.report_progress(90, 100);
             const { executeADRGenerationPrompt, formatMCPResponse } = await import('./utils/prompt-execution.js');
             const executionResult = await executeADRGenerationPrompt(adrPrompt, 'Generate comprehensive ADRs from PRD analysis with enhanced domain knowledge and optimization', {
                 temperature: 0.1,
@@ -4174,6 +4859,8 @@ For each generated ADR, create a file creation prompt using the following patter
 Generate well-structured ADRs that follow best practices and include all necessary sections.
 Focus on extracting architectural decisions from the PRD and creating actionable ADRs with clear reasoning.`,
             });
+            ctx.info('✅ ADR generation completed successfully');
+            ctx.report_progress(100, 100);
             if (executionResult.isAIGenerated) {
                 // AI execution successful - return actual ADR generation results
                 return formatMCPResponse({
@@ -4299,109 +4986,6 @@ The enhanced process maintains full traceability from PRD requirements to genera
             throw new McpAdrError(`Failed to generate ADR prompts from PRD: ${error instanceof Error ? error.message : String(error)}`, 'PROMPT_GENERATION_ERROR');
         }
     }
-    async generateAdrTodo(args) {
-        const { scope = 'all', phase = 'both', linkAdrs = true, includeRules = true, ruleSource = 'both', preserveExisting = true, forceSyncToMarkdown = false, intentId, createJsonBackup = true, } = args;
-        const { getAdrDirectoryPath } = await import('./utils/config.js');
-        const path = await import('path');
-        // Use absolute ADR path relative to project
-        const absoluteAdrPath = args['adrDirectory']
-            ? path.resolve(this.config.projectPath, args['adrDirectory'])
-            : getAdrDirectoryPath(this.config);
-        // Keep relative path for display purposes
-        const adrDirectory = args['adrDirectory'] || this.config.adrDirectory;
-        this.logger.info(`Generating JSON-first TODO for ADRs in: ${absoluteAdrPath} (phase: ${phase})`);
-        try {
-            // Always use JSON-first TODO system
-            this.logger.info('Using JSON-first TODO system for ADR task generation');
-            // TODO management has been deprecated and moved to mcp-shrimp-task-manager
-            this.logger.warn('⚠️ TODO management has been deprecated - use mcp-shrimp-task-manager instead');
-            // Optional: Create backup if requested and JSON exists
-            if (createJsonBackup) {
-                try {
-                    this.logger.info('Backup feature deprecated - use mcp-shrimp-task-manager for task management');
-                }
-                catch {
-                    // Continue if backup fails - might be first time setup
-                    this.logger.debug('No existing JSON data to backup');
-                }
-            }
-            // Import ADR tasks into JSON system has been deprecated
-            const importResult = {
-                content: [
-                    {
-                        type: 'text',
-                        text: `⚠️ **TODO Management Deprecated**
-
-This feature has been moved to mcp-shrimp-task-manager.
-
-**Replacement:** Use the external \`mcp-shrimp-task-manager\` for:
-- Task planning and breaking down from ADRs
-- Task tracking and status updates
-- Task dependencies and priorities
-- Task completion and verification
-
-**Migration:** The system now uses memory-centric architecture where task management is handled by external MCP servers.`,
-                    },
-                ],
-            };
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `# ✅ JSON-First TODO Generated from ADRs
-
-## 🏗️ JSON-First TODO System Active
-✅ **todo-data.json** - JSON-first TODO backend created/updated  
-✅ **TODO.md** - Markdown frontend ${forceSyncToMarkdown ? 'synchronized' : 'available for sync'}  
-
-## Configuration Applied
-- **ADR Directory**: ${adrDirectory}
-- **Scope**: ${scope}
-- **TDD Phase**: ${phase}
-- **ADR Dependency Linking**: ${linkAdrs ? 'Enabled' : 'Disabled'}
-- **Rules Integration**: ${includeRules ? `Enabled (${ruleSource})` : 'Disabled'}
-- **Preserve Existing**: ${preserveExisting}
-- **Force Markdown Sync**: ${forceSyncToMarkdown ? 'Enabled' : 'Disabled'}
-- **Intent Linking**: ${intentId ? `Linked to ${intentId}` : 'None'}
-- **JSON Backup**: ${createJsonBackup ? 'Created' : 'Skipped'}
-
-## JSON-First Architecture Benefits
-✅ **Structured Data**: JSON backend ensures consistent LLM interactions
-✅ **Automatic Sync**: JSON-to-markdown conversion maintains TODO.md compatibility  
-✅ **Enhanced Metadata**: Full task lifecycle with dependencies, assignees, priorities
-✅ **Complete Integration**: Native support for scoring, git automation, and knowledge graph
-✅ **Backup Protection**: Automatic data preservation during updates
-✅ **No Manual Setup**: All cache files auto-generated, tests can immediately validate
-
-${importResult.content?.[0]?.text || 'TODO management feature has been deprecated'}
-
-## Available Operations (use manage_todo_v2 tool)
-1. **View Tasks**: \`get_tasks\` operation with filtering and sorting
-2. **Update Status**: \`update_task\` operation with status, progress, notes
-3. **Bulk Updates**: \`bulk_update\` operation for multiple tasks
-4. **Analytics**: \`get_analytics\` operation for progress metrics
-5. **Sync Control**: \`sync_to_markdown\` and \`sync_knowledge_graph\` operations
-
-## Validation & Progress Tracking
-- **Progress Check**: Use \`compare_adr_progress\` to validate implementation vs ADRs
-- **Git Integration**: Use \`smart_git_push\` for automatic task status updates
-- **Scoring**: Integrated with smart scoring for release readiness assessment
-
-## TDD Workflow Integration
-- **Phase 1**: Mock test generation tasks created
-- **Phase 2**: Production implementation tasks linked to tests
-- **Dependencies**: ADR relationships mapped to task dependencies
-- **Validation**: Architectural rules integrated into task criteria
-
-*All TODO data is now managed in JSON format with automatic markdown sync*`,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            throw new McpAdrError(`Failed to generate ADR todo: ${error instanceof Error ? error.message : String(error)}`, 'GENERATION_ERROR');
-        }
-    }
     async compareAdrProgress(args) {
         const { todoPath = 'TODO.md', adrDirectory = this.config.adrDirectory, projectPath = this.config.projectPath, environment = 'auto-detect', environmentConfig = {}, validationType = 'full', includeFileChecks = true, includeRuleValidation = true, deepCodeAnalysis = true, functionalValidation = true, strictMode = true, environmentValidation = true, } = args;
         const { getAdrDirectoryPath } = await import('./utils/config.js');
@@ -4458,7 +5042,10 @@ ${importResult.content?.[0]?.text || 'TODO management feature has been deprecate
             let discoveryResult = null;
             if (validationType === 'full' || validationType === 'adr-only') {
                 const { discoverAdrsInDirectory } = await import('./utils/adr-discovery.js');
-                discoveryResult = await discoverAdrsInDirectory(absoluteAdrPath, true, projectPath);
+                discoveryResult = await discoverAdrsInDirectory(absoluteAdrPath, projectPath, {
+                    includeContent: true,
+                    includeTimeline: false,
+                });
             }
             const analysis = await this.performLocalAdrProgressAnalysis({
                 todoContent,
@@ -4643,14 +5230,17 @@ ${importResult.content?.[0]?.text || 'TODO management feature has been deprecate
 
 ## Environment Context
 - **Target Environment**: ${environment}
-- **Security Level**: ${environmentConfig.securityLevel || 'Not specified'}
-- **Required Files**: ${environmentConfig.requiredFiles?.length || 0} files
-- **Required Services**: ${environmentConfig.requiredServices?.length || 0} services
+- **Security Level**: ${environmentConfig?.['securityLevel'] || 'Not specified'}
+- **Required Files**: ${environmentConfig?.['requiredFiles']?.length || 0} files
+- **Required Services**: ${environmentConfig?.['requiredServices']?.length || 0} services
 
 ## ADR Discovery Results
 ${totalAdrs > 0
             ? `Found ${totalAdrs} ADRs:\n${discoveredAdrs
-                .map((adr, i) => `${i + 1}. **${adr.title}** (${adr.status}) - ${adr.filename}`)
+                .map((adr, i) => {
+                const adrRecord = adr;
+                return `${i + 1}. **${adrRecord['title']}** (${adrRecord['status']}) - ${adrRecord['filename']}`;
+            })
                 .join('\n')}`
             : 'No ADRs found in the specified directory.'}
 
@@ -4716,23 +5306,9 @@ ${environmentValidation
 
 ## Next Steps
 1. Address high-priority alignment issues identified above
-2. ${totalTasks === 0 ? 'Create initial TODO.md from ADR requirements using generate_adr_todo tool' : 'Update TODO.md with missing tasks'}
+2. ${totalTasks === 0 ? 'Create initial TODO.md from ADR requirements' : 'Update TODO.md with missing tasks'}
 3. ${includeFileChecks ? 'Verify implementation of completed tasks' : 'Enable file checks for detailed implementation verification'}
 4. ${includeRuleValidation ? 'Resolve architectural rule compliance violations' : 'Enable rule validation for compliance checking'}
-
-## Integration Commands
-
-To regenerate TODO after fixes:
-\`\`\`json
-{
-  "tool": "generate_adr_todo",
-  "args": {
-    "adrDirectory": "${adrDirectory}",
-    "phase": "both",
-    "linkAdrs": true,
-    "includeRules": ${includeRuleValidation}
-  }
-}
 \`\`\`
 
 To re-run this validation with strict mode:
@@ -4792,17 +5368,20 @@ To re-run this validation with strict mode:
         const misaligned = [];
         const missing = [];
         // Simple keyword matching for alignment detection
-        const adrKeywords = adrs.flatMap(adr => [
-            adr.title.toLowerCase(),
-            ...(adr.decision || '')
-                .toLowerCase()
-                .split(/\s+/)
-                .filter((w) => w.length > 4),
-            ...(adr.context || '')
-                .toLowerCase()
-                .split(/\s+/)
-                .filter((w) => w.length > 4),
-        ]);
+        const adrKeywords = adrs.flatMap(adr => {
+            const adrRecord = adr;
+            return [
+                String(adrRecord['title'] || '').toLowerCase(),
+                ...String(adrRecord['decision'] || '')
+                    .toLowerCase()
+                    .split(/\s+/)
+                    .filter((w) => w.length > 4),
+                ...String(adrRecord['context'] || '')
+                    .toLowerCase()
+                    .split(/\s+/)
+                    .filter((w) => w.length > 4),
+            ];
+        });
         // Environment-specific keywords that should be prioritized
         const envKeywords = [];
         if (environment && environmentConfig) {
@@ -4818,7 +5397,8 @@ To re-run this validation with strict mode:
         }
         for (const task of tasks) {
             const taskLower = task.title.toLowerCase();
-            const hasKeywordMatch = adrKeywords.some(keyword => taskLower.includes(keyword) || keyword.includes(taskLower.split(' ')[0]));
+            const firstWord = taskLower.split(' ')[0] || '';
+            const hasKeywordMatch = adrKeywords.some(keyword => taskLower.includes(keyword) || keyword.includes(firstWord));
             // Environment-aware alignment scoring
             const hasEnvKeywordMatch = envKeywords.some(keyword => taskLower.includes(keyword));
             if (hasKeywordMatch || hasEnvKeywordMatch) {
@@ -4830,8 +5410,9 @@ To re-run this validation with strict mode:
         }
         // Identify potential missing tasks based on ADR content
         for (const adr of adrs) {
-            if (adr.status === 'accepted' && adr.decision) {
-                const decisionWords = adr.decision.toLowerCase().split(/\s+/);
+            const adrRecord = adr;
+            if (adrRecord['status'] === 'accepted' && adrRecord['decision']) {
+                const decisionWords = String(adrRecord['decision']).toLowerCase().split(/\s+/);
                 const implementationWords = [
                     'implement',
                     'create',
@@ -4842,25 +5423,28 @@ To re-run this validation with strict mode:
                     'configure',
                 ];
                 if (implementationWords.some(word => decisionWords.includes(word))) {
-                    const hasCorrespondingTask = tasks.some(task => task.title.toLowerCase().includes(adr.title.toLowerCase().split(' ')[0]));
+                    const adrTitle = String(adrRecord['title'] || '');
+                    const adrFirstWord = adrTitle.toLowerCase().split(' ')[0] || '';
+                    const hasCorrespondingTask = tasks.some(task => task.title.toLowerCase().includes(adrFirstWord));
                     if (!hasCorrespondingTask) {
-                        missing.push(`Implement ${adr.title}`);
+                        missing.push(`Implement ${adrTitle}`);
                     }
                 }
             }
         }
         // Environment-specific missing tasks
         if (environment && environmentConfig) {
-            if (environmentConfig.requiredFiles) {
-                for (const file of environmentConfig.requiredFiles) {
+            const envConfig = environmentConfig;
+            if (envConfig['requiredFiles']) {
+                for (const file of envConfig['requiredFiles']) {
                     const hasFileTask = tasks.some(task => task.title.toLowerCase().includes(file.toLowerCase()));
                     if (!hasFileTask) {
                         missing.push(`Create ${file} for ${environment} environment`);
                     }
                 }
             }
-            if (environmentConfig.requiredServices) {
-                for (const service of environmentConfig.requiredServices) {
+            if (envConfig['requiredServices']) {
+                for (const service of envConfig['requiredServices']) {
                     const hasServiceTask = tasks.some(task => task.title.toLowerCase().includes(service.toLowerCase()));
                     if (!hasServiceTask) {
                         missing.push(`Setup ${service} service for ${environment}`);
@@ -5544,14 +6128,130 @@ Please provide:
         const { default: generateAdrBootstrapScripts } = await import('./tools/adr-bootstrap-validation-tool.js');
         return await generateAdrBootstrapScripts(args);
     }
-    async discoverExistingAdrs(args) {
-        const { discoverExistingAdrs } = await import('./tools/adr-suggestion-tool.js');
-        return await discoverExistingAdrs(args);
+    async bootstrapValidationLoop(args) {
+        const { default: bootstrapValidationLoop } = await import('./tools/bootstrap-validation-loop-tool.js');
+        return await bootstrapValidationLoop(args);
+    }
+    async discoverExistingAdrs(args, context) {
+        const ctx = context || createNoOpContext();
+        try {
+            ctx.info('🔍 Starting ADR discovery process...');
+            ctx.report_progress(0, 100);
+            ctx.info('📂 Phase 1: Scanning ADR directory');
+            ctx.report_progress(30, 100);
+            const { discoverExistingAdrs } = await import('./tools/adr-suggestion-tool.js');
+            ctx.info('📄 Phase 2: Analyzing ADR files');
+            ctx.report_progress(60, 100);
+            const result = await discoverExistingAdrs(args);
+            ctx.info('✅ ADR discovery completed successfully');
+            ctx.report_progress(100, 100);
+            return result;
+        }
+        catch (error) {
+            ctx.error?.(`❌ ADR discovery failed: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
+    }
+    async analyzeAdrTimeline(args) {
+        try {
+            const projectPath = args['projectPath'] || this.config.projectPath;
+            const adrDirectory = args['adrDirectory'] || 'docs/adrs';
+            const generateActions = args['generateActions'] ?? true;
+            const thresholdProfile = args['thresholdProfile'];
+            const autoDetectContext = args['autoDetectContext'] ?? true;
+            const includeContent = args['includeContent'] ?? true;
+            const forceExtract = args['forceExtract'] ?? false;
+            const { discoverAdrsInDirectory } = await import('./utils/adr-discovery.js');
+            const { formatActionReport } = await import('./utils/adr-action-analyzer.js');
+            // Discover ADRs with timeline analysis
+            const result = await discoverAdrsInDirectory(adrDirectory, projectPath, {
+                includeContent,
+                includeTimeline: true,
+                timelineOptions: {
+                    forceExtract,
+                    useCache: true,
+                    cacheTTL: 3600,
+                },
+                generateActions,
+                ...(thresholdProfile ? { thresholdProfile } : {}),
+                autoDetectContext,
+            });
+            // Format response
+            let responseText = `# ADR Timeline Analysis\n\n`;
+            responseText += `**Project:** ${projectPath}\n`;
+            responseText += `**ADR Directory:** ${adrDirectory}\n`;
+            responseText += `**Total ADRs:** ${result.totalAdrs}\n\n`;
+            // Add timeline summary
+            if (result.adrs.some((adr) => adr.timeline)) {
+                const withTimeline = result.adrs.filter((adr) => adr.timeline).length;
+                responseText += `## Timeline Data\n\n`;
+                responseText += `- **ADRs with Timeline:** ${withTimeline}/${result.totalAdrs}\n`;
+                const ages = result.adrs
+                    .filter((adr) => adr.timeline)
+                    .map((adr) => adr.timeline.age_days);
+                if (ages.length > 0) {
+                    const avgAge = Math.floor(ages.reduce((a, b) => a + b, 0) / ages.length);
+                    const oldestAge = Math.max(...ages);
+                    responseText += `- **Average ADR Age:** ${avgAge} days\n`;
+                    responseText += `- **Oldest ADR:** ${oldestAge} days\n`;
+                }
+                responseText += `\n`;
+            }
+            // Add action queue report
+            if (result.actionQueue) {
+                responseText += `---\n\n`;
+                responseText += formatActionReport(result.actionQueue, {
+                    projectPath,
+                    thresholdProfile: thresholdProfile || 'auto-detected',
+                });
+            }
+            else if (generateActions) {
+                responseText += `## No Actions Required\n\n`;
+                responseText += `All ADRs are up to date and within acceptable thresholds.\n`;
+            }
+            // Add summary stats
+            if (result.summary.byStatus) {
+                responseText += `\n---\n\n## ADR Status Distribution\n\n`;
+                Object.entries(result.summary.byStatus).forEach(([status, count]) => {
+                    responseText += `- **${status}:** ${count}\n`;
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: responseText,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `# ADR Timeline Analysis Failed\n\n**Error:** ${error instanceof Error ? error.message : String(error)}\n\nPlease check that the ADR directory exists and contains valid ADR files.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
     }
     async reviewExistingAdrs(args) {
         const { reviewExistingAdrs } = await import('./tools/review-existing-adrs-tool.js');
         return await reviewExistingAdrs(args);
     }
+    /**
+     * ADR validation tool implementations
+     */
+    async validateAdr(args) {
+        const { validateAdr } = await import('./tools/adr-validation-tool.js');
+        return await validateAdr(args);
+    }
+    async validateAllAdrs(args) {
+        const { validateAllAdrs } = await import('./tools/adr-validation-tool.js');
+        return await validateAllAdrs(args);
+    }
     /**
      * Research integration tool implementations
      */
@@ -5596,6 +6296,73 @@ Please provide:
         const { generateResearchQuestions } = await import('./tools/research-question-tool.js');
         return await generateResearchQuestions(args);
     }
+    /**
+     * Perform research tool implementation
+     */
+    async performResearch(args, context) {
+        const ctx = context || createNoOpContext();
+        if (!('question' in args) || typeof args['question'] !== 'string') {
+            throw new McpAdrError('Missing required parameter: question', 'INVALID_ARGUMENTS');
+        }
+        try {
+            ctx.info('🔍 Starting research process...');
+            ctx.report_progress(0, 100);
+            ctx.info('📊 Phase 1: Initializing research framework');
+            ctx.report_progress(10, 100);
+            const { performResearch } = await import('./tools/perform-research-tool.js');
+            ctx.info('📚 Phase 2: Executing research orchestration');
+            ctx.report_progress(20, 100);
+            const result = await performResearch(args, ctx // ✅ Pass context to tool function for progress updates
+            );
+            return result;
+        }
+        catch (error) {
+            ctx.error?.(`❌ Research execution failed: ${error instanceof Error ? error.message : String(error)}`);
+            throw new McpAdrError(`Failed to perform research: ${error instanceof Error ? error.message : String(error)}`, 'RESEARCH_EXECUTION_ERROR');
+        }
+    }
+    /**
+     * LLM web search tool implementation
+     */
+    async llmWebSearch(args, context) {
+        const ctx = context || createNoOpContext();
+        if (!('query' in args) || typeof args['query'] !== 'string') {
+            throw new McpAdrError('Missing required parameter: query', 'INVALID_ARGUMENTS');
+        }
+        ctx.info('🌐 Starting LLM-managed web search...');
+        ctx.report_progress(0, 100);
+        const { llmWebSearch } = await import('./tools/llm-web-search-tool.js');
+        return await llmWebSearch(args, ctx // ✅ Pass context to tool function for progress updates
+        );
+    }
+    /**
+     * LLM cloud management tool implementation
+     */
+    async llmCloudManagement(args, context) {
+        const ctx = context || createNoOpContext();
+        if (!('provider' in args) || !('action' in args) || !('llmInstructions' in args)) {
+            throw new McpAdrError('Missing required parameters: provider, action, llmInstructions', 'INVALID_ARGUMENTS');
+        }
+        ctx.info('🔧 Starting LLM-managed cloud operation...');
+        ctx.report_progress(0, 100);
+        const { llmCloudManagement } = await import('./tools/llm-cloud-management-tool.js');
+        return await llmCloudManagement(args, ctx // ✅ Pass context to tool function for progress updates
+        );
+    }
+    /**
+     * LLM database management tool implementation
+     */
+    async llmDatabaseManagement(args, context) {
+        const ctx = context || createNoOpContext();
+        if (!('database' in args) || !('action' in args) || !('llmInstructions' in args)) {
+            throw new McpAdrError('Missing required parameters: database, action, llmInstructions', 'INVALID_ARGUMENTS');
+        }
+        ctx.info('🗄️ Starting LLM-managed database operation...');
+        ctx.report_progress(0, 100);
+        const { llmDatabaseManagement } = await import('./tools/llm-database-management-tool.js');
+        return await llmDatabaseManagement(args, ctx // ✅ Pass context to tool function for progress updates
+        );
+    }
     /**
      * Deployment analysis tool implementation
      */
@@ -5807,11 +6574,117 @@ Please provide:
             return response;
         }
     }
+    /**
+     * Enrich response with state reinforcement and apply masking
+     *
+     * Implements Phase 2 of context decay mitigation by injecting
+     * context reminders every N turns or when response exceeds token threshold.
+     *
+     * Phase 3 extension: Records conversation turns to structured external memory.
+     */
+    async enrichResponseWithStateReinforcement(response, toolName, toolArgs) {
+        const startTime = Date.now();
+        try {
+            // Extract text content from response
+            const textContent = response.content
+                .filter((item) => item.type === 'text')
+                .map(item => item.text)
+                .join('\n\n');
+            if (!textContent) {
+                // No text content to enrich, just apply masking
+                return await this.applyOutputMasking(response);
+            }
+            // Enrich with state reinforcement (Phase 2)
+            const enriched = await this.stateReinforcementManager.enrichResponseWithContext(textContent);
+            // Prepare final response
+            let finalResponse;
+            // Replace text content with enriched version if context was injected
+            if (enriched.contextInjected) {
+                finalResponse = {
+                    ...response,
+                    content: response.content.map(item => {
+                        if (item.type === 'text') {
+                            return {
+                                type: 'text',
+                                text: enriched.enrichedContent,
+                            };
+                        }
+                        return item;
+                    }),
+                };
+            }
+            else {
+                finalResponse = response;
+            }
+            // Record conversation turn (Phase 3: Structured External Memory)
+            if (toolName) {
+                const duration = Date.now() - startTime;
+                // Check if response has expandableId (from tiered response)
+                const expandableIdMatch = textContent.match(/expandableId:\s*(\S+)/);
+                const expandableId = expandableIdMatch ? expandableIdMatch[1] : undefined;
+                await this.conversationMemoryManager.recordTurn({
+                    type: 'tool_call',
+                    toolName,
+                    toolArgs,
+                }, {
+                    content: enriched.enrichedContent || textContent,
+                    tokenCount: enriched.tokenCount,
+                    contextInjected: enriched.contextInjected,
+                    ...(expandableId ? { expandableId } : {}),
+                }, {
+                    duration,
+                    cacheHit: false, // Could be enhanced to track cache hits
+                    errorOccurred: false,
+                });
+                this.logger.debug(`Conversation turn recorded for ${toolName}`, 'McpAdrAnalysisServer', {
+                    turnNumber: enriched.turnNumber,
+                });
+            }
+            // Apply masking to final response
+            return await this.applyOutputMasking(finalResponse);
+        }
+        catch (error) {
+            this.logger.error('State reinforcement or conversation recording failed, returning original response', 'McpAdrAnalysisServer', error instanceof Error ? error : undefined);
+            // Fallback to just masking if enrichment fails
+            return await this.applyOutputMasking(response);
+        }
+    }
     /**
      * Read MCP resource with prompt-driven caching
      */
     async readResource(uri) {
         try {
+            // Import resource router and templated resources (ensures routes are registered)
+            const { resourceRouter } = await import('./resources/resource-router.js');
+            // Import templated resources to register routes
+            await import('./resources/adr-by-id-resource.js');
+            await import('./resources/research-by-topic-resource.js');
+            await import('./resources/todo-by-id-resource.js');
+            await import('./resources/rule-by-id-resource.js');
+            await import('./resources/technology-by-name-resource.js');
+            await import('./resources/pattern-by-name-resource.js');
+            await import('./resources/validated-pattern-by-platform-resource.js');
+            await import('./resources/pattern-sources-by-platform-resource.js');
+            await import('./resources/pattern-base-code-by-platform-resource.js');
+            // Try routing first (handles templated resources)
+            if (resourceRouter.canRoute(uri)) {
+                const result = await resourceRouter.route(uri);
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: result.contentType,
+                            text: JSON.stringify(result.data, null, 2),
+                        },
+                    ],
+                    _meta: {
+                        lastModified: result.lastModified,
+                        etag: result.etag,
+                        cacheKey: result.cacheKey,
+                    },
+                };
+            }
+            // Fall back to static resource handling
             // Parse URI to determine resource type and parameters
             const url = new globalThis.URL(uri);
             const resourceType = url.pathname.replace('/', '');
@@ -5868,6 +6741,222 @@ Please provide:
                         ],
                     };
                 }
+                case 'todo_list': {
+                    const { generateTodoListResource } = await import('./resources/todo-list-resource.js');
+                    const result = await generateTodoListResource();
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'research_index': {
+                    const { generateResearchIndexResource } = await import('./resources/research-index-resource.js');
+                    const result = await generateResearchIndexResource();
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'rule_catalog': {
+                    const { generateRuleCatalogResource } = await import('./resources/rule-catalog-resource.js');
+                    const result = await generateRuleCatalogResource();
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'rule_generation': {
+                    const { generateRuleGenerationResource } = await import('./resources/rule-generation-resource.js');
+                    const result = await generateRuleGenerationResource(undefined, url.searchParams);
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'project_status': {
+                    const { generateProjectStatusResource } = await import('./resources/project-status-resource.js');
+                    const result = await generateProjectStatusResource();
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'deployment_status': {
+                    const { generateDeploymentStatusResource } = await import('./resources/deployment-status-resource.js');
+                    const result = await generateDeploymentStatusResource(undefined, url.searchParams);
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'environment_analysis': {
+                    const { generateEnvironmentAnalysisResource } = await import('./resources/environment-analysis-resource.js');
+                    const result = await generateEnvironmentAnalysisResource(undefined, url.searchParams);
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'memory_snapshots': {
+                    const { generateMemorySnapshotsResource } = await import('./resources/memory-snapshots-resource.js');
+                    const result = await generateMemorySnapshotsResource(undefined, url.searchParams);
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'project_metrics': {
+                    const { generateProjectMetricsResource } = await import('./resources/project-metrics-resource.js');
+                    const result = await generateProjectMetricsResource();
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'deployment_history': {
+                    const { generateDeploymentHistoryResource } = await import('./resources/deployment-history-resource.js');
+                    const result = await generateDeploymentHistoryResource(undefined, url.searchParams);
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'code_quality': {
+                    const { generateCodeQualityResource } = await import('./resources/code-quality-resource.js');
+                    const result = await generateCodeQualityResource(undefined, url.searchParams);
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
+                case 'validated_patterns': {
+                    const { generateValidatedPatternsCatalogResource } = await import('./resources/validated-patterns-catalog-resource.js');
+                    const result = await generateValidatedPatternsCatalogResource();
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: result.contentType,
+                                text: JSON.stringify(result.data, null, 2),
+                            },
+                        ],
+                        _meta: {
+                            lastModified: result.lastModified,
+                            etag: result.etag,
+                            cacheKey: result.cacheKey,
+                        },
+                    };
+                }
                 default:
                     throw new McpAdrError(`Unknown resource type: ${resourceType}`, 'UNKNOWN_RESOURCE');
             }
@@ -5885,6 +6974,22 @@ Please provide:
     async start() {
         // Validate configuration before starting
         await this.validateConfiguration();
+        // Initialize memory entity manager
+        await this.memoryEntityManager.initialize();
+        this.logger.info('Memory Entity Manager initialized', 'McpAdrAnalysisServer');
+        // Initialize conversation memory manager (Phase 3: Structured External Memory)
+        await this.conversationMemoryManager.initialize();
+        this.logger.info('Phase 3 (Structured External Memory) initialized', 'McpAdrAnalysisServer');
+        // Generate initial server context file
+        try {
+            await this.contextGenerator.writeContextFile(this.kgManager, this.memoryEntityManager, this.conversationMemoryManager);
+            this.logger.info('Server context file generated at .mcp-server-context.md', 'McpAdrAnalysisServer');
+        }
+        catch (error) {
+            this.logger.warn('Failed to generate initial server context file', 'McpAdrAnalysisServer', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
         const transport = new StdioServerTransport();
         await this.server.connect(transport);
         // Keep the process alive
@@ -5896,16 +7001,70 @@ Please provide:
     /**
      * File system tool implementations
      */
+    /**
+     * List accessible roots (MCP best practice)
+     */
+    async listRoots() {
+        const roots = this.rootManager.listRoots();
+        const rootsList = roots
+            .map(r => `### ${r.name}\n\n**Path**: \`${r.path}\`\n\n**Description**: ${r.description}\n`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `# Available File System Roots\n\nThese are the directories that can be accessed by this MCP server.\n\n${rootsList}\nUse these paths with \`read_directory\` and \`read_file\` tools to explore and access files.`,
+                },
+            ],
+        };
+    }
+    /**
+     * Read directory contents (MCP best practice for autonomous file discovery)
+     */
+    async readDirectory(args) {
+        const targetPath = args.path || this.config.projectPath;
+        try {
+            const path = await import('path');
+            const resolvedPath = path.resolve(targetPath);
+            // Security check: ensure path is within accessible roots
+            if (!this.rootManager.isPathAllowed(resolvedPath)) {
+                const roots = this.rootManager.listRoots();
+                const rootList = roots.map(r => `  - ${r.name}: ${r.path}`).join('\n');
+                throw new McpAdrError(`Access denied: Path '${targetPath}' is outside accessible roots.\n\nAccessible roots:\n${rootList}\n\nUse list_roots tool for more details.`, 'ACCESS_DENIED');
+            }
+            const { readdir } = await import('fs/promises');
+            const entries = await readdir(resolvedPath, { withFileTypes: true });
+            const files = entries.filter(e => e.isFile()).map(e => `📄 ${e.name}`);
+            const dirs = entries.filter(e => e.isDirectory()).map(e => `📁 ${e.name}/`);
+            const root = this.rootManager.getRootForPath(resolvedPath);
+            const relPath = this.rootManager.getRelativePathFromRoot(resolvedPath);
+            const filesList = files.length > 0 ? files.join('\n') : '(no files)';
+            const dirsList = dirs.length > 0 ? dirs.join('\n') : '(no directories)';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `# Directory: ${targetPath}\n\n**Root**: ${root?.name}\n**Relative Path**: ${relPath || '/'}\n**Full Path**: \`${resolvedPath}\`\n\n## Directories (${dirs.length})\n\n${dirsList}\n\n## Files (${files.length})\n\n${filesList}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new McpAdrError(`Failed to read directory: ${error instanceof Error ? error.message : String(error)}`, 'DIRECTORY_READ_ERROR');
+        }
+    }
     async readFile(args) {
         const { filePath } = args;
         try {
             const fs = await import('fs/promises');
             const path = await import('path');
-            // Resolve path relative to project path for security
-            const safePath = path.resolve(this.config.projectPath, filePath);
-            // Security check: ensure path is within project directory
-            if (!safePath.startsWith(this.config.projectPath)) {
-                throw new McpAdrError('Access denied: Path is outside project directory', 'ACCESS_DENIED');
+            // Resolve path (handle both relative and absolute paths)
+            const safePath = path.resolve(filePath);
+            // Security check: ensure path is within accessible roots
+            if (!this.rootManager.isPathAllowed(safePath)) {
+                const roots = this.rootManager.listRoots();
+                const rootList = roots.map(r => `  - ${r.name}: ${r.path}`).join('\n');
+                throw new McpAdrError(`Access denied: Path '${filePath}' is outside accessible roots.\n\nAccessible roots:\n${rootList}\n\nUse list_roots tool for more details.`, 'ACCESS_DENIED');
             }
             const content = await fs.readFile(safePath, 'utf-8');
             return {
@@ -5979,40 +7138,6 @@ Please provide:
             throw new McpAdrError(`Failed to list directory: ${error instanceof Error ? error.message : String(error)}`, 'DIRECTORY_LIST_ERROR');
         }
     }
-    async manageTodoJson(_args) {
-        try {
-            // TODO management has been deprecated and moved to mcp-shrimp-task-manager
-            this.logger.warn('⚠️ manageTodoJson deprecated - use mcp-shrimp-task-manager instead');
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `⚠️ **TODO Management Tool Deprecated**
-
-This tool (manageTodoJson) has been deprecated and is no longer functional.
-
-**Replacement:** Use the external \`mcp-shrimp-task-manager\` for task management:
-- Task planning and breaking down
-- Task tracking and status updates
-- Task dependencies and priorities
-- Task completion and verification
-
-**Migration:** The system has moved to a memory-centric architecture where task management is handled by external MCP servers rather than internal JSON files.
-
-**Error:** TodoJsonManager was removed - use mcp-shrimp-task-manager for task management`,
-                    },
-                ],
-                isError: false,
-            };
-        }
-        catch (error) {
-            // If it's already a McpAdrError with good details, re-throw it as-is
-            if (error instanceof Error && error.name === 'McpAdrError') {
-                throw error;
-            }
-            throw new McpAdrError(`JSON TODO management failed: ${error instanceof Error ? error.message : String(error)}`, 'TODO_JSON_MANAGEMENT_ERROR');
-        }
-    }
     async generateDeploymentGuidance(args) {
         try {
             const { generateDeploymentGuidance } = await import('./tools/deployment-guidance-tool.js');
@@ -6091,6 +7216,15 @@ This tool has been deprecated and replaced with memory-centric health scoring.
             throw new McpAdrError(`Memory loading failed: ${error instanceof Error ? error.message : String(error)}`, 'MEMORY_LOADING_ERROR');
         }
     }
+    async expandAnalysisSection(args) {
+        try {
+            const { expandAnalysisSection } = await import('./tools/expand-analysis-tool.js');
+            return await expandAnalysisSection(args);
+        }
+        catch (error) {
+            throw new McpAdrError(`Failed to expand analysis: ${error instanceof Error ? error.message : String(error)}`, 'EXPAND_ANALYSIS_ERROR');
+        }
+    }
     async interactiveAdrPlanning(args) {
         try {
             const { interactiveAdrPlanning } = await import('./tools/interactive-adr-planning-tool.js');
@@ -6112,9 +7246,91 @@ This tool has been deprecated and replaced with memory-centric health scoring.
             throw new McpAdrError(`Tool chain orchestration failed: ${error instanceof Error ? error.message : String(error)}`, 'TOOL_CHAIN_ORCHESTRATOR_ERROR');
         }
     }
+    /**
+     * Phase 3: Expand Memory Tool
+     * Retrieves and expands stored content from tiered responses
+     */
+    async expandMemory(args) {
+        try {
+            const { expandMemory } = await import('./tools/conversation-memory-tool.js');
+            return await expandMemory(args, this.conversationMemoryManager);
+        }
+        catch (error) {
+            throw new McpAdrError(`Memory expansion failed: ${error instanceof Error ? error.message : String(error)}`, 'MEMORY_EXPANSION_ERROR');
+        }
+    }
+    /**
+     * Phase 3: Query Conversation History Tool
+     * Searches and retrieves conversation sessions
+     */
+    async queryConversationHistory(args) {
+        try {
+            const { queryConversationHistory } = await import('./tools/conversation-memory-tool.js');
+            return await queryConversationHistory(args, this.conversationMemoryManager);
+        }
+        catch (error) {
+            throw new McpAdrError(`Conversation history query failed: ${error instanceof Error ? error.message : String(error)}`, 'CONVERSATION_QUERY_ERROR');
+        }
+    }
+    /**
+     * Phase 3: Get Conversation Snapshot Tool
+     * Retrieves current conversation context
+     */
+    async getConversationSnapshot(args) {
+        try {
+            const { getConversationSnapshot } = await import('./tools/conversation-memory-tool.js');
+            return await getConversationSnapshot(args, this.conversationMemoryManager);
+        }
+        catch (error) {
+            throw new McpAdrError(`Conversation snapshot retrieval failed: ${error instanceof Error ? error.message : String(error)}`, 'SNAPSHOT_ERROR');
+        }
+    }
+    /**
+     * Phase 3: Get Memory Statistics Tool
+     * Retrieves conversation memory statistics
+     */
+    async getMemoryStats() {
+        try {
+            const { getMemoryStats } = await import('./tools/conversation-memory-tool.js');
+            return await getMemoryStats(this.conversationMemoryManager);
+        }
+        catch (error) {
+            throw new McpAdrError(`Memory stats retrieval failed: ${error instanceof Error ? error.message : String(error)}`, 'MEMORY_STATS_ERROR');
+        }
+    }
+    /**
+     * Get Server Context Tool
+     * Generates comprehensive server context file for LLM @ referencing
+     */
+    async getServerContext(args) {
+        try {
+            const { getServerContext } = await import('./tools/get-server-context-tool.js');
+            return await getServerContext(args, this.kgManager, this.memoryEntityManager, this.conversationMemoryManager);
+        }
+        catch (error) {
+            throw new McpAdrError(`Server context generation failed: ${error instanceof Error ? error.message : String(error)}`, 'SERVER_CONTEXT_ERROR');
+        }
+    }
 }
 /**
- * Main execution
+ * Main execution function for the MCP ADR Analysis Server
+ *
+ * @description Initializes and starts the MCP server with proper configuration,
+ * error handling, and graceful shutdown. Handles command line arguments for
+ * help, version, and test modes.
+ *
+ * @returns {Promise<void>} Resolves when server shuts down gracefully
+ *
+ * @throws {Error} When server initialization fails or configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * // Start the server (typically called from CLI)
+ * await main();
+ * ```
+ *
+ * @since 1.0.0
+ * @category Main
  */
 async function main() {
     const args = process.argv.slice(2);