AI工具网关服务

┌───────────┐     ┌───────────┐     ┌─────────────────────────────────────────────────┐
│    MCP    │────▶│ Entra ID  │     │                  AWS Cloud                      │
│   Client  │◀────│  (PKCE)   │     │                                                 │
└───────────┘     └───────────┘     │  ┌───────────────────────────────────────────┐  │
      │                │            │  │      Bedrock AgentCore Gateway            │  │
      │           OAuth Token       │  │  • JWT validation (OIDC)                  │  │
      │                │            │  │  • Semantic tool search                   │  │
      │                ▼            │  │  • Interceptor: JWT → User Info           │  │
      └───────────▶ Gateway ────────┼──│  • Target: tool_schema.json routing       │  │
                      URL           │  └──────────────────────┬────────────────────┘  │
                                    │                         │                       │
                                    │  ┌──────────────────────▼────────────────────┐  │
                                    │  │         Main Lambda (Rust) + Interceptor  │  │
                                    │  │  • Weather lookup (Open-Meteo API)        │  │
                                    │  │  • Personalized greetings                 │  │
                                    │  └──────────────────────┬────────────────────┘  │
                                    │                         │                       │
                                    │  ┌────────────────┴────────┐                    │
                                    │  │     CloudWatch Logs     │                    │
                                    │  └─────────────────────────┘                    │
                                    └─────────────────────────┬───────────────────────┘
                                                              ▼
                                                   ┌─────────────────┐
                                                   │  Open-Meteo API │
                                                   └─────────────────┘

**Stack**: ARM64 Lambdas (128MB, ~1.3MB UPX) | Entra ID OAuth | CloudWatch (3d retention)

**Features**: JWT token decoding, automatic weather lookup, personalized user greetings, secure header propagation, dynamic schema generation

**License**: MIT

## Model Context Protocol Implementation

This is a **Model Context Protocol (MCP) server** implemented as an AWS Lambda function for Amazon Bedrock AgentCore. MCP is an open-source specification that enables AI agents to discover and interact with external tools and APIs in a standardized way. This server uses the `rmcp` crate's `#[tool]` macro for MCP-compliant schema generation.

The Bedrock AgentCore Gateway is configured with a `SEMANTIC` search type, which enables intelligent tool selection. This means it can understand natural language queries, match tool descriptions and parameters, and provide context-aware tool recommendations, significantly improving the agent's ability to utilize available tools effectively.

## Features

- **ARM64/Graviton** - 20% cheaper, UPX compressed to 1.3MB per Lambda
- **Secretless OAuth** - PKCE flow, no client secrets
- **JWT Token Decoding** - Automatic user information extraction from Entra ID tokens with expiry validation
- **Gateway Interceptor** - Header propagation and identity resolution between gateway and tools
- **Dynamic Schema Generation** - Tool schemas automatically generated and deployed
- **Regional NAT Gateway** - Auto HA across AZs, stable egress IP
- **Zero Unsafe** - No `unwrap/expect/panic/unsafe`, strict lints
- **Concurrency Limits** - Function-level concurrent execution limits to prevent cost overruns
- **Event Notifications** - SNS notifications for infrastructure events
- **Structured Logging** - JSON logs for CloudWatch
- **Dead Letter Queue** - Failed invocations stored in encrypted SQS for debugging
- **Auto Schemas** - Generated from code annotations
- **Fast Cold Start** - Minimal deps, optimized binary
- **Cost Optimized** - Minimum memory (128MB), conservative timeouts, low concurrency limits
- **Principle of Least Privilege** - IAM policies scoped to specific resources
- **Resource Cleanup** - Terraform properly manages all resources
- **Free Tier** - Typical usage $0/month
- **Smart Weather Lookup** - Automatic geocoding and weather data retrieval from Open-Meteo
- **Personalized Greetings** - Context-aware user greetings with automatic name extraction

## One-Time Backend Setup

Before you can deploy, you need to run a one-time setup command to create the Terraform backend infrastructure:

```bash
make setup-backend

make deploy

make setup-backend # One-time backend setup (S3 with native locking)
make deploy        # Build and deploy to AWS
make test-token    # Get OAuth token + launch MCP Inspector

# Deploy a manual environment (replace 123 with your PR number)
gh workflow run preview-environment.yml -f action=deploy -f pr_number=123

# Destroy a manual environment
gh workflow run preview-environment.yml -f action=destroy -f pr_number=123

# Trigger the test workflow which mints an installation token and validates it
# from the Actions tab: "Test: GitHub App Installation Token" → Run workflow
# or via CLI:
# gh workflow run test-github-app-token.yml

make update-secrets

src/
├── main.rs              # Main Lambda bootstrap + tracing
├── handler.rs           # Main Lambda event handler
├── lib.rs               # Library crate
├── models/              # Request/response types (JsonSchema)
│   ├── mod.rs
│   ├── weather.rs
│   └── open_meteo.rs
├── tools/               # Tool implementations (#[tool] macro)
│   ├── mod.rs
│   ├── weather.rs
│   └── personalized.rs
├── http/                # Global HTTP client
│   ├── mod.rs
│   └── client.rs
└── bin/
    ├── generate_schema.rs  # Schema generation utility
    └── interceptor.rs      # Gateway interceptor Lambda
iac/
├── main.tf              # Terraform infrastructure
└── ...

make schema    # Generate tool_schema.json
make build     # Debug build
make release   # ARM64 + UPX (~1.3MB)
make test      # Run tests
make all       # Test + release build
cargo clippy   # Run clippy lints
cargo fmt      # Format code

make setup-backend # One-time backend setup
make deploy        # Build and deploy to AWS
make tf-destroy    # Destroy infrastructure

make test-token   # OAuth + Inspector (token auto-copied)
make test-lambda  # Direct Lambda test
make logs         # Tail CloudWatch logs
make login        # AWS + Azure auth
make clean        # Remove tokens/backups

make tf-init   # Initialize Terraform
make tf-plan   # Plan changes
make tf-apply  # Apply changes
make tf-destroy # Destroy infrastructure

# Disabled (default) - Minimal error information for security
gateway_exception_level = null

# Error level - Only error messages
gateway_exception_level = "ERROR"

# Warning level - Warning and error messages
gateway_exception_level = "WARN"

# Info level - Informational, warning, and error messages
gateway_exception_level = "INFO"

# Debug level - Most verbose logging (use only for troubleshooting)
gateway_exception_level = "DEBUG"

variable "rust_log_level" {
  default = "debug"  # or "trace"
}

use rmcp::tool;

#[tool(description = "Get current weather for a location")]
pub async fn get_weather(request: WeatherRequest) -> Result<WeatherResponse> {
    // implementation
}

#[derive(Debug, Deserialize, JsonSchema)]
pub struct YourRequest {
    #[schemars(description = "Input description")]
    pub input: String,
}

#[tool(description = "Clear, detailed description")]
pub async fn your_tool(request: YourRequest) -> Result<YourResponse> {
    // implementation
}

tool_entry!(
    aws_lambda_mcp::tools::your_tool::your_tool_tool_attr(),
    YourRequest,
    YourResponse
),

[package.metadata.lambda.deploy]
memory = 128
timeout = 30
tracing = "active"