# blogger-mcp

Google Blogger API v3 기반의 커스텀 [MCP](https://modelcontextprotocol.io/) 서버.
Claude Code / Claude Desktop 등 MCP 호스트에서 자신의 Blogger 블로그에 글을
조회/작성/수정/삭제할 수 있도록 도구(tools)를 제공합니다.

## 주요 기능 (MCP Tools)

| 도구 | 설명 |
| --- | --- |
| `list_blogs` | 인증된 사용자의 블로그 목록 |
| `get_blog_by_url` | 블로그 URL → Blog ID 조회 |
| `list_posts` | 블로그 글 목록 (status 필터 지원) |
| `get_post` | 특정 글 조회 |
| `create_post` | 새 글 작성 (`isDraft=true`로 임시 저장) |
| `update_post` | 글 수정 (title/content/labels) |
| `delete_post` | 글 영구 삭제 |
| `publish_post` | 임시 저장 글 발행 |
| `revert_post` | 발행된 글을 임시 저장으로 되돌림 |

## 아키텍처

```
Claude Code ──stdio──► blogger-mcp (Node)
                          │
                          ├─ src/index.ts     : MCP server (tools 등록/디스패치)
                          ├─ src/auth.ts      : OAuth 2.0 토큰 로드/저장/갱신
                          └─ src/auth-cli.ts  : 최초 1회 대화형 인증용 CLI
                          │
                          ▼
                  Google Blogger API v3
```

- **인증**: OAuth 2.0 (Desktop 앱). 최초 1회 `npm run auth`로 로컬 콜백 서버를
  띄워 토큰을 받아 `~/.config/blogger-mcp/token.json`에 저장. refresh token
  으로 이후 자동 갱신됨.
- **Scopes**: `https://www.googleapis.com/auth/blogger`
- **Transport**: stdio (MCP host가 자식 프로세스로 기동)

## 빠른 시작

### 1. 설치 및 빌드

```bash
git clone https://github.com/mech12/blogger-mcp.git
cd blogger-mcp
npm install
npm run build
```

### 2. OAuth 클라이언트 준비

[Google Cloud Console](https://console.cloud.google.com/)에서 Blogger API v3을
활성화하고 **Desktop 앱** 타입의 OAuth 클라이언트를 발급받아
`client_secret.json`을 다운로드.

```bash
mkdir -p ~/.config/blogger-mcp
cp /path/to/client_secret.json ~/.config/blogger-mcp/client_secret.json
```

> 자세한 Google Cloud 설정은 아래 **Blogger API v3 인증 발급** 참고.

### 3. 최초 인증

```bash
npm run auth
```

브라우저로 표시되는 URL을 열고 동의하면 `~/.config/blogger-mcp/token.json`이
생성됩니다.

### 4. Claude Code에 등록

```bash
claude mcp add blogger --scope user -- node /absolute/path/to/blogger-mcp/dist/index.js
```

또는 `~/.claude.json`에 직접:

```json
{
  "mcpServers": {
    "blogger": {
      "command": "node",
      "args": ["/absolute/path/to/blogger-mcp/dist/index.js"]
    }
  }
}
```

## 환경변수

| 변수 | 기본값 | 설명 |
| --- | --- | --- |
| `BLOGGER_MCP_CRED_DIR` | `~/.config/blogger-mcp` | 자격 증명 디렉터리 |
| `BLOGGER_MCP_CLIENT_SECRET` | `$CRED_DIR/client_secret.json` | OAuth 클라이언트 JSON 경로 |

## Blogger API v3 인증 발급 (요약)

1. **Google Cloud 프로젝트 생성** — https://console.cloud.google.com/
2. **API 라이브러리**에서 `Blogger API v3` 사용 설정
3. **OAuth 동의 화면** 구성
   - User Type: **외부(External)**
   - Scope 추가: `https://www.googleapis.com/auth/blogger`
   - 테스트 사용자에 본인 Google 계정 추가
4. **사용자 인증 정보 → OAuth 클라이언트 ID**
   - 애플리케이션 유형: **데스크톱 앱**
   - 생성 후 JSON 다운로드 → `~/.config/blogger-mcp/client_secret.json`
5. **Blog ID 확인**
   - Blogger 관리자 URL의 `blogID=...` 숫자 또는 `get_blog_by_url` 도구로 조회

> 프로젝트에 특화된 상세 가이드는 호스트 프로젝트의
> `docs/vibe/mcp/blogger-mcp.md`에서 관리합니다.

## 구현 계획 (Design Notes)

- **스택**: TypeScript + Node 18+, `@modelcontextprotocol/sdk`, `googleapis`,
  `google-auth-library`.
- **토큰 저장 위치**: `~/.config/blogger-mcp/`. `.gitignore`로 보호.
- **에러 전략**: tool 호출 실패는 MCP가 자동으로 에러 래핑. 인증 누락 시
  `No stored token. Run \`npm run auth\` first.` 메시지로 가이드.
- **확장 로드맵**:
  - Markdown → HTML 변환 도구 (`marked` 기반)
  - 이미지 업로드(Blogger는 Picasa/Google Photos 우회 필요 → 차후 옵션)
  - 글 스케줄 발행 (`published` 필드 세팅)

## 개발

```bash
npm run dev       # tsc --watch
npm run build     # dist/ 생성
npm start         # dist/index.js 실행 (MCP stdio 서버)
npm run auth      # OAuth 최초 인증
```

## 라이선스

MIT