# Boosters AX — AI 에이전트 연동 가이드

> 이 문서를 AI(Claude, GPT, 힉스필드 자동화 등)에게 그대로 주고
> **"작업이 끝나면 부스터스 AX에 올려줘"** 라고 말하면 됩니다.
> API 키는 https://ax.boosters-labs.com/my.html → **API 연동**에서 발급하세요.

---

## 방법 1 — MCP (Claude Code / Claude Desktop 권장)

터미널에서 한 줄:

```bash
claude mcp add --transport http boosters-ax https://ax.boosters-labs.com/api/mcp --header "Authorization: Bearer <내_API_키>"
```

이후 Claude 에게 자연어로 요청하면 됩니다:
- "이 프로젝트 부스터스 AX에 올려줘" → `submit_work`
- "방금 수정한 거 업데이트해줘. 노트는 '다크모드 추가'" → 같은 project_key 로 갱신
- "내가 올린 작업 목록 보여줘" → `list_my_works`

## 방법 2 — REST API (모든 도구 공통)

### 작업물 올리기 / 업데이트
```
POST https://ax.boosters-labs.com/api/submit
Authorization: Bearer <내_API_키>
Content-Type: application/json

{
  "title": "재고 대시보드",
  "url": "https://my-dashboard.vercel.app",
  "description": "Claude로 만든 실시간 재고 현황판",
  "project_key": "axp_inventory-dashboard",
  "create_if_missing": true,
  "update_note": "차트 필터 기능 추가",
  "doc_md": "# 재고 대시보드\n\n## 사용법\n...",
  "tool_slugs": ["claude"],
  "category": "ax"
}
```

응답:
```json
{ "ok": true, "id": "…", "action": "created", "project_key": "axp_inventory-dashboard",
  "url": "…", "view": "https://ax.boosters-labs.com/works.html?work=…" }
```

### 핵심 규칙
1. **게시물 = 프로젝트 단위** — 프로젝트당 게시물 1개를 유지합니다. 기능을 추가/수정했다면 새 글이 아니라
   **같은 게시물을 갱신**하고, 무엇이 바뀌었는지 `update_note` 에 남기세요. 업데이트 히스토리가 타임라인으로 쌓입니다.
2. **`project_key` 는 결정적으로 직접 정하세요** — `axp_<프로젝트>` (소문자/숫자/`-_.`, 예: `axp_inventory-dashboard`)
   + `"create_if_missing": true` 로 보내면 **없으면 그 키로 생성, 있으면 같은 게시물이 갱신**됩니다.
   서로 다른 에이전트(Claude Code, Codex, 자동화 등)가 같은 키로 호출해도 **같은 게시물로 수렴**합니다 — 새 글이 쌓이지 않음.
   (`project_key` 없이 올리면 서버가 랜덤 키를 발급해 응답으로 돌려줍니다 — 이 방식도 여전히 동작)
3. **정한 키를 저장소 루트에 `.ax-works.json` 으로 커밋하세요** — 다음에 어떤 에이전트가 와도 이 파일을 읽고 같은 게시물을 이어서 갱신합니다.
   ```json
   { "project_key": "axp_inventory-dashboard" }
   ```
4. **`update_note` 를 매번 한 줄 남기세요** — 사이트의 업데이트 히스토리 타임라인에 표시됩니다. 예: `"결제 플로우 버그 수정"`.
5. **`doc_md` 로 문서를 함께 보내세요** — 마크다운 문서가 구글 드라이브에 자동 업로드되고, 업데이트 때마다 **같은 드라이브 파일이 갱신**됩니다. 사이트 상세에서도 바로 읽힙니다.

### 보조 엔드포인트
| 메서드 | 경로 | 용도 |
|---|---|---|
| GET | `/api/me/submissions` | 내 작업물 목록 + project_key (Bearer 키 필요) |
| GET | `/api/meta` | 유효한 tool/type/tag 슬러그 목록 (인증 불필요) |

### 파일 업로드 (링크가 없는 결과물)
```json
{ "title": "…", "file": { "filename": "report.pdf", "mime_type": "application/pdf", "data_base64": "<base64>" } }
```
4MB 이하. 업로드된 드라이브 링크가 `url` 이 됩니다. 같은 project_key 로 다시 보내면 드라이브 파일 내용이 교체됩니다.

### 에러 코드
`UNAUTHORIZED`(키 없음) · `INVALID_API_KEY`(잘못된/폐기 키) · `MISSING_FIELDS` · `PROJECT_NOT_FOUND`(project_key 오타) · `PAYLOAD_TOO_LARGE` · `DRIVE_UPLOAD_FAILED` · `INTERNAL_ERROR`

---

## 에이전트에게 주는 지시문 예시 (복사해서 사용)

```
너는 작업을 완료하거나 의미 있게 수정할 때마다 부스터스 AX에 결과물을 올려야 해.
- 엔드포인트: POST https://ax.boosters-labs.com/api/submit
- 인증 헤더: Authorization: Bearer <내_API_키>
- 처음 올리면 응답의 project_key 를 기억하고, 이후엔 project_key 로 같은 게시물을 업데이트해.
- 매번 update_note 에 변경 요약을 한국어 한 줄로 넣어.
- 프로젝트 설명 문서는 doc_md 필드에 마크다운으로 함께 보내 (자동으로 드라이브에 올라가고 갱신돼).
```