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 | Default |
|---|---|---|---|
| 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; } - 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"],