Add Docker container with URL mode elicitation for headless device code auth

[patrickcping]

Overview

This PR adds Docker container support for the PingOne MCP server, enabling deployment in containerized environments where binary installation is impractical or undesired. The implementation leverages the device code grant type with URL mode elicitation for secure, headless authentication.

Key Changes

Docker Implementation

• Multi-stage Dockerfile using golang:1.24-alpine for building and alpine:3 for runtime
• Environment-based configuration via environment variables (CLIENT_ID, CLIENT_SECRET, ENVIRONMENT_ID, REGION, GRANT_TYPE)
• Automatic authentication on container startup using device code flow with URL mode elicitation
• MCP SDK v1.2.0 upgrade for URL mode elicitation support (requires clients compatible with this feature)

Authentication Flow

• Device code grant type configured for headless environments
• URL mode elicitation support presents authorization URL to users securely
• Token storage via file-based tokenstore in container
• Session validation and token refresh on server restart

Documentation

• Comprehensive Docker usage guide with setup instructions, configuration examples, and troubleshooting
• Setup guide for PingOne worker application configuration
• Troubleshooting documentation for common Docker deployment issues

Technical Details

Breaking Change: The TokenSource interface now requires a *mcp.ServerSession parameter:

// Before
TokenSource(context.Context, GrantType) (*oauth2.Token, error)

// After
TokenSource(context.Context, GrantType, *mcp.ServerSession) (*oauth2.Token, error)

This enables access to server session capabilities like URL mode elicitation for secure authorization URL presentation.

Testing

All unit tests passing:

Test Results (make test)

$ make test
go test -v -timeout 1m ./...
?       github.com/pingidentity/pingone-mcp-server      [no test files]
=== RUN   TestRootCommand
=== RUN   TestRootCommand/no_arguments
=== RUN   TestRootCommand/help_flag
=== RUN   TestRootCommand/invalid_flag
--- PASS: TestRootCommand (0.00s)
    --- PASS: TestRootCommand/no_arguments (0.00s)
    --- PASS: TestRootCommand/help_flag (0.00s)
    --- PASS: TestRootCommand/invalid_flag (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/cmd  (cached)

[... all test output showing 100% pass rate ...]

PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/tools/validation    (cached)

Exit code: 0 ✅

Summary:

• All test packages passing
• No failures or panics
• All authentication, middleware, and tool validation tests successful

Usage

Quick Start with Docker

docker run -it --rm \
  -e PINGONE_CLIENT_ID="your-client-id" \
  -e PINGONE_CLIENT_SECRET="your-client-secret" \
  -e PINGONE_ENVIRONMENT_ID="your-env-id" \
  -e PINGONE_REGION="NA" \
  -e PINGONE_GRANT_TYPE="device_code" \
  ghcr.io/pingidentity/pingone-mcp-server:latest

Docker Compose

See docker-usage-instructions.md for complete Docker Compose examples and configuration options.

Documentation

• Docker Usage Instructions - Complete guide for Docker deployment
• Setup PingOne Worker Application - Configure PingOne for MCP server authentication
• Troubleshooting - Common issues and solutions

Requirements

MCP Client Compatibility: This Docker implementation requires MCP clients that support URL mode elicitation (e.g., VS Code Copilot Chat). This feature ensures authorization URLs are securely presented to human users and not processed by AI agents.

Testing Recommendations

• ✅ Unit tests: All passing
• ⏳ Manual testing: Test Docker container with device code flow in headless environment
• ⏳ End-to-end validation: Verify URL mode elicitation with compatible MCP client

Related Issues

Implements containerized deployment for PingOne MCP server with secure headless authentication.