Skip to main content
Glama

mcp-adr-analysis-server

by tosin2013
mcp-concepts.mdโ€ข13.9 kB
# ๐Ÿ’ก Understanding Model Context Protocol (MCP) **Purpose**: This document explains the fundamental concepts behind MCP and how the ADR Analysis Server leverages these concepts for architectural analysis. --- ## ๐Ÿง  What is Model Context Protocol? **Model Context Protocol (MCP)** is a standardized way for AI assistants to interact with external tools, data sources, and services. Think of it as a "universal translator" that allows AI models to: - **Access Real Data** - Read files, databases, APIs, and other external sources - **Execute Actions** - Run commands, modify files, trigger workflows - **Maintain Context** - Remember information across conversations and sessions - **Extend Capabilities** - Add specialized skills beyond what the AI was trained on ### The Problem MCP Solves Before MCP, AI assistants were limited to: - โŒ Only information from their training data (which becomes outdated) - โŒ No ability to access real-time data or current files - โŒ No way to take actions in the real world - โŒ Each integration required custom, one-off solutions With MCP, AI assistants can: - โœ… Access current, real-time information - โœ… Interact with your actual project files and data - โœ… Execute specialized analysis and automation tools - โœ… Use standardized, reusable integrations --- ## ๐Ÿ—๏ธ MCP Architecture ```mermaid graph TB subgraph "Your Environment" User[๐Ÿ‘ค You] AI[๐Ÿค– AI Assistant<br/>Claude, ChatGPT, etc.] end subgraph "MCP Layer" Client[๐Ÿ“ฑ MCP Client<br/>Desktop app, IDE, etc.] Protocol[๐Ÿ”Œ MCP Protocol<br/>JSON-RPC over stdio] end subgraph "MCP Server" Server[๐Ÿ—๏ธ ADR Analysis Server] Tools[๐Ÿ› ๏ธ Tools<br/>37 analysis functions] Resources[๐Ÿ“š Resources<br/>Dynamic content] Prompts[๐Ÿ’ญ Prompts<br/>AI templates] end subgraph "Your Project" Files[๐Ÿ“ Files] Code[๐Ÿ’ป Code] Docs[๐Ÿ“„ Documentation] ADRs[๐Ÿ“‹ ADRs] end User --> AI AI --> Client Client --> Protocol Protocol --> Server Server --> Tools Server --> Resources Server --> Prompts Tools --> Files Tools --> Code Tools --> Docs Tools --> ADRs ``` ### Key Components 1. **MCP Client** - The application that connects your AI assistant to MCP servers 2. **MCP Protocol** - Standardized communication format (JSON-RPC) 3. **MCP Server** - Specialized service that provides tools and data (like our ADR Analysis Server) 4. **Tools** - Functions the AI can call to perform specific tasks 5. **Resources** - Dynamic content the AI can access (files, data, etc.) 6. **Prompts** - Templates that help the AI understand how to use the tools effectively --- ## ๐Ÿ› ๏ธ How Tools Work ### Tool Execution Flow ```mermaid sequenceDiagram participant AI as ๐Ÿค– AI Assistant participant MCP as ๐Ÿ“ก MCP Protocol participant Server as ๐Ÿ—๏ธ ADR Server participant Project as ๐Ÿ“ Your Project AI->>MCP: "I need to analyze this project" MCP->>Server: tool_call: analyze_project_ecosystem Server->>Project: Read files, analyze structure Project-->>Server: Project data Server->>Server: Process with AI analysis Server-->>MCP: Analysis results MCP-->>AI: Structured analysis data AI-->>AI: Generate response for user ``` ### Tool Categories in ADR Analysis Server #### **Analysis Tools** (Understanding) - `analyze_project_ecosystem` - Comprehensive project analysis - `discover_existing_adrs` - Find and catalog existing decisions - `analyze_content_security` - Scan for sensitive information #### **Generation Tools** (Creating) - `generate_adrs_from_prd` - Create ADRs from requirements - `generate_adr_todo` - Extract implementation tasks - `suggest_adrs` - Recommend missing decisions #### **Validation Tools** (Checking) - `compare_adr_progress` - Track implementation progress - `validate_rules` - Check code compliance - `deployment_readiness` - Verify deployment preparation #### **Management Tools** (Organizing) - `manage_cache` - Handle server cache - `smart_git_push` - Secure version control - `troubleshoot_guided_workflow` - Systematic problem solving --- ## ๐Ÿ“š Resources: Dynamic Content Access Resources in MCP are like "live documents" that the AI can read. Unlike static files, resources are generated dynamically based on your current project state. ### Our Key Resources #### **Architectural Knowledge Graph** ``` adr://architectural_knowledge_graph?projectPath=/your/project ``` A comprehensive map of your project's: - Technology stack and dependencies - Architectural patterns and designs - Decision relationships and impacts - Implementation status and progress #### **Analysis Report** ``` adr://analysis_report?projectPath=/your/project&focusAreas=security,performance ``` Real-time analysis including: - Current architectural state - Identified issues and risks - Recommendations and next steps - Progress metrics and trends #### **ADR List** ``` adr://adr_list?adrDirectory=./adrs ``` Live catalog of architectural decisions: - All current ADRs with metadata - Decision status and implementation progress - Cross-references and dependencies - Search and filtering capabilities ### Why Resources Matter Resources enable the AI to: - **Stay Current** - Always work with up-to-date project information - **Understand Context** - See the full picture of your architecture - **Make Connections** - Identify relationships between decisions and code - **Track Progress** - Monitor changes and implementation status --- ## ๐Ÿ’ญ Prompts: AI Guidance Templates Prompts in MCP are specialized templates that help the AI understand how to use tools effectively for specific tasks. ### Prompt Categories #### **Analysis Prompts** Help the AI conduct thorough architectural analysis: - Project ecosystem evaluation templates - Security assessment guidelines - Performance analysis frameworks #### **Generation Prompts** Guide the AI in creating high-quality content: - ADR writing standards and templates - Documentation structure patterns - Code generation guidelines #### **Validation Prompts** Ensure the AI performs comprehensive checks: - Deployment readiness checklists - Rule compliance verification - Progress tracking methodologies ### How Prompts Enhance AI Performance Without prompts, AI might: - Miss important architectural considerations - Generate inconsistent documentation formats - Overlook security or compliance requirements - Fail to follow established best practices With specialized prompts, AI: - โœ… Follows proven architectural analysis methodologies - โœ… Generates consistent, professional documentation - โœ… Applies comprehensive security and compliance checks - โœ… Adheres to industry standards and best practices --- ## ๐Ÿ”„ The AI-MCP Workflow ### Typical Analysis Session 1. **Initial Discovery** ``` AI asks: "What kind of project are we working with?" โ†’ Calls analyze_project_ecosystem โ†’ Gets comprehensive project understanding ``` 2. **Context Building** ``` AI reads: adr://architectural_knowledge_graph โ†’ Understands existing decisions and patterns โ†’ Identifies relationships and dependencies ``` 3. **Gap Analysis** ``` AI calls: suggest_adrs โ†’ Identifies missing architectural decisions โ†’ Prioritizes based on project needs and risks ``` 4. **Documentation Generation** ``` AI calls: generate_adr_from_decision โ†’ Creates professional ADR documents โ†’ Follows established templates and standards ``` 5. **Implementation Planning** ``` AI calls: generate_adr_todo โ†’ Extracts actionable implementation tasks โ†’ Creates prioritized development roadmap ``` 6. **Progress Tracking** ``` AI calls: compare_adr_progress โ†’ Monitors implementation against decisions โ†’ Identifies blockers and next steps ``` ### Benefits of This Workflow - **Systematic** - Follows proven architectural analysis methodologies - **Consistent** - Uses standardized templates and formats - **Comprehensive** - Covers all aspects of architectural decision-making - **Actionable** - Produces concrete next steps and implementation plans - **Traceable** - Maintains clear connection between decisions and implementation --- ## ๐ŸŽฏ Why MCP ADR Analysis Server is Powerful ### Traditional Approach (Without MCP) ``` You โ†’ Generic AI โ†’ Generic responses based on training data ``` - Limited to AI's training knowledge - No access to your actual project - Generic advice that may not apply - No ability to generate actual files or track progress ### MCP-Enhanced Approach ``` You โ†’ AI + MCP โ†’ Specialized tools โ†’ Your actual project โ†’ Tailored analysis ``` - Works with your real project files and structure - Applies specialized architectural analysis techniques - Generates actual ADR documents and implementation plans - Tracks real progress and provides ongoing guidance ### Key Advantages 1. **Real-Time Analysis** - Always works with current project state 2. **Specialized Knowledge** - Applies architectural best practices and methodologies 3. **Actionable Outputs** - Generates actual files, documentation, and plans 4. **Continuous Learning** - Builds knowledge graph that improves over time 5. **Integration-Ready** - Works with your existing tools and workflows --- ## ๐Ÿš€ Advanced MCP Concepts ### Conversational Context MCP enables AI to maintain context across multiple interactions: ```json { "conversationContext": { "projectType": "microservices", "previousDecisions": ["database-selection", "api-gateway"], "currentPhase": "security-review", "constraints": ["budget-limited", "timeline-aggressive"] } } ``` This context helps the AI: - Remember previous decisions and their rationale - Understand project constraints and priorities - Provide consistent recommendations across sessions - Build on previous analysis rather than starting fresh ### Knowledge Graph Integration The server builds a persistent knowledge graph that captures: ```mermaid graph LR subgraph "Project Knowledge" Tech[Technology Stack] Arch[Architecture Patterns] Decisions[ADR Decisions] Issues[Identified Issues] Progress[Implementation Progress] end Tech --> Decisions Arch --> Decisions Decisions --> Issues Decisions --> Progress Progress --> Tech ``` This enables: - **Learning from Experience** - Each analysis improves future recommendations - **Relationship Discovery** - Understanding how decisions impact each other - **Progress Tracking** - Monitoring implementation across time - **Pattern Recognition** - Identifying recurring issues and solutions ### Advanced AI Techniques The server employs sophisticated prompting techniques: #### **Automatic Prompt Engineering (APE)** - Generates optimized prompts for better analysis results - Adapts prompting strategies based on project characteristics - Continuously improves prompt effectiveness through feedback #### **Knowledge Generation** - Builds comprehensive understanding of project context - Synthesizes information from multiple sources - Creates structured knowledge representations #### **Reflexion Framework** - Self-corrects analysis through iterative refinement - Validates findings against multiple criteria - Improves accuracy through reflection and revision --- ## ๐ŸŽ“ Implications for Architecture Work ### How MCP Changes Architecture Analysis **Before MCP:** - Manual analysis of project structure and decisions - Generic architectural advice from documentation - Disconnected tools and processes - Inconsistent documentation and tracking **With MCP:** - Automated, comprehensive project analysis - Tailored recommendations based on actual project state - Integrated workflow from analysis to implementation - Consistent, professional documentation and tracking ### Best Practices for MCP-Enhanced Architecture Work 1. **Start with Comprehensive Analysis** - Use `analyze_project_ecosystem` to build complete understanding - Enable enhanced mode for maximum insight 2. **Leverage Continuous Context** - Include conversation context in tool calls - Build on previous analysis rather than starting fresh 3. **Follow the Full Workflow** - Discovery โ†’ Analysis โ†’ Decision โ†’ Documentation โ†’ Implementation โ†’ Tracking 4. **Use Specialized Tools for Specific Needs** - Security analysis for sensitive projects - Deployment readiness for production systems - Performance analysis for high-scale applications 5. **Maintain the Knowledge Graph** - Regular analysis updates keep the knowledge current - Progressive refinement improves accuracy over time --- ## ๐Ÿ”ฎ The Future of AI-Assisted Architecture MCP represents a fundamental shift toward AI assistants that can: - **Work with Real Data** - Not just trained knowledge - **Take Real Actions** - Generate files, run analysis, track progress - **Maintain Real Context** - Remember and build on previous work - **Provide Real Value** - Actionable insights and implementation guidance The ADR Analysis Server demonstrates this future by providing AI assistants with: - Deep architectural analysis capabilities - Professional documentation generation - Implementation tracking and guidance - Continuous learning and improvement This enables a new level of AI-human collaboration where the AI becomes a true architectural partner, not just a conversational interface to static knowledge. --- **Related Reading:** - **[Tutorial: Your First MCP Analysis](./tutorials/01-first-steps.md)** - Hands-on introduction to using MCP - **[API Reference](./reference/api-reference.md)** - Complete tool documentation - **[Architecture Overview](architecture-decisions.md)** - Design decisions behind the server

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tosin2013/mcp-adr-analysis-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server