### Getting Started Guide Source

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/dynamic-pattern-configuration-system.md

Configure a 'Getting Started' guide as a supplementary source. These guides are recommended for fast onboarding, prerequisites, and environment setup.

```yaml
- type: 'documentation'
  url: 'https://docs.openshift.com/getting-started/'
  purpose: 'Quick start and initial setup'
  priority: 9
```

--------------------------------

### Manual Steps for Development

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/WEBSITE_SETUP.md

Manually install dependencies and start the development server. Execute 'npm install' to install necessary packages, then 'npm run docs:dev' to start the development server.

```bash
cd docs
npm install               # Install dependencies
npm run docs:dev         # Start development server
npm run docs:build       # Build for production
```

--------------------------------

### Advanced Setup with Scripts

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/WEBSITE_SETUP.md

Utilize shell scripts for initial setup and development server startup. Run './setup-website.sh setup' for the first-time setup and './setup-website.sh dev' to start the development server.

```bash
cd docs
./setup-website.sh setup  # First-time setup
./setup-website.sh dev    # Start development
```

--------------------------------

### Development Setup and Commands

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies, run initial checks, and start the development server. Ensure Node.js and npm meet the specified versions.

```bash
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
npm install

npm run typecheck
npm run lint
npm run test

npm run dev
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/community/CONTRIBUTING.md

Install project dependencies and start the development server.

```bash
npm install
npm run dev
```

--------------------------------

### Quick Start: Setup and Development

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/WEBSITE_SETUP.md

Use these commands to quickly set up and run the documentation website locally. Navigate to the 'docs' directory and run 'npm run setup' followed by 'npm run dev'.

```bash
cd docs
npm run setup
npm run dev
```

--------------------------------

### Environment Setup Task Example

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Example of creating an environment setup task. This snippet is part of a larger workflow for environment validation.

```markdown
- Create environment setup tas...
```

--------------------------------

### Bash Script for First Time Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

A script to perform the initial setup for a project, likely including dependency installation and configuration.

```bash
```bash
./setup.sh
```
```

--------------------------------

### Start Firebase Emulators

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/patterns/firebase-patterns-comparison.md

Initial setup and start commands for Firebase emulators.

```bash
firebase init emulators
firebase emulators:start
```

--------------------------------

### New Project Setup with MCP Tools

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/ide-rules/quickstart-guide.md

Use this example to set up a new project by analyzing its ecosystem, generating ADRs from PRDs, and creating IDE rules.

```bash
# 1. First, analyze the project ecosystem
Tool: analyze_project_ecosystem
Parameters: {
  "analysisDepth": "comprehensive",
  "includeEnvironment": true
}

# 2. Generate ADRs if needed
Tool: generate_adrs_from_prd
Parameters: {
  "prdPath": "PRD.md",
  "outputDirectory": "./adrs"
}

# 3. Generate IDE rules based on architecture
/generate-ide-rules --ide cursor --project . --include-workflows
```

--------------------------------

### Manual Docusaurus Setup and Commands

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/DOCUSAURUS_QUICKSTART.md

Manual setup involves installing dependencies, starting the development server, and building for production. These commands are essential for managing your Docusaurus project.

```bash
cd docs

# Install dependencies
npm install

# Start development server
npm run start

# Build for production
npm run build
```

--------------------------------

### Get Workflow Guidance for New Project Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/ide-rules/universal-workflows.md

Use this tool to get guidance on setting up a new project architecture from requirements. Specify the goal, project context, available assets, and desired timeframe.

```shell
Tool: get_workflow_guidance
Parameters: {
  "goal": "new project architecture setup from PRD",
  "projectContext": "new_project", 
  "availableAssets": ["PRD.md"],
  "timeframe": "thorough_review"
}
```

--------------------------------

### Development Setup and Verification

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/CONTRIBUTING.md

Clone the repository, install dependencies, and run verification commands to ensure your development environment is set up correctly.

```bash
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
npm install

# Verify setup works
npm run typecheck
npm run lint
npm run test

# Start development
npm run dev
```

--------------------------------

### Incremental IDE Rule Adoption: Basic Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/ide-rules/quickstart-guide.md

Start with basic IDE rules for incremental adoption.

```bash
# Phase 1: Basic rules
/generate-ide-rules --ide cursor --project .
```

--------------------------------

### NPM Script for Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

A quick npm script for dependency installation. It is designed for fast execution.

```bash
```bash
npm install
```
```

--------------------------------

### Setup Advanced Documentation Structure

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.md

Use the mcp1_setup_structure command to set up the advanced documentation structure, including examples.

```bash
mcp1_setup_structure --includeExamples=true
```

--------------------------------

### First time setup using npm or Bash script

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/README_SCRIPTS.md

Choose between a simple npm setup or a detailed Bash script setup for your documentation website. Navigate to the docs directory before running the commands.

```bash
cd docs
npm run setup
```

```bash
cd docs
./setup-website.sh setup
```

--------------------------------

### One-Line Setup for Ansible Environment

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/ANSIBLE_QUICKSTART.md

Sets up a Python virtual environment, installs Ansible and MCP dependencies, and installs the required Ansible collection.

```bash
python3.11 -m venv venv-ansible && \
source venv-ansible/bin/activate && \
pip install --upgrade pip setuptools wheel && \
pip install ansible mcp && \
ansible-galaxy collection install tosin2013.mcp_audit
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/development.md

Clone the project repository, navigate into the directory, install Node.js dependencies, build the project, run tests, and start the development server.

```bash
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server

npm install

npm run build

npm test

npm run dev
```

--------------------------------

### Navigate to Docs Directory

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/CONVERSION_CHECKLIST.md

Change the current directory to the 'docs' folder. This is typically the first step before running installation or setup commands.

```bash
cd docs
```

--------------------------------

### Start Docs Development Server

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/development.md

Start a local development server to preview the documentation site.

```bash
# Start development server
npm run start
```

--------------------------------

### Example Use Case: Docker to Kubernetes Migration Context

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/notes/RESEARCH-DRIVEN-INTEGRATION-ANALYSIS.md

Illustrates the initial environment context for a 'Docker to Kubernetes' migration decision, highlighting existing Docker setup and the absence of a Kubernetes cluster.

```text
Auto-discovered environment:
- ✅ Docker 24.0.0 running
- ✅ 15 containers currently deployed
- ❌ No Kubernetes cluster
- ✅ docker-compose.yml configurations
- 🟡 docker-compose used in deployment scripts

Context: User wants to evaluate K8s migration
```

--------------------------------

### Get Development Guidance for New Project Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/ide-rules/universal-workflows.md

Obtain development guidance for the planning phase. Specify the development phase, relevant ADRs, technology stack, and team context.

```shell
Tool: get_development_guidance
Parameters: {
  "developmentPhase": "planning",
  "adrsToImplement": [],
  "technologyStack": [],
  "teamContext": {
    "size": "small_team",
    "experienceLevel": "mixed"
  }
}
```

--------------------------------

### Bash Command for Self-Hosted Option

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Example of a bash command for a self-hosted setup. Ensure proper spacing around fenced code blocks.

```bash
docker run -p 3000:3000 -e FIRECRAWL_API_KEY="YOUR_API_KEY" -e FIRECRAWL_HOST="0.0.0.0" tosin2013/mcp-adr-analysis-server:latest
```

--------------------------------

### Install Docs Dependencies

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/development.md

Install the necessary dependencies for building the project documentation.

```bash
# Install docs dependencies
cd docs
npm install
```

--------------------------------

### Install Node.js and npm

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/mcp-client-compatibility.md

Resolve 'Command not found: npx' errors by installing Node.js and npm, then verifying their installation.

```bash
# Install Node.js and npm
# Then verify installation
node --version
npm --version
```

--------------------------------

### Recommended workflow for new contributors

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/README_SCRIPTS.md

New contributors should use the `setup-website.sh` script for their first-time setup and to access help. This script provides guidance and detailed information.

```bash
# First time (use script for guidance)
./setup-website.sh setup
./setup-website.sh help
```

--------------------------------

### CI/CD Security Integration with GitHub Actions

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/tutorials/security-focused-workflow.md

Set up a GitHub Actions workflow to automate security analysis on every push and pull request. This example includes checkout, Node.js setup, package installation, and environment variable configuration for the security scan.

```yaml
# .github/workflows/security.yml
name: Security Analysis

on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install MCP Server
        run: npm install -g mcp-adr-analysis-server

      - name: Run Security Analysis
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          PROJECT_PATH: ${{ github.workspace }}
          EXECUTION_MODE: full
        run: |
          echo "Running MCP security analysis..."
          # Note: Actual implementation would use MCP client
          # This is a placeholder for the workflow structure
```

--------------------------------

### Run setup-website.sh with a command

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/README_SCRIPTS.md

Execute the advanced Bash script for documentation website management. Use specific commands for setup, development, building, previewing, deployment, cleaning, or help.

```bash
./setup-website.sh [command]
```

--------------------------------

### Update README: Quick Start - Perform Research Example

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/planning/DOCUMENTATION-UPDATE-PLAN.md

This JSON snippet provides an example of how to use the `perform_research` tool within the Quick Start section of the README.md file. It demonstrates a typical question about the project's container orchestration.

```json
{
  "tool": "perform_research",
  "args": {
    "question": "What container orchestration are we using?"
  }
}
```

--------------------------------

### Create a Sample Project

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/notes/media/01-first-steps.md

This bash script sets up a minimal Node.js project for testing the analysis server. It creates a project directory, initializes npm, and adds basic server and README files.

```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
```

--------------------------------

### Example Prompt for Referencing Context

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/tool-context-documentation-plan.md

This example shows how to reference a generated context document in a future prompt to guide tool execution.

```text
Example prompt:
"Using the context from docs/context/bootstrap-{timestamp}.md,
continue the deployment process for {platform}"
```

--------------------------------

### IDE-Triggered CI/CD Pipeline Example

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Illustrates a basic CI/CD pipeline triggered by IDE actions. This example assumes a standard CI/CD setup.

```bash
echo "Running CI/CD pipeline..."
# Add your CI/CD commands here
exit 0
```

--------------------------------

### Start development server using npm or Bash script

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/README_SCRIPTS.md

Initiate the development server for your documentation website. You can use either the npm script or the Bash script for this task.

```bash
npm run dev
```

```bash
./setup-website.sh dev
```

--------------------------------

### Install MCP ADR Analysis Server Standalone Script

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Install the MCP ADR Analysis Server as a standalone script. This is the recommended method for initial setup.

```bash
bash <(curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/install.sh) --standalone
```

--------------------------------

### Build and Preview Site

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/WEBSITE_SETUP.md

Builds the project for production and starts a local server to preview the built site.

```bash
npm run docs:build
npm run docs:preview
```

--------------------------------

### GitHub Actions Workflow for Ansible Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/ANSIBLE_SETUP.md

This snippet shows a GitHub Actions workflow to set up Python, install Ansible, and install the MCP Audit Collection.

```yaml
# Example GitHub Actions workflow
- name: Setup Python 3.11
  uses: actions/setup-python@v4
  with:
    python-version: '3.11'

- name: Install Ansible
  run: |
    python -m venv venv-ansible
    source venv-ansible/bin/activate
    pip install ansible

- name: Install MCP Audit Collection
  run: |
    source venv-ansible/bin/activate
    ansible-galaxy collection install tosin2013.mcp_audit

- name: Run Ansible Tests
  run: |
    source venv-ansible/bin/activate
    cd playbooks
    ansible-playbook test-mcp-server.yml
```

--------------------------------

### Create Sample Project with Security Issues

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/tutorials/security-focused-workflow.md

Sets up a project structure and creates files including package.json, src/index.js, config/database.yml, and Dockerfile, intentionally introducing common security vulnerabilities.

```bash
# Create project structure
mkdir -p src config ./adrs
cd ~/security-tutorial-project

# Create package.json
cat > package.json << 'EOF'
{
  "name": "secure-api-service",
  "version": "1.0.0",
  "description": "A secure API service with authentication",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js"
  },
  "dependencies": {
    "express": "^4.18.0",
    "jsonwebtoken": "^9.0.0",
    "bcrypt": "^5.1.0",
    "helmet": "^6.0.0"
  }
}
EOF

# Create source code with intentional security issues
cat > src/index.js << 'EOF'
const express = require('express');
const jwt = require('jsonwebtoken');
const bcrypt = require('bcrypt');

const app = express();

// ❌ Security Issue: Hardcoded secret
const JWT_SECRET = "super-secret-key-12345";
const API_KEY = "sk-1234567890abcdef";

// ❌ Security Issue: No rate limiting
app.use(express.json());

// ❌ Security Issue: Overly permissive CORS
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Headers', '*');
  next();
});

// Authentication endpoint
app.post('/auth', async (req, res) => {
  const { username, password } = req.body;

  // ❌ Security Issue: Weak password validation
  if (password.length < 4) {
    return res.status(400).json({ error: 'Password too short' });
  }

  // ❌ Security Issue: SQL injection vulnerable (simulated)
  const query = `SELECT * FROM users WHERE username = '${username}'`;

  const token = jwt.sign({ username }, JWT_SECRET);
  res.json({ token });
});

// Protected endpoint
app.get('/api/data', (req, res) => {
  const token = req.headers.authorization;

  // ❌ Security Issue: No proper token validation
  if (!token) {
    return res.status(401).json({ error: 'No token' });
  }

  res.json({ data: 'sensitive information' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
EOF

# Create configuration with secrets
cat > config/database.yml << 'EOF'
development:
  adapter: postgresql
  database: secure_api_dev
  username: admin
  password: "admin123"  # ❌ Security Issue: Weak password in config
  host: localhost
  port: 5432

production:
  adapter: postgresql
  database: secure_api_prod
  username: prod_user
  password: "P@ssw0rd123!"  # ❌ Security Issue: Password in config
  host: db.company.com
  port: 5432
EOF

# Create Docker configuration with security issues
cat > Dockerfile << 'EOF'
FROM node:16

# ❌ Security Issue: Running as root
WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

# ❌ Security Issue: Exposed port without restrictions
EXPOSE 3000

CMD ["npm", "start"]
EOF
```

--------------------------------

### Run Automated Docusaurus Setup Script

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/CONVERSION_CHECKLIST.md

Execute the provided shell script to automate the Docusaurus setup process. This script handles dependency installation and configuration.

```bash
./setup-docusaurus.sh
```

--------------------------------

### Get ADR Suggestions

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/troubleshooting.md

Use this JSON to get ADR suggestions when ADR generation fails. This can help identify missing decision data or provide a starting point for new ADRs.

```json
{
  "tool": "suggest_adrs",
  "parameters": {
    "projectPath": ".",
    "analysisScope": "all",
    "maxSuggestions": 5
  }
}
```

--------------------------------

### Recommended workflow for daily development

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/README_SCRIPTS.md

For daily development, use `npm run dev` for quick iteration. For production builds and deployment, the `setup-website.sh` script is recommended for its detailed feedback and guided process.

```bash
# Daily development
npm run dev

# Building for production
./setup-website.sh build  # Better feedback

# Deploying
./setup-website.sh deploy  # Guided process
```

--------------------------------

### Quick Setup with Environment Variables

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/playbooks/VAULT_SETUP.md

Use environment variables for API keys and project paths for quick local testing. Ensure you activate your virtual environment before running the playbook.

```bash
export OPENROUTER_API_KEY="sk-or-v1-your-api-key-here"
export PROJECT_PATH="/path/to/your/project"

# Run playbook
source venv-ansible/bin/activate
cd playbooks
ansible-playbook test-mcp-server-enhanced.yml
```

--------------------------------

### Install MCP ADR Analysis Server from Source

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to/deploy-to-production.md

Clone the repository, install dependencies, build the project, and run tests.

```bash
# Alternative: Install from source
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
npm install
npm run build
npm test  # Ensure all tests pass
```

--------------------------------

### Update TODOs for Environment Setup Completion

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/ide-rules/environment-validation-workflow.md

Bulk updates TODO items tagged with 'environment' and 'setup' that are currently 'in_progress'. Sets their status to 'completed' and adds a timestamped note indicating environment component installation.

```json
Tool: manage_todo_json
Parameters: {
  "operation": "bulk_update",
  "updates": {
    "status": "completed",
    "notes": "Environment components installed - [timestamp]"
  },
  "filters": {
    "tags": ["environment", "setup"],
    "status": "in_progress"
  }
}
```

--------------------------------

### Bash Command for Git Clone

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Example of cloning a Git repository. Ensure you have Git installed and appropriate permissions.

```bash
git clone https://github.com/anthropics/mcp-adr-analysis-server.git
```

--------------------------------

### Interactive Documentation Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/ide-rules/additional-workflows.md

Configure interactive documentation features within an IDE. This setup enables inline examples, runnable snippets, architecture diagrams, and decision records, generated from code comments, test cases, and usage patterns.

```yaml
interactive_docs:
  features:
    - inline_examples
    - runnable_snippets
    - architecture_diagrams
    - decision_records
  
  generation:
    - from_code_comments
    - from_test_cases
    - from_usage_patterns
```

--------------------------------

### Create Environment Configuration Files

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/tutorials/security-focused-workflow.md

Set up environment configuration files for development and production. Create a `.env.example` file for committed configurations and copy it to `.env` for local development, ensuring `.env` is added to `.gitignore` to prevent committing sensitive data.

```bash
# Create .env.example (safe to commit)
cat > .env.example << 'EOF'
# JWT Configuration
JWT_SECRET=your-super-secure-jwt-secret-here

# External API Configuration
API_KEY=your-api-key-here

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=secure_api_dev
DB_USER=your-db-user
DB_PASSWORD=your-db-password

# Server Configuration
PORT=3000
NODE_ENV=development
EOF

# Create actual .env (DO NOT commit)
cp .env.example .env
# Edit .env with real values

# Add .env to .gitignore
echo ".env" >> .gitignore
```

--------------------------------

### Start Local Development Environment

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/DOCKER_SETUP.md

Use this command to spin up the development environment with hot-reloading. No local Node.js installation is required.

```bash
docker-compose --profile dev up
```

--------------------------------

### New Project Setup Workflow

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/prompting-guide.md

This multi-tool workflow outlines the steps for setting up a new project. It involves analyzing the project structure, suggesting ADRs, generating implementation tasks, and validating deployment readiness.

```markdown
1. "Analyze project structure using analyze_project_ecosystem"
2. "Based on findings, suggest missing ADRs using suggest_adrs"
3. "Generate implementation tasks using generate_adr_todo"
4. "Validate deployment readiness using deployment_readiness"
```

--------------------------------

### Install Dependencies and Build Docs

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/QUICK_START.md

Run these commands from the repository root to install project dependencies and generate API documentation.

```bash
npm install
npm run docs:build
npm run docs:serve
```

--------------------------------

### Clone and Install Project Dependencies

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/README.md

Use these commands to clone the repository, navigate into the project directory, and install dependencies, build the project, and run tests.

```bash
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
npm install && npm run build && npm test
```

--------------------------------

### Configure SOD CLI

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Example configuration for the SOD CLI, specifying the output directory for ADRs. This setup is used for generating documentation.

```json
{
  "output": "./docs/adr"
}
```

--------------------------------

### Prepare Production Environment

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to/deploy-to-production.md

Create a dedicated user and directory for the MCP server, then switch to the new user.

```bash
sudo useradd -m -s /bin/bash mcpserver
sudo usermod -aG sudo mcpserver

sudo su - mcpserver

mkdir -p /opt/mcp-adr-analysis-server
cd /opt/mcp-adr-analysis-server
```

--------------------------------

### Perform Research with Basic Question

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/notes/USER_GUIDANCE.md

Use the 'perform_research' tool with a simple question to get initial information about your project. This is the starting point for most inquiries.

```json
{
  "tool": "perform_research",
  "args": {
    "question": "What container orchestration platform are we using?"
  }
}
```

--------------------------------

### Example: Deployment Phases Configuration

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/patterns/CONTRIBUTING.md

Define deployment phases sequentially with clear names, descriptions, estimated durations, and verification commands. Ensure prerequisites are listed.

```yaml
deploymentPhases:
  - order: 1
    name: 'Prerequisites Validation'
    description: 'Verify tools and access'
    estimatedDuration: '2-5 minutes'
    canParallelize: false
    prerequisites: []
    commands:
      - description: 'Verify CLI tool installed'
        command: 'tool --version'
        expectedExitCode: 0

  - order: 2
    name: 'Deploy Application'
    description: 'Deploy to platform'
    estimatedDuration: '5-10 minutes'
    canParallelize: false
    prerequisites: ['Prerequisites Validation']
    commands:
      - description: 'Run deployment'
        command: 'deploy --config config.yaml'
        expectedExitCode: 0
```

--------------------------------

### New Project Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Use this command to set up a new project with the MCP ADR Analysis Server.

```bash
mcp-adr-analysis-server setup new-project --name "my-new-project"
```

--------------------------------

### Verify Ansible Setup and MCP SDK

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/ANSIBLE_QUICKSTART.md

Verifies the Python version, Ansible version, installed MCP audit collection, and the MCP SDK functionality.

```bash
source venv-ansible/bin/activate
python --version          # Should show 3.11.x
ansible --version         # Should show ansible [core 2.19.x]
ansible-galaxy collection list | grep mcp_audit  # Should show collection
python -c "from mcp import ClientSession; print('MCP SDK OK')"  # Should succeed
```

--------------------------------

### Bad Example: Query Instructions

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/patterns/CONTRIBUTING.md

Avoid single-line, vague query instructions. They lack detail and actionable guidance.

```yaml
queryInstructions: 'Read this for information'
```

--------------------------------

### Basic ADR Bootstrap Validation Configuration

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/reference/validation-tools.md

Example of a basic configuration for `validate_adr_bootstrap`. This setup validates the ADR directory using the 'madr' compliance framework.

```json
{
  "tool": "validate_adr_bootstrap",
  "parameters": {
    "adrDirectory": "./adrs",
    "complianceFramework": "madr"
  }
}
```

--------------------------------

### CI/CD Deployment Example

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/examples/bootstrap-workflow-guide-for-users.md

Integrate deployment steps into a CI/CD workflow using bootstrap and validation scripts.

```yaml
# .github/workflows/deploy.yml
- name: Deploy to Kubernetes
  run: |
    ./bootstrap.sh
    ./validate_bootstrap.sh
```

--------------------------------

### Perform Basic Research

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/notes/research-integration.md

Use this command for simple research questions about project authentication or deployment patterns. No special setup is required beyond having the tool installed.

```bash
# Research authentication methods
mcp-adr perform_research --question "What authentication methods are used in this project?"

```

```bash
# Investigate deployment patterns
mcp-adr perform_research --question "How is the application deployed?"

```

--------------------------------

### Incremental Adoption Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Configure the analysis server for an incremental adoption strategy within the project.

```bash
mcp-adr-analysis-server setup incremental --strategy "module-by-module" --start "module-a"
```

--------------------------------

### MCP Client Configuration Example

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

This JSON configuration specifies client-side settings, including the server address and port. Adjust these values to match your server setup.

```json
{
  "server_address": "http://localhost:8080",
  "api_key": "your_api_key_here"
}
```

--------------------------------

### Example Server Context File

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/server-context-file.md

This markdown file provides a structured overview of the server's state, including project details, available tools, memory status, and recent analytics. Use this file to give LLMs immediate context.

```markdown
# MCP Server Context & Memory

> **Last Updated**: 2025-01-12T15:30:00Z

## 🎯 Server Quick Reference

**Name**: mcp-adr-analysis-server
**Project Path**: `/home/user/my-project`
**ADR Directory**: `docs/adrs`

### Available Tools

1. **adr_suggestion** - Suggest new ADRs
2. **smart_score** - Score architecture (0-100)
3. **deployment_readiness** - Validate deployment
   ...

## 🧠 Memory & Knowledge Graph Status

### Active Intents

**Total**: 15 | **Active**: 2 | **Completed**: 13

**Recent Intents**:

- **Implement database migration strategy** - executing - 2h ago
- **Select API gateway solution** - planning - 1d ago
  ...

### Memory Entities

**Total Entities**: 28
**Relationships**: 45
**Average Confidence**: 87%

**Entity Breakdown**:

- Architectural Decisions: 12
- Technical Decisions: 8
- Observations: 5
- Patterns: 3

## 📊 Recent Analytics

### Tool Usage

1. **adr_suggestion**: 34 calls
2. **smart_score**: 28 calls
3. **deployment_readiness**: 15 calls

### Score Trends

- **Current Score**: 87/100
- **Improvement**: +12 points
  ...
```

--------------------------------

### Example Markdown List Item

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

Markdown lists should be properly indented and surrounded by blank lines. Ordered list items should typically start with '1.' for consistency.

```markdown
1. Install Yeoman and the Langium generator:

```

```markdown
2. Run the generator and answer the prompts:

```

```markdown
3. Open the new folder in VS Code and install the recommended extensions.

```

```markdown
4. Run the `npm install` command in the project directory.

```

```markdown
5. Run the `npm run quickstart` command.

```

--------------------------------

### New DI Mocking Example

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/test-infrastructure-simplification-summary.md

Demonstrates simple dependency injection (DI) mocking for tests. This method is robust, fast, and easy to understand, requiring minimal setup.

```typescript
// Simple DI mocking
test('tool works', async () => {
  const mockDeps = {
    fs: { readFile: jest.fn().mockResolvedValue('content') },
  };

  const result = await tool(args, mockDeps);
  expect(result).toBeDefined();
});
```

--------------------------------

### Build Production Docs

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/development.md

Build the production-ready static site for the documentation.

```bash
# Build production site
npm run build
```

--------------------------------

### Bootstrap Deployment Output

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/examples/bootstrap-workflow-guide-for-users.md

Example output from the bootstrap.sh script, showing the progress and success of each deployment phase, including validation, namespace setup, secrets, and application deployment.

```text
========================================
Bootstrap Deployment - kubernetes
========================================

Phase 1: Prerequisites Validation
  ✓ kubectl is installed
  ✓ Cluster is accessible

Phase 2: Namespace Setup
  ✓ Created namespace: myapp

Phase 3: Secrets
  ✓ Created secrets from .env

Phase 4: Application Deployment
  ✓ Deployment created: myapp
  ✓ Service created: myapp

Phase 5: Waiting for pods...
  ✓ Pods are running (3/3)

========================================
✅ Bootstrap complete! (took 2m 34s)
========================================
```

--------------------------------

### Example File Naming Conventions

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/tool-context-documentation-plan.md

Illustrates the format for naming context files, including tool category, detail, and ISO date.

```text
bootstrap-openshift-20250119T143022.md
```

```text
deployment-readiness-check-20250119T101500.md
```

```text
research-validated-patterns-20250118T154433.md
```

```text
planning-microservices-architecture-20250115.md
```

--------------------------------

### Build and Serve API Documentation Locally

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/README.md

Install dependencies, generate API documentation using TypeDoc, and serve it locally. Ensure you have Node.js and npm installed.

```bash
npm install          # Required once after cloning (installs typedoc)
npm run docs:build   # Generate API docs into docs/api/
npm run docs:serve   # Serve locally via Python HTTP server
```

--------------------------------

### Knowledge Graph Query Related Code

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/explanation/ai-architecture-concepts.md

Example of querying the Knowledge Graph to find related code based on a starting node and edge type. Allows specifying the search depth.

```typescript
// Query related code
const relatedCode = await knowledgeGraph.query({
  from: 'adr-001',
  edgeType: 'IMPLEMENTS',
  depth: 2,
});
```

--------------------------------

### Bash Command for Firecrawl Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

This command is used to set up Firecrawl, likely involving installation or configuration. Ensure proper blank lines around this code block as per markdown linting rules.

```bash
firecrawl install
```

--------------------------------

### Bash Command for Website Setup

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/reports/markdown-validation_20251003_185155.txt

This command is used for setting up the website. Ensure the environment is correctly configured before execution.

```bash
npm run dev -- --open
```

--------------------------------

### Start Production Testing Environment

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/DOCKER_SETUP.md

This command starts the production testing environment, including Nginx serving, Gzip compression, security headers, and asset caching.

```bash
docker-compose --profile prod up --build
```

--------------------------------

### Install and Verify MCP Python SDK

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/ANSIBLE_SETUP.md

Steps to install the MCP Python SDK using pip and verify its installation by importing a class.

```bash
source venv-ansible/bin/activate
pip install mcp

# Verify installation
python -c "from mcp import ClientSession; print('MCP SDK OK')"
```

--------------------------------

### Bootstrap Deployment Output Example

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/examples/bootstrap-workflow-guide-for-users.md

This is an example of the output you can expect when running the bootstrap script, showing the progression through different deployment phases and validation checks.

```bash
========================================
Bootstrap Deployment - kubernetes
Pattern: Kubernetes
========================================

Starting Phase 1: Prerequisites Validation
  → Verify kubectl is installed
kubectl version --client
  → Verify cluster connectivity
kubectl cluster-info
✓ Phase 1 complete

Starting Phase 2: Namespace Setup
  → Create namespace
kubectl create namespace myapp
✓ Phase 2 complete

...

========================================
✅ Bootstrap deployment complete!
========================================

```

--------------------------------

### JSDoc Example for analyzeProject

Source: https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/development.md

Example of JSDoc comments for a public function, including parameter, return, and throws tags, along with a usage example.

```typescript
/**
 * Analyzes a project for architectural patterns
 *
 * @param projectPath - Absolute path to the project root
 * @param options - Analysis configuration options
 * @returns Analysis result with detected patterns
 * @throws {Error} When project path doesn't exist
 *
 * @example
 * ```typescript
 * const result = await analyzeProject('/path/to/project', {
 *   depth: 'comprehensive'
 * });
 * ```
 */
export async function analyzeProject(
  projectPath: string,
  options: AnalysisOptions
): Promise<AnalysisResult> {
  // Implementation
}
```