Update auth example for standalone third-party usage (#2)

Make the auth example self-contained so it can be used by third-party
developers without needing the full gopher-mcp-rust repository locally.

Changes:
- Update Cargo.toml to use SDK via git dependency instead of local path
- Rewrite run_example.sh to download native libs from GitHub releases
- Add SDK_VERSION and NATIVE_LIB_DIR environment variable support
- Update README with installation and troubleshooting instructions
- Add .gitignore for native/ directory and build artifacts

Author: RahulHere

examples/auth/.gitignore

@@ -0,0 +1,17 @@
+# Build output
+target/
+
+# Downloaded native libraries
+native/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+
+# Cargo lock is committed for reproducible builds
+# Cargo.lock

examples/auth/Cargo.toml

@@ -2,7 +2,7 @@
 name = "auth-mcp-server"
 version = "0.1.0"
 edition = "2021"
-description = "OAuth-protected MCP server example using gopher-auth"
+description = "OAuth-protected MCP server example using gopher-orch SDK"
 license = "MIT"
 
 [dependencies]
@@ -22,7 +22,8 @@ serde_json = "1"
 http = "1"
 
 # Gopher Orch SDK with auth FFI
-gopher-orch = { path = "../..", features = ["auth"] }
+# Use git dependency for standalone example
+gopher-orch = { git = "https://github.com/GopherSecurity/gopher-mcp-rust.git", features = ["auth"] }
 
 # Logging
 tracing = "0.1"

examples/auth/README.md

@@ -1,50 +1,89 @@
-# Rust Auth MCP Server
+# Gopher Auth MCP Server - Rust Example
 
-An OAuth-protected MCP (Model Context Protocol) server example demonstrating JWT token validation and scope-based access control for MCP tools.
+This example demonstrates an MCP (Model Context Protocol) server with OAuth 2.0 authentication using the gopher-mcp-rust SDK.
 
-## Features
+## Overview
 
-- **OAuth 2.0 Protected Resources**: Implements RFC 9728 protected resource metadata
-- **OpenID Connect Discovery**: Supports OIDC discovery endpoints
-- **JWT Token Validation**: Validates tokens using gopher-auth native library
-- **Scope-Based Access Control**: Tools require specific scopes (e.g., `mcp:read`, `mcp:admin`)
-- **MCP Protocol Support**: Full JSON-RPC 2.0 implementation for MCP tools
-- **Weather Tools Example**: Three tools demonstrating different access levels
+The auth example server provides:
+- OAuth 2.0 / OIDC discovery endpoints (RFC 8414, RFC 9728)
+- JWT token validation via native library
+- Scope-based authorization for MCP tools
+- Example weather tools with different scope requirements
 
-## Requirements
+## Prerequisites
 
 - Rust 1.70 or later
-- (Optional) gopher-auth native library for JWT validation
+- GitHub CLI (`gh`) for downloading native libraries
 
-## Quick Start
-
-### Run Without Authentication
+## Installation
 
-The fastest way to try the server:
+### 1. Clone or Copy This Example
 
 ```bash
-./run_example.sh --no-auth
+# Option A: Clone the repository
+git clone https://github.com/GopherSecurity/gopher-mcp-rust.git
+cd gopher-mcp-rust/examples/auth
+
+# Option B: Copy the example files to your project
+# Copy the examples/auth directory contents
+```
+
+### 2. Install the Rust SDK
+
+The SDK is specified in `Cargo.toml` as a git dependency:
+
+```toml
+[dependencies]
+gopher-orch = { git = "https://github.com/GopherSecurity/gopher-mcp-rust.git", features = ["auth"] }
 ```
 
-Or manually:
+### 3. Download Native Libraries
+
+The SDK requires native libraries for OAuth token validation. The `run_example.sh` script downloads these automatically, or you can install them manually:
 
 ```bash
-cargo run
+# Using the run script (downloads automatically)
+./run_example.sh --no-auth
+
+# Or download manually using the install script
+curl -sSL https://raw.githubusercontent.com/GopherSecurity/gopher-mcp-rust/main/install-native.sh | bash -s -- latest ./native
 ```
 
-### Run With Configuration
+## Quick Start
+
+### Development Mode (No Auth)
 
 ```bash
-./run_example.sh --config server.config
+# Run with auth disabled (all requests bypass authentication)
+./run_example.sh --no-auth
+
+# Or build and run manually
+cargo build --release
+./target/release/auth-mcp-server
 ```
 
-### Build Release
+### With Full OAuth Support
 
 ```bash
+# Run with OAuth authentication enabled
+./run_example.sh
+
+# Or build manually with environment set
+export DYLD_LIBRARY_PATH="./native/lib:$DYLD_LIBRARY_PATH"
 cargo build --release
 ./target/release/auth-mcp-server server.config
 ```
 
+### Using Environment Variables
+
+```bash
+# Use a specific SDK version
+SDK_VERSION=v0.1.3 ./run_example.sh
+
+# Use custom native library location
+NATIVE_LIB_DIR=/usr/local/lib ./run_example.sh --skip-download
+```
+
 ## Configuration
 
 Create a `server.config` file with INI-style key-value pairs:
@@ -88,7 +127,7 @@ auth_disabled=true
 | `request_timeout` | HTTP request timeout in seconds | `30` |
 | `auth_disabled` | Disable authentication | `false` |
 
-## API Endpoints
+## Available Endpoints
 
 ### Health Check
 
@@ -122,9 +161,10 @@ curl -X POST http://localhost:3001/mcp \
   -H "Content-Type: application/json" \
   -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
 
-# Call Tool
+# Call Tool (with auth)
 curl -X POST http://localhost:3001/mcp \
   -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
   -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get-weather","arguments":{"city":"NYC"}}}'
 ```
 
@@ -136,14 +176,83 @@ curl -X POST http://localhost:3001/mcp \
 | `get-forecast` | `mcp:read` | Get 5-day weather forecast |
 | `get-weather-alerts` | `mcp:admin` | Get weather alerts for a region |
 
+### Tool Examples
+
+```bash
+# get-weather (no auth required)
+curl -X POST http://localhost:3001/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get-weather","arguments":{"city":"Tokyo"}}}'
+
+# get-forecast (requires mcp:read scope)
+curl -X POST http://localhost:3001/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer TOKEN_WITH_MCP_READ" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get-forecast","arguments":{"city":"Paris"}}}'
+
+# get-weather-alerts (requires mcp:admin scope)
+curl -X POST http://localhost:3001/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer TOKEN_WITH_MCP_ADMIN" \
+  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get-weather-alerts","arguments":{"region":"California"}}}'
+```
+
+## Troubleshooting
+
+### "Native library not found" at runtime
+
+The native gopher-orch library is required for JWT validation:
+
+```bash
+# Download using the run script
+./run_example.sh
+
+# Or manually download
+curl -sSL https://raw.githubusercontent.com/GopherSecurity/gopher-mcp-rust/main/install-native.sh | bash -s -- latest ./native
+```
+
+Verify the library is installed:
+```bash
+ls -la ./native/lib/libgopher-orch*
+```
+
+### Library path not set
+
+```bash
+# macOS
+export DYLD_LIBRARY_PATH="./native/lib:$DYLD_LIBRARY_PATH"
+
+# Linux
+export LD_LIBRARY_PATH="./native/lib:$LD_LIBRARY_PATH"
+```
+
+### "Auth client creation failed"
+
+Check that:
+1. `jwks_uri` points to a valid JWKS endpoint
+2. `issuer` matches the token issuer
+3. Network can reach the auth server
+
+### "Token validation failed"
+
+Ensure:
+1. Token is not expired
+2. Token issuer matches config
+3. Token was signed by a key in JWKS
+4. Required scopes are present in token
+
 ## Project Structure
 
 ```
-examples/auth/
-├── Cargo.toml           # Dependencies and metadata
-├── server.config        # Default configuration
-├── run_example.sh       # Launcher script
+auth/
+├── Cargo.toml           # Dependencies (uses gopher-orch SDK)
+├── Cargo.lock           # Dependency lock file
+├── server.config        # Example configuration
+├── run_example.sh       # Build and run script
 ├── README.md            # This file
+├── native/              # Downloaded native libraries
+│   ├── lib/             # .dylib/.so files
+│   └── include/         # Header files
 └── src/
     ├── main.rs          # Entry point and router setup
     ├── config.rs        # Configuration parsing
@@ -184,6 +293,17 @@ cargo test -- --nocapture
 | Variable | Description |
 |----------|-------------|
 | `RUST_LOG` | Log level (e.g., `info`, `debug`, `trace`) |
+| `SDK_VERSION` | Version of gopher-mcp-rust SDK (default: v0.1.2) |
+| `NATIVE_LIB_DIR` | Directory for native libraries (default: ./native/lib) |
+| `DYLD_LIBRARY_PATH` | macOS library search path |
+| `LD_LIBRARY_PATH` | Linux library search path |
+
+## SDK Documentation
+
+For more information about the gopher-mcp-rust SDK:
+
+- Repository: https://github.com/GopherSecurity/gopher-mcp-rust
+- Documentation: https://docs.rs/gopher-orch (after crates.io publish)
 
 ## License