discover_existing_adrs
Find and catalog existing architectural decision records in your project directory to maintain documentation integrity.
Instructions
Discover and catalog existing ADRs in the project
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| adrDirectory | No | Directory to search for ADRs | docs/adrs |
| includeContent | No | Whether to include ADR content in analysis |
Implementation Reference
- The main handler function for the 'discover_existing_adrs' MCP tool. It initializes the .mcp-adr-cache infrastructure, scans the ADR directory for existing ADRs using discoverAdrsInDirectory helper, formats a comprehensive MCP response with ADR catalog, statistics, recommendations, and example next-step commands.export async function discoverExistingAdrs(args: { adrDirectory?: string; includeContent?: boolean; projectPath?: string; }): Promise<any> { const { adrDirectory = 'docs/adrs', includeContent = false, projectPath = process.cwd() } = args; try { // INITIALIZE COMPLETE CACHE INFRASTRUCTURE (since this is typically the first command) // NOTE: All console output goes to stderr to preserve stdout for MCP JSON-RPC console.error('[ADR-Suggestion] Initializing complete cache infrastructure...'); // 1. TodoJsonManager removed - use mcp-shrimp-task-manager for task management console.error( '[ADR-Suggestion] TodoJsonManager is deprecated and was removed in memory-centric transformation' ); // Skip todo initialization - TodoJsonManager removed console.error('[ADR-Suggestion] Initialized todo-data.json and cache directory'); // 2. ProjectHealthScoring removed - use relationship-based importance instead console.error( '[ADR-Suggestion] ProjectHealthScoring is deprecated and was removed in memory-centric transformation' ); // Skip health scoring initialization - ProjectHealthScoring removed console.error('[ADR-Suggestion] Initialized project-health-scores.json'); // 3. Initialize KnowledgeGraphManager (creates knowledge-graph-snapshots.json and todo-sync-state.json) // Set PROJECT_PATH temporarily for proper initialization const originalConfig = process.env['PROJECT_PATH']; process.env['PROJECT_PATH'] = projectPath; const { KnowledgeGraphManager } = await import('../utils/knowledge-graph-manager.js'); const kgManager = new KnowledgeGraphManager(); await kgManager.loadKnowledgeGraph(); // Creates knowledge-graph-snapshots.json and todo-sync-state.json console.error( '[ADR-Suggestion] Initialized knowledge-graph-snapshots.json and todo-sync-state.json' ); // Restore original config if (originalConfig !== undefined) { process.env['PROJECT_PATH'] = originalConfig; } else { delete process.env['PROJECT_PATH']; } console.error('[ADR-Suggestion] Complete cache infrastructure ready!'); // Use the new ADR discovery utility const { discoverAdrsInDirectory } = await import('../utils/adr-discovery.js'); const discoveryResult = await discoverAdrsInDirectory(adrDirectory, projectPath, { includeContent, includeTimeline: false, }); // Format the results for MCP response return { content: [ { type: 'text', text: `# šÆ Complete ADR Discovery & Cache Infrastructure Initialized ## Cache Infrastructure Status ā **todo-data.json** - JSON-first TODO system initialized ā **project-health-scores.json** - Multi-component project health scoring ā **knowledge-graph-snapshots.json** - Knowledge graph system & intent tracking ā **todo-sync-state.json** - TODO synchronization state ā **Cache Directory** - Complete infrastructure ready at \`.mcp-adr-cache/\` ## ADR Discovery Results ### Discovery Summary - **Directory**: ${discoveryResult.directory} - **Total ADRs Found**: ${discoveryResult.totalAdrs} - **Include Content**: ${includeContent ? 'Yes' : 'No (metadata only)'} ## Discovered ADRs ${ discoveryResult.adrs.length > 0 ? discoveryResult.adrs .map( adr => ` ### ${adr.title} - **File**: ${adr.filename} - **Status**: ${adr.status} - **Date**: ${adr.date || 'Not specified'} - **Path**: ${adr.path} ${adr.metadata?.number ? `- **Number**: ${adr.metadata.number}` : ''} ${adr.metadata?.category ? `- **Category**: ${adr.metadata.category}` : ''} ${adr.metadata?.tags?.length ? `- **Tags**: ${adr.metadata.tags.join(', ')}` : ''} ${ includeContent && adr.content ? ` #### Content Preview \`\`\`markdown ${adr.content.slice(0, 500)}${adr.content.length > 500 ? '...' : ''} \`\`\` ` : '' } ` ) .join('\n') : 'No ADRs found in the specified directory.' } ## Summary Statistics ### By Status ${ Object.entries(discoveryResult.summary.byStatus) .map(([status, count]) => `- **${status}**: ${count}`) .join('\n') || 'No status information available' } ### By Category ${ Object.entries(discoveryResult.summary.byCategory) .map(([category, count]) => `- **${category}**: ${count}`) .join('\n') || 'No category information available' } ## Recommendations ${discoveryResult.recommendations.map(rec => `- ${rec}`).join('\n')} ## Next Steps Based on the discovered ADRs, you can: 1. **Analyze for Missing Decisions**: Use the \`suggest_adrs\` tool with the discovered ADR titles 2. **Generate Implementation TODOs**: Use the \`generate_adr_todo\` tool 3. **Create New ADRs**: Use the \`generate_adr_from_decision\` tool for new decisions ### Example Commands To suggest new ADRs based on discovered ones: \`\`\`json { "tool": "suggest_adrs", "args": { "existingAdrs": ${JSON.stringify(discoveryResult.adrs.map(adr => adr.title))}, "analysisType": "comprehensive" } } \`\`\` To generate a todo list from discovered ADRs: \`\`\`json { "tool": "generate_adr_todo", "args": { "adrDirectory": "${adrDirectory}", "scope": "all" } } \`\`\` ## Raw Discovery Data For programmatic use, the raw discovery data is: \`\`\`json ${JSON.stringify(discoveryResult, null, 2)} \`\`\` `, }, ], }; } catch (error) { throw new McpAdrError( `Failed to discover ADRs: ${error instanceof Error ? error.message : String(error)}`, 'DISCOVERY_ERROR' ); } }