diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 50dd24c..6c701f5 100644 --- a/CONTRIBUTING.md +++ b/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 +``` diff --git a/README.md b/README.md index 57662bb..9b9a97a 100644 --- a/README.md +++ b/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 "user1@example.com,user2@example.com" \ - --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 "user1@example.com,user2@example.com" \ - 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="user1@example.com,user2@example.com" \ - -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="user1@example.com,user2@example.com" \ - -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.