# laf-mcp-template

자사 서비스를 **LAF 봇**에 연결하는 MCP 서버의 출발점입니다.
계약은 [mcp-contract.md](https://github.com/LAF-labs/openbot/blob/main/docs/laf/mcp-contract.md)
한 장이 전부이고, 이 저장소는 그 계약의 실행 가능한 최소 구현 + 제출 전
검사기 + CI입니다.

**Use this template** 버튼으로 자사 레포를 만들고, `collectSignals()` 하나만
채우면 표준 툴 `laf.watch`가 완성됩니다.

## 시작

```bash
bun install
bun start          # http://127.0.0.1:8765/mcp
bun run check      # 제출 전 검사 — 등록 화면과 같은 질문을 CI에서 미리
```

원격 서버 검사는 `bun laf-mcp-check.ts <url> [--token <bearer>] [--json]`.

## 채우는 순서

1. **`collectSignals()`** — "멈추면 큰일"인 것들만. 텔레메트리가 아니라
   당직 목록입니다. 문턱 판정(몇 개부터 `warn`인가)은 반드시 서버에서
   끝내서 `status`로 내보냅니다. 백엔드가 죽어도 프로토콜 에러 대신
   신호로 답합니다 (계약 §1.2).
2. **자유 툴 추가** — 봇에게 시킬 일 단위로, 툴 10개 이하 권장. 툴마다
   MCP 표준 어노테이션을 선언합니다 (계약 §2). **어노테이션 없는 툴은
   등록 시 최고 위험(destructive)으로 취급**되어 봇이 사실상 못 씁니다.
   쓰기 툴은 처음부터 만들지 말고, 읽기만으로 한 주 굴려본 뒤 필요해진
   것만 추가하는 쪽이 실제로 빠릅니다.
3. **검사 통과** — `bun run check`가 FAIL 0이 될 때까지. 포함된 GitHub
   Actions 워크플로가 매 푸시마다 같은 검사를 돌립니다.
4. **배포** — 자사 인프라에. 코드 리뷰·비밀 관리·가용성은 자사 책임이며,
   플랫폼에는 URL과 Bearer 토큰만 전달됩니다.
5. **등록** — LAF 관리 화면에 URL을 등록하면, 플랫폼이 `laf.watch`를
   주기 폴링(모델 없이, 순수 코드로)하고 신호의 출현·소멸·전이만
   이벤트로 만듭니다. 자유 툴은 봇 대화에서 위험도 선언대로 실행됩니다 —
   읽기는 조용히, 파괴적·발신·돈은 사람 승인을 기다립니다.

## 하지 말 것

- 문턱 판정을 플랫폼에 미루기 — `status`는 서버에서 확정합니다.
- 백엔드 장애를 프로토콜 에러로 내기 — 신호로 답합니다.
- 어노테이션 생략 — 전부 destructive 취급됩니다.
- 등록 후 어노테이션 하향 — 권한 상승으로 간주되어 자동 정지 + 재동의가
  걸립니다.

## 파일

| 파일 | 무엇 |
|---|---|
| `index.ts` | 참조 서버 (~100줄). 무상태 Streamable HTTP — 재시작이 아무것도 잃지 않습니다 |
| `laf-mcp-check.ts` | 제출 전 검사기. 등록 화면과 같은 질문 — [LAF-labs/openbot](https://github.com/LAF-labs/openbot)에서 그대로 가져온 파일이며 직접 수정하지 않습니다 |
| `.github/workflows/check.yml` | 서버를 띄우고 검사기를 돌리는 CI |

MIT — [LICENSE](LICENSE).