# MCP Lambda SAM

Model Context Protocol (MCP) implementation using AWS Lambda and SAM.

## Overview

This project provides a serverless implementation of the Model Context Protocol, with two distinct interfaces:

1. **System Configuration** (Administrative):
   - Registration of MCP tools, resources, and prompts
   - IAM permission management
   - Infrastructure setup and configuration

2. **System Usage** (Client):
   - Establishing SSE connections
   - Sending commands
   - Receiving streaming responses

## Architecture

### Mermaid Diagram

You can visualize the system using this Mermaid syntax:

```mermaid
graph TD
  Client --> MCP[/"MCP Lambda\n(/sse & /message)"/]
  MCP -->|read/write| SessionTable[(Session Table)]
  MCP -->|query| RegistrationTable[(Registration Table)]
  MCP -->|invoke| RegisteredLambda["Registered Lambda Tool"]

  Admin[Administrator] --> RegistrationLambda[/"Registration Lambda\n(/register)"/]
  RegistrationLambda -->|write| RegistrationTable
```

- The **MCP Lambda** reads registrations from the Registration Table on startup and when handling requests.
- It uses the Session Table to persist session state.
- It **invokes registered Lambda tools** dynamically using the ARNs stored in the Registration Table. 

## System Configuration Guide (Administrators)

This section is for system administrators who need to configure and manage the MCP server.

### Deployment

```bash
npx @markvp/mcp-lambda-sam deploy
```

The command will interactively prompt for administrative configuration:
- Stack name (for multiple instances)
- AWS Region
- VPC configuration (optional)

### Permissions Overview

To access MCP endpoints, users and clients must have IAM permission to invoke the relevant Function URLs.

- **Administrators**: must be allowed to invoke the `mcp-registration` function URL
- **Clients**: must be allowed to invoke the `mcp` function URL

You can grant access using either an IAM policy or `aws lambda add-permission` (see below).

### Assigning Permissions via AWS CLI

To grant permission to invoke the **registration function URL**:

```bash
aws lambda add-permission \
  --function-name <registration-function-name> \
  --statement-id allow-registration \
  --action lambda:InvokeFunctionUrl \
  --principal "*" \
  --function-url-auth-type IAM
```

To grant permission to invoke the **MCP function URL** (SSE and message):

```bash
aws lambda add-permission \
  --function-name <mcp-function-name> \
  --statement-id allow-mcp \
  --action lambda:InvokeFunctionUrl \
  --principal "*" \
  --function-url-auth-type IAM
```

Replace `<registration-function-name>` and `<mcp-function-name>` with the actual Lambda function names.

### Registration API

Use these endpoints to manage MCP tools, resources, and prompts:

#### Register a New Tool
```bash
awscurl -X POST ${REGISTRATION_URL}/register \
  --region ap-southeast-2 \
  --service lambda \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tool",
    "name": "example",
    "description": "Example tool",
    "lambdaArn": "arn:aws:lambda:region:account:function:name",
    "parameters": {
      "input": "string"
    }
  }'
```

#### Update Registration
```bash
awscurl -X PUT ${REGISTRATION_URL}/register/{id} \
  --region ap-southeast-2 \
  --service lambda \
  -d '...'
```

#### Delete Registration
```bash
awscurl -X DELETE ${REGISTRATION_URL}/register/{id} \
  --region ap-southeast-2 \
  --service lambda
```

#### List Registrations
```bash
awscurl ${REGISTRATION_URL}/register \
  --region ap-southeast-2 \
  --service lambda
```

### Required IAM Permissions

#### For Administrators
Administrators need these permissions to manage registrations:
```json
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "lambda:InvokeFunctionUrl",
    "Resource": "arn:aws:lambda:${region}:${account}:function:${stack-id}-mcp-registration",
    "Condition": {
      "StringEquals": {
        "lambda:FunctionUrlAuthType": "AWS_IAM"
      }
    }
  }]
}

```

## System Usage Guide (Clients)

This section is for clients who want to use the MCP server.

### Required IAM Permissions

Clients need these permissions to use the MCP server:
```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "lambda:InvokeFunctionUrl",
            "Resource": [
                "arn:aws:lambda:${region}:${account}:function:${stack-id}-mcp",
            ],
            "Condition": {
                "StringEquals": {
                    "lambda:FunctionUrlAuthType": "AWS_IAM"
                }
            }
        }
    ]
}
```

### Connecting to the Server

1. **Establish SSE Connection**:
```typescript
const sse = new EventSource(SSE_URL, {
  headers: { 
    Authorization: 'AWS4-HMAC-SHA256 ...', // Must be AWS SigV4 signed
  }
});

sse.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};
```

### Example cURL for SSE

```bash
awscurl -X GET "${MCP_URL}/sse" \
  --region ap-southeast-2 \
  --service lambda
```

The first event will include a `sessionId`. Use this when sending messages.

2. **Send Commands**:
```bash
awscurl -X POST "${MCP_URL}/message?sessionId=session-123" \
  --region ap-southeast-2 \
  --service lambda \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "example",
    "params": {
      "input": "hello"
    }
  }'
```

### Error Handling

#### Common Client Errors
- `401`: Invalid/missing AWS credentials
- `403`: Insufficient permissions
- `404`: Invalid session ID
- `429`: Rate limit exceeded

#### Troubleshooting
1. **Connection Issues**:
   - Verify AWS credentials
   - Check IAM permissions
   - Ensure network connectivity

2. **Command Execution Errors**:
   - Verify session ID is active
   - Check command format matches tool registration
   - Ensure parameters match schema

## Requirements

- AWS CLI installed and configured
- AWS SAM CLI installed
- Node.js 20.x or later
- An AWS account with permissions to create:
  - Lambda functions
  - DynamoDB tables
  - IAM roles
  - SQS queues

## AWS SAM CLI Setup

To deploy this application locally or to AWS using the AWS SAM CLI:

1. Install the AWS SAM CLI: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html
2. Ensure it's available in your PATH:
   ```bash
   sam --version
   ```
3. Build and deploy the application:
   ```bash
   sam build
   sam deploy --guided
   ```
4. Follow the prompts to configure the stack name, region, capabilities, and parameter overrides.

You can rerun `sam deploy` without `--guided` to use saved configuration.

## Installation

You can install and deploy this application in four ways:

### 1. Using AWS Serverless Application Repository (SAR)

The easiest way to deploy the MCP server is through the AWS Serverless Application Repository (SAR):

- Go to the [SAR Console](https://serverlessrepo.aws.amazon.com/applications)
- Search for **mcp-lambda-sam** by Mark Van Proctor
- Click **Deploy**
- Set your parameters:
  - `StackIdentifier`: Unique ID for this MCP server instance
  - `VpcEnabled`: Set to `true` if deploying in a VPC
  - `VpcId` and `SubnetIds`: Provide only if `VpcEnabled` is `true`
- Follow the prompts to deploy

Alternatively, you can deploy from the AWS CLI:
```bash
aws serverlessrepo create-cloud-formation-change-set \
  --application-id arn:aws:serverlessrepo:ap-southeast-2:522814717816:applications/mcp-lambda-sam \
  --stack-name your-stack-name \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides '[{"name":"StackIdentifier","value":"your-stack-id"}]'
```
  
### 2. Using npx (CLI)

```bash
npx @markvp/mcp-lambda-sam deploy
```

The command will interactively prompt for administrative configuration:
- Stack name (for multiple instances)
- AWS Region
- VPC configuration (optional)

### 3. Programmatic Usage with Install
Install the package:

```bash
npm install @markvp/mcp-lambda-sam
```

After installing the package, you can use it programmatically:
```javascript
import { deploy } from '@markvp/mcp-lambda-sam';

// Usage example
deploy();
```

### 4. Local Development and Deployment
Install the package:

```bash
npm install @markvp/mcp-lambda-sam
```

After making development changes, you can deploy it manually:
```bash
npm run deploy
```

## Development
```bash
# Install dependencies
npm install

# Lint
npm run lint

# Run tests
npm test

# Build
npm run build

# Deploy
npm run deploy
```

### Publishing to SAR

If you're contributing to this project and need to publish updates to SAR:

1. Package the application:
```bash
npm run package:sar
```

2. Publish to SAR:
```bash
npm run publish:sar
```

3. Make the application public (one-time setup):
   - Go to AWS Console > Serverless Application Repository
   - Select the application
   - Click "Share" and choose "Public"
   - Apply the following sharing policy:
   ```json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": "*",
               "Action": "serverlessrepo:CreateCloudFormationTemplate",
               "Resource": "arn:aws:serverlessrepo:${region}:${account-id}:applications/mcp-lambda-sam"
           }
       ]
   }
   ```

## License

MIT

## Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request