diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3375ec0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing + +## Build from Source + +> Prerequisites +> +> * Go 1.20 or higher +> * Git +> * Make (optional, for simplified builds) + +1. **Clone the repository:** + ```bash + git clone https://github.com/wso2/open-mcp-auth-proxy + cd open-mcp-auth-proxy + ``` + +2. **Install dependencies:** + ```bash + go get -v -t -d ./... + ``` + +3. **Build the application:** + + **Option A: Using Make** + + ```bash + # Build for all platforms + make all + + # Or build for specific platforms + make build-linux # For Linux (x86_64) + make build-linux-arm # For ARM-based Linux + make build-darwin # For macOS + make build-windows # For Windows + ``` + + **Option B: Manual build (works on all platforms)** + + ```bash + # Build for your current platform + go build -o openmcpauthproxy ./cmd/proxy + + # Cross-compile for other platforms + GOOS=linux GOARCH=amd64 go build -o openmcpauthproxy-linux ./cmd/proxy + GOOS=windows GOARCH=amd64 go build -o openmcpauthproxy.exe ./cmd/proxy + GOOS=darwin GOARCH=amd64 go build -o openmcpauthproxy-macos ./cmd/proxy + ``` + +After building, you'll find the executables in the `build` directory (when using Make) or in your project root (when building manually). + +### Additional Make Targets + +If you're using Make, these additional targets are available: + +```bash +make test # Run tests +make coverage # Run tests with coverage report +make fmt # Format code with gofmt +make vet # Run go vet +make clean # Clean build artifacts +make help # Show all available targets +``` \ No newline at end of file diff --git a/README.md b/README.md index 7b707ff..bd7abac 100644 --- a/README.md +++ b/README.md @@ -10,83 +10,38 @@ A lightweight authorization proxy for Model Context Protocol (MCP) servers that ![Architecture Diagram](https://github.com/user-attachments/assets/41cf6723-c488-4860-8640-8fec45006f92) -## πŸ›‘οΈ What it Does? - -- Intercept incoming requests -- Validate authorization tokens -- Offload authentication and authorization to OAuth-compliant Identity Providers -- Support the MCP authorization protocol - - ## πŸš€ Features -- **Dynamic Authorization** based on MCP Authorization Specification. -- **JWT Validation** (signature, audience, and scopes). -- **Identity Provider Integration** (OAuth/OIDC via Asgardeo, Auth0, Keycloak). -- **Protocol Version Negotiation** via `MCP-Protocol-Version` header. -- **Comprehensive Authentication Feedback** via RFC-compliant challenges. -- **Flexible Transport Modes**: SSE and stdio. - -## πŸ“Œ MCP Specification Verions - -| Version | Behavior | -| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 2025-03-26 | Only signature check of Bearer JWT on both `/sse` and `/message`
No scope or audience enforcement | -| Latest(draft) | Read `MCP-Protocol-Version` from client header
SSE handshake returns `WWW-Authenticate: Bearer resource_metadata="…"`
`/message` enforces:
`aud` claim == `ResourceIdentifier`
`scope` claim contains `requiredScope`
Scope based access control
Rich `WWW-Authenticate` on 401s
Serves `/​.well-known/oauth-protected-resource` JSON | +- **Dynamic Authorization**: based on MCP Authorization Specification. +- **JWT Validation**: Validates the token’s signature, checks the `audience` claim, and enforces scope requirements. +- **Identity Provider Integration**: Supports integrating any OAuth/OIDC provider such as Asgardeo, Auth0, Keycloak, etc. +- **Protocol Version Negotiation**: via `MCP-Protocol-Version` header. +- **Flexible Transport Modes**: Supports STDIO, SSE and streamable HTTP transport options. ## πŸ› οΈ Quick Start -### Prerequisites - -* Go 1.20 or higher -* A running MCP server - -> If you don't have an MCP server, you can use the included example: -> -> 1. Navigate to the `resources` directory -> 2. Set up a Python environment: +> **Prerequisites** > -> ```bash -> python3 -m venv .venv -> source .venv/bin/activate -> pip3 install -r requirements.txt -> ``` -> -> 3. Start the example server: -> -> ```bash -> python3 echo_server.py -> ``` - -* An MCP client that supports MCP authorization - -### Basic Usage +> * A running MCP server (Use the [example MCP server](resources/README.md) if you don't have an MCP server already) +> * An MCP client that supports MCP authorization specification 1. Download the latest release from [Github releases](https://github.com/wso2/open-mcp-auth-proxy/releases/latest). 2. Start the proxy in demo mode (uses pre-configured authentication with Asgardeo sandbox): -#### Linux/macOS: +- Linux/macOS: + ```bash ./openmcpauthproxy --demo ``` -#### Windows: +- Windows: + ```powershell .\openmcpauthproxy.exe --demo ``` -> The repository comes with a default `config.yaml` file that contains the basic configuration: -> -> ```yaml -> listen_port: 8080 -> base_url: "http://localhost:8000" # Your MCP server URL -> paths: -> sse: "/sse" -> messages: "/messages/" -> ``` - -3. Connect using an MCP client like [MCP Inspector](https://github.com/shashimalcse/inspector)(This is a temporary fork with fixes for authentication [issues](https://github.com/modelcontextprotocol/typescript-sdk/issues/257) in the original implementation) +3. Connect using an MCP client like [MCP Inspector](https://github.com/modelcontextprotocol/inspector). ## πŸ”’ Integrate an Identity Provider @@ -96,10 +51,10 @@ To enable authorization through your Asgardeo organization: 1. [Register](https://asgardeo.io/signup) and create an organization in Asgardeo 2. Create an [M2M application](https://wso2.com/asgardeo/docs/guides/applications/register-machine-to-machine-app/) - 1. [Authorize this application](https://wso2.com/asgardeo/docs/guides/applications/register-machine-to-machine-app/#authorize-the-api-resources-for-the-app) to invoke "Application Management API" with the `internal_application_mgt_create` scope +3. [Authorize this application](https://wso2.com/asgardeo/docs/guides/applications/register-machine-to-machine-app/#authorize-the-api-resources-for-the-app) to invoke "Application Management API" with the `internal_application_mgt_create` scope ![image](https://github.com/user-attachments/assets/0bd57cac-1904-48cc-b7aa-0530224bc41a) -3. Update `config.yaml` with the following parameters. +4. Update `config.yaml` with the following parameters. ```yaml base_url: "http://localhost:8000" # URL of your MCP server @@ -115,7 +70,7 @@ authorization_servers: # Authorization ser jwks_uri: "https://api.asgardeo.io/t/acme/oauth2/jwks" # JWKS URL ``` -4. Start the proxy with Asgardeo integration: +5. Start the proxy with Asgardeo integration: ```bash ./openmcpauthproxy --asgardeo @@ -126,59 +81,24 @@ jwks_uri: "https://api.asgardeo.io/t/acme/oauth2/jwks" # JWKS URL - [Auth0](docs/integrations/Auth0.md) - [Keycloak](docs/integrations/keycloak.md) -# βš™οΈ Advanced Configuration +## Transport Modes -### Transport Modes - -The proxy supports two transport modes: - -- **SSE Mode (Default)**: For Server-Sent Events transport -- **stdio Mode**: For MCP servers that use stdio transport +### **STDIO Mode** When using stdio mode, the proxy: - Starts an MCP server as a subprocess using the command specified in the configuration - Communicates with the subprocess through standard input/output (stdio) -- **Note**: Any commands specified (like `npx` in the example below) must be installed on your system first -To use stdio mode: - -```bash -./openmcpauthproxy --demo --stdio -``` - -#### Example: Running an MCP Server as a Subprocess +> **Note**: Any commands specified (like `npx` in the example below) must be installed on your system first 1. Configure stdio mode in your `config.yaml`: ```yaml -listen_port: 8080 -base_url: "http://localhost:8000" - stdio: enabled: true user_command: "npx -y @modelcontextprotocol/server-github" # Example using a GitHub MCP server env: # Environment variables (optional) - - "GITHUB_PERSONAL_ACCESS_TOKEN=gitPAT" - -# CORS configuration -cors: - allowed_origins: - - "http://localhost:5173" # Origin of your client application - allowed_methods: - - "GET" - - "POST" - - "PUT" - - "DELETE" - allowed_headers: - - "Authorization" - - "Content-Type" - allow_credentials: true - -# Demo configuration for Asgardeo -demo: - org_name: "openmcpauthdemo" - client_id: "N0U9e_NNGr9mP_0fPnPfPI0a6twa" - client_secret: "qFHfiBp5gNGAO9zV4YPnDofBzzfInatfUbHyPZvM0jka" + - "GITHUB_PERSONAL_ACCESS_TOKEN=gitPAT" ``` 2. Run the proxy with stdio mode: @@ -187,132 +107,10 @@ demo: ./openmcpauthproxy --demo ``` -The proxy will: -- Start the MCP server as a subprocess using the specified command -- Handle all authorization requirements -- Forward messages between clients and the server +- **SSE Mode (Default)**: For Server-Sent Events transport +- **Streamable HTTP Mode**: For Streamable HTTP transport -### πŸ“ Complete Configuration Reference - -```yaml -# Common configuration -listen_port: 8080 -base_url: "http://localhost:8000" -port: 8000 - -# Path configuration -paths: - sse: "/sse" - messages: "/messages/" - -# Transport mode -transport_mode: "sse" # Options: "sse" or "stdio" - -# stdio-specific configuration (used only in stdio mode) -stdio: - enabled: true - user_command: "npx -y @modelcontextprotocol/server-github" # Command to start the MCP server (requires npx to be installed) - work_dir: "" # Optional working directory for the subprocess - -# CORS configuration -cors: - allowed_origins: - - "http://localhost:5173" - allowed_methods: - - "GET" - - "POST" - - "PUT" - - "DELETE" - allowed_headers: - - "Authorization" - - "Content-Type" - allow_credentials: true - -# Demo configuration for Asgardeo -demo: - org_name: "openmcpauthdemo" - client_id: "N0U9e_NNGr9mP_0fPnPfPI0a6twa" - client_secret: "qFHfiBp5gNGAO9zV4YPnDofBzzfInatfUbHyPZvM0jka" - -# Asgardeo configuration (used with --asgardeo flag) -resource_identifier: "http://localhost:8080" -scopes_supported: -- "read:tools" -- "read:resources" -audience: "" -authorization_servers: -- "https://api.asgardeo.io/t/acme" -jwks_uri: "https://api.asgardeo.io/t/acme/oauth2/jwks" -``` -## Build from Source - -### Prerequisites - -* Go 1.20 or higher -* Git -* Make (optional, for simplified builds) - -### Clone and Build - -1. **Clone the repository:** - ```bash - git clone https://github.com/wso2/open-mcp-auth-proxy - cd open-mcp-auth-proxy - ``` - -2. **Install dependencies:** - ```bash - go get -v -t -d ./... - ``` - -3. **Build the application:** - - **Option A: Using Make** - ```bash - # Build for all platforms - make all - - # Or build for specific platforms - make build-linux # For Linux (x86_64) - make build-linux-arm # For ARM-based Linux - make build-darwin # For macOS - make build-windows # For Windows - ``` - - **Option B: Manual build (works on all platforms)** - ```bash - # Build for your current platform - go build -o openmcpauthproxy ./cmd/proxy - - # Cross-compile for other platforms - GOOS=linux GOARCH=amd64 go build -o openmcpauthproxy-linux ./cmd/proxy - GOOS=windows GOARCH=amd64 go build -o openmcpauthproxy.exe ./cmd/proxy - GOOS=darwin GOARCH=amd64 go build -o openmcpauthproxy-macos ./cmd/proxy - ``` - -### Run the Built Application - -After building, you'll find the executables in the `build` directory (when using Make) or in your project root (when building manually). - -**Linux/macOS:** -```bash -# If built with Make -./build/linux/openmcpauthproxy --demo - -# If built manually -./openmcpauthproxy --demo -``` - -**Windows:** -```powershell -# If built with Make -.\build\windows\openmcpauthproxy.exe --demo - -# If built manually -.\openmcpauthproxy.exe --demo -``` - -### Available Command Line Options +## Available Command Line Options ```bash # Start in demo mode (using Asgardeo sandbox) @@ -331,15 +129,6 @@ After building, you'll find the executables in the `build` directory (when using ./openmcpauthproxy --help ``` -### Additional Make Targets +## Contributing -If you're using Make, these additional targets are available: - -```bash -make test # Run tests -make coverage # Run tests with coverage report -make fmt # Format code with gofmt -make vet # Run go vet -make clean # Clean build artifacts -make help # Show all available targets -``` +We appreciate your contributions, whether it is improving documentation, adding new features, or fixing bugs. To get started, please refer to our [contributing guide](CONTRIBUTING.md). diff --git a/resources/README.md b/resources/README.md new file mode 100644 index 0000000..047c220 --- /dev/null +++ b/resources/README.md @@ -0,0 +1,21 @@ +# Example MCP server + +Use this example MCP server, if you don't already have an MCP server to test the open-mcp-auth-proxy. + +## Setting Up + +1. Navigate to the `resources` directory + +2. Set up a Python environment: + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip3 install -r requirements.txt +``` + +3. Start the example server: + +```bash +python3 echo_server.py +```