Serverless Aws

This is a POC of a service using AI Agents where there is a Model Context Protocol (MCP) server and one MCP Client that will interact with the MCP server and external services.

Technologies used

• Node.js
• TypeScript
• AWS SAM
• AWS Lambda
• AWS API Gateway
• Google Gemini
• Claude Desktop

How to run it locally

Since the MCP Client doesn't have a real use beyond interacting with the MCP server, we can use Claude Desktop as a client.

• Add your GeminiApiKey to the samconfig.toml file in the root of the project.

• Deploy the MCP server in AWS (Go to the Getting Started section of this Readme)

• Install Claude Desktop

• In your claude_desktop_config.json file, add the following configuration:

  {
      "mcpServers": {
         "mcp-server": {
            "command": "npx",
            "args": [
               "-y",
               "mcp-remote",
               "https://12345.execute-api.us-east-2.amazonaws.com/Prod/mcp", // your mcp server api url
               "--transport",
               "http-only",
               "--header",
               "x-api-key:abcd1234" // your api key
            ]
         }
      }
   }
  

Architecture

The project follows hexagonal architecture (ports and adapters) with the following structure:

src/
├── domain/           # Core business logic
│   ├── entities/     # Domain entities (WebhookEvent)
│   ├── ports/        # Interface definitions (WebhookRepository, Logger)
│   └── use-cases/    # Business use cases (ProcessWebhookUseCase)
├── infrastructure/   # Infrastructure implementations
│   └── adapters/     # Adapters for external services (CloudWatchLogger, InMemoryWebhookRepository)
└── handlers/         # Lambda function handlers
    └── webhook.ts           # SQS handler

Prerequisites

• Node.js 22.x
• AWS SAM CLI
• AWS CLI configured with appropriate credentials
• Docker (for local testing)

Getting Started

1. Install dependencies:

   npm install
   

2. Build the project using SAM:

   npm run sam:build
   

3. Run tests to ensure everything is working:

   npm test
   

4. For full integration testing, deploy to AWS:

   npm run sam:deploy
   

Development

Local Development

What You Can Test Locally

1. Lambda Function Testing:

   npm run sam:build
   sam local invoke WebhookProcessorFunction -e test-event.json
   

2. Unit Tests:

   npm test
   npm run test:coverage
   

3. Type Checking:

   npm run type-check
   

4. Linting:

   npm run lint
   npm run lint:fix
   

What Requires AWS Deployment

• Full Integration Testing: API Gateway → SQS → Lambda flow
• Webhook Endpoint Testing: The /webhook endpoint functionality
• SQS Integration: Queue processing and DLQ behavior

To test the complete flow, deploy to AWS:

npm run sam:deploy

Then test with a real webhook request to your deployed API Gateway endpoint.

Testing

• Run unit tests:

  npm test