SafeCart-AI

트랙: 01 — AI Growth & Agentic Commerce

문제: 곧 사람들은 판매자의 봇과 채팅하며 쇼핑하지 않게 될 것입니다. 대신 자신만의 AI 에이전트에게 쇼핑을 맡기게 됩니다. 판매자에게는 AI 에이전트가 카탈로그를 둘러보고 고객을 대신해 돈을 지출할 수 있게 해 주는 안전한 수단이 필요합니다. 이 프로젝트는 바로 그 빠져 있던 신뢰 계층을 제공합니다.

기능

SafeCart-AI는 Model Context Protocol을 통해 판매자의 상품 카탈로그를 모든 MCP 호환 AI 에이전트(예: Claude)에 노출합니다.

에이전트는 상품을 둘러보고 구매를 요청할 수 있지만, 모든 구매는 Razorpay 테스트 모드 주문 생성 전에 정책 엔진을 통과해야 합니다.

정책 엔진은 다음을 적용합니다:

• 설명 가능성 — 에이전트는 구매에 대한 타당한 사유를 제공해야 합니다.

• 지출 상한 — 구매는 거래별 한도와 세션 전체 지출 상한을 통해 통제됩니다.

• 게이팅 — 중간 금액 구매는 자동 실행되지 않고 담당자 승인을 받도록 보냅니다.

• 감사 기록 — 구매 시도는 무엇이 요청되었는지, 왜 요청되었는지, 시스템이 어떤 결정을 내렸는지와 함께 기록됩니다.

• 안전한 실패 처리 — 품절 상품과 같은 유효하지 않은 요청은 명확한 안내와 함께 거부됩니다.

Related MCP server: agent-commerce-mcp-server

Architecture

AI Agent (Claude, etc.)
        │
        │ MCP tools:
        │ browse_products
        │ get_product_details
        │ request_purchase
        │ get_audit_trail
        ▼
  mcp_server.py
        │
        ▼
    policy.py ──────────────► SQLite audit log
        │                       logs/audit.db
        │
        │ approved requests
        ▼
razorpay_client.py ────────► Razorpay Test-Mode Orders API

dashboard.py (Flask)
        │
        └────────────────────► Human approve/reject UI

Why this design

결제 통합은 의도적으로 정책 엔진과 분리되어 있습니다.

razorpay_client.py는 정책 레이어가 구매 요청을 승인한 후에만 호출됩니다. 이렇게 함으로써 의사 결정 로직과 결제 통합을 분리하고, 구매 결정을 설명 가능하고 감사 가능한 것으로 만듭니다.

이 프로젝트는 다음 원칙을 바탕으로 설계되었습니다:

AI가 구매를 요청할 수 있고, 정책이 허용 여부를 결정하며, 고위험 구매는 인간의 승인을 요구할 수 있습니다.

Policy Rules

현재 데모에서는 다음과 같은 한도를 사용합니다:

이 값들은 policy.py에서 조정할 수 있습니다.

에이전트는 또한 유효한 구매 사유를 제공해야 합니다. 사유가 누락되어 있거나 너무 짧은 요청은 거부됩니다.

Project Structure

agent-commerce-gateway/
│
├── mcp_server.py
├── policy.py
├── razorpay_client.py
├── dashboard.py
├── test_agent.py
├── requirements.txt
├── README.md
├── .env.example
│
├── data/
│   └── products.json
│
├── templates/
│   └── dashboard.html
│
└── logs/
    └── audit.db

주요 파일

설치

1. 가상 환경 생성

Windows:

python -m venv venv
venv\Scripts\activate

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

2. 의존성 설치

pip install -r requirements.txt

3. Razorpay 테스트 모드 구성

.env.example에서 .env 파일을 만들고 Razorpay TEST MODE 자격 증명을 추가합니다:

RAZORPAY_KEY_ID=your_test_key_id
RAZORPAY_KEY_SECRET=your_test_key_secret

.env 파일이나 실제 자격 증명을 GitHub에 커밋하지 마세요.

프로젝트 실행

1. MCP 서버 시작

python mcp_server.py

이렇게 하면 MCP 호환 AI 에이전트가 연결되는 서버가 시작됩니다.

2. AI 에이전트 연결

Claude Desktop을 사용하는 경우, MCP 서버를 Claude Desktop 설정에 추가합니다:

{
  "mcpServers": {
    "agent-commerce-gateway": {
      "command": "python",
      "args": [
        "/absolute/path/to/mcp_server.py"
      ]
    }
  }
}

/absolute/path/to/mcp_server.py를 사용자의 컴퓨터에서의 실제 경로로 교체합니다.

설정을 저장한 후 Claude Desktop을 재시작합니다.

그런 다음 연결된 AI 에이전트에게 다음과 같이 요청할 수 있습니다:

Browse this merchant's products.

또는:

Buy me the wireless earbuds because I need them for online classes.

3. 대시보드 시작

다른 터미널을 엽니다:

python dashboard.py

그런 다음 엽니다:

http://localhost:5001

대시보드는 감사 기록을 확인하고 담당 승인이 필요한 구매를 검토하는 데 사용됩니다.

구매 흐름 동작 과정

예 1 — 자동 승인 구매

사용자가 다음과 같이 요청한다고 가 유의합니다:

Buy me the Wireless Earbuds because I need them for online classes.

AI는 상품, 수량, 사유를 포함한 구매 요청을 보냅니다.

총액이 자동 승인 한도 이내라면:

Purchase Request
       ↓
Policy Check
       ↓
Approved
       ↓
Razorpay Test Order

예 2 — 담당 승인

사용자가 ₹3,499인 Mechanical Keyboard를 요청했다고 가volumes합니다.

자동 승인 한도를 넘지만 담당 승인 범위이므로:

Purchase Request
       ↓
Policy Check
       ↓
Pending Human Approval
       ↓
Dashboard
       ↓
Human Approves / Rejects

프로토타입 참고: 현재 구현은 대시보드 승인을 audit 데이터베이스에 기록합니다. 실제 운영 구현에서는 그 승인을 이후 Razorpay 주문 생성 단계와 연결해야 합니다.

예 3 — 정상 거부 처리

요청한 상품이 품절인 경우:

Purchase Request
       ↓
Policy Check
       ↓
Out of Stock
       ↓
Rejected
       ↓
Clear Explanation

시스템은 조용히 실패하지 않고 결제를 진행하지도 않습니다.

MCP 도구

MCP 서버에는 네 가지 주요 도구가 있습니다:

browse_products()

판매자의 현재 상품 카탈로그를 반환합니다.

get_product_details(product_id)

특정 상품에 대한 상세 정보를 반환합니다.

request_purchase(product_id, quantity, reason)

사용자를 대신하여 구매를 요청합니다. 요청은 Razorpay 주문이 생성되기 전에 정책 엔진에서 평가됩니다.

get_audit_trail()

현재 세션의 구매 시도와 그 결정 결과를 반환합니다.

감사 기록

모든 구매 시도는 SQLite에 저장됩니다.

감사 기록에는 다음이 포함됩니다:

• 타임스탬프

• 세션 ID

• 상품 ID

• 상품명

• 가격

• 수량

• 구매 사유

• 결정 내용

이로써 다음을 이해할 수 있습니다:

AI가 무엇을 요청했는가? 왜 요청했는가? 시스템은 무엇을 결정했는가?

데모 시나리오

프로젝트 시연을 위해:

1. MCP 서버를 AI 에이전트에 연결합니다.

2. AI 에이전트에 판매자 카탈로그를 보도록 요청합니다.

3. 명확한 사유와 함께 Wireless Earbuds (p001, ₹1,499) 를 요청합니다.

4. 자동 승인되고 Razorpay 테스트 주문이 생성되는 것을 보여줍니다.

5. Mechanical Keyboard (p003, ₹3,499) 를 요청합니다.

6. 대시보드를 통한 담당 승인이 필요한 것을 보여줍니다.

7. 4K Webcam (p005) 을 요청합니다.

8. 품절 요청이 정상적으로 거부되는 것을 보여줍니다.

9. 전체 감사 기록을 보여줍니다.

테스트

주요 MCP 흐름을 테스트하는 테스트 에이전트가 포함되어 있습니다.

실행:

python test_agent.py

테스트 스크립트는 다음을 확인합니다:

• MCP 연결

• 상품 카탈로그 조회

• 소액 구매

• 중간 금액 구매

• 품절 상품 구매

• 감사 기록 조회

어떤 문제가 있었고 어떻게 해결했는가

1. 유효하지 않은 구매 사유

정책 레이어는 모든 구매에 타당한 사유를 요구합니다. 사유가 없거나 너무 짧은 요청은 설명되지 않는 구매를 허용하지 않고 거부됩니다.

2. 품절 상품

품절 상품 요청은 정책 레이어 내에서 처리되며, 어플리케이션이 충돌하는 대신 명확한 거부로 반환됩니다.

3. Razorpay 실패

Razorpay 주문 생성은 정책 결정과 분리하여 처리합니다. 정책 승인 후 테스트 주문 생성에 실패하면 MCP 서버는 예외를 잡아서 중단하지 않고 payment_error 결과를 반환합니다.

4. 지출 한도

구매 합계는 승인 전에 거래별 한도와 세션 지출 상한 두 곳 모두에서 검사됩니다.

한계 및 향후 계획

이 프로젝트는 해커톤과 데모의 범위를 위해 설계된 프로토타입입니다.

• 세션 정체성이 단순함: 현재 구현은 실행 시 세션 ID 하나를 사용합니다. 실제 운영 체계는 인증된 에이전트와 사용자 신원을 매칭해야 합니다.

• 정책 임계값이 고정됨: 운영 버전에서는 에이전트 신용 내역, 사용자 환경 설정, 위험 점수 또는 판매자 규칙에 따라 한도를 조절할 수 있습니다.

• 테스트 모드 결제뿐 — 실제의 결제류 동작은 구현하지 않고 Razorpay 테스트 주문만 생성합니다.

• 대시보드 인증 없음 — 현재 Flask 대시보드는 시연용이며 운영에서는 인증/인가가 필요합니다.

• 인간 승인 이후 처리 부재 — 현재 프로토타입은 담당 승인을 감사 DB에만 기록하며, 이 승인을 이후 결제 및 주문 단계와 연결해야 합니다.

• 보안 한계 — 실제 배포에서는 강력한 검증과 인증, 인가, 보안 세션 관리 및 악의적이거나 손상된 에이전트 방어 기능이 필요합니다.

향후 기능

• 에이전트 인증 및 정체성 관리

• 사용자별 지출 한도

• 동적 위험 점수

• 에이전트 신뢰/평판 점수

• 적응형 정책 임계값

• 결제 상태 웹훅

• 실제 결제 흐름

• 대시보드 인증 보안

• 사기 탐지

• 고급 분석

• 더욱 포괄적인 자동 테스트

🏆 핵심 요지

SafeCart-AI는 정책으로 제어되는 MCP 커머스 게이트웨이입니다. AI 에이전트가 사용자를 대신에 쇼핑할 수 있으며, 설명 가능한 지출 한도, 고위험 구매에 대한 인간의 승인, 완전한 감사 기록을 강제합니다.

핵심 원칙

AI Agent
   ↓
Request Purchase
   ↓
Policy Engine
   ↓
┌──────────────┬─────────────────┬──────────────┐
│              │                 │
Approved    Human Review       Rejected
│              │                 │
↓              ↓                 ↓
Razorpay    Dashboard         No Payment
Test Order  Approval
│              │
└──────────────┴─────────────────┐
                                 ↓
                           Audit Trail

AI가 요청하고, 정책이 결정하며, 사람이 위험을 통제합니다. 결제는 승인된 후에만 실행됩니다.