MCP Login Poc

🎴 Luna卡 MCP 登录 POC（概念验证）

这是一个基于ID/密码+OAuth（授权码+PKCE）认证的最小功能POC（概念验证）。

📋 项目结构

MCP Login Poc/
├── cdk/                    # AWS 인프라 (CDK)
│   ├── bin/
│   ├── lib/
│   ├── lambda/            # Lambda 함수 코드
│   │   ├── public/       # 무인증 API
│   │   └── protected/    # 인증 필요 API
│   └── scripts/          # 데이터 시드 스크립트
├── frontend/              # Next.js 프론트엔드
│   ├── pages/
│   │   ├── index.js      # 공개 랜딩 페이지
│   │   ├── dashboard.js  # 보호된 대시보드
│   │   ├── api/
│   │   │   ├── login.js  # Cognito 로그인 리다이렉트
│   │   │   └── token.js  # 토큰 교환
│   │   └── auth/
│   │       └── callback.js # OAuth 콜백
│   └── styles/
├── mcp-server/            # MCP 서버 (Claude 연동)
│   ├── server.js         # Express 서버
│   └── README.md
└── README.md              # 이 파일

🎯 主要功能

✅ 实现的功能

1. 公开内容查询 （无认证）

- 卡片商品信息 - 金融产品信息

1. 查看结算明细 （需要认证）

- 基于JWT的认证 - 用户各自的支付记录

1. OAuth认证流程

- Cognito 托管用户界面 - 授权码 + 密码客户端凭证（PKCE） - 访问令牌管理

1. MCP服务器（与Claude联动）

- 获取公开内容工具 - getPayments 工具（OAuth）

🚀 开始

1. AWS基础设施部署

cd cdk

# 패키지 설치
npm install

# Lambda 함수 의존성 설치
cd lambda/public && npm install && cd ../..
cd lambda/protected && npm install && cd ../..

# CDK 배포
npm run deploy

# 배포 완료 후 출력값 확인 및 저장:
# - UserPoolId
# - FrontendClientId
# - McpClientId
# - CognitoDomain
# - ApiEndpoint

2. 样本数据种子

cd cdk/scripts
npm install
npm run seed

重要： 首次创建用户后，DynamoDB的 userId为Cognito用户 sub 需要将其值进行更改。

3. 创建Cognito用户

AWS 控制台 → Cognito 用户池 → 用户 → 创建用户

• 用户名： testuser （或者想要的名字）
• 电子邮件：真实的电子邮件地址
• 设置临时密码

生成后用户的 sub 确认值，并在DynamoDB中 mcp-poc-payments 将表格中的现有数据对应到 sub改为“罗”。

4. 前端设置及运行

cd frontend

# 패키지 설치
npm install

# 환경변수 설정
cp .env.example .env

# .env 파일 편집 (CDK 출력값 입력):
# NEXT_PUBLIC_API_BASE_URL=https://xxxxx.execute-api.ap-northeast-2.amazonaws.com
# NEXT_PUBLIC_COGNITO_DOMAIN=mcp-poc-xxxxx.auth.ap-northeast-2.amazoncognito.com
# NEXT_PUBLIC_COGNITO_CLIENT_ID=xxxxx (FrontendClientId)
# NEXT_PUBLIC_COGNITO_REGION=ap-northeast-2
# NEXT_PUBLIC_COGNITO_REDIRECT_URI=http://localhost:3000/auth/callback

# 개발 서버 실행
npm run dev

在浏览器中 http://localhost:3000 连接

5. Vercel 部署（可选）

# Vercel CLI 설치
npm i -g vercel

# 배포
cd frontend
vercel

# 환경변수 설정 (Vercel Dashboard 또는 CLI)
vercel env add NEXT_PUBLIC_API_BASE_URL
vercel env add NEXT_PUBLIC_COGNITO_DOMAIN
vercel env add NEXT_PUBLIC_COGNITO_CLIENT_ID
vercel env add NEXT_PUBLIC_COGNITO_REGION
vercel env add NEXT_PUBLIC_COGNITO_REDIRECT_URI

# REDIRECT_URI를 Vercel 도메인으로 변경
# 예: https://your-app.vercel.app/auth/callback

重要： 在Vercel部署后，需要在Cognito User Pool的应用客户端设置中添加回调URL。

AWS 控制台 → Cognito → 用户池 → 应用客户端 → 编辑托管用户界面设置

• 在回调URL中 https://your-app.vercel.app/auth/callback 添加
• 在登出URL中 https://your-app.vercel.app 附加

6. MCP服务器设置及运行

cd mcp-server

# 패키지 설치
npm install

# 환경변수 설정
cp .env.example .env

# .env 파일 편집 (CDK 출력값 입력):
# API_BASE_URL=https://xxxxx.execute-api.ap-northeast-2.amazonaws.com
# COGNITO_DOMAIN=mcp-poc-xxxxx.auth.ap-northeast-2.amazoncognito.com
# COGNITO_CLIENT_ID=xxxxx (McpClientId - 주의: Frontend와 다름!)
# COGNITO_REGION=ap-northeast-2
# COGNITO_REDIRECT_URI=http://localhost:4000/oauth/callback
# PORT=4000

# 서버 실행
npm start

服务器 http://localhost:4000中运行。

7. MCP服务器测试

公开内容查看（无需认证）

curl -X POST http://localhost:4000/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "getPublicContent",
    "arguments": {
      "type": "cards"
    }
  }'

OAuth 登录及支付记录查询

1. 在浏览器中 http://localhost:4000/oauth/authorize 连接
2. 在Cognito托管UI中登录
3. 在回调页面上复制访问令牌
4. 以下命令用于查询支付记录：

curl -X POST http://localhost:4000/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "getPayments",
    "arguments": {},
    "access_token": "여기에-액세스-토큰-붙여넣기"
  }'

🤖 Cursor/Claude 联动

当前MCP服务器状态

这个POC的MCP服务器是 标准REST API服务器它已实现为（某种形式）。若要直接在Claude Desktop或Cursor中连接，则需要额外的操作：

选项1：手动测试（当前可用）

在Cursor的AI聊天中，你可以这样请求：

"MCP 서버에 연결해서 루나카드 상품 목록을 가져와줘"

Cursor自动地 http://localhost:4000/mcp/execute 调用端点。

选项2：集成MCP SDK（推荐，需要额外工作）

要使用官方MCP SDK实现完全集成：

1. @modelcontextprotocol/sdk 安装包
2. MCP标准协议实现
3. 在Cursor配置文件中注册MCP服务器

详细内容请见 MCP官方文档请参考。

📝 API 端点

公开API（无认证）

• GET /public/cards - 卡片商品列表
• GET /public/products - 金融产品列表

受保护的API（需要JWT）

• GET /me/payments - 用户支付记录

- 头球 Authorization: Bearer

🔐 认证流程

사용자 → 프론트엔드 → Cognito Hosted UI
                           ↓
                    (ID/비밀번호 입력)
                           ↓
      콜백 (인증 코드) → 토큰 교환 (PKCE)
                           ↓
                     액세스 토큰 획득
                           ↓
              API Gateway (JWT Authorizer)
                           ↓
                    Lambda (DynamoDB)

🧪 测试场景

1. 查看公开内容

1. 访问前端主页
2. 确认3个信用卡商品，2个金融商品

2. 认证后查看支付记录

1. 点击“我的仪表盘”
2. 重定向到登录页面
3. 使用Cognito托管UI登录
4. 在仪表盘上查看3条支付记录

3. 通过MCP服务器连接Claude

1. 运行MCP服务器
2. 公开内容API调用（无认证）
3. OAuth 登录
4. 调用支付记录API（认证）

🛠️ 故障排除

CDK 分发失败

• AWS凭证验证： aws configure
• 执行CDK Bootstrap： cdk bootstrap

Cognito 登录失败

• 确认回调URL是否已正确注册
• 确认App Client ID是否正确
• 确认用户是否已添加到用户池中

API Gateway 401 错误

• 验证JWT令牌是否正确
• 确认App Client ID是否已注册到JWT Authorizer
• 确认令牌是否未过期

无法查询DynamoDB数据

• userId是Cognito用户的 sub并确认是否一致
• 确认表名是否正确
• 确认Lambda函数是否具有DynamoDB的读取权限

📚 参考资料

• AWS CDK 文档
• Amazon Cognito 用户池
• Next.js 文档
• 模型上下文协议
• OAuth 2.0 PKCE（公共客户端证明代码，Proof Key for Code Exchange）

📄 许可证

这个项目是作为POC（概念验证）而制作的。

👥 贡献

如有任何疑问或改进建议，请提交问题。