Merge pull request #21 from StrongMonkey/docs

Chore: First pass of docs

Author: StrongMonkey

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build website
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -241,8 +241,6 @@ jobs:
           tags: |
             type=ref,event=tag
             type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Build and push Docker image

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/01-overview.md

@@ -0,0 +1,57 @@
+---
+title: Overview
+slug: /
+---
+
+MCP OAuth Proxy is an open-source OAuth 2.1 proxy server that adds authentication and authorization to MCP (Model Context Protocol) servers.
+
+## What is MCP OAuth Proxy?
+
+MCP OAuth Proxy acts as a bridge between OAuth providers (Google, Microsoft, GitHub) and MCP servers, providing:
+
+- **OAuth 2.1 Compliance** - Full OAuth 2.1 authorization server with PKCE support
+- **MCP Integration** - Seamless proxy to MCP servers with user context injection
+- **Multi-Provider Support** - Works with any OAuth 2.0 provider via auto-discovery
+- **Database Flexibility** - PostgreSQL for production, SQLite for development
+
+## Architecture
+
+The proxy sits in front of your MCP server to handle OAuth 2.1 authentication and validate user identity from external providers.
+
+Here's how it works:
+
+1. **OAuth 2.1 Flow** - When a client needs access, the proxy redirects to an external auth provider (Google, Microsoft, GitHub) to verify user identity
+2. **Token Issuance** - Once authentication is complete, the proxy issues an access token back to the client
+3. **MCP Auth Compliance** - Follows the MCP authentication specification and works with any compatible MCP client
+4. **Request Proxying** - Validates the access token and forwards authenticated requests to your MCP server
+5. **User Context** - Sends necessary headers to the MCP server about user identity and access to external services based on the OAuth scopes you configured
+
+![Architecture Diagram](/img/architect.png)
+
+The proxy supports PostgreSQL for production deployments and SQLite for development, with automatic schema creation and encrypted storage for sensitive data.
+
+## Headers Sent to MCP Server
+
+When proxying requests to your MCP server, the OAuth proxy automatically injects the following headers with user information:
+
+| Header                     | Description                               | Example                |
+| -------------------------- | ----------------------------------------- | ---------------------- |
+| `X-Forwarded-User`         | User ID from the OAuth provider           | `12345678901234567890` |
+| `X-Forwarded-Email`        | User's email address                      | `[email protected]`     |
+| `X-Forwarded-Name`         | User's display name                       | `John Doe`             |
+| `X-Forwarded-Access-Token` | OAuth access token for external API calls | `ya29.a0ARrdaM...`     |
+
+These headers allow your MCP server to:
+
+- **Identify the user** making the request
+- **Personalize responses** based on user information
+- **Make authenticated API calls** to external services using the access token
+- **Implement user-specific logic** and access controls
+
+:::note
+Headers are only set if the corresponding user information is available from the OAuth provider. If a property is not available, the header is removed to avoid stale data.
+:::
+
+## Next Steps
+
+- [Getting Started](/getting-started) - Quick setup guide