mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/research-integration-tool.ts:362-448 (handler)

  Main MCP tool handler for 'create_research_template'. Validates input, imports helper to generate template, creates filename, and returns structured response with template content and next steps.

  export async function createResearchTemplate(args: {
    title?: string;
    projectPath?: string;
    researchType?: string;
    category?: string;
    researchPath?: string;
    includeProjectAnalysis?: boolean;
  }): Promise<any> {
    const {
      title = args.researchType || 'Research Template',
      projectPath: _projectPath = '/project',
      researchType = 'general',
      category = researchType || 'general',
      researchPath = 'docs/research',
      includeProjectAnalysis: _includeProjectAnalysis = false,
    } = args;
  
    try {
      // Validate title parameter
      if (!title || typeof title !== 'string') {
        throw new Error('Title is required and must be a string');
      }
  
      const { createResearchTemplate } = await import('../utils/research-integration.js');
  
      const template = createResearchTemplate(title, category);
      const filename = `${title
        .toLowerCase()
        .replace(/[^a-z0-9\s-]/g, '')
        .replace(/\s+/g, '-')}.md`;
      const fullPath = `${researchPath}/${filename}`;
  
      return {
        content: [
          {
            type: 'text',
            text: `# Research Template Created
  
  ## Template Details
  - **Title**: ${title}
  - **Category**: ${category}
  - **Filename**: ${filename}
  - **Full Path**: ${fullPath}
  
  ## Template Content
  
  \`\`\`markdown
  ${template}
  \`\`\`
  
  ## Next Steps
  
  1. **Save the template** to the specified path: \`${fullPath}\`
  2. **Fill in the research details** following the template structure
  3. **Conduct your research** and document findings
  4. **Use the research integration tool** to analyze impact on ADRs
  
  ## Template Sections
  
  - **Research Question**: Define what you're investigating
  - **Background**: Provide context and motivation
  - **Methodology**: Describe your research approach
  - **Key Findings**: Document specific discoveries with evidence
  - **Implications**: Analyze architectural and technology impact
  - **Recommendations**: Provide actionable suggestions
  - **Related ADRs**: Link to potentially affected decisions
  - **Next Steps**: Plan follow-up actions
  
  ## Research Best Practices
  
  - Use clear, specific research questions
  - Document evidence and sources thoroughly
  - Assess confidence levels for findings
  - Consider architectural implications early
  - Link findings to existing ADRs when relevant
  - Plan for regular research reviews and updates
  `,
          },
        ],
      };
    } catch (error) {
      throw new McpAdrError(
        `Failed to create research template: ${error instanceof Error ? error.message : String(error)}`,
        'TEMPLATE_CREATION_ERROR'
      );
    }
  }

• src/utils/research-integration.ts:713-780 (helper)

  Supporting utility function that generates the actual Markdown template content for research documents based on title and category.

  export function createResearchTemplate(title: string, category: string = 'general'): string {
    const date = new Date().toISOString().split('T')[0];
  
    return `# ${title}
  
  **Date**: ${date}
  **Category**: ${category}
  **Status**: In Progress
  
  ## Research Question
  
  [What specific question or problem is this research addressing?]
  
  ## Background
  
  [Provide context and background information]
  
  ## Methodology
  
  [Describe how the research was conducted]
  
  ## Key Findings
  
  ### Finding 1
  - **Description**: [Detailed description]
  - **Evidence**: [Supporting evidence or data]
  - **Confidence**: [High/Medium/Low]
  - **Source**: [Source of information]
  
  ### Finding 2
  - **Description**: [Detailed description]
  - **Evidence**: [Supporting evidence or data]
  - **Confidence**: [High/Medium/Low]
  - **Source**: [Source of information]
  
  ## Implications
  
  ### Architectural Impact
  [How do these findings impact architectural decisions?]
  
  ### Technology Choices
  [What technology choices are affected?]
  
  ### Risk Assessment
  [What risks are identified or mitigated?]
  
  ## Recommendations
  
  1. [Specific recommendation 1]
  2. [Specific recommendation 2]
  3. [Specific recommendation 3]
  
  ## Related ADRs
  
  - [List any ADRs that might be affected by this research]
  
  ## Next Steps
  
  - [ ] [Action item 1]
  - [ ] [Action item 2]
  - [ ] [Action item 3]
  
  ## References
  
  - [Reference 1]
  - [Reference 2]
  - [Reference 3]
  `;

• src/tools/research-integration-tool.ts:362-369 (schema)

  TypeScript type definition for the tool input parameters (schema). Defines optional parameters like title, category, paths, etc.

  export async function createResearchTemplate(args: {
    title?: string;
    projectPath?: string;
    researchType?: string;
    category?: string;
    researchPath?: string;
    includeProjectAnalysis?: boolean;
  }): Promise<any> {

• src/utils/server-context-generator.ts:252-253 (registration)

  Tool listed in server context generator's hardcoded tool catalog, indicating availability and description.

  name: 'create_research_template',
  description: 'Create structured research templates for investigations',