Merge pull request #120 from guyernest/feat/cargo-pmcp-oauth

feat(cargo-pmcp): add OAuth integration for aws-lambda and pmcp.run deployment targets using AWS Cognito.

Author: guyernest

cargo-pmcp/README.md

@@ -17,6 +17,7 @@ Production-grade MCP server development toolkit.
 - **WASM Support**: Automatic WASM compilation for edge deployments
 - **Infrastructure as Code**: CDK-based AWS deployment with complete stack management
 - **Deployment Management**: Logs, metrics, secrets, rollback, and destroy capabilities
+- **OAuth Authentication**: Production-ready OAuth 2.0 with AWS Cognito, supporting Dynamic Client Registration (DCR)
 
 ## Installation
 
@@ -208,6 +209,48 @@ cargo pmcp deploy destroy --target google-cloud-run --clean
 - `deploy test --verbose` - Test the deployment
 - `deploy outputs --format json` - Show deployment outputs
 
+### OAuth Authentication
+
+Enable OAuth 2.0 authentication for your MCP server with AWS Cognito. MCP clients (like Claude Desktop, ChatGPT, Cursor) automatically discover and use OAuth via the standard OpenID Connect discovery endpoint.
+
+**Initialize with OAuth:**
+```bash
+# Create deployment with OAuth enabled
+cargo pmcp deploy init --target aws-lambda --oauth cognito
+
+# This creates:
+# - Cognito User Pool with optional social logins
+# - OAuth Proxy Lambda (handles DCR, authorize, token endpoints)
+# - Token Validator Lambda Authorizer (stateless JWT validation)
+# - ClientRegistrationTable in DynamoDB
+```
+
+**OAuth Options:**
+- `--oauth cognito` - Use AWS Cognito (recommended for AWS deployments)
+- `--oauth oidc` - Use external OIDC provider (future)
+- `--oauth shared:<name>` - Use organization's shared OAuth infrastructure
+
+**How It Works:**
+1. MCP clients discover OAuth endpoints via `/.well-known/openid-configuration`
+2. Clients self-register using Dynamic Client Registration (RFC 7591)
+3. Users authenticate via Cognito Hosted UI (supports social logins, MFA)
+4. Clients send Bearer tokens on every MCP request
+5. API Gateway validates tokens using Lambda Authorizer (stateless JWT)
+6. Your MCP server code requires zero OAuth logic
+
+**View Registered Clients:**
+```bash
+cargo pmcp oauth clients
+```
+
+**Test with OAuth:**
+```bash
+# Opens browser for authentication, then runs tests
+cargo pmcp test --server myserver
+```
+
+For detailed OAuth architecture and configuration, see [docs/oauth-design.md](docs/oauth-design.md).
+
 ## Test Scenarios
 
 Test scenarios are YAML files that define test steps and assertions for your MCP server.
@@ -276,8 +319,8 @@ The typical development workflow:
 5. **Generate tests**: `cargo pmcp test --server myserver --generate-scenarios`
 6. **Customize tests**: Edit `scenarios/myserver/generated.yaml`
 7. **Run tests**: `cargo pmcp test --server myserver`
-8. **Deploy**:
-   - AWS Lambda: `cargo pmcp deploy init --target aws-lambda && cargo pmcp deploy`
+8. **Deploy with OAuth**:
+   - AWS Lambda: `cargo pmcp deploy init --target aws-lambda --oauth cognito && cargo pmcp deploy`
    - Google Cloud Run: `cargo pmcp deploy init --target google-cloud-run && cargo pmcp deploy`
    - Cloudflare Workers: `cargo pmcp deploy init --target cloudflare-workers && cargo pmcp deploy`
 9. **Monitor**: `cargo pmcp deploy logs --tail` and `cargo pmcp deploy metrics`

cargo-pmcp/docs/PMCP_RUN_INTEGRATION_UPDATE.md

@@ -0,0 +1,126 @@
+# pmcp.run Service Integration Update Required
+
+## Summary
+
+The cargo-pmcp SDK has been updated to generate Lambda-only CDK templates (no API Gateway) for pmcp-run deployments. However, the pmcp.run Step Functions workflow still expects the old template format with `ApiUrl` output.
+
+## Current Error
+
+```
+Deployment failed: Failed to extract stack outputs
+```
+
+This occurs because the workflow tries to extract `ApiUrl` from CloudFormation outputs, but the Lambda-only template doesn't have an API Gateway.
+
+## cargo-pmcp Changes (Completed)
+
+1. **CDK Template for pmcp-run** now only deploys:
+   - Lambda function
+   - IAM execution role (implicit)
+   - Log group
+
+2. **Outputs from CDK template**:
+   - `LambdaArn` - The Lambda function ARN
+   - `LambdaName` - The Lambda function name
+   - `ApiUrl` - Placeholder: `https://api.pmcp.run/{use-deployment-id}/mcp` (for backward compat)
+   - `DashboardUrl` - CloudWatch console URL
+
+3. **URL Construction**: cargo-pmcp constructs the MCP endpoint URL from the deployment ID:
+   ```
+   https://api.pmcp.run/{deployment_id}/mcp
+   ```
+
+## pmcp.run Service Changes Required
+
+### 1. Update Step Functions Workflow
+
+**File**: `amplify/functions/deployment-workflow/state-machine.json`
+
+**Current** (line 320):
+```json
+"apiUrl": "{% $states.result.Stacks[0].Outputs[OutputKey='ApiUrl'].OutputValue %}"
+```
+
+**New**:
+```json
+"lambdaArn": "{% $states.result.Stacks[0].Outputs[OutputKey='LambdaArn'].OutputValue %}",
+"lambdaName": "{% $states.result.Stacks[0].Outputs[OutputKey='LambdaName'].OutputValue %}",
+"apiUrl": "{% 'https://api.pmcp.run/' + $deploymentId + '/mcp' %}"
+```
+
+### 2. Wire Lambda to Shared API Gateway
+
+After CloudFormation deployment succeeds, the workflow needs to:
+
+1. **Create Lambda integration** on the shared API Gateway:
+   ```typescript
+   const integration = new apigatewayv2.CfnIntegration(this, 'Integration', {
+     apiId: SHARED_API_GATEWAY_ID,
+     integrationType: 'AWS_PROXY',
+     integrationUri: lambdaArn,
+     payloadFormatVersion: '2.0',
+   });
+   ```
+
+2. **Create route** for `/{serverId}/mcp`:
+   ```typescript
+   new apigatewayv2.CfnRoute(this, 'Route', {
+     apiId: SHARED_API_GATEWAY_ID,
+     routeKey: `POST /${serverId}/mcp`,
+     target: `integrations/${integration.ref}`,
+   });
+   ```
+
+3. **Grant API Gateway permission** to invoke the Lambda:
+   ```typescript
+   new lambda.CfnPermission(this, 'ApiGatewayPermission', {
+     action: 'lambda:InvokeFunction',
+     functionName: lambdaName,
+     principal: 'apigateway.amazonaws.com',
+     sourceArn: `arn:aws:execute-api:${region}:${account}:${SHARED_API_GATEWAY_ID}/*/*`,
+   });
+   ```
+
+### 3. Update DynamoDB Record
+
+Store `lambdaArn` in the deployment record:
+```json
+{
+  "id": "dep_xxxxx",
+  "projectName": "chess",
+  "status": "success",
+  "lambdaArn": "arn:aws:lambda:us-west-2:123456789:function:chess",
+  "lambdaName": "chess",
+  "url": "https://api.pmcp.run/dep_xxxxx/mcp"
+}
+```
+
+## Alternative: Quick Fix for Backward Compatibility
+
+If the service-side changes take time, cargo-pmcp can temporarily generate templates with a per-server API Gateway (the old way) for pmcp-run target. However, this defeats the cost optimization benefits of the shared API Gateway architecture.
+
+## Testing
+
+Once pmcp.run service is updated:
+
+```bash
+cd ~/Development/mcp/pmcp/test-chess/chess
+rm -rf .pmcp deploy
+cargo pmcp deploy init --oauth cognito --target pmcp-run
+cargo pmcp deploy --target pmcp-run
+```
+
+Expected output:
+```
+🎉 Deployment successful!
+
+📊 Deployment Details:
+   Name: chess
+   ID: dep_xxxxx
+
+🔌 MCP Endpoint:
+   URL: https://api.pmcp.run/dep_xxxxx/mcp
+
+🏥 Health Check:
+   URL: https://api.pmcp.run/dep_xxxxx/health
+```