[로컬 Claude Desktop]  ──stdio──►  src/index.ts  ──► SqliteStore
                                                        │
                                                   UsageStore (공통 인터페이스)
                                                        │
[다른 디바이스 Claude]  ──HTTPS──►  src/worker.ts ──► D1Store
                       (mcp-remote)  API_KEY 인증      Cloudflare D1

src/
  index.ts          # stdio 서버 진입점
  worker.ts         # Cloudflare Workers 진입점 (wrangler 빌드 전용)
  db.ts             # UsageStore 인터페이스 + createStore/getStore 팩토리
  db/
    sqlite.ts       # SqliteStore — better-sqlite3 동기 API → Promise 래핑
    d1.ts           # D1Store — Cloudflare D1 네이티브 async API
  sheets.ts         # Google Sheets Webhook (지수 백오프 재시도)
  tools/
    usage.ts        # log_usage / get_my_stats / submit_daily_report
    session.ts      # log_session
scripts/
  log-hook.mjs      # Claude Code hook 자동 기록 스크립트
migrations/
  0001_init.sql     # D1 스키마 마이그레이션
tests/              # vitest 단위 테스트 22개
.claude/
  agents/           # token-estimator / session-summarizer / report-validator
  settings.json     # PostToolUse/Stop hook 설정

winget install Microsoft.VisualStudio.2022.BuildTools

git clone <repo>
cd mcp
npm install

SHEETS_WEBHOOK_URL=https://script.google.com/macros/s/YOUR_SCRIPT_ID/exec
DEFAULT_USER_EMAIL=your@email.com
DB_PATH=./data/usage.db

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": ["tsx", "E:\\apps\\mcp\\src\\index.ts"]
    }
  }
}

npm install           # wrangler 포함
npx wrangler login    # Cloudflare 계정 로그인 (브라우저 인증)

npx wrangler d1 create mcp-usage

[[d1_databases]]
binding      = "DB"
database_name = "mcp-usage"
database_id  = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

npm run migrate:remote   # D1에 테이블/뷰 생성
npm run deploy           # Workers에 배포

npx wrangler secret put API_KEY             # 임의의 긴 문자열
npx wrangler secret put DEFAULT_USER_EMAIL  # your@email.com
npx wrangler secret put SHEETS_WEBHOOK_URL  # Google Apps Script URL

curl https://mcp-server.<account>.workers.dev \
  -H "Authorization: Bearer <API_KEY>"
# → {"status":"ok","server":"mcp-server"}

{
  "mcpServers": {
    "mcp-server-cloud": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp-server.<account>.workers.dev",
        "--header", "Authorization: Bearer <API_KEY>"
      ]
    }
  }
}

사용자: 이 코드 리뷰해줘 [... 대화 진행 ...]

사용자: 고마워, 오늘 대화 토큰 기록해줘
AI: [log_usage 호출]
    기록 완료 (id: 7)
    모델: claude-sonnet-4-6
    입력: 12,450 | 출력: 3,812 | 합계: 16,262

사용자: 오늘 사용량 보여줘
AI: [get_my_stats 호출]

## 토큰 사용량 (your@email.com)

| 날짜       | 모델              |    입력 |    출력 |    합계 |
|------------|-------------------|--------:|--------:|--------:|
| 2026-05-12 | claude-sonnet-4-6 | 12,450  |  3,812  | 16,262  |

**누적 합계: 16,262 tokens**

사용자: 오늘 사용량 제출해줘
AI: [get_my_stats → submit_daily_report 순서로 호출]
    제출 성공: 1행 제출 완료 (시도: 1회)

사용자: 이번 세션 기록해줘
AI: [log_session 호출]
    세션 기록 완료: data/sessions/2026-05-12.md
    제목: 인증 모듈 리팩토링

대화가 완전히 끝날 때마다 다음을 순서대로 호출하세요:

1. log_usage — 이 대화의 추정 토큰 수 기록
   (model: 현재 모델명, input_tokens/output_tokens: 추정값)

2. log_session — 코드 작업이 있었을 때만 호출
   (title, summary, files_changed, key_decisions, tags)

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": ["tsx", "E:\\apps\\mcp\\src\\index.ts"]
    },
    "mcp-server-cloud": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp-server.<account>.workers.dev",
        "--header", "Authorization: Bearer <API_KEY>"
      ]
    }
  }
}

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|Bash",
      "hooks": [{"type": "command", "command": "node E:\\apps\\mcp\\scripts\\log-hook.mjs"}]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{"type": "command", "command": "node E:\\apps\\mcp\\scripts\\log-hook.mjs"}]
    }]
  }
}

# Session Log — 2026-05-12

- `10:23:41` **Edit** `src/db.ts`
- `10:24:05` **Write** `src/db/sqlite.ts`
- `10:31:12` **Bash** `npm test`

---
> `10:35:00` 세션 종료 [end_turn] (sid: a1b2c3d4)

## 10:35:01 — UsageStore 인터페이스 추출
> `구현` `TypeScript` `리팩토링`

기존 db.ts의 동기 함수를 UsageStore 인터페이스로 추상화하여 D1 어댑터를 추가할 수 있도록 구조를 분리했다.

function doPost(e) {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Usage');
  const rows = JSON.parse(e.postData.contents);
  rows.forEach(function(row) {
    sheet.appendRow([
      row.date, row.email, row.model,
      row.input_tokens, row.output_tokens, row.total_tokens,
      new Date().toISOString()
    ]);
  });
  return ContentService
    .createTextOutput(JSON.stringify({ success: true, rowsWritten: rows.length }))
    .setMimeType(ContentService.MimeType.JSON);
}

npm run dev           # tsx watch — 로컬 서버 실시간 재시작
npm run build         # tsc — dist/ 빌드
npm run start         # 빌드된 서버 실행
npm test              # vitest — 22개 단위 테스트
npm run inspect       # MCP Inspector UI 테스트

npm run dev:worker    # wrangler dev — 로컬 Workers 서버 (:8787)
npm run deploy        # Cloudflare Workers 배포
npm run migrate:remote  # D1 스키마 원격 적용
npm run tail          # Workers 실시간 로그