Ops Lense

Ops Lense는 원격으로 호스팅되는 상거래 운영을 위한 Model Context Protocol (MCP) 서버입니다. 운영 전문가가 멈춘 주문을 조사하고, 문제를 파악하며, 매번 엔지니어의 도움 없이 안전하게 다음 조치를 취할 수 있도록 돕습니다.

이 과제는 의도적으로 한 가지 워크플로에 집중합니다: 멈춘 주문 조사 및 복구 — 주문, 결제, 재고, 이행 전반에 걸쳐.

시연 내용

운영자는 MCP 지원 AI 클라이언트에 다음과 같은 질문을 할 수 있습니다:

이 결제된 주문이 왜 아직 멈춰 있나요?

AI는 Ops Lense를 사용하여 다음을 수행할 수 있습니다:

1. 주문 찾기;

2. 운영 타임라인 검사;

3. 백엔드 데이터에서 가능한 실패 진단;

4. 제안된 조치가 얼마나 안전하게 수행될 수 있는지 판단;

5. 운영자 확인 후 제한된 복구를 미리 보고 실행; 또는

6. 고위험 조치를 실행 대신 수동 검토 대기열로 전송.

따라서 MCP는 별도 애플리케이션에 추가 통합이 아닌, 핵심 제품 인터페이스입니다.

안전 모델

모든 상거래 작업이 동일한 수준의 AI 자율성을 가져야 하는 것은 아닙니다. Ops Lense는 작업을 세 가지 범주로 나눕니다.

확인 흐름

resync_inventory_reservation은 보호된 쓰기 작업입니다.

첫 번째 호출:

confirmed=false

서버는 주문을 검증하고 데이터베이스를 변경하지 않고 제안된 효과를 반환합니다.

운영자가 명시적으로 작업을 승인한 후, 클라이언트는 다음을 호출할 수 있습니다:

confirmed=true

그러면 서버가 제한된 변경을 수행하고 감사 항목을 기록합니다.

수동 검토 흐름

중요한 작업은 의도적으로 직접 MCP 변경으로 사용할 수 없습니다. request_manual_review는 pending_review 감사 항목을 대신 생성합니다.

다른 운영자가 해당 요청을 검토, 승인 및 실행하는 별도의 프로세스는 의도적으로 과제 범위 밖에 있습니다. 보류 중인 요청은 list_manual_reviews를 통해 계속 볼 수 있습니다.

MCP 도구

MCP 리소스

Ops Lense는 하나의 운영 리소스를 노출합니다:

ops://action-policy

이 리소스는 세 가지 작업 범주와 MCP 클라이언트가 도구를 선택하거나 실행할 때 따라야 하는 규칙을 설명합니다.

사용자가 요청을 어떻게 표현하든 안정적인 운영 정책을 사용할 수 있어야 하므로 MCP 프롬프트 대신 리소스를 선택했습니다. 전용 프롬프트는 의도적으로 좁은 이 워크플로에 거의 가치를 추가하지 않을 것입니다.

종단간 워크플로 예시

대표적인 인시던트는 결제가 성공적으로 캡처되었지만 재고 예약 단계가 누락된 주문입니다.

1. 운영자가 주문이 왜 멈췄는지 묻습니다.

2. AI는 주문을 찾아야 하는 경우 search_orders를 사용합니다.

3. get_order_timeline을 호출하여 발생한 상황을 검사합니다.

4. diagnose_order를 호출하여 결제 및 운영 상태를 연관시킵니다.

5. 진단 결과 INVENTORY_RESERVATION_MISSING이 식별되고 resync_inventory_reservation을 권장합니다.

6. AI가 confirmed=false로 도구를 호출하고 제안된 복구를 운영자에게 보여줍니다.

7. 운영자가 승인합니다.

8. AI가 confirmed=true로 도구를 다시 호출합니다.

9. MCP가 복구를 수행하고 감사 기록을 작성합니다.

10. AI가 get_order_timeline을 다시 호출하여 결과 상태를 확인합니다.

고위험 요청은 다른 경로를 따릅니다. 예를 들어, 운영자가 환불을 요청하면 MCP는 결제 상태를 변경하는 대신 수동 검토 요청을 생성합니다. 그런 다음 list_manual_reviews로 요청을 검사할 수 있습니다.

이를 통해 데모는 조사 → 진단 → 인간 확인 → 변경 → 검증 → 에스컬레이션을 포괄하는 하나의 일관된 스토리를 제공합니다.

아키텍처

MCP-enabled AI client
        |
        | Streamable HTTP
        v
   Ops Lense MCP
        |
        +-- Investigation tools
        +-- Diagnostic logic
        +-- Safety / action policy
        +-- Guarded actions
        |
        v
   Neon PostgreSQL
   synthetic commerce data

기술:

• TypeScript

• 로컬 개발 및 스크립트용 Bun

• Heroku의 Node.js 24

• Model Context Protocol 서버 패키지

• Express HTTP 전송

• Neon PostgreSQL

• Zod 입력 검증

합성 데이터는 워크플로에 필요한 최소 백엔드 시스템(고객, 주문, 결제, 재고, 이행, 운영 이벤트, 조사 이력, 작업 감사 기록)을 모델링합니다.

로컬 실행

전제 조건

다음이 필요합니다:

• Bun

• PostgreSQL 데이터베이스; Neon은 호스팅 데모에 적합

1. 종속성 설치

bun install

2. 환경 변수 구성

프로젝트 루트에 .env 파일 생성:

DATABASE_URL=postgresql://YOUR_DATABASE_URL
MCP_AUTH_TOKEN=YOUR_STRONG_RANDOM_TOKEN
PORT=3000

3. 합성 데이터베이스 생성

bun scripts/setup-db.ts

이 명령은 과제 테이블을 삭제하고 다시 생성합니다. 보관해야 하는 데이터가 포함된 데이터베이스에 대해 실행하지 마십시오.

4. 데모 데이터 시드

bun scripts/seed-db.ts

시드된 모든 고객, 주문, 결제, 재고, 이행 기록은 합성 데이터입니다.

5. MCP 서버 빌드 및 시작

bun run build
bun run start

bun run build는 TypeScript를 dist/로 컴파일합니다. 그런 다음 start 명령이 Node로 컴파일된 서버를 실행하여 Heroku 런타임 경로와 일치시킵니다.

로컬 MCP 엔드포인트:

http://localhost:3000/mcp

Heroku에 배포

저장소에는 npm start로 웹 다이노를 시작하는 Procfile이 포함되어 있습니다. Heroku가 TypeScript 프로젝트를 빌드하고 컴파일된 Node.js 서버를 실행합니다.

1. Heroku 앱 생성

heroku create YOUR_APP_NAME

2. 데이터베이스 구성

PostgreSQL 연결 문자열과 MCP 엔드포인트를 보호하는 데 사용되는 강력한 Bearer 토큰을 설정합니다:

heroku config:set DATABASE_URL="YOUR_DATABASE_URL" MCP_AUTH_TOKEN="YOUR_STRONG_RANDOM_TOKEN" -a YOUR_APP_NAME

Heroku는 PORT를 자동으로 제공하므로 수동으로 구성할 필요가 없습니다.

3. 배포

git push heroku HEAD:main

배포 중에 Heroku는 Node 종속성을 설치하고 build 스크립트를 실행합니다. 그런 다음 웹 다이노가 시작됩니다:

node dist/index.js

호스팅된 MCP 엔드포인트는 다음과 같습니다:

https://YOUR_APP_NAME.herokuapp.com/mcp

Heroku 앱이 사용자 지정 도메인을 사용하는 경우 /mcp와 함께 해당 도메인을 사용하십시오.

4. 배포 확인

heroku logs --tail -a YOUR_APP_NAME

MCP 서버가 시작되어 Heroku의 할당된 포트에 바인딩되는 것을 볼 수 있습니다.

합성 데이터베이스는 로컬 머신에서 동일한 DATABASE_URL을 사용하여 배포 전에 초기화하거나, 해당 환경에서 Bun을 사용할 수 있는 경우 일회성 Heroku 명령으로 설정 및 시드 스크립트를 실행하여 초기화할 수 있습니다. 가장 간단한 배포 경로를 위해 서버를 배포하기 전에 로컬에서 Neon을 초기화하고 시드하십시오.

AI 클라이언트에서 연결

Ops Lense는 원격 HTTP MCP 엔드포인트를 사용합니다. 원격/Streamable HTTP 서버를 지원하는 MCP 클라이언트에서 엔드포인트와 Bearer 토큰을 추가하십시오:

{
  "serverUrl": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_STRONG_RANDOM_TOKEN"
  }
}

배포된 인스턴스의 경우 로컬 URL을 호스팅된 MCP URL로 바꾸고 서버에 MCP_AUTH_TOKEN으로 구성된 동일한 토큰을 사용하십시오.

연결 후 클라이언트는 도구와 ops://action-policy 리소스를 자동으로 발견해야 합니다.

그런 다음 자연스럽게 시작할 수 있습니다. 예:

Show me recent orders that may need attention.

Why is this order stuck? Investigate it and tell me what we can safely do.

Show me all actions currently waiting for manual review.

확인이 필요한 작업의 경우 AI는 운영자에게 미리 보기를 제시하고 두 번째 도구 호출(confirmed=true)을 하기 전에 명시적 승인을 받아야 합니다.

MCP Inspector로 연결

MCP Inspector는 채팅 클라이언트와 독립적으로 서버를 테스트하는 데 유용합니다.

로컬 서버가 실행 중인 상태:

npx @modelcontextprotocol/inspector

Inspector에서 다음에 연결:

http://localhost:3000/mcp

그런 다음 발견된 도구/리소스를 검사하고 워크플로를 수동으로 호출할 수 있습니다.

검증

다음 명령으로 프로젝트의 타입 검사:

npm run typecheck

구성된 합성 데이터베이스에 대해 집중된 Vitest 통합 스위트 실행:

npm test

tests/operations.test.ts의 테스트는 격리된 임시 레코드를 생성하고, PostgreSQL에 대해 실제 도구 함수를 실행한 후 해당 레코드를 제거합니다. 다음을 검증합니다:

• 캡처된 결제와 누락된 예약이 INVENTORY_RESERVATION_MISSING을 생성함;

• 최종 주문이 활성 재고 실패로 진단되지 않음;

• confirmed=false는 변경을 수행하지 않음;

• confirmed=true는 제한된 재고 복구를 수행하고 감사 항목을 기록함;

• 이미 완료된 재동기화를 반복하는 것은 안전한 무동작임;

• 환불 요청은 결제 상태를 변경하지 않고 검토 대기열에 추가됨;

• 중복된 보류 검토 요청이 억제됨.

스위트에는 현재 8개의 통합 테스트가 포함되어 있습니다. 성공적인 실행은 8 passed를 보고합니다.

이 테스트는 의도적으로 광범위한 적용 범위 지표보다는 워크플로와 안전 경계에 초점을 맞추고 있습니다.

주요 제품 결정

워크플로를 좁게 유지

이 과제는 완전한 상거래 백엔드를 구축하려는 시도가 아닙니다. 멈춘 주문 작업은 여러 시스템, 진단, 복구, 안전, 검증을 포함하는 간결한 워크플로를 제공하기 때문에 선택되었습니다.

AI에 유용한 자율성을 부여하되, 무제한 쓰기 액세스는 금지

모든 작업을 읽기 전용으로 만들면 운영자는 단순한 인시던트를 해결하기 위해 다른 시스템에 의존해야 합니다. 모든 변경을 허용하면 불필요한 운영 위험이 발생합니다.

3단계 모델은 중간 지점을 제공합니다: 조사는 자동, 제한된 복구는 운영자 확인 필요, 중요한 작업은 수동 검토 뒤에 유지.

중요 작업을 MCP 실행 밖으로 유지

환불 및 유사한 작업은 이 합성 프로젝트에서 데이터베이스 변경으로 기술적으로 표현될 수 있지만, 그렇게 하면 잘못된 프로덕션 동작을 시연하게 됩니다. MCP는 대신 검토 요청을 생성하고 경계를 명시적으로 만듭니다.

MCP 표면을 작게 유지

노출된 각 도구는 선택된 워크플로에서 명확한 역할을 가지고 있습니다. 목표는 AI 클라이언트가 안정적으로 도구를 선택할 수 있도록 하는 것이지, 사용 가능한 도구 수를 최대화하는 것이 아닙니다.

범위 및 가정

포함:

• 합성 상거래 데이터

• 주문 조사

• 지원되는 멈춤 주문 조건의 결정론적 진단

• 보호된 재고 복구

• 감사 로깅

• 수동 검토 대기열

• 원격으로 접근 가능한 MCP 인터페이스

의도적으로 제외:

• 프론트엔드/관리 대시보드

• 실제 고객 데이터

• 프로덕션 결제 또는 창고 자격 증명

• 사용자 계정, 세션, OAuth 및 역할 기반 액세스 제어

• 직접 환불 실행

• 수동 검토 승인/실행 UI

• 완전한 상거래 백엔드

• 광범위한 반품, 사기, 카탈로그 및 고객 지원 워크플로

호스팅된 과제 서버는 단일 베어러 토큰을 사용하여 MCP가 공개적으로 노출되는 것을 방지합니다. 프로덕션 시스템의 경우, 신원 인식 인증, 권한 부여/RBAC, 비밀 키 순환, 더 강력한 동시성 제어, 공급자별 통합, 관측 가능성, 그리고 완전한 검토 워크플로가 추가되어야 합니다.

저장소 구조

src/
  index.ts
  db.ts
  resources.ts
  tools/
    diagnose-order.ts
    get-stats.ts
    get-timeline.ts
    list-manual-reviews.ts
    request-manual-review.ts
    resync-inventory.ts
    search-orders.ts
scripts/
  setup-db.ts
  seed-db.ts
tests/
  operations.test.ts
vitest.config.ts

AI 작업 기록

이 섹션에는 제출 전 과제의 실제 AI 사용 내역이 포함되어야 합니다:

• 사용된 AI 코딩 도구 및 정확한 모델

• 각 모델이 해당 작업에 선택된 이유

• 작업이 어떻게 계획되고 분해되었는지

• AI와 개발자가 처리한 책임 분담

• AI에 제공된 중요한 프롬프트/컨텍스트

• 거부되거나 크게 변경된 AI 제안 최소 하나

• AI 생성 작업이 어떻게 검토 및 검증되었는지

• 남은 위험 또는 미완료 작업

개발 중 변경된 제품 결정 중 하나는 중대한 작업의 처리 방식이었습니다. 환불 및 유사한 중요한 작업을 실행 가능한 MCP 도구로 노출하는 대신, 수동 검토 큐 뒤로 이동되었습니다. 이는 유용한 AI 자율성을 유지하면서 금전적 또는 운영상 중요한 결정을 직접적인 모델 실행 외부에 두게 합니다.

제출

최종 제출에는 다음이 포함되어야 합니다:

• 호스팅된 MCP URL

• 소스 저장소 URL

• 이 README

• 중요한 워크플로 동작에 대한 검증/테스트

• 완료된 AI 작업 기록

• 4~5분 비동기 데모

데모는 코드 워크스루보다 실제 제품 워크플로를 우선시해야 합니다: 주문을 조사하고, 진단하고, 안전한 수정을 미리보고, 확인하고, 결과를 검증한 다음, 중요한 작업이 수동 검토로 라우팅되는 과정을 보여주세요.