🏗️ Generation Tools Reference

Complete reference for MCP ADR Analysis Server content generation and creation tools.

📋 Quick Reference

Tool	Purpose	Key Parameters	Output
`suggest_adrs`	Generate ADR suggestions	`projectPath`, `maxSuggestions`	ADR recommendations with reasoning
`generate_adr_from_decision`	Create ADR from decision data	`decisionData`, `template`	Complete ADR document
`generate_adr_todo`	Create implementation tasks	`adrDirectory`, `phase`	TODO list with priorities
`generate_content_masking`	Create masked content	`content`, `maskingLevel`	Sanitized content

📝 suggest_adrs

Purpose: Analyze project and suggest missing or needed architectural decision records.

Parameters

interface SuggestAdrsParams {
  projectPath: string; // Required: Absolute path to project
  maxSuggestions?: number; // Maximum number of ADRs to suggest (default: 5)
  analysisScope?: 'technology' | 'architecture' | 'security' | 'all';
  includeStakeholders?: boolean; // Include stakeholder recommendations
  collaborativeMode?: boolean; // Enable collaborative features
  securityFocused?: boolean; // Focus on security-related decisions
  enableTreeSitterAnalysis?: boolean; // Enable AST-based analysis
}

Usage Examples

Basic ADR Suggestions

{
  "tool": "suggest_adrs",
  "parameters": {
    "projectPath": "/path/to/project",
    "maxSuggestions": 3
  }
}

Security-Focused ADR Suggestions

{
  "tool": "suggest_adrs",
  "parameters": {
    "projectPath": "/path/to/project",
    "maxSuggestions": 5,
    "analysisScope": "security",
    "securityFocused": true,
    "enableTreeSitterAnalysis": true
  }
}

Collaborative ADR Planning

{
  "tool": "suggest_adrs",
  "parameters": {
    "projectPath": "/path/to/project",
    "maxSuggestions": 8,
    "analysisScope": "all",
    "includeStakeholders": true,
    "collaborativeMode": true
  }
}

Response Format

interface AdrSuggestion {
  title: string;
  priority: 'low' | 'medium' | 'high' | 'critical';
  category: string;
  rationale: string;
  stakeholders: string[];
  estimatedEffort: string;
  dependencies: string[];
  evidence: string[];
  confidence: number;
}

interface SuggestAdrsResponse {
  suggestions: AdrSuggestion[];
  analysisMetadata: {
    projectType: string;
    technologyStack: string[];
    complexityScore: number;
    analysisDepth: string;
  };
  recommendations: {
    priorityOrder: string[];
    implementationStrategy: string;
    timelineEstimate: string;
  };
}

Common Use Cases

New Project Setup: Identify initial architectural decisions needed
Legacy System Analysis: Find undocumented architectural decisions
Technology Migration: Plan decisions for migration projects
Security Audit: Identify security-related decisions needed
Team Onboarding: Help new team members understand decision needs

📄 generate_adr_from_decision

Purpose: Create a complete ADR document from structured decision data.

Parameters

interface GenerateAdrFromDecisionParams {
  decisionData: {
    title: string;
    context: string;
    decision?: string;
    options?: string[];
    consequences?: string[];
    stakeholders?: string[];
    timeline?: string;
    status?: 'proposed' | 'accepted' | 'deprecated' | 'superseded';
  };
  template?: 'madr' | 'nygard' | 'alexandrian' | 'custom';
  outputPath?: string; // Where to save the ADR file
  includeMetadata?: boolean; // Include creation metadata
  generateId?: boolean; // Auto-generate ADR ID
}

Usage Examples

Basic ADR Generation

{
  "tool": "generate_adr_from_decision",
  "parameters": {
    "decisionData": {
      "title": "Database Technology Selection",
      "context": "Need to choose database technology for new microservice",
      "decision": "Use PostgreSQL for primary data storage",
      "consequences": [
        "Positive: ACID compliance and reliability",
        "Positive: Strong ecosystem and tooling",
        "Challenge: Need PostgreSQL expertise on team"
      ]
    },
    "template": "madr",
    "outputPath": "././adrs/001-database-selection.md"
  }
}

Comprehensive ADR with Stakeholders

{
  "tool": "generate_adr_from_decision",
  "parameters": {
    "decisionData": {
      "title": "API Authentication Strategy",
      "context": "Multiple client applications need secure API access with different authentication requirements",
      "options": [
        "JWT tokens with refresh mechanism",
        "OAuth 2.0 with PKCE",
        "API keys with rate limiting"
      ],
      "decision": "Implement OAuth 2.0 with PKCE for web clients and API keys for service-to-service communication",
      "consequences": [
        "Positive: Industry standard security practices",
        "Positive: Supports multiple client types",
        "Challenge: More complex implementation",
        "Challenge: Need OAuth infrastructure"
      ],
      "stakeholders": ["security-team", "frontend-team", "mobile-team"],
      "timeline": "Implementation by Q2 2024",
      "status": "accepted"
    },
    "template": "madr",
    "includeMetadata": true,
    "generateId": true
  }
}

Custom Template ADR

{
  "tool": "generate_adr_from_decision",
  "parameters": {
    "decisionData": {
      "title": "Monitoring and Observability Strategy",
      "context": "Need comprehensive monitoring for distributed system",
      "decision": "Implement OpenTelemetry with Prometheus and Grafana"
    },
    "template": "custom",
    "customTemplate": {
      "sections": [
        "title",
        "status",
        "context",
        "decision",
        "implementation_plan",
        "monitoring_metrics",
        "consequences"
      ]
    }
  }
}

Response Format

interface GenerateAdrResponse {
  adrContent: string;
  metadata: {
    id: string;
    filename: string;
    template: string;
    createdAt: string;
    wordCount: number;
  };
  validation: {
    isValid: boolean;
    completenessScore: number;
    missingElements: string[];
  };
  suggestions: {
    improvements: string[];
    relatedAdrs: string[];
  };
}

✅ generate_adr_todo

Purpose: Generate implementation tasks and TODO lists from ADR directory analysis.

Parameters

interface GenerateAdrTodoParams {
  adrDirectory: string; // Required: Path to ADR directory
  outputPath?: string; // Where to save TODO file
  phase?: 'planning' | 'implementation' | 'both';
  linkAdrs?: boolean; // Link tasks back to ADRs
  includeRules?: boolean; // Include rule-based tasks
  priorityFilter?: 'low' | 'medium' | 'high' | 'critical';
  securityFocused?: boolean; // Focus on security tasks
  assignees?: string[]; // Suggested assignees
}

Usage Examples

Basic TODO Generation

{
  "tool": "generate_adr_todo",
  "parameters": {
    "adrDirectory": "./adrs",
    "outputPath": "TODO.md",
    "phase": "both"
  }
}

Security-Focused TODO List

{
  "tool": "generate_adr_todo",
  "parameters": {
    "adrDirectory": "./adrs",
    "outputPath": "SECURITY_TODO.md",
    "phase": "implementation",
    "securityFocused": true,
    "priorityFilter": "high",
    "linkAdrs": true,
    "includeRules": true
  }
}

Team-Assigned TODO Generation

{
  "tool": "generate_adr_todo",
  "parameters": {
    "adrDirectory": "./adrs",
    "phase": "implementation",
    "assignees": ["@backend-team", "@security-team", "@devops-team"],
    "linkAdrs": true
  }
}

Response Format

interface TodoItem {
  id: string;
  title: string;
  description: string;
  priority: 'low' | 'medium' | 'high' | 'critical';
  category: string;
  estimatedEffort: string;
  assignee?: string;
  relatedAdr: string;
  dependencies: string[];
  acceptanceCriteria: string[];
}

interface GenerateAdrTodoResponse {
  todos: TodoItem[];
  summary: {
    totalTasks: number;
    byPriority: Record<string, number>;
    byCategory: Record<string, number>;
    estimatedTotalEffort: string;
  };
  recommendations: {
    implementationOrder: string[];
    riskMitigation: string[];
  };
}

🛡️ generate_content_masking

Purpose: Create masked versions of content to hide sensitive information while preserving structure.

Parameters

interface GenerateContentMaskingParams {
  content: string; // Required: Content to mask
  maskingLevel?: 'basic' | 'standard' | 'strict' | 'paranoid';
  preserveStructure?: boolean; // Keep original structure
  includeLineNumbers?: boolean; // Include line number references
  userDefinedPatterns?: string[]; // Custom patterns to mask
  maskingStrategy?: 'replacement' | 'redaction' | 'tokenization';
  outputFormat?: 'text' | 'markdown' | 'json';
}

Usage Examples

Basic Content Masking

{
  "tool": "generate_content_masking",
  "parameters": {
    "content": "const apiKey = 'sk-1234567890abcdef'; const dbPassword = 'mySecretPassword123';",
    "maskingLevel": "standard",
    "preserveStructure": true
  }
}

Advanced Security Masking

{
  "tool": "generate_content_masking",
  "parameters": {
    "content": "Database connection: postgresql://user:password@localhost:5432/mydb",
    "maskingLevel": "strict",
    "preserveStructure": true,
    "userDefinedPatterns": ["postgresql://[^\\s]+", "user:[^@]+@"],
    "maskingStrategy": "tokenization",
    "includeLineNumbers": true
  }
}

Custom Pattern Masking

{
  "tool": "generate_content_masking",
  "parameters": {
    "content": "Company API: COMP_12345_SECRET_TOKEN",
    "maskingLevel": "paranoid",
    "userDefinedPatterns": ["COMP_[A-Z0-9_]+", "SECRET_[A-Z0-9_]+"],
    "outputFormat": "markdown"
  }
}

Response Format

interface ContentMaskingResponse {
  maskedContent: string;
  maskingReport: {
    patternsFound: Array<{
      pattern: string;
      count: number;
      locations: Array<{
        line: number;
        column: number;
      }>;
    }>;
    maskingLevel: string;
    preservedStructure: boolean;
  };
  securityAnalysis: {
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    remainingRisks: string[];
    recommendations: string[];
  };
}

🔧 Advanced Generation Patterns

Chaining Generation Tools

Progressive Content Creation Workflow:

// 1. Analyze project for ADR needs
{
  "tool": "suggest_adrs",
  "parameters": {
    "projectPath": ".",
    "analysisScope": "all"
  }
}

// 2. Generate specific ADRs from suggestions
{
  "tool": "generate_adr_from_decision",
  "parameters": {
    "decisionData": {
      "title": "From suggestion analysis",
      "context": "Based on project analysis"
    }
  }
}

// 3. Create implementation tasks
{
  "tool": "generate_adr_todo",
  "parameters": {
    "adrDirectory": "./adrs",
    "phase": "implementation"
  }
}

// 4. Mask sensitive content for sharing
{
  "tool": "generate_content_masking",
  "parameters": {
    "content": "Generated ADR content",
    "maskingLevel": "standard"
  }
}

Batch Generation

Generate Multiple ADRs:

// Batch ADR generation pattern
const adrSuggestions = [
  { title: 'Database Selection', priority: 'high' },
  { title: 'API Design', priority: 'medium' },
  { title: 'Security Framework', priority: 'critical' },
];

for (const suggestion of adrSuggestions) {
  await generateAdrFromDecision({
    decisionData: {
      title: suggestion.title,
      context: `Generated from analysis for ${suggestion.title}`,
      priority: suggestion.priority,
    },
    template: 'madr',
    outputPath: `././adrs/${suggestion.title.toLowerCase().replace(/\s+/g, '-')}.md`,
  });
}

Template Customization

Custom ADR Templates:

{
  "custom_templates": {
    "security_adr": {
      "sections": [
        "title",
        "status",
        "security_context",
        "threat_model",
        "decision",
        "security_implications",
        "implementation_plan",
        "monitoring_requirements"
      ]
    },
    "api_adr": {
      "sections": [
        "title",
        "status",
        "api_context",
        "design_options",
        "decision",
        "api_specification",
        "backward_compatibility",
        "migration_plan"
      ]
    }
  }
}

📊 Generation Best Practices

1. Content Quality

Comprehensive Context: Provide detailed context for better ADR generation
Clear Decisions: Make decisions explicit and actionable
Evidence-Based: Include evidence and reasoning
Stakeholder Involvement: Identify relevant stakeholders

2. Template Selection

MADR: Best for most architectural decisions
Nygard: Good for simple, quick decisions
Custom: Use for organization-specific requirements
Consistency: Maintain template consistency across project

3. Security Considerations

Content Masking: Always mask sensitive content before sharing
Pattern Recognition: Use comprehensive pattern libraries
Validation: Validate masked content for completeness
Audit Trail: Maintain audit trail of masking operations

4. Automation Integration

CI/CD Integration: Automate ADR generation in pipelines
Template Management: Version control ADR templates
Quality Gates: Implement quality checks for generated content
Feedback Loops: Collect feedback to improve generation quality

Analysis Tools - Tools for project analysis before generation
Security Tools - Security-focused generation tools
Validation Tools - Tools for validating generated content
API Reference - Complete API documentation

Need help with content generation? → Troubleshooting Guide or File an Issue

📋 Quick Reference​

📝 suggest_adrs​

Parameters​

Usage Examples​

Basic ADR Suggestions​

Security-Focused ADR Suggestions​

Collaborative ADR Planning​

Response Format​

Common Use Cases​

📄 generate_adr_from_decision​

Parameters​

Usage Examples​

Basic ADR Generation​

Comprehensive ADR with Stakeholders​

Custom Template ADR​

Response Format​

✅ generate_adr_todo​

Parameters​

Usage Examples​

Basic TODO Generation​

Security-Focused TODO List​

Team-Assigned TODO Generation​

Response Format​

🛡️ generate_content_masking​

Parameters​

Usage Examples​

Basic Content Masking​

Advanced Security Masking​

Custom Pattern Masking​

Response Format​

🔧 Advanced Generation Patterns​

Chaining Generation Tools​

Batch Generation​

Template Customization​

📊 Generation Best Practices​

1. Content Quality​

2. Template Selection​

3. Security Considerations​

4. Automation Integration​

🔗 Related Documentation​

📋 Quick Reference

📝 suggest_adrs

Parameters

Usage Examples

Basic ADR Suggestions

Security-Focused ADR Suggestions

Collaborative ADR Planning

Response Format

Common Use Cases

📄 generate_adr_from_decision

Parameters

Usage Examples

Basic ADR Generation

Comprehensive ADR with Stakeholders

Custom Template ADR

Response Format

✅ generate_adr_todo

Parameters

Usage Examples

Basic TODO Generation

Security-Focused TODO List

Team-Assigned TODO Generation

Response Format

🛡️ generate_content_masking

Parameters

Usage Examples

Basic Content Masking

Advanced Security Masking

Custom Pattern Masking

Response Format

🔧 Advanced Generation Patterns

Chaining Generation Tools

Batch Generation

Template Customization

📊 Generation Best Practices

1. Content Quality

2. Template Selection

3. Security Considerations

4. Automation Integration

🔗 Related Documentation