mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/adr-suggestion-tool.ts:936-1094 (handler)

  Primary MCP tool handler for 'generate_adr_from_decision'. Processes args, imports utility, generates AI prompts, executes generation, formats response with metadata, filename suggestions, and 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:49-66 (schema)

  Type definitions for tool inputs: DecisionData and GenerateAdrFromDecisionArgs interfaces used for input validation and typing.
  // Decision Data for ADR Generation export interface DecisionData { title: string; context: string; decision: string; consequences: string; alternatives?: string[]; evidence?: string[]; } // Generate ADR from Decision Arguments export interface GenerateAdrFromDecisionArgs { decisionData: DecisionData; templateFormat?: 'custom' | 'nygard' | 'madr'; existingAdrs?: string[]; adrDirectory?: string; }
• src/utils/adr-suggestions.ts:280-338 (helper)

  Utility function called by the handler to create the specific AI prompt and instructions for generating the ADR content from decision data.
  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/server-context-generator.ts:143-145 (registration)

  Tool name and description registered/listed in the server context generator's hardcoded tools array, confirming it as an available MCP tool.
  name: 'generate_adr_from_decision', description: 'Generate ADR from a specific architectural decision', },