SAM Lambda MCP

Implementación del Protocolo de Contexto de Modelo (MCP) utilizando AWS Lambda y SAM.

Descripción general

Este proyecto proporciona una implementación sin servidor del Protocolo de Contexto de Modelo, con dos interfaces distintas:

1. Configuración del sistema (administrativa):

   • Registro de herramientas, recursos y avisos de MCP

   • Gestión de permisos de IAM

   • Configuración y configuración de la infraestructura

2. Uso del sistema (cliente):

   • Establecimiento de conexiones SSE

   • Envío de comandos

   • Recibir respuestas en streaming

Related MCP server: Node Omnibus MCP Server

Arquitectura

Diagrama de sirena

Puedes visualizar el sistema utilizando esta sintaxis de 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

• MCP Lambda lee registros de la tabla de registros durante el inicio y al manejar solicitudes.

• Utiliza la tabla de sesión para conservar el estado de la sesión.

• Invoca herramientas Lambda registradas dinámicamente utilizando los ARN almacenados en la tabla de registro.

Guía de configuración del sistema (administradores)

Esta sección es para los administradores de sistemas que necesitan configurar y administrar el servidor MCP.

Despliegue

npx @markvp/mcp-lambda-sam deploy

El comando solicitará interactivamente la configuración administrativa:

• Nombre de la pila (para múltiples instancias)

• Región de AWS

• Configuración de VPC (opcional)

Descripción general de permisos

Para acceder a los puntos finales de MCP, los usuarios y clientes deben tener permiso de IAM para invocar las URL de función relevantes.

• Administradores : deben tener permiso para invocar la URL de la función mcp-registration

• Clientes : se debe permitir invocar la URL de la función mcp

Puede otorgar acceso mediante una política de IAM o mediante aws lambda add-permission (ver a continuación).

Asignación de permisos a través de AWS CLI

Para conceder permiso para invocar la función de registro URL :

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

Para otorgar permiso para invocar la URL de la función MCP (SSE y mensaje):

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

Reemplace <registration-function-name> y <mcp-function-name> con los nombres de función Lambda reales.

API de registro

Utilice estos puntos finales para administrar herramientas, recursos y avisos de MCP:

Registrar una nueva herramienta

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"
    }
  }'

Actualizar registro

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

Eliminar registro

awscurl -X DELETE ${REGISTRATION_URL}/register/{id} \
  --region ap-southeast-2 \
  --service lambda

Lista de registros

awscurl ${REGISTRATION_URL}/register \
  --region ap-southeast-2 \
  --service lambda

Permisos de IAM necesarios

Para administradores

Los administradores necesitan estos permisos para gestionar los registros:

{
  "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"
      }
    }
  }]
}

Guía de uso del sistema (clientes)

Esta sección es para los clientes que desean utilizar el servidor MCP.

Permisos de IAM necesarios

Los clientes necesitan estos permisos para utilizar el servidor MCP:

{
    "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"
                }
            }
        }
    ]
}

Conectarse al servidor

1. Establecer conexión SSE :

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));
};

Ejemplo de cURL para SSE

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

El primer evento incluirá un sessionId . Úselo al enviar mensajes.

2. Enviar comandos :

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"
    }
  }'

Manejo de errores

Errores comunes del cliente

• 401 : Credenciales de AWS no válidas o faltantes

• 403 : Permisos insuficientes

• 404 : ID de sesión no válido

• 429 : Límite de velocidad excedido

Solución de problemas

1. Problemas de conexión :

   • Verificar las credenciales de AWS

   • Comprobar los permisos de IAM

   • Garantizar la conectividad de la red

2. Errores de ejecución de comandos :

   • Verificar que el ID de sesión esté activo

   • Compruebe que el formato del comando coincida con el registro de la herramienta

   • Asegúrese de que los parámetros coincidan con el esquema

Requisitos

• AWS CLI instalada y configurada

• AWS SAM CLI instalado

• Node.js 20.x o posterior

• Una cuenta de AWS con permisos para crear:

  • Funciones lambda

  • Tablas de DynamoDB

  • Roles de IAM

  • Colas SQS

Configuración de la CLI de AWS SAM

Para implementar esta aplicación localmente o en AWS mediante la CLI de AWS SAM:

1. Instale la CLI de AWS SAM: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html

2. Asegúrese de que esté disponible en su PATH:

   sam --version

3. Construya e implemente la aplicación:

   sam build
   sam deploy --guided

4. Siga las instrucciones para configurar el nombre de la pila, la región, las capacidades y las anulaciones de parámetros.

Puede volver a ejecutar sam deploy sin --guided para usar la configuración guardada.

Instalación

Puede instalar e implementar esta aplicación de cuatro maneras:

1. Uso del repositorio de aplicaciones sin servidor de AWS (SAR)

La forma más sencilla de implementar el servidor MCP es a través del repositorio de aplicaciones sin servidor (SAR) de AWS:

• Vaya a la consola SAR

• Búsqueda de mcp-lambda-sam por Mark Van Proctor

• Haga clic en Implementar

• Establezca sus parámetros:

  • StackIdentifier : ID único para esta instancia del servidor MCP

  • VpcEnabled : configúrelo como true si se implementa en una VPC

  • VpcId y SubnetIds : Proporcione solo si VpcEnabled es true

• Siga las instrucciones para implementar

Alternativamente, puede implementar desde la AWS CLI:

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. Uso de npx (CLI)

npx @markvp/mcp-lambda-sam deploy

El comando solicitará interactivamente la configuración administrativa:

• Nombre de la pila (para múltiples instancias)

• Región de AWS

• Configuración de VPC (opcional)

3. Uso programático con instalación

Instalar el paquete:

npm install @markvp/mcp-lambda-sam

Después de instalar el paquete, puedes usarlo programáticamente:

import { deploy } from '@markvp/mcp-lambda-sam';

// Usage example
deploy();

4. Desarrollo local y despliegue

Instalar el paquete:

npm install @markvp/mcp-lambda-sam

Después de realizar cambios de desarrollo, puedes implementarlo manualmente:

npm run deploy

Desarrollo

# Install dependencies
npm install

# Lint
npm run lint

# Run tests
npm test

# Build
npm run build

# Deploy
npm run deploy

Publicación en SAR

Si está contribuyendo a este proyecto y necesita publicar actualizaciones en SAR:

1. Empaquetar la aplicación:

npm run package:sar

2. Publicar en SAR:

npm run publish:sar

3. Hacer pública la aplicación (configuración única):

   • Vaya a la consola de AWS > Repositorio de aplicaciones sin servidor

   • Seleccione la aplicación

   • Haga clic en "Compartir" y seleccione "Público".

   • Aplicar la siguiente política de uso compartido: GXP25

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Contribuyendo

1. Bifurcar el repositorio

2. Crea tu rama de funciones

3. Confirme sus cambios

4. Empujar hacia la rama

5. Crear una nueva solicitud de extracción