Skip to main content

🎓 Tutorial 1: Your First MCP ADR Analysis

Learning Goal: By the end of this tutorial, you'll understand MCP basics and have created your first architectural decision record.

Prerequisites:

Time Required: 30 minutes

📚 What You'll Learn​

  1. MCP Fundamentals - What is Model Context Protocol and how it works
  2. Server Setup - Installing and configuring the MCP ADR Analysis Server
  3. First Analysis - Running your first project analysis
  4. Creating ADRs - Generating your first architectural decision record
  5. Next Steps - Where to go from here

🔧 Step 1: Understanding MCP​

Model Context Protocol (MCP) connects AI assistants to external tools and data sources. Think of it as a bridge that lets your AI assistant:

  • Access Files - Read and write files in your project
  • Run Analysis - Execute specialized analysis tools
  • Generate Content - Create documents, code, and recommendations
  • Maintain Context - Remember information across conversations

How MCP ADR Analysis Server Fits In​

The MCP ADR Analysis Server specializes in:

  • Project Analysis - Understanding your codebase and architecture
  • Decision Discovery - Finding architectural decisions that need documentation
  • ADR Generation - Creating professional architectural decision records
  • Progress Tracking - Monitoring implementation of architectural decisions

🚀 Step 2: Installation and Setup​

Install the Server​

# Global installation (recommended for learning)
npm install -g mcp-adr-analysis-server

# Verify installation
mcp-adr-analysis-server --version

You should see output like: MCP ADR Analysis Server v2.5.0

If you installed from source instead of globally, run this first from the repository root:

npm install
npm run build

Configure Your MCP Client​

Add this configuration to your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

Important Configuration Notes:

  • Replace /path/to/your/project with your actual project path
  • Get your OpenRouter API key from https://openrouter.ai/keys
  • EXECUTION_MODE: "full" enables AI-powered analysis (use "prompt-only" for basic mode)
  • AI_MODEL specifies which AI model to use (optional, defaults to claude-3-sonnet)
  • LOG_LEVEL: "ERROR" reduces console output (use "INFO" or "DEBUG" for more details)

Test the Connection​

In your MCP client chat (Claude Desktop, Cline, Cursor, or Windsurf), ask the assistant to run the tool:

analyze_project_ecosystem

Equivalent JSON-RPC request (for programmatic clients):

{
  "method": "tools/call",
  "params": {
    "name": "analyze_project_ecosystem",
    "arguments": {
      "projectPath": "."
    }
  }
}

If you see detailed analysis output, you're ready to proceed! 🎉

Initialize the Memory System​

Important: To enable the intelligent memory features (pattern recognition, relationship inference, etc.), you need to load your ADRs into the memory system first:

{
  "tool": "memory_loading",
  "arguments": {
    "action": "load_adrs",
    "forceReload": true
  }
}

This command will:

  • Discover all ADRs in your configured directory
  • Transform them into memory entities
  • Build relationship graphs between decisions
  • Enable intelligent pattern recognition
  • Populate the .mcp-adr-cache directory

After running this, your memory system will be actively learning from your architectural decisions and providing intelligent insights!

Where data is stored: project analysis cache lives in .mcp-adr-cache in your project. Conversation memory snapshots are stored in your OS temp directory under $TMPDIR/{projectName}/conversation-memory/.

Note: The server works in two modes:

  • EXECUTION_MODE: "full" - AI-powered analysis with intelligent insights (requires OpenRouter API key)
  • EXECUTION_MODE: "prompt-only" - Basic analysis with structured prompts for manual AI use

For the full learning experience, we recommend using "full" mode with an OpenRouter API key.

🔍 Step 3: Your First Project Analysis​

Let's analyze a project to understand what the server can do. The MCP ADR Analysis Server uses research-driven architecture to query your live environment instead of relying on static analysis alone.

What is Research-Driven Analysis?​

Research-driven analysis works by:

  1. Cascading through multiple sources in order of reliability:

    • Your project files and code
    • Existing knowledge graph of ADRs and decisions
    • Live environment resources (Docker, Kubernetes, OpenShift, Ansible)
    • Web search (fallback for external context)

  2. Confidence scoring (0-1 scale) determines result reliability

  3. Live environment detection automatically discovers available tools

  4. Red Hat ecosystem support for OpenShift (oc), Podman, and Ansible

Why Research-Driven? This approach helps LLMs with less domain knowledge by providing real-time context from your actual infrastructure instead of guessing or hallucinating.

First: Load ADRs into Memory (If You Have Any)​

If your project already has ADRs in the ./adrs directory (or your configured ADR directory), load them into the memory system first:

{
  "tool": "memory_loading",
  "arguments": {
    "action": "load_adrs",
    "forceReload": true
  }
}

This populates the .mcp-adr-cache directory and enables intelligent pattern recognition.

Create a Sample Project​

If you don't have a project ready, create a simple one:

mkdir my-learning-project
cd my-learning-project

# Create a simple Node.js project
npm init -y

# Add some basic files
echo "const express = require('express');" > server.js
echo "# My Learning Project" > README.md
mkdir src docs

Run Comprehensive Analysis​

In your MCP client, run:

{
  "tool": "analyze_project_ecosystem",
  "arguments": {
    "projectPath": ".",
    "enhancedMode": true,
    "recursiveDepth": "comprehensive"
  }
}

Understanding the Results​

The analysis will show you:

  1. 🏗️ Technology Stack - Languages, frameworks, and tools detected
  2. 📁 Project Structure - Directory organization and patterns
  3. 🔍 Architecture Patterns - Design patterns and architectural styles found
  4. ⚠️ Identified Issues - Potential problems or improvements
  5. 💡 Recommendations - Suggested next steps and improvements

Exercise: Look through the analysis results and identify:

  • What programming language(s) were detected?
  • What project structure pattern was identified?
  • What recommendations were made?

Research-Driven Analysis in Action​

Now let's explore the perform_research tool, which uses the research-orchestrator to answer questions about your project:

{
  "tool": "perform_research",
  "arguments": {
    "question": "What deployment infrastructure is currently available in this project?",
    "projectPath": ".",
    "adrDirectory": "./adrs"
  }
}

What You'll See:

## Research Results

**Confidence**: 85.0% ✓

### Answer

The project has Docker and Kubernetes available. Found docker-compose.yml
configuration for local development and Kubernetes manifests in k8s/ directory.

### Sources Consulted

✓ Project Files: Analyzed 45 files
✓ Knowledge Graph: Found 2 related ADRs
✓ Environment: Detected docker, kubectl
✗ Web Search: Not needed (confidence above threshold)

### Key Findings

- Docker: Container orchestration available
- Kubernetes: kubectl configured and accessible
- Infrastructure decisions documented in ADR-003

Understanding Confidence Scores:

  • ≥70%: High confidence, results are reliable
  • 60-69%: Medium confidence, consider web search fallback
  • <60%: Low confidence, automatic web search triggered

Exercise: Try asking research questions about:

  1. "What database technology is used in this project?"
  2. "Are there any container orchestration tools configured?"
  3. "What testing frameworks are available?"

📋 Step 4: Creating Your First ADR​

Now let's create an architectural decision record based on your project analysis.

Discover What Decisions Need Documentation​

{
  "tool": "suggest_adrs",
  "arguments": {
    "projectPath": ".",
    "analysisScope": "all",
    "maxSuggestions": 3
  }
}

This will suggest 3 architectural decisions that should be documented.

Generate Your First ADR​

Pick one of the suggested decisions and create an ADR:

{
  "tool": "generate_adr_from_decision",
  "arguments": {
    "decisionData": {
      "title": "Web Framework Selection",
      "context": "Need to choose a web framework for the HTTP API",
      "decision": "Express.js",
      "rationale": "Widely adopted, excellent ecosystem, team familiarity",
      "consequences": [
        "Fast development",
        "Large community support",
        "Potential performance limitations for high-scale scenarios"
      ]
    },
    "adrDirectory": "./adrs"
  }
}

Review Your ADR​

Check the ././adrs/ directory. You should see a new file like 001-web-framework-selection.md.

Exercise: Open the ADR file and review:

  • Is the structure clear and professional?
  • Does the rationale make sense for your project?
  • Are the consequences realistic?

Load Your New ADR into Memory​

Now that you've created an ADR, load it into the memory system to enable intelligent insights:

{
  "tool": "memory_loading",
  "arguments": {
    "action": "load_adrs",
    "forceReload": true
  }
}

This will process your new ADR and start building the knowledge graph that powers the intelligent features.

Validate ADR Against Reality​

Use the new research-driven ADR validation to check if your documented decision matches actual implementation:

{
  "tool": "validate_adr",
  "arguments": {
    "adrPath": "././adrs/001-web-framework-selection.md",
    "projectPath": ".",
    "includeEnvironmentCheck": true,
    "confidenceThreshold": 0.6
  }
}

What This Does:

  1. Reads your ADR to understand the documented decision
  2. Researches live environment to check actual implementation
  3. Compares documentation vs reality with confidence scoring
  4. Reports gaps or drift between decision and implementation

Example Result:

## ADR Validation: Web Framework Selection

**Research Confidence**: 78.0% ✓

### Implementation Status: ✓ MATCHES

- Express.js detected in package.json (v4.18.2)
- Express routes found in src/routes/
- Middleware patterns consistent with documented decision

### Environment Check: ✓ PASSED

- Node.js v20.0.0 (meets requirements)
- npm packages installed correctly
- No conflicting frameworks detected

### Validation Result: ADR accurately reflects current implementation

Exercise: Validate all your ADRs at once:

{
  "tool": "validate_all_adrs",
  "arguments": {
    "projectPath": ".",
    "adrDirectory": "./adrs",
    "includeEnvironmentCheck": true,
    "minConfidence": 0.6
  }
}

📈 Step 5: Track Implementation Progress​

ADRs aren't just documentation - they're implementation roadmaps.

Generate TODO Items​

{
  "tool": "generate_adr_todo",
  "arguments": {
    "adrDirectory": "./adrs",
    "todoFormat": "both",
    "includePriorities": true
  }
}

This creates a TODO.md file with actionable tasks based on your ADR.

Check Progress​

As you implement the decisions, track progress:

{
  "tool": "compare_adr_progress",
  "arguments": {
    "todoPath": "TODO.md",
    "adrDirectory": "./adrs"
  }
}

🎯 Step 6: Understanding What You've Accomplished​

Congratulations! You've just:

✅ Set up MCP - Connected an AI assistant to powerful analysis tools
✅ Analyzed Architecture - Used AI to understand your project structure
✅ Created Professional ADRs - Generated industry-standard architectural documentation
✅ Established Process - Set up a system for tracking architectural decisions

Key Concepts You've Learned​

  1. MCP Protocol - How AI assistants connect to external tools
  2. Project Analysis - Automated discovery of architectural patterns
  3. ADR Generation - Creating structured architectural decision records
  4. Implementation Tracking - Monitoring progress on architectural decisions

🚀 Next Steps​

Now that you understand the basics, you can:

Immediate Next Steps​

Explore Specific Use Cases​

Deep Dive into Features​

🆘 Need Help?​

Common Issues​

"Tool not found" error

  • Verify MCP server installation: mcp-adr-analysis-server --version
  • If using a source install, build first: npm install && npm run build
  • Check MCP client configuration
  • Ensure environment variables are set correctly

"Permission denied" errors

  • Check file permissions in your project directory
  • Ensure ADR_DIRECTORY exists or can be created

Analysis seems incomplete

  • Try enhancedMode: true for more comprehensive analysis
  • Increase recursiveDepth to "comprehensive"
  • Check that PROJECT_PATH points to your project root

Get Support​

API Key Issues​

"AI execution not enabled" errors

  • Check that OPENROUTER_API_KEY is set in your MCP configuration
  • Verify your API key is valid at https://openrouter.ai/keys
  • Ensure EXECUTION_MODE is set to "full"

"Permission denied" or rate limit errors

  • Check your OpenRouter account has sufficient credits
  • Try a different AI model (e.g., "openai/gpt-4o-mini" for lower cost)
  • Reduce analysis scope with enhancedMode: false

💡 Bonus: Track Your Learning with @.mcp-server-context.md​

Your Project's Living Memory​

As you've been working through this tutorial, the MCP server has been quietly building a memory of your progress in a special file called .mcp-server-context.md. This auto-generated file is like your project's brain - it remembers everything!

What's Inside?​

The context file tracks:

  • ✅ Tools you've used and how often
  • ✅ Patterns discovered in your project
  • ✅ Active intents and what you're working on
  • ✅ Architecture scores and improvements
  • ✅ Recommendations for next steps
  • ✅ Memory entities and relationships

Try It Now!​

In your AI assistant, use the @ symbol to reference the file:

@.mcp-server-context.md What have I learned in this tutorial?
Show me the patterns discovered and my current project score.

Your AI assistant will respond with:

  • Summary of what tools you used
  • Patterns detected in your project
  • Your current architecture score
  • Recommended next actions

Real-World Examples​

Checking Progress:

@.mcp-server-context.md How has my architecture score improved?

Understanding Discoveries:

@.mcp-server-context.md What architectural patterns did you find?

Planning Next Steps:

@.mcp-server-context.md What should I focus on next?

Why This Matters​

  1. Continuity - Resume work seamlessly by seeing what you were doing
  2. Learning - Track your progress and see patterns emerge
  3. Guidance - Get AI-powered recommendations based on your project
  4. Team Sharing - Share context with team members (they can @ it too!)

Learn More​

Want to master the context file? Check out:

✅ Success Checklist​

You have successfully completed this tutorial if:

  • MCP server is running (you see adr-analysis in your MCP client's server list)
  • You can run analyze_project_ecosystem without errors
  • Memory system is initialized (.mcp-adr-cache directory exists in your project)
  • You've generated your first ADR (check the ./adrs/ directory for a new .md file)

❌ If something isn't working, check the Troubleshooting Guide

Ready for Tutorial 2? → Working with Existing Projects

This tutorial is part of the MCP ADR Analysis Server learning path. Each tutorial builds on the previous one while being useful on its own.