MCP 람다 SAM
AWS Lambda와 SAM을 사용한 MCP(Model Context Protocol) 구현.
개요
이 프로젝트는 두 가지 고유한 인터페이스를 갖춘 모델 컨텍스트 프로토콜의 서버리스 구현을 제공합니다.
- 시스템 구성 (관리):
- MCP 도구, 리소스 및 프롬프트 등록
- IAM 권한 관리
- 인프라 설정 및 구성
- 시스템 사용 (클라이언트):
- SSE 연결 설정
- 명령 보내기
- 스트리밍 응답 수신
건축학
인어 다이어그램
다음 Mermaid 구문을 사용하여 시스템을 시각화할 수 있습니다.
지엑스피1
- MCP Lambda는 시작 시와 요청을 처리할 때 등록 테이블에서 등록을 읽습니다.
- 세션 상태를 유지하기 위해 세션 테이블을 사용합니다.
- 등록 테이블에 저장된 ARN을 사용하여 등록된 Lambda 도구를 동적으로 호출합니다 .
시스템 구성 가이드(관리자)
이 섹션은 MCP 서버를 구성하고 관리해야 하는 시스템 관리자를 위한 것입니다.
전개
npx @markvp/mcp-lambda-sam deploy
이 명령을 실행하면 관리 구성을 묻는 대화형 메시지가 표시됩니다.
- 스택 이름(여러 인스턴스의 경우)
- AWS 지역
- VPC 구성(선택 사항)
권한 개요
MCP 엔드포인트에 액세스하려면 사용자와 클라이언트에게 관련 함수 URL을 호출할 수 있는 IAM 권한이 있어야 합니다.
- 관리자 :
mcp-registration 함수 URL을 호출할 수 있어야 합니다. - 클라이언트 :
mcp 함수 URL을 호출할 수 있어야 합니다.
IAM 정책이나 aws lambda add-permission 사용하여 액세스 권한을 부여할 수 있습니다(아래 참조).
AWS CLI를 통한 권한 할당
등록 기능 호출에 대한 권한을 부여하려면 URL을 사용 하세요.
aws lambda add-permission \
--function-name <registration-function-name> \
--statement-id allow-registration \
--action lambda:InvokeFunctionUrl \
--principal "*" \
--function-url-auth-type IAM
MCP 기능 URL (SSE 및 메시지)을 호출할 수 있는 권한을 부여하려면 다음을 수행합니다.
aws lambda add-permission \
--function-name <mcp-function-name> \
--statement-id allow-mcp \
--action lambda:InvokeFunctionUrl \
--principal "*" \
--function-url-auth-type IAM
<registration-function-name> 과 <mcp-function-name> 실제 Lambda 함수 이름으로 바꾸세요.
등록 API
다음 엔드포인트를 사용하여 MCP 도구, 리소스 및 프롬프트를 관리하세요.
새 도구 등록
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"
}
}'
등록 업데이트
awscurl -X PUT ${REGISTRATION_URL}/register/{id} \
--region ap-southeast-2 \
--service lambda \
-d '...'
등록 삭제
awscurl -X DELETE ${REGISTRATION_URL}/register/{id} \
--region ap-southeast-2 \
--service lambda
등록 목록
awscurl ${REGISTRATION_URL}/register \
--region ap-southeast-2 \
--service lambda
필수 IAM 권한
관리자를 위한
관리자는 등록을 관리하기 위해 다음과 같은 권한이 필요합니다.
{
"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"
}
}
}]
}
시스템 사용 가이드(클라이언트)
이 섹션은 MCP 서버를 사용하려는 고객을 위한 것입니다.
필수 IAM 권한
클라이언트는 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"
}
}
}
]
}
서버에 연결
- 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));
};
SSE에 대한 cURL 예시
awscurl -X GET "${MCP_URL}/sse" \
--region ap-southeast-2 \
--service lambda
첫 번째 이벤트에는 sessionId 포함됩니다. 메시지를 보낼 때 사용하세요.
- 명령 보내기 :
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"
}
}'
오류 처리
일반적인 클라이언트 오류
401 : AWS 자격 증명이 잘못되었거나 누락되었습니다.403 : 권한이 부족합니다404 : 잘못된 세션 ID입니다.429 : 속도 제한을 초과했습니다.
문제 해결
- 연결 문제 :
- AWS 자격 증명 확인
- IAM 권한 확인
- 네트워크 연결성 확보
- 명령 실행 오류 :
- 세션 ID가 활성화되어 있는지 확인하세요
- 명령 형식이 도구 등록과 일치하는지 확인합니다.
- 매개변수가 스키마와 일치하는지 확인하세요.
요구 사항
- AWS CLI 설치 및 구성
- AWS SAM CLI 설치됨
- Node.js 20.x 이상
- 다음을 생성할 권한이 있는 AWS 계정:
- 람다 함수
- DynamoDB 테이블
- IAM 역할
- SQS 대기열
AWS SAM CLI 설정
AWS SAM CLI를 사용하여 이 애플리케이션을 로컬 또는 AWS에 배포하려면:
- AWS SAM CLI를 설치하세요: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html
- PATH에서 사용할 수 있는지 확인하세요.
- 애플리케이션을 빌드하고 배포합니다.
sam build
sam deploy --guided
- 프롬프트에 따라 스택 이름, 지역, 기능 및 매개변수 재정의를 구성합니다.
--guided 없이 sam deploy 다시 실행하면 저장된 구성을 사용할 수 있습니다.
설치
다음 네 가지 방법으로 이 애플리케이션을 설치하고 배포할 수 있습니다.
1. AWS Serverless Application Repository(SAR) 사용
MCP 서버를 배포하는 가장 쉬운 방법은 AWS Serverless Application Repository(SAR)를 사용하는 것입니다.
- SAR 콘솔 로 이동
- Mark Van Proctor의 mcp-lambda-sam 검색
- 배포를 클릭하세요
- 매개변수를 설정하세요:
StackIdentifier : 이 MCP 서버 인스턴스의 고유 IDVpcEnabled : VPC에 배포하는 경우 true 로 설정VpcId 및 SubnetIds : VpcEnabled 가 true 인 경우에만 제공
- 배포를 위한 프롬프트를 따르세요
또는 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. npx(CLI) 사용하기
npx @markvp/mcp-lambda-sam deploy
이 명령을 실행하면 관리 구성을 묻는 대화형 메시지가 표시됩니다.
- 스택 이름(여러 인스턴스의 경우)
- AWS 지역
- VPC 구성(선택 사항)
3. Install을 통한 프로그래밍 방식 사용
패키지를 설치하세요:
npm install @markvp/mcp-lambda-sam
패키지를 설치한 후에는 프로그래밍 방식으로 사용할 수 있습니다.
import { deploy } from '@markvp/mcp-lambda-sam';
// Usage example
deploy();
4. 지역 개발 및 배치
패키지를 설치하세요:
npm install @markvp/mcp-lambda-sam
개발 변경 사항을 적용한 후에는 수동으로 배포할 수 있습니다.
개발
# Install dependencies
npm install
# Lint
npm run lint
# Run tests
npm test
# Build
npm run build
# Deploy
npm run deploy
SAR에 게시
이 프로젝트에 기여하고 SAR에 업데이트를 게시해야 하는 경우:
- 애플리케이션을 패키징합니다.
- SAR에 게시:
- 애플리케이션을 공개합니다(한 번만 설정):
- AWS 콘솔 > 서버리스 애플리케이션 저장소로 이동
- 응용 프로그램을 선택하세요
- "공유"를 클릭하고 "공개"를 선택하세요
- 다음 공유 정책을 적용하세요: GXP25
특허
MIT
기여하다
- 저장소를 포크하세요
- 기능 브랜치를 생성하세요
- 변경 사항을 커밋하세요
- 지점으로 밀어 넣기
- 새로운 풀 리퀘스트 만들기