docs update

.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+    paths: [ 'docs/**', 'mkdocs.yml', 'requirements.txt' ]
+  pull_request:
+    branches: [ main ]
+    paths: [ 'docs/**', 'mkdocs.yml', 'requirements.txt' ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+        if: github.ref == 'refs/heads/main'
+
+      - name: Build documentation
+        env:
+          PROJECT_VERSION: ${{ github.ref_name }}
+          BUILD_DATE: ${{ github.event.head_commit.timestamp }}
+        run: |
+          mkdocs build --clean --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v2
+        if: github.ref == 'refs/heads/main'
+        with:
+          path: ./site
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -60,6 +60,10 @@ pnpm dev
 
 ## Documentation
 
+**📚 [View Full Documentation](https://raxitai.github.io/mcp-oauth-sample/)** - Interactive Material for MkDocs site
+
+### Quick Reference
+
 | Topic | Description |
 |-------|-------------|
 | [🚀 Setup Guide](./docs/setup.md) | Complete installation and configuration |
@@ -71,6 +75,20 @@ pnpm dev
 | [❓ Troubleshooting](./docs/troubleshooting.md) | Common issues and solutions |
 | [👨‍💻 Development](./docs/development.md) | Development guide and contributing |
 
+### Local Documentation Development
+
+```bash
+# Serve documentation locally with hot reload
+./docs-serve.sh
+
+# Or on Windows
+docs-serve.bat
+
+# Manual setup
+pip install -r requirements.txt
+mkdocs serve
+```
+
 ## MCP Specification Compliance
 
 This implementation is fully compliant with the MCP Authorization Specification. 

docs-serve.bat

@@ -0,0 +1,61 @@
+@echo off
+REM MkDocs development server script for Windows
+
+echo 🚀 Setting up MkDocs for MCP OAuth Sample documentation...
+
+REM Check if Python is installed
+python --version >nul 2>&1
+if errorlevel 1 (
+    echo ❌ Python is required but not installed.
+    echo Please install Python and try again.
+    pause
+    exit /b 1
+)
+
+REM Check if pip is installed
+pip --version >nul 2>&1
+if errorlevel 1 (
+    echo ❌ pip is required but not installed.
+    echo Please install pip and try again.
+    pause
+    exit /b 1
+)
+
+REM Create virtual environment if it doesn't exist
+if not exist "venv" (
+    echo 📦 Creating virtual environment...
+    python -m venv venv
+)
+
+REM Activate virtual environment
+echo 🔄 Activating virtual environment...
+call venv\Scripts\activate.bat
+
+REM Install/upgrade pip
+echo ⬆️ Upgrading pip...
+python -m pip install --upgrade pip
+
+REM Install dependencies
+echo 📥 Installing MkDocs dependencies...
+pip install -r requirements.txt
+
+REM Check if mkdocs.yml exists
+if not exist "mkdocs.yml" (
+    echo ❌ mkdocs.yml not found in current directory.
+    echo Please run this script from the project root.
+    pause
+    exit /b 1
+)
+
+echo ✅ Setup complete!
+echo.
+echo 🌐 Starting MkDocs development server...
+echo 📖 Documentation will be available at: http://127.0.0.1:8000
+echo 🔄 The server will auto-reload when you make changes to the docs.
+echo ⏹️ Press Ctrl+C to stop the server.
+echo.
+
+REM Start the development server
+mkdocs serve
+
+pause

docs-serve.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# MkDocs development server script
+
+set -e
+
+echo "🚀 Setting up MkDocs for MCP OAuth Sample documentation..."
+
+# Check if Python is installed
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Python 3 is required but not installed."
+    echo "Please install Python 3 and try again."
+    exit 1
+fi
+
+# Check if pip is installed
+if ! command -v pip &> /dev/null; then
+    echo "❌ pip is required but not installed."
+    echo "Please install pip and try again."
+    exit 1
+fi
+
+# Create virtual environment if it doesn't exist
+if [ ! -d "venv" ]; then
+    echo "📦 Creating virtual environment..."
+    python3 -m venv venv
+fi
+
+# Activate virtual environment
+echo "🔄 Activating virtual environment..."
+source venv/bin/activate
+
+# Install/upgrade pip
+echo "⬆️ Upgrading pip..."
+pip install --upgrade pip
+
+# Install dependencies
+echo "📥 Installing MkDocs dependencies..."
+pip install -r requirements.txt
+
+# Check if mkdocs.yml exists
+if [ ! -f "mkdocs.yml" ]; then
+    echo "❌ mkdocs.yml not found in current directory."
+    echo "Please run this script from the project root."
+    exit 1
+fi
+
+echo "✅ Setup complete!"
+echo ""
+echo "🌐 Starting MkDocs development server..."
+echo "📖 Documentation will be available at: http://127.0.0.1:8000"
+echo "🔄 The server will auto-reload when you make changes to the docs."
+echo "⏹️ Press Ctrl+C to stop the server."
+echo ""
+
+# Start the development server
+mkdocs serve

docs/hooks.py

@@ -0,0 +1,20 @@
+import os
+import logging
+from mkdocs.config import config_options
+from mkdocs.plugins import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+class CustomHooksPlugin(BasePlugin):
+    """Custom hooks for MCP OAuth Sample documentation"""
+
+    def on_env(self, env, config, files, **kwargs):
+        """Add custom environment variables to the Jinja2 environment"""
+        env.globals['project_version'] = os.environ.get('PROJECT_VERSION', '1.0.0')
+        env.globals['build_date'] = os.environ.get('BUILD_DATE', 'unknown')
+        return env
+
+    def on_page_markdown(self, markdown, page, config, files, **kwargs):
+        """Process markdown before conversion to HTML"""
+        # Add custom processing if needed
+        return markdown

docs/index.md

@@ -1,6 +1,15 @@
 # MCP OAuth Sample Documentation
 
-Welcome to the comprehensive documentation for the MCP OAuth Sample project - an OAuth 2.1 authorization server with Model Context Protocol (MCP) integration.
+<div class="status-indicator online">
+  <span>🟢</span>
+  <span>Live Demo Available</span>
+</div>
+
+Welcome to the comprehensive documentation for the MCP OAuth Sample project - a production-ready OAuth 2.1 authorization server with Model Context Protocol (MCP) integration.
+
+!!! info "What is MCP OAuth Sample?"
+
+    This project extends the [run-llama/mcp-nextjs](https://github.com/run-llama/mcp-nextjs) reference implementation with OAuth 2.1 compliance, refresh tokens, DIY analytics, and enhanced security monitoring.
 
 ## Quick Navigation
 
@@ -29,14 +38,37 @@ This project extends the [run-llama/mcp-nextjs](https://github.com/run-llama/mcp
 
 ## Key Features
 
-- ✅ OAuth 2.1 Authorization Server with PKCE
-- ✅ MCP Server with Authentication
-- ✅ Real-time Analytics Dashboard
-- ✅ Security Monitoring & Threat Detection
-- ✅ Google SSO Integration
-- ✅ PostgreSQL with Prisma ORM
-- ✅ Next.js 15 App Router
-- ✅ Production Deployment Ready
+<div class="feature-grid">
+  <div class="feature-card">
+    <h3>🔐 OAuth 2.1 Compliance</h3>
+    <p>Full OAuth 2.1 authorization server with PKCE support, refresh token rotation, and resource indicators.</p>
+  </div>
+
+  <div class="feature-card">
+    <h3>🔌 MCP Integration</h3>
+    <p>Authenticated Model Context Protocol server with tool execution and transport support.</p>
+  </div>
+
+  <div class="feature-card">
+    <h3>📊 DIY Analytics</h3>
+    <p>Real-time analytics dashboard with performance metrics, user tracking, and OAuth insights.</p>
+  </div>
+
+  <div class="feature-card">
+    <h3>🛡️ Security Monitoring</h3>
+    <p>Comprehensive threat detection, security event logging, and risk assessment.</p>
+  </div>
+
+  <div class="feature-card">
+    <h3>🚀 Production Ready</h3>
+    <p>Built with Next.js 15, PostgreSQL, Prisma ORM, and optimized for Vercel deployment.</p>
+  </div>
+
+  <div class="feature-card">
+    <h3>🔗 Google SSO</h3>
+    <p>Integrated Google authentication with NextAuth.js and multi-admin support.</p>
+  </div>
+</div>
 
 ## Quick Start
 

docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => { 
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})