docs: improve documentation structure and add AI development setup (#53)

- Reorganize README to prioritize documentation link and simplify overview
- Move detailed configuration and usage examples to external documentation
- Add AI development environment setup instructions to CONTRIBUTING.md
- Consolidate duplicate AI setup instructions across files

Author: hrntknr

CONTRIBUTING.md

@@ -41,3 +41,19 @@ feat!: change authentication API to support multiple providers
 ## Pull Request Template
 
 This project uses a pull request template to ensure consistency and completeness. Please follow the guidelines in [./.github/pull_request_template.md](./.github/pull_request_template.md) when creating pull requests.
+
+## AI Development Environment Setup
+
+You can link this file to your preferred AI development environment for better integration:
+
+```bash
+# For Claude Code
+ln -s CONTRIBUTING.md CLAUDE.md
+
+# For Gemini
+ln -s CONTRIBUTING.md GEMINI.md
+
+# For GitHub Copilot
+mkdir -p .github
+ln -s CONTRIBUTING.md .github/copilot-instructions.md
+```

README.md

@@ -11,6 +11,10 @@
 - **Publish local MCP servers safely**: Supports all stdio, SSE, and HTTP transports. For stdio, traffic is converted to `/mcp`. For SSE/HTTP, it’s proxied as-is. Of course, with authentication.
 - **Verified across major MCP clients**: Claude, Claude Code, ChatGPT, GitHub Copilot, Cursor, etc. — the proxy smooths client-specific quirks for consistent auth.
 
+---
+
+📖 **For detailed usage, configuration, and examples, see the [Documentation](https://sigbit.github.io/mcp-auth-proxy/)**
+
 ## Quickstart
 
 > Domain binding & 80/443 must be accessible from outside.
@@ -27,10 +31,10 @@ If you use stdio transport
   -- npx -y @modelcontextprotocol/server-filesystem ./
 ```
 
-That's it! Your HTTP endpoint is now available at `https://{your-domain}/mcp`.  
-To proxy SSE or HTTP transport, specify a URL; to use the stdio transport, specify a command.
+That's it! Your HTTP endpoint is now available at `https://{your-domain}/mcp`.
 
-(Listen on 80/443 and automatically set up certificates, but use the no-auto-tls option if not needed.)
+- stdio (when a command is specified): MCP endpoint is https://{your-domain}/mcp.
+- SSE/HTTP (when a URL is specified): MCP endpoint uses the backend’s original path (no conversion).
 
 ## Verified MCP Client
 
@@ -46,99 +50,6 @@ To proxy SSE or HTTP transport, specify a URL; to use the stdio transport, speci
 
 - \*1: https://platform.openai.com/docs/mcp
 
-## 🚀 Usage
-
-### Method 1: Download Binary
-
-Download the latest binary from [releases](https://github.com/sigbit/mcp-auth-proxy/releases) and run with command line options:
-
-```bash
-./mcp-auth-proxy \
-  --external-url "https://{your-domain}" \
-  --tls-accept-tos \
-  --password "changeme" \
-  --google-client-id "your-google-client-id" \
-  --google-client-secret "your-google-client-secret" \
-  --google-allowed-users "[email protected],[email protected]" \
-  --github-client-id "your-github-client-id" \
-  --github-client-secret "your-github-client-secret" \
-  --github-allowed-users "username1,username2" \
-  --oidc-configuration-url "https://your-oidc-provider.com/.well-known/openid-configuration" \
-  --oidc-client-id "your-oidc-client-id" \
-  --oidc-client-secret "your-oidc-client-secret" \
-  --oidc-allowed-users "[email protected],[email protected]" \
-  http://localhost:8080 # or execute command (for stdio transport)
-```
-
-### Method 2: Docker
-
-```bash
-docker run --rm --net=host \
-  -e EXTERNAL_URL=https://{your-domain} \
-  -e TLS_ACCEPT_TOS=1 \
-  -e PASSWORD=changeme \
-  -e GOOGLE_CLIENT_ID="your-google-client-id" \
-  -e GOOGLE_CLIENT_SECRET="your-google-client-secret" \
-  -e GOOGLE_ALLOWED_USERS="[email protected],[email protected]" \
-  -e GITHUB_CLIENT_ID="your-github-client-id" \
-  -e GITHUB_CLIENT_SECRET="your-github-client-secret" \
-  -e GITHUB_ALLOWED_USERS="username1,username2" \
-  -e OIDC_CONFIGURATION_URL="https://your-oidc-provider.com/.well-known/openid-configuration" \
-  -e OIDC_CLIENT_ID="your-oidc-client-id" \
-  -e OIDC_CLIENT_SECRET="your-oidc-client-secret" \
-  -e OIDC_ALLOWED_USERS="[email protected],[email protected]" \
-  -v ./data:/data \
-  ghcr.io/sigbit/mcp-auth-proxy:latest \
-  http://localhost:8080 # or execute command (for stdio transport)
-```
-
-## 🔧 Configuration
-
-### Provider Setup
-
-#### Google OAuth Setup
-
-1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
-2. Create a new project or select an existing one
-3. Create OAuth consent screen
-4. Credentials → Create credentials → OAuth client ID (Web application)
-5. Add authorized redirect URI: `{EXTERNAL_URL}/.auth/google/callback`
-
-#### GitHub OAuth Setup
-
-1. Go to the [Register new OAuth App](https://github.com/settings/applications/new)
-2. Set Authorization callback URL: `{EXTERNAL_URL}/.auth/github/callback`
-
-#### OIDC Provider Setup
-
-1. Configure your OIDC provider (e.g., Keycloak, Auth0, Azure AD, etc.)
-2. Create a new client application
-3. Set redirect URI: `{EXTERNAL_URL}/.auth/oidc/callback`
-4. Note the configuration URL (usually issuer URL + /.well-known/openid-configuration), client ID, and client secret
-5. Configure the userinfo endpoint to return user identification field (default: email)
-
 ## Note
 
 For a simpler approach to publish local MCP servers over OAuth, consider [MCP Warp](https://github.com/sigbit/mcp-warp), which provides an OAuth Proxy + ngrok-like service. We highly recommend considering this option as well.
-
-## 🤝 Contributing
-
-For developer guidelines, contribution instructions, and commit message conventions, please see [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-### AI Development Environment Setup
-
-You can link CONTRIBUTING.md to your preferred AI development environment for better integration:
-
-```bash
-# For Claude Code
-ln -s CONTRIBUTING.md CLAUDE.md
-
-# For Gemini
-ln -s CONTRIBUTING.md GEMINI.md
-
-# For GitHub Copilot
-mkdir -p .github
-ln -s CONTRIBUTING.md .github/copilot-instructions.md
-```
-
-This allows your AI assistant to access the contribution guidelines regardless of which development environment you prefer to use.