feat(mcp-server): add server-level default authentication and MCP proxy server support

[johnlanni]

higress-group/wasm-go#25

✨ Key Features

1. Server-Level Default Authentication

• defaultDownstreamSecurity: Configure default client-to-gateway authentication for all tools and tools/list requests
• defaultUpstreamSecurity: Configure default gateway-to-backend authentication for all backend requests
• Priority-based configuration: Tool-level settings override server-level defaults, which override scheme defaults

2. MCP Proxy Server Type

• New server type mcp-proxy: Proxy client MCP requests to backend MCP servers
• Configurable backend URL: mcpServerURL field for specifying backend MCP server endpoint
• Timeout configuration: timeout field for controlling request timeouts
• Full authentication support: Both client-to-gateway and gateway-to-backend authentication

3. Authentication Code Refactoring

• Shared authentication utilities: Moved common auth logic to auth_utils.go
• Code reuse: Both REST and proxy servers now share the same authentication implementation
• Unified type system: Common SecurityScheme, SecurityRequirement, and AuthRequestContext structs

4. Configuration Structure Improvements

• Direct server fields: mcpServerURL, timeout, defaultDownstreamSecurity, defaultUpstreamSecurity are now direct server properties
• Simplified configuration: Reduced nesting and improved configuration clarity
• Backward compatibility: Existing configurations continue to work

🔧 Technical Changes

Core Implementation

• pkg/mcp/server/auth_utils.go: New shared authentication utilities
• pkg/mcp/server/proxy_server.go: Enhanced with default security and direct field support
• pkg/mcp/server/rest_server.go: Updated to use shared auth utilities and support default security
• pkg/mcp/server/proxy_tool.go: Refactored authentication parameter passing using dedicated structs

Configuration Updates

• pkg/mcp/server/plugin.go: Updated to parse new configuration fields directly from server object
• Authentication flow: Enhanced to support tools/list requests and non-tool-specific interfaces

Test Coverage

• Authentication header verification: Tests now verify actual HTTP headers sent to backend services
• Default security testing: Comprehensive tests for server-level default authentication scenarios
• Proxy server testing: Full test coverage for MCP proxy functionality

📚 Documentation

Updated Documentation

• Chinese README: Comprehensive updates with new features, examples, and AI prompt templates
• English README: Complete synchronization with Chinese documentation
• Configuration examples: Added MCP proxy server examples with various authentication scenarios
• AI prompt templates: Updated to support both REST-to-MCP and MCP proxy configurations

New Examples

• Basic MCP proxy server configuration
• Advanced passthrough authentication scenarios
• Mixed authentication strategies
• Server-level default security configurations

🔒 Security Enhancements

Two-Tier Authentication

• Client-to-Gateway: Validates MCP client identity and extracts credentials
• Gateway-to-Backend: Applies appropriate authentication for backend service calls
• Passthrough support: Optional credential forwarding from client to backend

Authentication Priority

1. Tool-level configuration (highest priority)
2. Server-level default configuration
3. Security scheme default credentials (lowest priority)

🧪 Testing

New Test Coverage

• Server-level default authentication scenarios
• MCP proxy server authentication flow
• Authentication header verification in actual HTTP requests
• URL modification handling in authentication
• Direct server field configuration and retrieval

Test Improvements

• Removed deprecated authentication functions and tests
• Enhanced test accuracy for HTTP header verification
• Added comprehensive proxy server integration tests

🎯 Use Cases

MCP Proxy Server

Perfect for scenarios where you need to:

• Add authentication layer to existing MCP servers
• Implement unified access control for multiple backend MCP services
• Provide transparent credential forwarding
• Add monitoring and logging to MCP communications

Server-Level Authentication

Ideal for:

• Unified authentication policies across all tools
• Simplifying configuration for large numbers of tools
• Providing default authentication for tools/list and other protocol operations
• Implementing consistent security practices

🔍 Files Changed

• examples/mcp-server/README.md - Updated Chinese documentation
• examples/mcp-server/README_EN.md - New English documentation
• examples/mcp-server/main_test.go - Enhanced authentication tests
• pkg/mcp/server/auth_utils.go - New shared authentication utilities
• pkg/mcp/server/plugin.go - Updated configuration parsing
• pkg/mcp/server/proxy_server.go - Enhanced proxy server implementation
• pkg/mcp/server/rest_server.go - Updated to use shared auth utilities
• pkg/mcp/server/proxy_tool.go - Refactored authentication handling
• Various test files - Comprehensive test updates

✅ Validation

• ✅ All existing functionality preserved
• ✅ Comprehensive test coverage for new features
• ✅ Documentation fully updated in both languages
• ✅ Authentication flow verified with actual HTTP request testing
• ✅ Backward compatibility maintained

---

Note

Introduces an MCP proxy server with HTTP/SSE transport, server-level default auth (downstream/upstream), shared auth utilities, enhanced REST server, dynamic tool allow-listing, and comprehensive docs/tests.

• MCP Server:
  • New mcp-proxy type with transport (http/sse), mcpServerURL, timeout, and passthroughAuthHeader in pkg/mcp/server/proxy_server.go.
  • SSE support: end-to-end SSE proxying and streaming handling in pkg/mcp/server/sse_proxy.go with response-body interception in plugin.go.
  • Server-level default auth: defaultDownstreamSecurity and defaultUpstreamSecurity parsed in pkg/mcp/server/plugin.go; applied in both proxy and REST servers.
  • Shared auth utilities: SecurityScheme, SecurityRequirement, AuthRequestContext, ExtractAndRemoveIncomingCredential, ApplySecurity in pkg/mcp/server/auth_utils.go (used by REST/proxy).
  • Dynamic tool allow-list: compute effective allow-tools via config/header intersection in pkg/mcp/server/plugin.go and proxy handlers.
  • REST server: refactored to use shared auth + default auth; supports direct-response tools and enhanced templating in pkg/mcp/server/rest_server.go.
  • JSON-RPC flow: pause/resume support via CtxNeedPause in pkg/mcp/utils/json_rpc.go.
• Config/Parsing:
  • Validation and parsing for new fields (transport, mcpServerURL, defaults, schemes) in pkg/mcp/server/plugin.go and config_validator_test.go.
• Examples:
  • Add CN/EN docs for configuration, proxy, passthrough, allowTools, templates (examples/mcp-server/README*.md).
  • Example Go-based weather server/tool and Dockerfile in examples/mcp-server/*.
• Tests:
  • Extensive unit/integration tests for proxy auth, tools/list & tools/call, SSE, defaults, allowTools, and REST features under pkg/mcp/server/*_test.go and examples/mcp-server/main_test.go.
• Misc:
  • Update .gitignore; add examples/mcp-server/go.mod.

^{Written by Cursor Bugbot for commit 707b07eb955aae3f25921aaba2e5b6f71a0778e7. This will update automatically on new commits. Configure here.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 43.46%. Comparing base (ef31e09) to head (f66aac9).
⚠️ Report is 773 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3096      +/-   ##
==========================================
+ Coverage   35.91%   43.46%   +7.55%     
==========================================
  Files          69       82      +13     
  Lines       11576    10917     -659     
==========================================
+ Hits         4157     4745     +588     
+ Misses       7104     5844    -1260     
- Partials      315      328      +13     

see 97 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.