mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/adr-suggestion-tool.ts:1082-1259 (handler)

  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'
      );
    }
  }