get_architectural_context

Analyze project architecture to generate architectural decision records, automatically setting up ADR infrastructure when needed for compliance and project success.

Instructions

Get detailed architectural context for specific files or the entire project, automatically sets up ADR infrastructure if missing, and provides outcome-focused workflow for project success

Input Schema

TableJSON Schema

Name	Required	Description
`filePath`	No	Specific file path to analyze (optional, analyzes entire project if not provided)
`includeCompliance`	No	Include compliance checks in the analysis
`conversationContext`	No	Rich context from the calling LLM about user goals and discussion history

Implementation Reference

src/tools/tool-catalog.ts:161-180 (registration)

Registration of the 'get_architectural_context' tool in the central TOOL_CATALOG map, including name, descriptions, category, complexity, token estimates, related tools, keywords, requiresAI flag, and simplified inputSchema.

TOOL_CATALOG.set('get_architectural_context', {
  name: 'get_architectural_context',
  shortDescription: 'Retrieve architectural context and knowledge graph',
  fullDescription:
    'Retrieves the current architectural context including knowledge graph relationships, ADR decisions, and technology mappings.',
  category: 'analysis',
  complexity: 'moderate',
  tokenCost: { min: 2000, max: 5000 },
  hasCEMCPDirective: true, // Phase 4.3: Moderate tool - context assembly
  relatedTools: ['analyze_project_ecosystem', 'discover_existing_adrs'],
  keywords: ['architecture', 'context', 'knowledge', 'graph'],
  requiresAI: false,
  inputSchema: {
    type: 'object',
    properties: {
      includeGraph: { type: 'boolean', default: true },
      includeMetrics: { type: 'boolean', default: false },
    },
  },
});

src/types/tool-arguments.ts:16-25 (schema)

TypeScript interface defining detailed input arguments for the get_architectural_context tool, used for type safety and validation (projectPath, filePath, analysis options). Note: Simplified schema in catalog.

export interface GetArchitecturalContextArgs {
  projectPath?: string;
  filePath?: string;
  includeCompliance?: boolean;
  analysisDepth?: string;
  recursiveDepth?: string;
  technologyFocus?: string[];
  analysisScope?: string[];
  includeEnvironment?: boolean;
}

src/resources/architectural-context-resource.ts:100-251 (helper)

Core logic for generating architectural context data from project ADRs, including ADR discovery, technology/pattern extraction, decision categorization, technology stack building, and recommendations. Likely called by tool handler.

export async function generateArchitecturalContextResource(
  _params: Record<string, string>,
  searchParams: URLSearchParams,
  kgManager?: KnowledgeGraphManager
): Promise<ResourceGenerationResult> {
  const projectPath = searchParams.get('projectPath') || process.cwd();
  const includeDeprecated = searchParams.get('includeDeprecated') !== 'false';
  const includeProposed = searchParams.get('includeProposed') !== 'false';
  const maxDecisions = parseInt(searchParams.get('maxDecisions') || '50', 10);

  const cacheKey = 'architectural-context';

  // Check cache
  const cached = await resourceCache.get<ResourceGenerationResult>(cacheKey);
  if (cached) {
    return cached;
  }

  try {
    // Discover ADRs to build context
    const { discoverAdrsInDirectory } = await import('../utils/adr-discovery.js');
    const pathModule = await import('path');

    const adrDirectory = pathModule.resolve(
      projectPath,
      process.env['ADR_DIRECTORY'] || 'docs/adrs'
    );

    const discoveryResult = await discoverAdrsInDirectory(adrDirectory, projectPath, {
      includeContent: true,
      includeTimeline: false,
    });

    // Categorize ADRs by status
    const statusCounts = {
      accepted: 0,
      deprecated: 0,
      proposed: 0,
      superseded: 0,
      unknown: 0,
    };

    const technologies = new Set<string>();
    const patterns = new Set<string>();
    const decisions: ArchitecturalContextData['decisions'] = [];

    for (const adr of discoveryResult.adrs) {
      const status = (adr.status || 'unknown').toLowerCase();
      if (status in statusCounts) {
        statusCounts[status as keyof typeof statusCounts]++;
      } else {
        statusCounts.unknown++;
      }

      // Skip deprecated if not requested
      if (!includeDeprecated && status === 'deprecated') continue;
      if (!includeProposed && status === 'proposed') continue;

      // Extract technologies from content
      const content = `${adr.context || ''} ${adr.decision || ''} ${adr.consequences || ''}`;
      extractTechnologies(content, technologies);
      extractPatterns(content, patterns);

      // Add to decisions list
      if (decisions.length < maxDecisions) {
        decisions.push({
          id: adr.filename.replace(/\.md$/, ''),
          title: adr.title || 'Untitled',
          status: adr.status || 'unknown',
          category: categorizeAdr(adr.title || '', content),
          impact: determineImpact(content),
          dependencies: extractDependencies(content),
        });
      }
    }

    // Build technology stack
    const technologyStack = categorizeTechnologies([...technologies]);

    // Build patterns list
    const patternsList = [...patterns].map(pattern => ({
      name: pattern,
      description: getPatternDescription(pattern),
      usedIn: findPatternUsage(pattern, discoveryResult.adrs),
      relatedAdrs: findRelatedAdrs(pattern, discoveryResult.adrs),
    }));

    // Generate recommendations
    const recommendations = generateRecommendations(discoveryResult.adrs, statusCounts, [
      ...technologies,
    ]);

    // Get additional context from knowledge graph if available
    if (kgManager) {
      try {
        const kg = await kgManager.loadKnowledgeGraph();
        if (kg && kg.intents) {
          // Extract technologies and patterns from intent goals
          kg.intents.forEach((intent: any) => {
            if (intent.parsedGoals) {
              intent.parsedGoals.forEach((goal: string) => {
                // Simple heuristic to extract tech/pattern mentions
                const lowerGoal = goal.toLowerCase();
                if (lowerGoal.includes('technology') || lowerGoal.includes('framework')) {
                  // Could extract specific technologies here
                }
              });
            }
          });
        }
      } catch {
        // Knowledge graph not available
      }
    }

    const contextData: ArchitecturalContextData = {
      summary: {
        totalAdrs: discoveryResult.totalAdrs,
        activeDecisions: statusCounts.accepted,
        deprecatedDecisions: statusCounts.deprecated,
        proposedDecisions: statusCounts.proposed,
        technologiesUsed: [...technologies].sort(),
        architecturalPatterns: [...patterns].sort(),
      },
      decisions,
      technologyStack,
      patterns: patternsList,
      recommendations,
      timestamp: new Date().toISOString(),
      projectPath,
    };

    const result: ResourceGenerationResult = {
      data: contextData,
      contentType: 'application/json',
      lastModified: new Date().toISOString(),
      cacheKey,
      ttl: 300, // 5 minutes cache
      etag: generateETag(contextData),
    };

    // Cache result
    resourceCache.set(cacheKey, result, result.ttl);

    return result;
  } catch (error) {
    throw new McpAdrError(
      `Failed to generate architectural context: ${error instanceof Error ? error.message : String(error)}`,
      'RESOURCE_GENERATION_ERROR'
    );
  }
}

src/tools/tool-catalog.ts:161-180 (helper)

TOOL_CATALOG entry provides metadata used by tool dispatcher/search_tools for dynamic tool discovery and lightweight listing.

TOOL_CATALOG.set('get_architectural_context', {
  name: 'get_architectural_context',
  shortDescription: 'Retrieve architectural context and knowledge graph',
  fullDescription:
    'Retrieves the current architectural context including knowledge graph relationships, ADR decisions, and technology mappings.',
  category: 'analysis',
  complexity: 'moderate',
  tokenCost: { min: 2000, max: 5000 },
  hasCEMCPDirective: true, // Phase 4.3: Moderate tool - context assembly
  relatedTools: ['analyze_project_ecosystem', 'discover_existing_adrs'],
  keywords: ['architecture', 'context', 'knowledge', 'graph'],
  requiresAI: false,
  inputSchema: {
    type: 'object',
    properties: {
      includeGraph: { type: 'boolean', default: true },
      includeMetrics: { type: 'boolean', default: false },
    },
  },
});

src/resources/tool-catalog-resource.ts:108-108 (registration)
References 'get_architectural_context' as a related tool in the analyze_project_ecosystem example within tool catalog resource.
```
*         relatedTools: ["get_architectural_context"],
```

mcp-adr-analysis-server