Frontline Copilot

AI 기반 리트 트리지 — 소매점 매않 관리를 위한 시스템.

항상 가동되는 시스템으로, 모든 소스에서 고객 리를 수집하고, Claude를 이요해 카테고리와 심각도로 분류하며, 조치요 유효도 리를 매장 관리자의 Airtable 태스수 목록으로 전다합니다. — 위해, 다음과 같 설치(식품 안안, 직원 태도, 건이나 등 critical 이슈)와 대한 실시간 Slack 라임도 제공됩니다.

또한, Airtable" MCP server로도 제공되어, 매장 관리자들은 Claude Desktop에서 대화형으로 조회하고 트라이지할 수 있습니다.

매장 운영을 위한 AI 코일러"라는 새를 - 등장한 카태고리에서 영감을 받았습니다.

문제

다점포 소매 체인의 등 관리자들은 고객 리뷰의 신호로 끝이 없습니다. 대부는 소음(칭찬이나 사소한 불만)이지만, 소수는 긴급합니다 (식품 안전, 차별, 부상 위험). 대부분의 도구는 관리자가 중요 다른 소수로 찾기 위해 모든 것을 읽 해야합니다. 여전히 규모를 자면 지는 싸움입니다.

Frontline Capilot은 이를 뒤집지 않습니다. Claude가 모든 것을 읽고, 관리자는 조치필요 부분만 보입니다.

Related MCP server: Shopify MCP Server

작동 방식

┌────────────┐   ┌──────────────┐   ┌────────────┐   ┌────────────┐
│  Reviews   │──▶│ Classifier   │──▶│  Airtable  │──▶│   Slack    │
│  (JSON /   │   │ (Claude API, │   │  (task     │   │  (critical │
│   Google)  │   │  tool use)   │   │  tracker)  │   │   alerts)  │
└────────────┘   └──────────────┘   └────────────┘   └────────────┘
                        │
                        ▼
                 ┌──────────────┐
                 │  MCP server  │◀── Claude Desktop, Cursor, ...
                 │  (3 tools)   │
                 └──────────────┘

각 리는 9개의 카테고리 중 하나로 분류하며, 심각도 1 (긍정) ~ 5 (치명) 내로 부여됩니다. 심각도 ≥ 3이면 Airtable 작업이 되고, ≥ 4이면 Slack 알림이 추적 발생합니다.

스크린샷

엔드-투-엔드 파이프라인 실

21건 리뷰를 약 60초 내 처리되었습니다. 작업 7건 생성, 실시간 중요 알림 4건 실행.

Airtabel — 태스크 보드

작업은 심각도 순으로 정렬되어 있고, 카테고리 색코드되어 표시됩니다. 이 것은 매장 관리자가 보 를 화입니다.

이랑 "### Airtable — 캔반 보기"

"감은 데이터를 카테고리별로 그룹, to overview"? cancel display.

Slack — 실시간 중요 알림

Block Kit 기반 카드에 행동 중심 레이아웃와 Airtable에 대Buckets 하르cket틀 수 있는 링크가 포함됩니다.

기술 스택 코드

• Python 3.10+ — dataclasses, str | None union 타입, pathlib

• Anthropic Claude Capilot — claude-haiku-be-4-5 tool use로 분류

• **Airtable REST ** — 태스크 추적기, raw requests 호출

• Slack Ineventing K300 — 풍부한 알림 카드를 위한 Block Kit

• MCP (Model Context Proto) — FastMCP 기반 대화형 인터페이스

• Adapter patterns for 리 source (Mock 소스 포함; Google Places Stutb)

외부 의존성은 anthropic, requests, mcp 딱 3개뿐이며, remainder 다 표준 library.

***## 고속 스타

# 1. Clone and install
git clone https://github.com/miguelpomarm/frontline-copilot
cd frontline-copilot
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Configure secrets
cp .env.example .env
# ... edit .env with your keys (see setup section below)

# 3. Run the pipeline
python triage.py

# 4. Launch as an MCP server (optional)
python mcp_server.py

설정 셋업 (일회성, ~10분)

1. Anthropic API Key

https://console.anthropic.com/ from key를 취득. 무료 요금제로도 데모에 충분하며, 21건 리뷰 처리 비용은 약 0.03달러입니다.

2. Airtable 베이스

Tasks 테이블을 만든 아래 필드를 추가합니다 (정확한 이름이어야 합니다):

그 다음 https://airtable.com/create/tokens에서 스코프(data.records:read, data.records:write)가 지정한 개인용 액세스 토큰을 만듭니다. 토큰과 베이스 ID(app...로 시작, 베이스 URL에 포함)를 복사해 두세요.

3. Slack Incoming Webhook

https://api.slack.com/apps에서 Slack앱을 이하고 Incoming Webhooks를 on 열어요. 중요 알림을 보내고 싶은 채널을 선택해 새 웹훅을 만든 다음 웹훅 URL을 복사하세요.

4. .env 파일에 기입

ANTHROPIC_API_KEY=sk-ant-...
AIRTABLE_API_KEY=pat...
AIRTABLE_BASE_ID=app...
AIRTABLE_TABLE_NAME=Tasks
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

5. 첫 실행

python triage.py --limit 3 --dry-run   # sanity check, no side effects
python triage.py --limit 3             # small live run
python triage.py                       # full 21 reviews

MCP integration (Claude Desktop)

이 구성을 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS)에 추가하고 Claude Desktop을 다시 시작합니다:

{
  "mcpServers": {
    "frontline-copilot": {
      "command": "python",
      "args": ["/absolute/path/to/frontline-copilot/mcp_server.py"]
    }
  }
}

그리고 Claude Desktop에서 이렇게 물어보세요:

"지금 Aurora Times 현황는 어때?"

Claude는 get_store_health("times_square")를 호출해 Airtable을 조회한 뒤, 오픈된 작업, 치명적 건수, 최다 카테고리 등 현재 스냅숏을 바로 응답하게 됩니다.

설계 결정 사항

리뷰어에게 짚고 넘어가야 할 일부러 만들 선택들입니다.

Closed taxonomy + Other bucket (분류 고정 + Other 버킷) 카테고리는 자유형식이 아니라 고정된 enum입니다. 그래야 라우팅과 지표가 일관됩니다. Other는 탈출구로, 초기 예측 대신 실제 데이터로 분류 체계를 넓히기 위해 주기적으로 점검하는 용도입니다.

프롬프트 엔지니어링 대신 Tool use Claude가 enum을 강제하는 Tool schema를 통해 구조화된 결과를 반환하게 됩니다. 파싱 버그가 없고, LLM이 분류 밖의 카테고리를 만들어내는 환각도 방지됩니다.

기본 모델은 Haiku 4.5 범위가 분류된 분류 작업에서 Haiku는 빠르고(1초 이내), 저렴하며(건당 약 $0.001), 정확성도 충분합니다. 이 결정만으로 프로덕션에서 중간 볼륨 기준 월 수천 달러를 절약할 수 있습니다.

리뷰 소스는 Adapter 패턴 ReviewSource는 추상 인터페이스입니다. MockSource와 문서화된 GooglePlacesSource stub 예제가 제공되며, Yelp·TrustPilot·사내 피드 등으로 바꾸려면 서브클래스만 추가하면 됩니다. 나머지 파이프라인은 그대로입니다.

리뷰 ID 기준의 Idempotency 같은 리뷰를 다시 처리해도 중복 작업이 생기지 않도록, 생성할 때마다 Airtable에 이미 있는지 확인합니다.

심각도 임계값은 상수로 조정 ACTION_THRESHOLD, ALERT_THRESHOLD는 모듈 레벨 상수이고, 다른 기준을 가진 고객은 코드가 아니라 숫자 두 개만 바꾸면 됩니다.

MVP는 동기(Sync) 방식 리뷰 21개를 순차 처리해 약 40초가 걸립니다. 비동기 전환은 대략 15줄(AsyncAnthropic + asyncio.gather + 레이트 제한 세마포어)이면 됩니다. 하지만 이 볼륨에서는 가독성이 속도보다 낫습니다.

별점보다 텍스트 본문 프롬프트에서 “별점보다 리뷰 텍스트를 더 무게있게 읽으세요”라고 명시했습니다. 식품 안전을 언급한 4점 별점 리는 심각도가 2가 아니라 5입니다.

로드맵 (구현되지 않음)

• FastAPI webhook 엔드포인트(POST /webhook/review) — 배치 대신 실시간 수입.

• GooglePlacesSource — 어탁터 인터페이스는 완성됐지만, 실제 실현은 API 연동 + retry 로직 등 약1시간.

• rate limit을 고려한 비동 미칭 — 대용량 운영을 위해.

• End-to-end 테스 стре (Playwright / pytest, 기록된 API interockation을 사용) — Airtable/Slack 효과 검증

• config.yaml 기반의 고객별 임계값 설정

License

MIT — LICENSE 파일을 확인하세요.

기솔 포트폴리오 작품으lo Miguel Pomar Martínez 이 제작했습니다.