Skip to content

Commit 2d3cbe9

Browse files
agairolaagairola
authored
Merge pull request #3 from raxITai/new-dash
docs update
2 parents 211d0b1 + d8e0e4e commit 2d3cbe9

File tree

10 files changed

+659
-9
lines changed

10 files changed

+659
-9
lines changed

‎.github/workflows/docs.yml

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths: [ 'docs/**', 'mkdocs.yml', 'requirements.txt' ]
7+
pull_request:
8+
branches: [ main ]
9+
paths: [ 'docs/**', 'mkdocs.yml', 'requirements.txt' ]
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: "pages"
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0
29+
30+
- name: Setup Python
31+
uses: actions/setup-python@v4
32+
with:
33+
python-version: '3.11'
34+
cache: 'pip'
35+
36+
- name: Install dependencies
37+
run: |
38+
python -m pip install --upgrade pip
39+
pip install -r requirements.txt
40+
41+
- name: Setup Pages
42+
id: pages
43+
uses: actions/configure-pages@v3
44+
if: github.ref == 'refs/heads/main'
45+
46+
- name: Build documentation
47+
env:
48+
PROJECT_VERSION: ${{ github.ref_name }}
49+
BUILD_DATE: ${{ github.event.head_commit.timestamp }}
50+
run: |
51+
mkdocs build --clean --strict
52+
53+
- name: Upload Pages artifact
54+
uses: actions/upload-pages-artifact@v2
55+
if: github.ref == 'refs/heads/main'
56+
with:
57+
path: ./site
58+
59+
deploy:
60+
if: github.ref == 'refs/heads/main'
61+
environment:
62+
name: github-pages
63+
url: ${{ steps.deployment.outputs.page_url }}
64+
runs-on: ubuntu-latest
65+
needs: build
66+
steps:
67+
- name: Deploy to GitHub Pages
68+
id: deployment
69+
uses: actions/deploy-pages@v2

‎README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,10 @@ pnpm dev
6060

6161
## Documentation
6262

63+
**📚 [View Full Documentation](https://raxitai.github.io/mcp-oauth-sample/)** - Interactive Material for MkDocs site
64+
65+
### Quick Reference
66+
6367
| Topic | Description |
6468
|-------|-------------|
6569
| [🚀 Setup Guide](./docs/setup.md) | Complete installation and configuration |
@@ -71,6 +75,20 @@ pnpm dev
7175
| [❓ Troubleshooting](./docs/troubleshooting.md) | Common issues and solutions |
7276
| [👨‍💻 Development](./docs/development.md) | Development guide and contributing |
7377

78+
### Local Documentation Development
79+
80+
```bash
81+
# Serve documentation locally with hot reload
82+
./docs-serve.sh
83+
84+
# Or on Windows
85+
docs-serve.bat
86+
87+
# Manual setup
88+
pip install -r requirements.txt
89+
mkdocs serve
90+
```
91+
7492
## MCP Specification Compliance
7593

7694
This implementation is fully compliant with the MCP Authorization Specification.

‎docs-serve.bat

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
@echo off
2+
REM MkDocs development server script for Windows
3+
4+
echo 🚀 Setting up MkDocs for MCP OAuth Sample documentation...
5+
6+
REM Check if Python is installed
7+
python --version >nul 2>&1
8+
if errorlevel 1 (
9+
echo ❌ Python is required but not installed.
10+
echo Please install Python and try again.
11+
pause
12+
exit /b 1
13+
)
14+
15+
REM Check if pip is installed
16+
pip --version >nul 2>&1
17+
if errorlevel 1 (
18+
echo ❌ pip is required but not installed.
19+
echo Please install pip and try again.
20+
pause
21+
exit /b 1
22+
)
23+
24+
REM Create virtual environment if it doesn't exist
25+
if not exist "venv" (
26+
echo 📦 Creating virtual environment...
27+
python -m venv venv
28+
)
29+
30+
REM Activate virtual environment
31+
echo 🔄 Activating virtual environment...
32+
call venv\Scripts\activate.bat
33+
34+
REM Install/upgrade pip
35+
echo ⬆️ Upgrading pip...
36+
python -m pip install --upgrade pip
37+
38+
REM Install dependencies
39+
echo 📥 Installing MkDocs dependencies...
40+
pip install -r requirements.txt
41+
42+
REM Check if mkdocs.yml exists
43+
if not exist "mkdocs.yml" (
44+
echo ❌ mkdocs.yml not found in current directory.
45+
echo Please run this script from the project root.
46+
pause
47+
exit /b 1
48+
)
49+
50+
echo ✅ Setup complete!
51+
echo.
52+
echo 🌐 Starting MkDocs development server...
53+
echo 📖 Documentation will be available at: http://127.0.0.1:8000
54+
echo 🔄 The server will auto-reload when you make changes to the docs.
55+
echo ⏹️ Press Ctrl+C to stop the server.
56+
echo.
57+
58+
REM Start the development server
59+
mkdocs serve
60+
61+
pause

‎docs-serve.sh

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
#!/bin/bash
2+
# MkDocs development server script
3+
4+
set -e
5+
6+
echo "🚀 Setting up MkDocs for MCP OAuth Sample documentation..."
7+
8+
# Check if Python is installed
9+
if ! command -v python3 &> /dev/null; then
10+
echo "❌ Python 3 is required but not installed."
11+
echo "Please install Python 3 and try again."
12+
exit 1
13+
fi
14+
15+
# Check if pip is installed
16+
if ! command -v pip &> /dev/null; then
17+
echo "❌ pip is required but not installed."
18+
echo "Please install pip and try again."
19+
exit 1
20+
fi
21+
22+
# Create virtual environment if it doesn't exist
23+
if [ ! -d "venv" ]; then
24+
echo "📦 Creating virtual environment..."
25+
python3 -m venv venv
26+
fi
27+
28+
# Activate virtual environment
29+
echo "🔄 Activating virtual environment..."
30+
source venv/bin/activate
31+
32+
# Install/upgrade pip
33+
echo "⬆️ Upgrading pip..."
34+
pip install --upgrade pip
35+
36+
# Install dependencies
37+
echo "📥 Installing MkDocs dependencies..."
38+
pip install -r requirements.txt
39+
40+
# Check if mkdocs.yml exists
41+
if [ ! -f "mkdocs.yml" ]; then
42+
echo "❌ mkdocs.yml not found in current directory."
43+
echo "Please run this script from the project root."
44+
exit 1
45+
fi
46+
47+
echo "✅ Setup complete!"
48+
echo ""
49+
echo "🌐 Starting MkDocs development server..."
50+
echo "📖 Documentation will be available at: http://127.0.0.1:8000"
51+
echo "🔄 The server will auto-reload when you make changes to the docs."
52+
echo "⏹️ Press Ctrl+C to stop the server."
53+
echo ""
54+
55+
# Start the development server
56+
mkdocs serve

‎docs/hooks.py

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
import os
2+
import logging
3+
from mkdocs.config import config_options
4+
from mkdocs.plugins import BasePlugin
5+
6+
logger = logging.getLogger(__name__)
7+
8+
class CustomHooksPlugin(BasePlugin):
9+
"""Custom hooks for MCP OAuth Sample documentation"""
10+
11+
def on_env(self, env, config, files, **kwargs):
12+
"""Add custom environment variables to the Jinja2 environment"""
13+
env.globals['project_version'] = os.environ.get('PROJECT_VERSION', '1.0.0')
14+
env.globals['build_date'] = os.environ.get('BUILD_DATE', 'unknown')
15+
return env
16+
17+
def on_page_markdown(self, markdown, page, config, files, **kwargs):
18+
"""Process markdown before conversion to HTML"""
19+
# Add custom processing if needed
20+
return markdown

‎docs/index.md

Lines changed: 41 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
11
# MCP OAuth Sample Documentation
22

3-
Welcome to the comprehensive documentation for the MCP OAuth Sample project - an OAuth 2.1 authorization server with Model Context Protocol (MCP) integration.
3+
<div class="status-indicator online">
4+
<span>🟢</span>
5+
<span>Live Demo Available</span>
6+
</div>
7+
8+
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.
9+
10+
!!! info "What is MCP OAuth Sample?"
11+
12+
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.
413

514
## Quick Navigation
615

@@ -29,14 +38,37 @@ This project extends the [run-llama/mcp-nextjs](https://github.com/run-llama/mcp
2938

3039
## Key Features
3140

32-
- ✅ OAuth 2.1 Authorization Server with PKCE
33-
- ✅ MCP Server with Authentication
34-
- ✅ Real-time Analytics Dashboard
35-
- ✅ Security Monitoring & Threat Detection
36-
- ✅ Google SSO Integration
37-
- ✅ PostgreSQL with Prisma ORM
38-
- ✅ Next.js 15 App Router
39-
- ✅ Production Deployment Ready
41+
<div class="feature-grid">
42+
<div class="feature-card">
43+
<h3>🔐 OAuth 2.1 Compliance</h3>
44+
<p>Full OAuth 2.1 authorization server with PKCE support, refresh token rotation, and resource indicators.</p>
45+
</div>
46+
47+
<div class="feature-card">
48+
<h3>🔌 MCP Integration</h3>
49+
<p>Authenticated Model Context Protocol server with tool execution and transport support.</p>
50+
</div>
51+
52+
<div class="feature-card">
53+
<h3>📊 DIY Analytics</h3>
54+
<p>Real-time analytics dashboard with performance metrics, user tracking, and OAuth insights.</p>
55+
</div>
56+
57+
<div class="feature-card">
58+
<h3>🛡️ Security Monitoring</h3>
59+
<p>Comprehensive threat detection, security event logging, and risk assessment.</p>
60+
</div>
61+
62+
<div class="feature-card">
63+
<h3>🚀 Production Ready</h3>
64+
<p>Built with Next.js 15, PostgreSQL, Prisma ORM, and optimized for Vercel deployment.</p>
65+
</div>
66+
67+
<div class="feature-card">
68+
<h3>🔗 Google SSO</h3>
69+
<p>Integrated Google authentication with NextAuth.js and multi-admin support.</p>
70+
</div>
71+
</div>
4072

4173
## Quick Start
4274

‎docs/javascripts/mathjax.js

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
window.MathJax = {
2+
tex: {
3+
inlineMath: [["\\(", "\\)"]],
4+
displayMath: [["\\[", "\\]"]],
5+
processEscapes: true,
6+
processEnvironments: true
7+
},
8+
options: {
9+
ignoreHtmlClass: ".*|",
10+
processHtmlClass: "arithmatex"
11+
}
12+
};
13+
14+
document$.subscribe(() => {
15+
MathJax.startup.output.clearCache()
16+
MathJax.typesetClear()
17+
MathJax.texReset()
18+
MathJax.typesetPromise()
19+
})

0 commit comments

Comments
 (0)