mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/expand-analysis-tool.ts:23-148 (handler)

  The main handler function that executes the tool logic: retrieves expandable analysis content from tiered response manager, handles full or section expansion, formats output in markdown or JSON.

  export async function expandAnalysisSection(
    params: ExpandAnalysisParams
  ): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
    const { expandableId, section, format = 'markdown' } = params;
  
    try {
      const memoryManager = new MemoryEntityManager();
      const tieredManager = new TieredResponseManager(memoryManager);
  
      await tieredManager.initialize();
  
      // Retrieve expandable content
      const expandableContent = await tieredManager.getExpandableContent(expandableId);
  
      if (!expandableContent) {
        throw new McpAdrError(
          `No expandable content found for ID: ${expandableId}. It may have been deleted or expired.`,
          'NOT_FOUND'
        );
      }
  
      // Determine what to return
      let outputContent: string;
      let title: string;
  
      if (section) {
        // Expand specific section
        if (!expandableContent.sections[section]) {
          const availableSections = Object.keys(expandableContent.sections).join(', ');
          throw new McpAdrError(
            `Section "${section}" not found. Available sections: ${availableSections}`,
            'INVALID_INPUT'
          );
        }
  
        outputContent = expandableContent.sections[section];
        title = `${expandableContent.metadata.toolName} - ${section}`;
      } else {
        // Expand full analysis
        outputContent = expandableContent.content;
        title = `${expandableContent.metadata.toolName} - Full Analysis`;
      }
  
      // Format output
      if (format === 'json') {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(
                {
                  expandableId,
                  section: section || 'full',
                  metadata: expandableContent.metadata,
                  content: outputContent,
                },
                null,
                2
              ),
            },
          ],
        };
      }
  
      // Markdown format (default)
      const formattedOutput = `# ${title}
  
  ## 📋 Analysis Details
  
  **Tool:** ${expandableContent.metadata.toolName}
  **Generated:** ${new Date(expandableContent.metadata.timestamp).toLocaleString()}
  **Token Count:** ~${expandableContent.metadata.tokenCount} tokens
  **Expandable ID:** \`${expandableId}\`
  
  ${section ? `**Section:** ${section}` : '**Scope:** Complete Analysis'}
  
  ---
  
  ## 📖 Content
  
  ${outputContent}
  
  ---
  
  ## 🔄 Related Actions
  
  ${
    !section && Object.keys(expandableContent.sections).length > 0
      ? `
  ### Available Sections
  
  You can expand specific sections for focused analysis:
  
  ${Object.keys(expandableContent.sections)
    .map(
      s =>
        `- **${s}**: \`expand_analysis_section\` with \`expandableId: "${expandableId}", section: "${s}"\``
    )
    .join('\n')}
  `
      : ''
  }
  
  ### Tool Arguments Used
  
  \`\`\`json
  ${JSON.stringify(expandableContent.metadata.toolArgs || {}, null, 2)}
  \`\`\`
  
  💡 **Tip:** You can reference this analysis using expandable ID \`${expandableId}\` in future conversations.
  `;
  
      return {
        content: [{ type: 'text', text: formattedOutput }],
      };
    } catch (error) {
      if (error instanceof McpAdrError) {
        throw error;
      }
  
      throw new McpAdrError(
        `Failed to expand analysis: ${error instanceof Error ? error.message : String(error)}`,
        'EXPANSION_ERROR'
      );
    }
  }

• src/tools/expand-analysis-tool.ts:12-21 (schema)

  TypeScript interface defining the input parameters for the expandAnalysisSection handler.

  interface ExpandAnalysisParams {
    /** ID of the expandable analysis */
    expandableId: string;
  
    /** Optional: Specific section to expand (if omitted, returns full analysis) */
    section?: string;
  
    /** Format of the output */
    format?: 'markdown' | 'json';
  }

• src/tools/tool-catalog.ts:979-998 (registration)

  Registration of the tool in the central TOOL_CATALOG with metadata, category, estimated costs, and JSON input schema for MCP tool discovery.

  TOOL_CATALOG.set('expand_analysis_section', {
    name: 'expand_analysis_section',
    shortDescription: 'Expand analysis section',
    fullDescription: 'Expands a specific section of analysis with more detail.',
    category: 'memory',
    complexity: 'moderate',
    tokenCost: { min: 1500, max: 3000 },
    hasCEMCPDirective: true, // Phase 4.3: Moderate tool - section expansion
    relatedTools: ['analyze_project_ecosystem', 'memory_loading'],
    keywords: ['expand', 'analysis', 'section', 'detail'],
    requiresAI: true,
    inputSchema: {
      type: 'object',
      properties: {
        sectionId: { type: 'string' },
        depth: { type: 'string', enum: ['summary', 'detailed', 'comprehensive'] },
      },
      required: ['sectionId'],
    },
  });

• src/utils/tiered-response-manager.ts:317-323 (helper)

  Usage in TieredResponseManager's formatTieredResponse method, which generates instructions referencing the expand_analysis_section tool.

      '💡 **To view full analysis:** Use `expand_analysis_section` tool with `expandableId: "' +
        response.expandableId +
        '"`'
    );
  
    return parts.join('\n');
  }