@kagayoi/hatena-blog-mcp 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,47 @@
1
+ # Changelog
2
+
3
+ このファイルは、[Keisuke69/hatena-blog-mcp](https://github.com/Keisuke69/hatena-blog-mcp) から派生したフォーク固有の変更を記録します。フォーク以前の履歴は Git のコミット履歴を参照してください。
4
+
5
+ 形式は [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) を参考にしています。リリース作業ではない変更を先取りしてバージョン番号へ割り当てず、次回リリースまで `Unreleased` に集約します。
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.0.2] - 2026-08-24
10
+
11
+ ### Added
12
+
13
+ - Cloudflare Workerモジュールとして利用できる公開npmパッケージ `@kagayoi/hatena-blog-mcp`
14
+ - はてなフォトライフの画像メタデータ取得と画像投稿を行う `get_image` / `upload_image` ツール
15
+ - Fotolife Atom API 用の WSSE 認証と、記事へ貼り付けられる `blog_syntax` の生成
16
+ - `update_entry` / `update_page` の `expected_edited` による取得済み版との競合検出
17
+ - MCP リクエスト、XML レスポンス、エラーボディ、投稿本文、カテゴリ、画像に対するサイズ・件数上限
18
+ - リクエスト中断シグナルと30秒の上流APIタイムアウト
19
+ - `wrangler.jsonc` から生成する Cloudflare Workers の環境・ランタイム型
20
+ - フォークであることを明示する README の案内
21
+ - `create_entry` / `update_entry` で本文先頭画像による自動アイキャッチを利用する `eyecatch_image_url` オプション
22
+
23
+ ### Changed
24
+
25
+ - XML パーサーを名前空間prefixに依存しない実装へ変更し、数値文字参照も正しく復号
26
+ - AtomPub レスポンスの必須ルート・フィールド・yes/no値を厳密に検証
27
+ - 自動リトライを GET / PUT / DELETE などの冪等メソッドに限定し、POST の重複作成を防止
28
+ - `scheduled=true` の新規投稿で `draft=true` と公開日時 `updated` を必須化
29
+ - `ALLOWED_ORIGINS` を `wrangler.jsonc` の永続設定へ移し、リスト外の明示的な Origin を403で拒否
30
+ - Wrangler の互換日付、リクエストシグナル設定、ログ・トレース設定を更新
31
+ - README、開発資料、ツール一覧、カバレッジ要件を13ツールの現行実装へ同期
32
+
33
+ ### Fixed
34
+
35
+ - ネットワーク例外が未処理のままMCPクライアントへ漏れる問題
36
+ - `fast-xml-parser` 5.7系で数値文字参照が文字列のまま残る問題
37
+ - `touch_updated` を持つ更新ツールが冪等と宣言されていた不整合
38
+ - カテゴリ文書が名前空間prefixによって解析できない問題
39
+ - 通常の `wrangler deploy` でコマンドライン指定のOrigin設定が失われる運用上の問題
40
+ - Windowsの改行コード差によってBiomeチェックが失敗する問題
41
+
42
+ ### Security
43
+
44
+ - Authorizationヘッダの形式・長さ・ヘッダ名を出力していた診断ログを削除
45
+ - エラーログを操作名、リクエストID、HTTPステータス、エラーカテゴリ、エラー型だけに限定
46
+ - XML 1.0で禁止された制御文字を投稿前に拒否
47
+ - 大きすぎるMCPリクエストと上流レスポンスをストリーム読み取り中に拒否
package/DESIGN.md ADDED
@@ -0,0 +1,96 @@
1
+ # System Design
2
+
3
+ この文書は、現在の実装から確認できる `hatena-blog-mcp` の設計正本である。エージェント向けの作業手順と必須コマンドは [AGENTS.md](./AGENTS.md) を参照する。
4
+
5
+ ## 目的と外部境界
6
+
7
+ 本システムは、はてなブログAtomPub APIとはてなフォトライフAtom APIを、Cloudflare Workers上のMCP Streamable HTTPサーバーとして公開する。利用者が持ち込むはてなIDとAPIキーをリクエスト単位で中継するBYOK方式であり、認証情報やアプリケーション状態を保存しない。
8
+
9
+ 外部境界は次の3つである。
10
+
11
+ - MCPクライアント: `POST /mcp` でJSON-RPCを送信し、Basic Authorizationをリクエストごとに渡す。
12
+ - はてなブログAtomPub API: エントリ、固定ページ、カテゴリを読み書きする。
13
+ - はてなフォトライフAtom API: 画像メタデータの取得と画像投稿を行う。
14
+
15
+ 永続ストレージ、KV、D1、Durable Objects、サーバー側セッション、アプリケーションキャッシュは使用しない。
16
+
17
+ ## 主要コンポーネント
18
+
19
+ | コンポーネント | 責務 |
20
+ | --- | --- |
21
+ | `src/adapters/cloudflare/index.ts` | Honoアプリ、CORS、Origin検証、MCPボディ上限、Basic認証、リクエスト単位のtransport生成 |
22
+ | `src/mcp/server.ts` | 新しい `McpServer` へ13ツールを登録 |
23
+ | `src/mcp/context.ts` | 認証情報、fetch、retry、signal、timeout、request IDをツールへ渡すリクエストスコープ |
24
+ | `src/mcp/tools/entries.ts` | エントリ5ツール、部分更新、公開予約条件、競合検出 |
25
+ | `src/mcp/tools/pages.ts` | 固定ページ5ツール、部分更新、競合検出 |
26
+ | `src/mcp/tools/categories.ts` | カテゴリ一覧ツール |
27
+ | `src/mcp/tools/images.ts` | Fotolife画像取得・投稿の2ツール |
28
+ | `src/atompub/client.ts` | はてなブログAtomPubのURL構築、HTTP、retry、timeout、上限付きレスポンス読み取り |
29
+ | `src/atompub/xml.ts` | Atom/XMLと型付きモデルの相互変換 |
30
+ | `src/fotolife/client.ts` | FotolifeのGET/POST、WSSE、timeout、上限付きレスポンス読み取り |
31
+ | `src/fotolife/xml.ts` | Fotolife XML、base64画像、記事用記法の変換 |
32
+ | `src/mcp/response.ts` | MCP成功結果、日本語エラー、秘密を除いた構造化ログ |
33
+ | `src/utils/` | Basic認証、サイズ上限、ストリーム読み取り、retry、XML 1.0文字検証 |
34
+
35
+ ## リクエストデータフロー
36
+
37
+ 1. CloudflareアダプターがOriginを評価する。`ALLOWED_ORIGINS` が空ならワイルドカードCORSを返し、設定時はリスト外の明示的なOriginを403で拒否する。Originを持たない非ブラウザ要求は許可する。
38
+ 2. `POST /mcp` の本文を16 MiB以内で読み取り、超過時はMCP処理や認証より前に413を返す。
39
+ 3. Basic Authorizationを `hatena_id:api_key` として解析する。欠落・不正形式は401にする。
40
+ 4. 認証情報、request signal、`cf-ray`またはUUIDのrequest IDを持つ `ToolContext` を生成する。
41
+ 5. リクエストごとに新しい `McpServer` と `WebStandardStreamableHTTPServerTransport` を生成する。ツールhandlerはそのリクエストのcontextだけを参照する。
42
+ 6. ブログ系ツールは `AtomPubClient`、画像系ツールは `FotolifeClient` を呼ぶ。クライアントは30秒timeoutと呼び出し元signalを上流fetchへ渡す。
43
+ 7. XMLを型付きモデルへ変換し、MCPのtext contentとstructured contentを返す。失敗時は利用者向けメッセージと、秘密を含まない構造化ログを生成する。
44
+ 8. レスポンス後にtransportとserverをbest-effortでcloseする。
45
+
46
+ ## 認証と秘密情報
47
+
48
+ - ブログAtomPubでは、受信したBasic Authorizationを上流へそのまま中継する。
49
+ - Fotolifeでは、同じ認証情報からリクエストごとにWSSEヘッダを生成する。nonceは `crypto.getRandomValues`、digestはプロトコル要件に従う。
50
+ - 認証情報はbinding、環境変数、ストレージ、ログへ保存しない。
51
+ - エラーログは操作名、request ID、HTTP status、エラーカテゴリ、エラー型だけを含み、Authorization、レスポンス本文、例外メッセージを含めない。
52
+
53
+ ## Atom/XML境界
54
+
55
+ - XMLパーサーはnamespace prefixを除いたlocal nameで処理し、任意のprefixと数値文字参照を受け入れる。
56
+ - エントリではedit link由来ID、Atom ID、title、content、updated、control/draftを必須とし、yes/no以外の制御値を拒否する。
57
+ - XML生成ではXML 1.0で禁止された文字を送信前に拒否し、テキストと属性を用途別にescapeする。
58
+ - はてなからのXMLレスポンスは8 MiB、エラーボディは16 KiBまで読み取る。
59
+ - 画像はデコード後10 MiB、記事本文は4 MiB、titleは1024文字、identifierは2048文字、カテゴリは100件かつ各256文字を上限とする。
60
+
61
+ ## 更新の不変条件
62
+
63
+ AtomPubのPUTは部分patchではないため、`update_entry` と `update_page` は先に現在値をGETし、指定された変更をマージしてから完全なPUTを送る。
64
+
65
+ - 未指定のtitle、content、draft、preview、カテゴリを既存値から維持する。
66
+ - `content_type` は既存値を必ず維持し、更新による記法変更を防ぐ。
67
+ - `updated` は `touch_updated=true` のときだけ送る。
68
+ - `custom_url` は呼び出し側が明示したときだけ送る。省略により既存スラッグを維持する。
69
+ - `expected_edited` が指定され、GETした現在値と異なる場合はPUTしない。
70
+ - `expected_edited` はGET後からPUTまでを原子的に保護しない。はてなAPIに条件付きPUTを使う実装はないため、この競合窓は残る。
71
+ - エントリの既存 `scheduled` はマージ時に維持する。新規投稿で `scheduled=true` を使う場合は `draft=true` と公開日時 `updated` を必須とする。
72
+ - `eyecatch_image_url` を明示した場合だけ、HTTP(S)画像を識別用コメント付きHTMLブロックとして本文先頭へ挿入する。これははてなブログの「本文の最初の画像」による自動選択を利用するもので、公式アイキャッチ項目は変更しない。再指定時はこのシステムが挿入した既存ブロックを置換し、オプション省略時は本文を変更しない。
73
+
74
+ ## retry・timeout・エラー
75
+
76
+ - 429、502、503、504とネットワーク例外をretry対象とする。
77
+ - 自動retryはGET、PUT、DELETE、HEAD、OPTIONS、TRACEに限定する。POSTは画像や記事の重複作成を防ぐため再試行しない。
78
+ - `Retry-After` を優先し、通常は指数backoff、jitter、最大待機時間を適用する。
79
+ - abortは即時伝播し、上流network例外とtimeoutは `AtomPubError` の `network_error` へ正規化する。
80
+ - 非成功HTTPレスポンスはstatusに対応する `AtomPubError` へ変換し、MCP層で日本語メッセージへ写像する。
81
+
82
+ ## 採用済み設計判断とトレードオフ
83
+
84
+ - Streamable HTTPのJSONレスポンスだけを提供する。Workerを単純なステートレス構成にできる一方、stdioクライアントは `mcp-remote` が必要で、SSEは利用できない。
85
+ - MCPサーバーをリクエストごとに生成する。生成コストは増えるが、異なる利用者のBYOK認証情報がhandler closureを通じて混在しない。
86
+ - CORSは既定でワイルドカードとする。幅広いMCPクライアントと接続できる一方、ブラウザ利用を限定できる環境では `ALLOWED_ORIGINS` の設定が必要である。
87
+ - ブログ更新はGET→merge→PUTを採用する。利用者が省略した値を保持できる一方、上流APIに条件付きPUTがないため完全な楽観的排他にはならない。
88
+ - Fotolife投稿はWSSEをリクエストごとに生成し、POSTを再試行しない。認証情報と重複投稿のリスクを抑える一方、一時的なnetwork失敗は利用者が結果を確認して再実行する必要がある。
89
+ - Fotolifeの一覧ツールは提供しない。実装は画像IDが分かる場合の取得と投稿に限定される。
90
+ - Cloudflare環境型をWranglerから生成してcommitする。設定とのずれを `--check` で検出できる一方、生成物が大きくなる。
91
+
92
+ ## 設定と検証境界
93
+
94
+ `wrangler.jsonc` はcompatibility date、request signal関連flag、`ALLOWED_ORIGINS`、ログ、traceを定義する。`src/worker-configuration.d.ts` はこの設定から生成される。
95
+
96
+ 自動テストはNode上のVitestで、clients、XML、MCP handlers、Honoアダプターを検証する。Cloudflareへのdeployは行わず、Wranglerのdry-run bundleでWorkerとしてbundle可能なことを確認する。coverage要件と実行コマンドは [AGENTS.md](./AGENTS.md) を参照する。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Keisuke Nishitani
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,309 @@
1
+ # hatena-blog-mcp
2
+
3
+ [日本語 README](./README.md) | English
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@kagayoi/hatena-blog-mcp)](https://www.npmjs.com/package/@kagayoi/hatena-blog-mcp)
6
+
7
+ An MCP (Model Context Protocol) server that wraps the [Hatena Blog AtomPub API](https://developer.hatena.ne.jp/ja/documents/blog/apis/atom) and [Hatena Fotolife Atom API](https://developer.hatena.ne.jp/ja/documents/fotolife/apis/atom/) with **read and write** support, designed to run on **Cloudflare Workers** with a **BYOK (Bring Your Own Key)** model.
8
+
9
+ Built for the canonical use case of asking Claude to bulk re-tag categories across every entry in a blog — without accidentally rewriting titles, bodies, or publish dates along the way.
10
+
11
+ ## Features
12
+
13
+ - Entries: `list_entries`, `get_entry`, `create_entry`, `update_entry`, `delete_entry`
14
+ - Pages: `list_pages`, `get_page`, `create_page`, `update_page`, `delete_page`
15
+ - Categories: `list_categories`
16
+ - Images: `get_image`, `upload_image`
17
+ - **Safe partial updates**: `update_entry` / `update_page` keep existing title, body, syntax, publish date, and slug unless you explicitly change them. The body's `content_type` is always taken from the existing entry so Markdown never silently flips to plain text.
18
+ - Zero state on the server — credentials live only in the `Authorization` header of each request.
19
+
20
+ ## Transport
21
+
22
+ - **MCP Streamable HTTP** only (`POST /mcp`, JSON response mode)
23
+ - No stdio — use [`mcp-remote`](https://github.com/geelen/mcp-remote) if your client can only speak stdio
24
+ - No SSE
25
+
26
+ ## Endpoints
27
+
28
+ | Method | Path | Purpose |
29
+ | --- | --- | --- |
30
+ | `POST` | `/mcp` | MCP Streamable HTTP entry point |
31
+ | `OPTIONS` | `/mcp` | CORS preflight |
32
+ | `GET` | `/` | Health / identification JSON |
33
+
34
+ ---
35
+
36
+ ## Quick start: Deploy to Cloudflare Workers
37
+
38
+ ### Install from npm
39
+
40
+ ```sh
41
+ mkdir my-hatena-blog-mcp
42
+ cd my-hatena-blog-mcp
43
+ npm init -y
44
+ npm install @kagayoi/hatena-blog-mcp
45
+ npm install --save-dev wrangler
46
+ ```
47
+
48
+ Create `src/index.ts` and re-export the packaged Worker:
49
+
50
+ ```ts
51
+ export { default } from "@kagayoi/hatena-blog-mcp";
52
+ ```
53
+
54
+ Create `wrangler.jsonc` with your own Worker name and settings:
55
+
56
+ ```jsonc
57
+ {
58
+ "$schema": "node_modules/wrangler/config-schema.json",
59
+ "name": "my-hatena-blog-mcp",
60
+ "main": "src/index.ts",
61
+ "compatibility_date": "2026-08-24",
62
+ "compatibility_flags": ["nodejs_compat", "enable_request_signal", "request_signal_passthrough"],
63
+ "vars": {
64
+ "ALLOWED_ORIGINS": ""
65
+ },
66
+ "observability": {
67
+ "enabled": true
68
+ }
69
+ }
70
+ ```
71
+
72
+ ```sh
73
+ npx wrangler login
74
+ npx wrangler deploy
75
+ ```
76
+
77
+ The npm package exports a Cloudflare Worker module. It is not a stdio server launched with `npx @kagayoi/hatena-blog-mcp`.
78
+
79
+ ### Install from the source repository
80
+
81
+ This method requires pnpm 10 or later.
82
+
83
+ ```sh
84
+ git clone https://github.com/1llum1n4t1s/KG.hatena-blog-mcp.git
85
+ cd KG.hatena-blog-mcp
86
+ pnpm install
87
+ pnpm exec wrangler login
88
+ pnpm exec wrangler deploy
89
+ ```
90
+
91
+ That's it. No secrets, no KV, no Durable Objects — clients supply credentials on each request. Your URL will look like `https://hatena-blog-mcp.<your-subdomain>.workers.dev`.
92
+
93
+ ### Optional Wrangler variable
94
+
95
+ | Variable | Default | Description |
96
+ | --- | --- | --- |
97
+ | `ALLOWED_ORIGINS` | empty → `*` | Comma-separated CORS allowlist (e.g. `https://claude.ai,https://chatgpt.com`). When non-empty, an explicit unlisted `Origin` is rejected with 403, including preflights. Empty preserves compatibility with a broad range of MCP clients. |
98
+
99
+ Edit `vars` in `wrangler.jsonc`, then deploy normally. A command-line-only `--var` is intentionally avoided because the next plain deploy would remove it.
100
+
101
+ ```jsonc
102
+ "vars": {
103
+ "ALLOWED_ORIGINS": "https://claude.ai,https://chatgpt.com"
104
+ }
105
+ ```
106
+
107
+ ---
108
+
109
+ ## Authentication (BYOK)
110
+
111
+ This server stores **no credentials**. Every request must carry:
112
+
113
+ ```
114
+ Authorization: Basic base64(hatena_id:api_key)
115
+ ```
116
+
117
+ Get your API key from **Hatena Blog → Settings → Advanced → AtomPub**. The Hatena ID is the left side of your blog URL (`<hatena_id>.hatenablog.com`).
118
+
119
+ The same deployed Worker can be shared by multiple users — each supplies their own key.
120
+
121
+ ---
122
+
123
+ ## Client setup
124
+
125
+ ### Claude Desktop / Claude.ai Web / mobile (native remote MCP)
126
+
127
+ Add a new remote MCP server and point it at your Worker URL:
128
+
129
+ - **URL**: `https://hatena-blog-mcp.<your-subdomain>.workers.dev/mcp`
130
+ - **Auth**: Basic, username = your Hatena ID, password = your AtomPub API key
131
+
132
+ ### Claude Code (or any stdio-only client) via `mcp-remote`
133
+
134
+ `mcp-remote` bridges stdio → Streamable HTTP locally:
135
+
136
+ ```jsonc
137
+ // ~/.claude.json or the equivalent per-client config
138
+ {
139
+ "mcpServers": {
140
+ "hatena-blog": {
141
+ "command": "npx",
142
+ "args": [
143
+ "mcp-remote",
144
+ "https://hatena-blog-mcp.<your-subdomain>.workers.dev/mcp",
145
+ "--header",
146
+ "Authorization: Basic ${BASIC_AUTH}"
147
+ ],
148
+ "env": {
149
+ "BASIC_AUTH": "<base64(hatena_id:api_key)>"
150
+ }
151
+ }
152
+ }
153
+ }
154
+ ```
155
+
156
+ Generate the base64 value with `printf '%s' 'hatena_id:api_key' | base64`.
157
+
158
+ ### MCP Inspector (for quick manual testing)
159
+
160
+ ```sh
161
+ pnpm exec wrangler dev # in one terminal
162
+ npx @modelcontextprotocol/inspector
163
+ ```
164
+
165
+ In the inspector, choose **Streamable HTTP**, URL `http://localhost:8787/mcp`, and set a custom header `Authorization: Basic <base64>`.
166
+
167
+ ---
168
+
169
+ ## Tool reference
170
+
171
+ Blog entry, page, and category tools take a required `blog_id` (e.g. `example.hatenablog.com`) and an optional `hatena_id` override. Image tools operate on the Fotolife account tied to the Authorization header, so they do not take `blog_id`.
172
+
173
+ ### Entries
174
+
175
+ | Name | Purpose | Required | Key options |
176
+ | --- | --- | --- | --- |
177
+ | `list_entries` | List entries (7 per page) | `blog_id` | `page`, `include_html` |
178
+ | `get_entry` | Fetch one entry | `blog_id`, `entry_id` | `include_html` |
179
+ | `create_entry` | Post a new entry | `blog_id`, `title`, `content` | `content_type`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `scheduled` (`true` requires `draft: true` + `updated`), `custom_url` |
180
+ | `update_entry` | **Partial update** | `blog_id`, `entry_id` | `title`, `content`, `eyecatch_image_url`, `categories` (`[]` to clear), `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
181
+ | `delete_entry` | Delete an entry | `blog_id`, `entry_id` | — |
182
+
183
+ `update_entry` semantics:
184
+ - Any field you omit is kept from the existing entry.
185
+ - `content_type` is **always** taken from the existing entry — you cannot change Markdown ↔ plain text via this tool.
186
+ - `updated` is only sent when `touch_updated: true` (default: keep the original publish date).
187
+ - `custom_url` is only sent when you specify it (default: keep the existing slug).
188
+ - Pass the preceding result's `edited` as `expected_edited` to reject the PUT if that fetched version is already stale. Hatena exposes no conditional PUT, so this is not an atomic guarantee across the server-side GET-to-PUT interval.
189
+
190
+ #### Automatic eyecatch from a lead image
191
+
192
+ Pass the optional `eyecatch_image_url` to `create_entry` or `update_entry` to insert that HTTP(S) image at the start of the article body. This uses Hatena Blog's fallback that automatically selects the first body image; it does not write Hatena's official eyecatch field. The image is also visible in the article body.
193
+
194
+ ```json
195
+ {
196
+ "name": "create_entry",
197
+ "arguments": {
198
+ "blog_id": "example.hatenablog.com",
199
+ "title": "An article with an automatic eyecatch",
200
+ "content": "### Body\n\nThe article starts here.",
201
+ "content_type": "text/x-markdown",
202
+ "eyecatch_image_url": "https://cdn-ak.f.st-hatena.com/images/fotolife/example.png"
203
+ }
204
+ }
205
+ ```
206
+
207
+ - You can pass the `image_url` returned by `upload_image` directly to `eyecatch_image_url`.
208
+ - Omitting the option leaves the body unchanged.
209
+ - When `update_entry` omits `content`, the image is added to the existing body. If this MCP previously inserted an automatic-eyecatch block, it is replaced to avoid duplicates.
210
+ - The 4 MiB body limit is checked after insertion.
211
+
212
+ ### Pages
213
+
214
+ Same shape as entries minus `categories` / `scheduled`. `create_page` requires `custom_url` (Hatena treats it as the page's permanent slug). `update_page` also accepts `expected_edited` for conflict detection.
215
+
216
+ ### Categories
217
+
218
+ - `list_categories` → `{ categories: string[], fixed: boolean }`. `fixed: true` means new categories can't be added to this blog.
219
+
220
+ ### Images (Hatena Fotolife)
221
+
222
+ | Name | Purpose | Required | Key options |
223
+ | --- | --- | --- | --- |
224
+ | `get_image` | Fetch one image's metadata | `image_id` | — |
225
+ | `upload_image` | Upload an image and return article-ready `blog_syntax` | `title`, `content_type`, `data_base64` | `folder` (default: `Hatena Blog`) |
226
+
227
+ Image operations derive a per-request WSSE header from the caller's Basic credentials; the API key is never stored server-side. `upload_image` POSTs are not retried automatically, preventing duplicate uploads.
228
+
229
+ Decoded images are limited to 10 MiB. MCP requests are limited to 16 MiB, Hatena XML responses to 8 MiB, and upstream error bodies to 16 KiB.
230
+
231
+ The official Fotolife feed does not enumerate images in the private `Hatena Blog` folder used by the blog editor, so this server intentionally omits a list tool. Extract image IDs from an entry's Fotolife syntax and inspect them with `get_image`.
232
+
233
+ ---
234
+
235
+ ## Example: bulk category re-tagging (the original motivation)
236
+
237
+ Once the MCP server is connected, ask Claude something like:
238
+
239
+ > "私のブログ `example.hatenablog.com` の全エントリを `list_entries` で列挙して、各エントリの本文を読んだうえで既存カテゴリを整理し直してください。タイトル・本文・投稿日時は絶対に変更しないでください。"
240
+
241
+ Because `update_entry` fetches and merges existing values, Claude can pass the intended change plus the `edited` value it just observed:
242
+
243
+ ```json
244
+ {
245
+ "name": "update_entry",
246
+ "arguments": {
247
+ "blog_id": "example.hatenablog.com",
248
+ "entry_id": "3000000000000000010",
249
+ "expected_edited": "2026-04-18T10:15:00+09:00",
250
+ "categories": ["技術", "TypeScript", "Cloudflare"]
251
+ }
252
+ }
253
+ ```
254
+
255
+ …without rewriting the body, flipping Markdown to plain text, or nudging the publish date to today.
256
+
257
+ ---
258
+
259
+ ## Development
260
+
261
+ ```sh
262
+ pnpm install
263
+ pnpm dev # wrangler dev on http://localhost:8787
264
+ pnpm test # vitest
265
+ pnpm test:coverage # overall 60%, xml.ts 90%, entries.ts 90% (75% branches)
266
+ pnpm lint # biome check
267
+ pnpm lint:fix # biome check --write
268
+ pnpm typecheck # tsc --noEmit
269
+ pnpm types:worker # regenerate Worker types from wrangler.jsonc
270
+ pnpm exec wrangler deploy --dry-run --outdir .wrangler/dry-run # bundle check
271
+ ```
272
+
273
+ ### Layout
274
+
275
+ ```
276
+ src/
277
+ atompub/ — stateless HTTP client for the Hatena AtomPub API
278
+ fotolife/ — WSSE auth + Hatena Fotolife Atom API client
279
+ mcp/
280
+ tools/ — entries.ts, pages.ts, categories.ts, images.ts (one tool group per file)
281
+ server.ts — createServer() registers all 13 tools onto a fresh McpServer
282
+ context.ts — per-request credentials + client factory
283
+ response.ts — ToolTextResult, Japanese error mapping, sanitised structured logs
284
+ adapters/cloudflare/
285
+ index.ts — Hono app: CORS → BYOK auth → Streamable HTTP transport
286
+ utils/
287
+ auth.ts — parseBasicAuth
288
+ body.ts — bounded request/response body readers
289
+ retry.ts — idempotent-method-only backoff + jitter, honours Retry-After
290
+ test/
291
+ fixtures/ — real AtomPub response samples
292
+ ...
293
+ ```
294
+
295
+ ---
296
+
297
+ ## Security notes
298
+
299
+ - **This server relays `Authorization` verbatim.** Credentials reach the Worker decoded from the header, then flow through to Hatena on each AtomPub call. They are never written to any durable storage, but you should still host this somewhere you trust. A malicious or compromised Worker could log or misuse every key that passes through it.
300
+ - **Logs intentionally omit credentials, error messages, and response bodies.** Only the operation, request ID, status, error category, and error type reach `console.*`. If you add logging, keep it that way.
301
+ - **CORS is wide open by default for compatibility.** Authentication uses `Authorization`, not cookies, and `Access-Control-Allow-Credentials` is never set. Configure `ALLOWED_ORIGINS` when browser clients can be enumerated; explicit unlisted Origins then receive 403. Non-browser requests without `Origin` remain allowed, and `Host` is not separately restricted, so enforce that at a front proxy if needed.
302
+ - **Rate limits and abuse.** A public deployment can be hammered by anyone who knows the URL. Cloudflare's free plan already enforces global limits, but consider Wrangler's `[limits]` block and a WAF rate-limit rule if this becomes a problem.
303
+ - **If an API key leaks**, revoke it from *Hatena Blog → Settings → Advanced → AtomPub* and rotate. This server has nothing to purge.
304
+
305
+ ---
306
+
307
+ ## License
308
+
309
+ MIT © Keisuke Nishitani