Antarestar Live — MCP Server (Hermes용)

MCP read-only로 Hermes(AI 에이전트)에게 Antarestar Live Dashboard 데이터에 대한 액세스를 제공합니다. 대시보드와 동일한 Google Sheet에서 데이터를 가져오며, 동일한 열 매핑을 사용합니다. 따라서 Hermes가 읽는 숫자는 대시보드에 표시되는 숫자와 같습니다.

사용 가능한 도구

모든 날짜는 YYYY-MM-DD 형식입니다. 읽기 전용 — Hermes는 데이터를 변경할 수 없습니다.

Related MCP server: SEOAnalytics Read MCP

1. 로컬 설정 및 테스트

npm install
npm run smoke      # tes lapisan data ke sheet live (harus keluar angka)
npm run typecheck  # cek TypeScript

MCP stdio로 테스트 (로컬 Hermes / MCP Inspector용):

npx @modelcontextprotocol/inspector npx tsx src/stdio.ts

2. Vercel에 배포 (원격 HTTP — 클라우드 Hermes용)

npm i -g vercel      # kalau belum
vercel               # deploy (ikutin promptnya)
vercel --prod        # deploy production

그런 다음 Vercel → Project → Settings → Environment Variables에서 설정:

• MCP_API_KEY = 긴 비밀 키 (Hermes가 반드시 전송해야 함)

• (선택 사항) SHEET_ID — 스프레드시트를 재정의하려는 경우

MCP 엔드포인트:

https://<project>.vercel.app/api/mcp      (atau /mcp)

3. Hermes 연결

Hermes(MCP 클라이언트)는 위 URL에 Streamable HTTP를 통해 연결하며, 헤더는 다음과 같습니다:

x-api-key: <MCP_API_KEY>

MCP 구성 예시 (일반적인 MCP 클라이언트 형식):

{
  "mcpServers": {
    "antarestar-live": {
      "url": "https://<project>.vercel.app/api/mcp",
      "headers": { "x-api-key": "<MCP_API_KEY>" }
    }
  }
}

엔드포인트 활성 상태 빠른 확인 (GET):

curl -H "x-api-key: <MCP_API_KEY>" https://<project>.vercel.app/api/mcp

아키텍처

Hermes (AI) ──MCP/HTTP──► api/mcp.ts ──► src/tools.ts ──► src/sheet.ts ──CSV──► Google Sheet
                          (Vercel)        (5 tools)      (parse + calcO)        (RAW Shopee/Tiktok, Data)

• src/csv.ts — 파서 및 숫자/날짜 변환 (대시보드에서 포팅됨).

• src/sheet.ts — 가져오기 + 파싱 + 집계 (인스턴스당 60초 캐시).

• src/tools.ts — 5개의 MCP 도구 정의.

• api/mcp.ts — Streamable HTTP 엔드포인트 + API 키 인증 (Vercel).

• src/stdio.ts — 로컬 모드 (stdio).

참고 사항

• 읽기 전용: 쓰기 도구가 없습니다. 안전합니다.

• 데이터는 시트를 따릅니다 — 대시보드/임포터가 데이터를 추가하면 MCP가 자동으로 업데이트됩니다 (60초 캐시).

• 도구를 추가하고 싶으신가요 (예: checkpoint_daily_live, daily_report_host)? src/tools.ts에 추가하고 탭 파서를 src/sheet.ts에 추가하기만 하면 됩니다.