# ハルCMS（HARU CMS）API・MCPドキュメント

> 日本語ファーストのヘッドレスCMS（運営: 株式会社Web春）。REST APIとホスト型MCPサーバーで
> 記事の作成・公開・管理を自動化できる。公開記事はキー不要の配信APIから取得する。

APIキー: ダッシュボード（https://app.harucms.com）で対象サイトの「APIキー」から発行
（`hcms_` + 32文字・表示は発行時の一度だけ・サイト単位のスコープ）

ベースURL:
- REST API: https://app.harucms.com/api/ext/v1 （Authorization: Bearer hcms_...）
- MCP:      https://app.harucms.com/mcp （Streamable HTTP・ステートレス・同じBearerキー）
- 配信API:  https://{サブドメイン}.harucms.app/v1/posts （公開・キー不要・CORS開放）

## ドキュメント

- [AI向け完全リファレンス](https://app.harucms.com/docs/llms-full.txt): API・MCP・配信・エラーの全仕様と実例。連携するならこれを読む
- [人間向けドキュメント](https://app.harucms.com/docs/): 同内容のHTML版
- [料金データ（JSON・認証不要）](https://app.harucms.com/api/public/pricing)

## 要点

- コンテンツは記事（post）: id, slug, title, body_md, body_html, excerpt, cover_image, category, status, collection, publish_at, published_at, author, seo
- body_md（Markdown）が原稿の正。body_html は省略すればサーバー生成
- status: draft（既定・安全）/ published（即公開）/ scheduled（publish_at必須・ISO 8601・5分間隔で自動公開）
- 記事の指定は id でも slug でも可
- エラーは `{ "error": "日本語メッセージ" }` + 400/401/403/404/409/503。分単位のレート制限は無し（429は返らない）。プランの月間リクエスト枠超過でも停止しない（100円/100万リクエストで自動継続）
- 二面下書き: 公開中の記事は「下書き」を別に持てる（PUT /posts/:id/draft で公開を保ったまま編集→プレビュー確認→POST /posts/:id/draft/apply で反映）
- メンバーと役割: サイトに招待した人がGoogleログインで編集できる（editor=記事の読み書き / viewer=閲覧のみ）。サイト設定・メンバー・APIキー・webhook・インポート・エクスポート・課金はオーナー専用。GET /api/app/me が各サイトに role を返す
- webhook: 公開面が変わった瞬間にPOST通知（post.published / post.unpublished / post.updated / post.deleted・HMAC署名・at-least-once・最大5回再試行）。SSGの自動ビルドは POST /webhooks にビルドフックURLを登録するだけ
- MCPツール（実在する18本のみ）: get_site_info, list_posts, get_post, create_post, update_post, delete_post, save_draft, apply_draft, discard_draft, get_post_history, list_categories, upload_image_from_url, list_images, delete_image, get_preview_url, get_plan_status, upgrade_plan, report_issue
- MCP登録（Claude Code）: `claude mcp add --transport http haru-cms https://app.harucms.com/mcp --header "Authorization: Bearer hcms_..."`