🎓 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:

Node.js ≥20.0.0 installed
Basic understanding of software architecture
Text editor or IDE

Time Required: 30 minutes

📚 What You'll Learn

MCP Fundamentals - What is Model Context Protocol and how it works
Server Setup - Installing and configuring the MCP ADR Analysis Server
First Analysis - Running your first project analysis
Creating ADRs - Generating your first architectural decision record
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

bash

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

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

You should see output like: 2.0.7

Configure Your MCP Client

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

json

{
  "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": "docs/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, try this simple command:

analyze_project_ecosystem

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

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.

Create a Sample Project

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

bash

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:

json

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

Understanding the Results

The analysis will show you:

🏗️ Technology Stack - Languages, frameworks, and tools detected
📁 Project Structure - Directory organization and patterns
🔍 Architecture Patterns - Design patterns and architectural styles found
⚠️ Identified Issues - Potential problems or improvements
💡 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?

📋 Step 4: Creating Your First ADR

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

Discover What Decisions Need Documentation

json

{
  "tool": "suggest_adrs",
  "parameters": {
    "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:

json

{
  "tool": "generate_adr_from_decision",
  "parameters": {
    "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": "docs/adrs"
  }
}

Review Your ADR

Check the docs/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?

📈 Step 5: Track Implementation Progress

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

Generate TODO Items

json

{
  "tool": "generate_adr_todo",
  "parameters": {
    "adrDirectory": "docs/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:

json

{
  "tool": "compare_adr_progress",
  "parameters": {
    "todoPath": "TODO.md",
    "adrDirectory": "docs/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

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

🚀 Next Steps

Now that you understand the basics, you can:

Immediate Next Steps

Tutorial 2: Working with Existing Projects - Learn to analyze codebases with existing architecture
Tutorial 3: Advanced Analysis Techniques - Explore security scanning, deployment readiness, and more

Explore Specific Use Cases

How-To: Handle Security Concerns - Scan for sensitive content and credentials
How-To: Prepare for Deployment - Validate your project is ready for production

Deep Dive into Features

API Reference - Complete documentation of all 37 available tools
Architecture Concepts - Understand the deeper architectural principles

🆘 Need Help?

Common Issues

"Tool not found" error

Verify MCP server installation: mcp-adr-analysis-server --version
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

Troubleshooting Guide - Solutions to common problems
GitHub Issues - Report bugs or request features
Main Documentation - Complete project overview

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

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.

🎓 Tutorial 1: Your First MCP ADR Analysis ​

📚 What You'll Learn ​

🔧 Step 1: Understanding MCP ​

How MCP ADR Analysis Server Fits In ​

🚀 Step 2: Installation and Setup ​

Install the Server ​

Configure Your MCP Client ​

Test the Connection ​

🔍 Step 3: Your First Project Analysis ​

Create a Sample Project ​

Run Comprehensive Analysis ​

Understanding the Results ​

📋 Step 4: Creating Your First ADR ​

Discover What Decisions Need Documentation ​

Generate Your First ADR ​

Review Your ADR ​

📈 Step 5: Track Implementation Progress ​

Generate TODO Items ​

Check Progress ​

🎯 Step 6: Understanding What You've Accomplished ​

Key Concepts You've Learned ​

🚀 Next Steps ​

Immediate Next Steps ​

Explore Specific Use Cases ​

Deep Dive into Features ​

🆘 Need Help? ​

Common Issues ​

Get Support ​

API Key Issues ​

🎓 Tutorial 1: Your First MCP ADR Analysis

📚 What You'll Learn

🔧 Step 1: Understanding MCP

How MCP ADR Analysis Server Fits In

🚀 Step 2: Installation and Setup

Install the Server

Configure Your MCP Client

Test the Connection

🔍 Step 3: Your First Project Analysis

Create a Sample Project

Run Comprehensive Analysis

Understanding the Results

📋 Step 4: Creating Your First ADR

Discover What Decisions Need Documentation

Generate Your First ADR

Review Your ADR

📈 Step 5: Track Implementation Progress

Generate TODO Items

Check Progress

🎯 Step 6: Understanding What You've Accomplished

Key Concepts You've Learned

🚀 Next Steps

Immediate Next Steps

Explore Specific Use Cases

Deep Dive into Features

🆘 Need Help?

Common Issues

Get Support

API Key Issues