mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/adr-suggestion-tool.ts:905-1061 (handler)

  The main MCP tool handler function that processes input arguments, generates prompts using helpers, executes AI generation, and returns formatted ADR content with file creation instructions.

  export async function generateAdrFromDecision(args: {
    decisionData: {
      title: string;
      context: string;
      decision: string;
      consequences: string;
      alternatives?: string[];
      evidence?: string[];
    };
    templateFormat?: 'nygard' | 'madr' | 'custom';
    existingAdrs?: string[];
    adrDirectory?: string;
  }): Promise<any> {
    const {
      decisionData,
      templateFormat = 'nygard',
      existingAdrs = [],
      adrDirectory = 'docs/adrs',
    } = args;
  
    try {
      const { generateAdrFromDecision, generateNextAdrNumber, suggestAdrFilename } =
        await import('../utils/adr-suggestions.js');
  
      if (
        !decisionData.title ||
        !decisionData.context ||
        !decisionData.decision ||
        !decisionData.consequences
      ) {
        throw new McpAdrError(
          'Decision data must include title, context, decision, and consequences',
          'INVALID_INPUT'
        );
      }
  
      const result = await generateAdrFromDecision(decisionData, templateFormat, existingAdrs);
  
      // Generate suggested metadata
      const adrNumber = generateNextAdrNumber(existingAdrs);
      const filename = suggestAdrFilename(decisionData.title, adrNumber);
      const fullPath = `${adrDirectory}/${filename}`;
  
      // Execute ADR generation with AI if enabled
      const { executeADRGenerationPrompt } = await import('../utils/prompt-execution.js');
      const executionResult = await executeADRGenerationPrompt(
        result.generationPrompt,
        result.instructions,
        {
          temperature: 0.1,
          maxTokens: 6000,
          responseFormat: 'text',
        }
      );
  
      if (executionResult.isAIGenerated) {
        // AI execution successful - return actual ADR content
        return formatMCPResponse({
          ...executionResult,
          content: `# Generated ADR: ${decisionData.title}
  
  ## ADR Metadata
  - **ADR Number**: ${adrNumber}
  - **Filename**: ${filename}
  - **Full Path**: ${fullPath}
  - **Template Format**: ${templateFormat.toUpperCase()}
  
  ## Generated ADR Content
  
  ${executionResult.content}
  
  ## File Creation Instructions
  
  To save this ADR to your project:
  
  1. **Create the ADR directory** (if it doesn't exist):
     \`\`\`bash
     mkdir -p ${adrDirectory}
     \`\`\`
  
  2. **Save the ADR content** to the file:
     \`\`\`bash
     cat > "${fullPath}" << 'EOF'
     ${executionResult.content}
     EOF
     \`\`\`
  
  3. **Verify the file** was created successfully:
     \`\`\`bash
     ls -la "${fullPath}"
     \`\`\`
  
  ## Next Steps
  
  1. **Review the generated ADR** for accuracy and completeness
  2. **Save the file** using the instructions above
  3. **Update your ADR index** or catalog
  4. **Share with stakeholders** for review and approval
  5. **Plan implementation** of the architectural decision
  
  ## Quality Checklist
  
  - ✅ **Title** is clear and descriptive
  - ✅ **Context** explains the problem and constraints
  - ✅ **Decision** is specific and actionable
  - ✅ **Consequences** cover both positive and negative impacts
  - ✅ **Format** follows ${templateFormat.toUpperCase()} template standards
  - ✅ **Numbering** is sequential (${adrNumber})
  `,
        });
      } else {
        // Fallback to prompt-only mode
        const { ensureDirectoryCompat: ensureDirectory, writeFileCompat: writeFile } =
          await import('../utils/file-system.js');
        const ensureDirPrompt = await ensureDirectory(adrDirectory);
        const writeFilePrompt = await writeFile(fullPath, '[ADR_CONTENT_PLACEHOLDER]');
  
        return {
          content: [
            {
              type: 'text',
              text: `# ADR Generation: ${decisionData.title}
  
  ${result.instructions}
  
  ## Suggested ADR Metadata
  - **ADR Number**: ${adrNumber}
  - **Filename**: ${filename}
  - **Full Path**: ${fullPath}
  - **Template Format**: ${templateFormat.toUpperCase()}
  
  ## Step 1: Create ADR Directory
  ${ensureDirPrompt.prompt}
  
  ## Step 2: Generate ADR Content
  
  ${result.generationPrompt}
  
  ## Step 3: Save ADR to File
  
  After generating the ADR content from Step 2, create the ADR file:
  
  ${writeFilePrompt.prompt}
  
  **Important**: Replace \`[ADR_CONTENT_PLACEHOLDER]\` with the actual generated ADR content from Step 2.
  `,
            },
          ],
        };
      }
    } catch (error) {
      throw new McpAdrError(
        `Failed to generate ADR: ${error instanceof Error ? error.message : String(error)}`,
        'GENERATION_ERROR'
      );
    }
  }

• src/types/tool-arguments.ts:60-65 (schema)

  TypeScript interface defining the input arguments for the generate_adr_from_decision tool.

  export interface GenerateAdrFromDecisionArgs {
    decisionData: DecisionData;
    templateFormat?: 'custom' | 'nygard' | 'madr';
    existingAdrs?: string[];
    adrDirectory?: string;
  }

• src/utils/adr-suggestions.ts:280-338 (helper)

  Helper function that generates the AI prompt and instructions used by the handler to create ADR content.

  export async function generateAdrFromDecision(
    decisionData: {
      title: string;
      context: string;
      decision: string;
      consequences: string;
      alternatives?: string[];
      evidence?: string[];
    },
    templateFormat: 'nygard' | 'madr' | 'custom' = 'nygard',
    existingAdrs?: string[]
  ): Promise<{ generationPrompt: string; instructions: string }> {
    try {
      const { generateAdrTemplatePrompt } = await import('../prompts/adr-suggestion-prompts.js');
  
      const generationPrompt = generateAdrTemplatePrompt(decisionData, templateFormat, existingAdrs);
  
      const instructions = `
  # ADR Generation Instructions
  
  This will generate a complete Architectural Decision Record from the provided decision data.
  
  ## Decision Summary
  - **Title**: ${decisionData.title}
  - **Template Format**: ${templateFormat.toUpperCase()}
  - **Alternatives**: ${decisionData.alternatives?.length || 0} considered
  - **Evidence**: ${decisionData.evidence?.length || 0} pieces
  
  ## Next Steps
  1. **Submit the generation prompt** to an AI agent for ADR creation
  2. **Parse the JSON response** to get the complete ADR
  3. **Review the generated content** for quality and completeness
  4. **Save the ADR** to the appropriate location with suggested filename
  
  ## Expected AI Response Format
  The AI will return a JSON object with:
  - \`adr\`: Complete ADR with content, metadata, and filename
  - \`suggestions\`: Placement, numbering, and review suggestions
  - \`qualityChecks\`: Quality assessment and improvement suggestions
  
  ## Usage Example
  \`\`\`typescript
  const result = await generateAdrFromDecision(decisionData, 'nygard', existingAdrs);
  // Submit result.generationPrompt to AI agent
  // Parse AI response as GeneratedAdr
  \`\`\`
  `;
  
      return {
        generationPrompt,
        instructions,
      };
    } catch (error) {
      throw new McpAdrError(
        `Failed to generate ADR: ${error instanceof Error ? error.message : String(error)}`,
        'GENERATION_ERROR'
      );
    }
  }

• src/utils/adr-suggestions.ts:343-362 (helper)

  Helper utility to generate the next ADR number based on existing ADRs.

  export function generateNextAdrNumber(existingAdrs: string[]): string {
    try {
      // Extract numbers from existing ADR filenames/titles
      const numbers = existingAdrs
        .map(adr => {
          const match = adr.match(/ADR[-_]?(\d+)/i) || adr.match(/(\d+)/);
          return match && match[1] ? parseInt(match[1], 10) : 0;
        })
        .filter(num => num > 0);
  
      const maxNumber = numbers.length > 0 ? Math.max(...numbers) : 0;
      const nextNumber = maxNumber + 1;
  
      return `ADR-${nextNumber.toString().padStart(4, '0')}`;
    } catch (error) {
      // Log to stderr to avoid corrupting MCP protocol
      console.error('[WARN] Failed to generate ADR number:', error);
      return 'ADR-0001';
    }
  }

• src/utils/adr-suggestions.ts:367-383 (helper)

  Helper utility to suggest ADR filename based on title and ADR number.

  export function suggestAdrFilename(title: string, adrNumber?: string): string {
    try {
      const number = adrNumber || 'XXXX';
      const cleanTitle = title
        .toLowerCase()
        .replace(/[^a-z0-9\s-]/g, '')
        .replace(/\s+/g, '-')
        .replace(/-+/g, '-')
        .replace(/^-|-$/g, '');
  
      return `${number.toLowerCase()}-${cleanTitle}.md`;
    } catch (error) {
      // Log to stderr to avoid corrupting MCP protocol
      console.error('[WARN] Failed to suggest filename:', error);
      return 'adr-new-decision.md';
    }
  }