@kagayoi/hatena-blog-mcp 1.0.0 → 1.0.1

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.
Files changed (120) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/DESIGN.md +45 -43
  3. package/README.en.md +115 -268
  4. package/README.md +106 -267
  5. package/dist/adapters/stdio/index.d.ts +5 -0
  6. package/dist/adapters/stdio/index.d.ts.map +1 -0
  7. package/dist/adapters/stdio/index.js +11 -0
  8. package/dist/adapters/stdio/index.js.map +1 -0
  9. package/dist/atompub/client.d.ts +54 -0
  10. package/dist/atompub/client.d.ts.map +1 -0
  11. package/dist/atompub/client.js +159 -0
  12. package/dist/atompub/client.js.map +1 -0
  13. package/dist/atompub/errors.d.ts +18 -0
  14. package/dist/atompub/errors.d.ts.map +1 -0
  15. package/dist/atompub/errors.js +40 -0
  16. package/dist/atompub/errors.js.map +1 -0
  17. package/dist/atompub/types.d.ts +106 -0
  18. package/dist/atompub/types.d.ts.map +1 -0
  19. package/dist/atompub/types.js +2 -0
  20. package/dist/atompub/types.js.map +1 -0
  21. package/dist/atompub/xml.d.ts +35 -0
  22. package/dist/atompub/xml.d.ts.map +1 -0
  23. package/dist/atompub/xml.js +380 -0
  24. package/dist/atompub/xml.js.map +1 -0
  25. package/dist/cli.d.ts +3 -0
  26. package/dist/cli.d.ts.map +1 -0
  27. package/dist/cli.js +17 -0
  28. package/dist/cli.js.map +1 -0
  29. package/dist/fotolife/client.d.ts +23 -0
  30. package/dist/fotolife/client.d.ts.map +1 -0
  31. package/dist/fotolife/client.js +89 -0
  32. package/dist/fotolife/client.js.map +1 -0
  33. package/dist/fotolife/types.d.ts +21 -0
  34. package/dist/fotolife/types.d.ts.map +1 -0
  35. package/dist/fotolife/types.js +2 -0
  36. package/dist/fotolife/types.js.map +1 -0
  37. package/dist/fotolife/wsse.d.ts +8 -0
  38. package/dist/fotolife/wsse.d.ts.map +1 -0
  39. package/dist/fotolife/wsse.js +45 -0
  40. package/dist/fotolife/wsse.js.map +1 -0
  41. package/dist/fotolife/xml.d.ts +5 -0
  42. package/dist/fotolife/xml.d.ts.map +1 -0
  43. package/dist/fotolife/xml.js +148 -0
  44. package/dist/fotolife/xml.js.map +1 -0
  45. package/dist/index.d.ts +6 -0
  46. package/dist/index.d.ts.map +1 -0
  47. package/dist/index.js +4 -0
  48. package/dist/index.js.map +1 -0
  49. package/{src/mcp/context.ts → dist/mcp/context.d.ts} +8 -26
  50. package/dist/mcp/context.d.ts.map +1 -0
  51. package/dist/mcp/context.js +28 -0
  52. package/dist/mcp/context.js.map +1 -0
  53. package/dist/mcp/response.d.ts +29 -0
  54. package/dist/mcp/response.d.ts.map +1 -0
  55. package/dist/mcp/response.js +68 -0
  56. package/dist/mcp/response.js.map +1 -0
  57. package/dist/mcp/server.d.ts +21 -0
  58. package/dist/mcp/server.d.ts.map +1 -0
  59. package/dist/mcp/server.js +35 -0
  60. package/dist/mcp/server.js.map +1 -0
  61. package/dist/mcp/tools/categories.d.ts +11 -0
  62. package/dist/mcp/tools/categories.d.ts.map +1 -0
  63. package/dist/mcp/tools/categories.js +34 -0
  64. package/dist/mcp/tools/categories.js.map +1 -0
  65. package/dist/mcp/tools/entries.d.ts +93 -0
  66. package/dist/mcp/tools/entries.d.ts.map +1 -0
  67. package/dist/mcp/tools/entries.js +340 -0
  68. package/dist/mcp/tools/entries.js.map +1 -0
  69. package/dist/mcp/tools/images.d.ts +18 -0
  70. package/dist/mcp/tools/images.d.ts.map +1 -0
  71. package/dist/mcp/tools/images.js +90 -0
  72. package/dist/mcp/tools/images.js.map +1 -0
  73. package/dist/mcp/tools/pages.d.ts +61 -0
  74. package/dist/mcp/tools/pages.d.ts.map +1 -0
  75. package/dist/mcp/tools/pages.js +230 -0
  76. package/dist/mcp/tools/pages.js.map +1 -0
  77. package/dist/utils/auth.d.ts +16 -0
  78. package/dist/utils/auth.d.ts.map +1 -0
  79. package/dist/utils/auth.js +19 -0
  80. package/dist/utils/auth.js.map +1 -0
  81. package/dist/utils/body.d.ts +11 -0
  82. package/dist/utils/body.d.ts.map +1 -0
  83. package/dist/utils/body.js +65 -0
  84. package/dist/utils/body.js.map +1 -0
  85. package/dist/utils/limits.d.ts +8 -0
  86. package/dist/utils/limits.d.ts.map +1 -0
  87. package/{src/utils/limits.ts → dist/utils/limits.js} +1 -1
  88. package/dist/utils/limits.js.map +1 -0
  89. package/dist/utils/retry.d.ts +33 -0
  90. package/dist/utils/retry.d.ts.map +1 -0
  91. package/dist/utils/retry.js +116 -0
  92. package/dist/utils/retry.js.map +1 -0
  93. package/dist/utils/xml.d.ts +2 -0
  94. package/dist/utils/xml.d.ts.map +1 -0
  95. package/dist/utils/xml.js +17 -0
  96. package/dist/utils/xml.js.map +1 -0
  97. package/package.json +24 -18
  98. package/src/adapters/cloudflare/index.ts +0 -179
  99. package/src/atompub/client.ts +0 -224
  100. package/src/atompub/errors.ts +0 -53
  101. package/src/atompub/types.ts +0 -113
  102. package/src/atompub/xml.ts +0 -441
  103. package/src/fotolife/client.ts +0 -106
  104. package/src/fotolife/types.ts +0 -28
  105. package/src/fotolife/wsse.ts +0 -56
  106. package/src/fotolife/xml.ts +0 -159
  107. package/src/index.ts +0 -3
  108. package/src/mcp/response.ts +0 -82
  109. package/src/mcp/server.ts +0 -38
  110. package/src/mcp/tools/categories.ts +0 -48
  111. package/src/mcp/tools/entries.ts +0 -477
  112. package/src/mcp/tools/images.ts +0 -123
  113. package/src/mcp/tools/pages.ts +0 -326
  114. package/src/utils/auth.ts +0 -48
  115. package/src/utils/body.ts +0 -71
  116. package/src/utils/retry.ts +0 -166
  117. package/src/utils/xml.ts +0 -20
  118. package/src/worker-configuration.d.ts +0 -13031
  119. package/tsconfig.json +0 -28
  120. package/wrangler.jsonc +0 -25
package/CHANGELOG.md CHANGED
@@ -6,6 +6,25 @@
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [1.0.1] - 2026-08-25
10
+
11
+ ### Changed
12
+
13
+ - **破壊的変更:** npmパッケージの実行方式をCloudflare Workerモジュールからローカルstdio CLIへ変更。既存利用者はWorker URLと `mcp-remote` を外し、`npx --yes @kagayoi/hatena-blog-mcp@latest` と `HATENA_ID` / `HATENA_API_KEY` をMCPクライアントへ設定してください
14
+ - npmパッケージをTypeScriptソースではなく、型宣言を含む `dist/` の実行可能成果物として配布
15
+ - MCPクライアントの推奨設定を `npx --yes @kagayoi/hatena-blog-mcp@latest` に変更
16
+
17
+ ### Added
18
+
19
+ - Node.js 22以上で動作するローカルMCP stdio CLIと `hatena-blog-mcp` コマンド
20
+ - `HATENA_ID` / `HATENA_API_KEY` 環境変数から上流API用のBasic認証を生成する起動処理
21
+ - 配布用CLIを実プロセスとして起動し、13ツールとアイキャッチ入力schemaを確認するstdio smoke test
22
+
23
+ ### Removed
24
+
25
+ - Cloudflare Workers / Hono / MCP Streamable HTTPアダプターとWrangler設定・生成型・依存関係
26
+ - ローカル利用時の `mcp-remote` ブリッジ要件
27
+
9
28
  ## [1.0.0] - 2026-08-24
10
29
 
11
30
  ### Changed
package/DESIGN.md CHANGED
@@ -1,56 +1,59 @@
1
1
  # System Design
2
2
 
3
- この文書は、現在の実装から確認できる `hatena-blog-mcp` の設計正本である。エージェント向けの作業手順と必須コマンドは [AGENTS.md](./AGENTS.md) を参照する。
3
+ この文書は、現在の実装から確認できる `hatena-blog-mcp` の設計正本である。作業規約と必須コマンドは [AGENTS.md](./AGENTS.md) を参照する。
4
4
 
5
5
  ## 目的と外部境界
6
6
 
7
- 本システムは、はてなブログAtomPub APIとはてなフォトライフAtom APIを、Cloudflare Workers上のMCP Streamable HTTPサーバーとして公開する。利用者が持ち込むはてなIDとAPIキーをリクエスト単位で中継するBYOK方式であり、認証情報やアプリケーション状態を保存しない。
7
+ 本システムは、はてなブログAtomPub APIとはてなフォトライフAtom APIを、Node.js上のローカルMCP stdioサーバーとして提供する。MCPクライアントから子プロセスとして起動され、標準入力と標準出力だけでMCPメッセージを交換する。
8
8
 
9
9
  外部境界は次の4つである。
10
10
 
11
- - MCPクライアント: `POST /mcp` でJSON-RPCを送信し、Basic Authorizationをリクエストごとに渡す。
11
+ - MCPクライアント: npm CLIを子プロセスとして起動し、stdioでMCPを通信する。
12
+ - プロセス環境: `HATENA_ID` と `HATENA_API_KEY` を起動時に渡す。
12
13
  - はてなブログAtomPub API: エントリ、固定ページ、カテゴリを読み書きする。
13
14
  - はてなフォトライフAtom API: 画像メタデータの取得と画像投稿を行う。
14
- - npm利用者: 公開パッケージ `@kagayoi/hatena-blog-mcp` のWorkerモジュールをimportし、利用者自身のWrangler設定からCloudflareへdeployする。
15
15
 
16
- 永続ストレージ、KV、D1、Durable Objects、サーバー側セッション、アプリケーションキャッシュは使用しない。
16
+ 公開HTTP endpoint、永続ストレージ、サーバー側セッション、アプリケーションキャッシュ、独自更新サービスは使用しない。
17
17
 
18
18
  ## 主要コンポーネント
19
19
 
20
20
  | コンポーネント | 責務 |
21
21
  | --- | --- |
22
- | `src/index.ts` | npmパッケージとWranglerが共有する公開エントリ。default Workerと`createApp`を再exportする |
23
- | `src/adapters/cloudflare/index.ts` | Honoアプリ、CORS、Origin検証、MCPボディ上限、Basic認証、リクエスト単位のtransport生成 |
24
- | `src/mcp/server.ts` | 新しい `McpServer` へ13ツールを登録 |
25
- | `src/mcp/context.ts` | 認証情報、fetch、retry、signal、timeout、request IDをツールへ渡すリクエストスコープ |
26
- | `src/mcp/tools/entries.ts` | エントリ5ツール、部分更新、公開予約条件、競合検出 |
22
+ | `src/cli.ts` | npmの実行入口。stdioサーバーを起動し、秘密を含まない起動エラーだけをstderrへ出す |
23
+ | `src/index.ts` | npmのライブラリ公開入口。サーバーfactory、認証helper、server情報をexportする |
24
+ | `src/adapters/stdio/index.ts` | 環境変数から認証contextを作り、`StdioServerTransport` とMCPサーバーを接続する |
25
+ | `src/mcp/server.ts` | 1つの `McpServer` へ13ツールを登録する |
26
+ | `src/mcp/context.ts` | 認証情報、fetch、retry、signal、timeout、request IDをツールへ渡す |
27
+ | `src/mcp/tools/entries.ts` | エントリ5ツール、部分更新、公開予約条件、競合検出、自動アイキャッチ |
27
28
  | `src/mcp/tools/pages.ts` | 固定ページ5ツール、部分更新、競合検出 |
28
29
  | `src/mcp/tools/categories.ts` | カテゴリ一覧ツール |
29
30
  | `src/mcp/tools/images.ts` | Fotolife画像取得・投稿の2ツール |
30
- | `src/atompub/client.ts` | はてなブログAtomPubのURL構築、HTTP、retry、timeout、上限付きレスポンス読み取り |
31
+ | `src/atompub/client.ts` | はてなブログAtomPubのURL構築、HTTP、retry、timeout、上限付き読み取り |
31
32
  | `src/atompub/xml.ts` | Atom/XMLと型付きモデルの相互変換 |
32
- | `src/fotolife/client.ts` | FotolifeのGET/POST、WSSE、timeout、上限付きレスポンス読み取り |
33
+ | `src/fotolife/client.ts` | FotolifeのGET/POST、WSSE、timeout、上限付き読み取り |
33
34
  | `src/fotolife/xml.ts` | Fotolife XML、base64画像、記事用記法の変換 |
34
35
  | `src/mcp/response.ts` | MCP成功結果、日本語エラー、秘密を除いた構造化ログ |
35
- | `src/utils/` | Basic認証、サイズ上限、ストリーム読み取り、retry、XML 1.0文字検証 |
36
+ | `src/utils/` | 認証生成、サイズ上限、ストリーム読み取り、retry、XML 1.0文字検証 |
36
37
 
37
- ## リクエストデータフロー
38
+ ## プロセスとデータフロー
38
39
 
39
- 1. CloudflareアダプターがOriginを評価する。`ALLOWED_ORIGINS` が空ならワイルドカードCORSを返し、設定時はリスト外の明示的なOriginを403で拒否する。Originを持たない非ブラウザ要求は許可する。
40
- 2. `POST /mcp` の本文を16 MiB以内で読み取り、超過時はMCP処理や認証より前に413を返す。
41
- 3. Basic Authorizationを `hatena_id:api_key` として解析する。欠落・不正形式は401にする。
42
- 4. 認証情報、request signal、`cf-ray`またはUUIDのrequest IDを持つ `ToolContext` を生成する。
43
- 5. リクエストごとに新しい `McpServer` と `WebStandardStreamableHTTPServerTransport` を生成する。ツールhandlerはそのリクエストのcontextだけを参照する。
44
- 6. ブログ系ツールは `AtomPubClient`、画像系ツールは `FotolifeClient` を呼ぶ。クライアントは30秒timeoutと呼び出し元signalを上流fetchへ渡す。
45
- 7. XMLを型付きモデルへ変換し、MCPのtext contentとstructured contentを返す。失敗時は利用者向けメッセージと、秘密を含まない構造化ログを生成する。
46
- 8. レスポンス後にtransportとserverをbest-effortでcloseする。
40
+ 1. MCPクライアントがNode CLIを起動し、環境変数で認証情報を渡す。
41
+ 2. stdioアダプターが2値の存在を検証し、`hatena_id:api_key` から上流用Basic Authorizationをメモリ上で生成する。
42
+ 3. 認証contextを閉じ込めた `McpServer` をプロセスごとに1つ生成し、stdio transportへ接続する。
43
+ 4. MCP SDKが標準入力のメッセージを各ツールhandlerへdispatchする。
44
+ 5. ブログ系ツールは `AtomPubClient`、画像系ツールは `FotolifeClient` を呼ぶ。クライアントは30秒timeoutを上流fetchへ適用する。
45
+ 6. XMLを型付きモデルへ変換し、MCPのtext contentとstructured contentを標準出力へ返す。
46
+ 7. 失敗時は利用者向けメッセージをMCP結果にし、stderrには秘密を含まない分類済みログだけを出す。
47
+
48
+ プロセスは認証情報を生存期間中だけ保持する。MCP protocol用の標準出力へ診断ログを書かない。
47
49
 
48
50
  ## 認証と秘密情報
49
51
 
50
- - ブログAtomPubでは、受信したBasic Authorizationを上流へそのまま中継する。
52
+ - ブログAtomPubでは、起動時に生成したBasic Authorizationを上流へ送る。
51
53
  - Fotolifeでは、同じ認証情報からリクエストごとにWSSEヘッダを生成する。nonceは `crypto.getRandomValues`、digestはプロトコル要件に従う。
52
- - 認証情報はbinding、環境変数、ストレージ、ログへ保存しない。
53
- - エラーログは操作名、request ID、HTTP status、エラーカテゴリ、エラー型だけを含み、Authorization、レスポンス本文、例外メッセージを含めない。
54
+ - `hatena_id` ツール引数はグループブログ用URLのIDだけを上書きし、APIキーは起動時の値を使う。
55
+ - 認証情報を引数、永続ストレージ、MCP応答、ログへ出さない。
56
+ - エラーログは操作名、任意のrequest ID、HTTP status、エラーカテゴリ、エラー型だけを含む。
54
57
 
55
58
  ## Atom/XML境界
56
59
 
@@ -67,34 +70,33 @@ AtomPubのPUTは部分patchではないため、`update_entry` と `update_page`
67
70
  - 未指定のtitle、content、draft、preview、カテゴリを既存値から維持する。
68
71
  - `content_type` は既存値を必ず維持し、更新による記法変更を防ぐ。
69
72
  - `updated` は `touch_updated=true` のときだけ送る。
70
- - `custom_url` は呼び出し側が明示したときだけ送る。省略により既存スラッグを維持する。
73
+ - `custom_url` は呼び出し側が明示したときだけ送る。
71
74
  - `expected_edited` が指定され、GETした現在値と異なる場合はPUTしない。
72
- - `expected_edited` はGET後からPUTまでを原子的に保護しない。はてなAPIに条件付きPUTを使う実装はないため、この競合窓は残る。
73
- - エントリの既存 `scheduled` はマージ時に維持する。新規投稿で `scheduled=true` を使う場合は `draft=true` と公開日時 `updated` を必須とする。
74
- - `eyecatch_image_url` を明示した場合だけ、HTTP(S)画像を識別用コメント付きHTMLブロックとして本文先頭へ挿入する。これははてなブログの「本文の最初の画像」による自動選択を利用するもので、公式アイキャッチ項目は変更しない。再指定時はこのシステムが挿入した既存ブロックを置換し、オプション省略時は本文を変更しない。
75
+ - `expected_edited` はGET後からPUTまでを原子的に保護しない。上流APIに条件付きPUTがないため、この競合窓は残る。
76
+ - エントリの既存 `scheduled` はマージ時に維持する。新規投稿の `scheduled=true` には `draft=true` と `updated` を必須とする。
77
+ - `eyecatch_image_url` を明示した場合だけ、HTTP(S)画像を識別用コメント付きHTMLブロックとして本文先頭へ挿入する。これは本文の最初の画像による自動選択を利用し、公式アイキャッチ項目は変更しない。再指定時は既存の自動挿入ブロックを置換する。
75
78
 
76
79
  ## retry・timeout・エラー
77
80
 
78
- - 429、502、503、504とネットワーク例外をretry対象とする。
79
- - 自動retryはGET、PUT、DELETE、HEAD、OPTIONS、TRACEに限定する。POSTは画像や記事の重複作成を防ぐため再試行しない。
81
+ - 429、502、503、504とnetwork例外をretry対象とする。
82
+ - 自動retryはGET、PUT、DELETE、HEAD、OPTIONS、TRACEに限定する。POSTは重複作成を防ぐため再試行しない。
80
83
  - `Retry-After` を優先し、通常は指数backoff、jitter、最大待機時間を適用する。
81
84
  - abortは即時伝播し、上流network例外とtimeoutは `AtomPubError` の `network_error` へ正規化する。
82
85
  - 非成功HTTPレスポンスはstatusに対応する `AtomPubError` へ変換し、MCP層で日本語メッセージへ写像する。
83
86
 
84
87
  ## 採用済み設計判断とトレードオフ
85
88
 
86
- - Streamable HTTPのJSONレスポンスだけを提供する。Workerを単純なステートレス構成にできる一方、stdioクライアントは `mcp-remote` が必要で、SSEは利用できない。
87
- - MCPサーバーをリクエストごとに生成する。生成コストは増えるが、異なる利用者のBYOK認証情報がhandler closureを通じて混在しない。
88
- - CORSは既定でワイルドカードとする。幅広いMCPクライアントと接続できる一方、ブラウザ利用を限定できる環境では `ALLOWED_ORIGINS` の設定が必要である。
89
- - ブログ更新はGET→merge→PUTを採用する。利用者が省略した値を保持できる一方、上流APIに条件付きPUTがないため完全な楽観的排他にはならない。
90
- - Fotolife投稿はWSSEをリクエストごとに生成し、POSTを再試行しない。認証情報と重複投稿のリスクを抑える一方、一時的なnetwork失敗は利用者が結果を確認して再実行する必要がある。
91
- - Fotolifeの一覧ツールは提供しない。実装は画像IDが分かる場合の取得と投稿に限定される。
92
- - Cloudflare環境型をWranglerから生成してcommitする。設定とのずれを `--check` で検出できる一方、生成物が大きくなる。
93
- - npmではコンパイル済みstdio CLIではなく、TypeScriptのCloudflare Workerモジュールを公開する。利用者ごとにWorker名、CORS、観測設定を所有できる一方、利用にはWrangler互換のbundle環境と利用者側の薄いエントリが必要になる。
94
- - npm tarballは `package.json` の `files` で実装・型・利用者向け文書へ限定し、リポジトリのlockfileを含めない。利用者は許容version範囲の修正版を取得できる一方、依存解決結果はリポジトリの開発環境と完全には固定されない。
89
+ - ローカルstdioだけを提供する。各利用者はNode.jsと認証環境変数を用意する必要がある一方、公開endpointの運用、共有認証面、HTTP中継、外部ホスティングを排除できる。
90
+ - MCPサーバーをプロセスごとに生成する。起動中は同じ認証contextを共有するため、別アカウントを使う場合はMCPプロセスを分ける。
91
+ - 認証情報は環境変数で渡す。ローカルプロセスからは参照可能だが、プロセス一覧へ露出しやすいコマンドライン引数を避けられる。
92
+ - 更新はMCP自身の自己書き換えではなく、起動設定のnpm specへ委ねる。`@latest` は起動時更新を容易にし、version固定は再現性を優先できる。
93
+ - ブログ更新はGET→merge→PUTを採用する。省略値を保持できる一方、完全な楽観的排他にはならない。
94
+ - Fotolife投稿はWSSEを毎回生成し、POSTを再試行しない。一時的なnetwork失敗では利用者が結果を確認して再実行する必要がある。
95
+ - Fotolifeの一覧ツールは提供しない。公式feedの制約に合わせ、画像IDが分かる場合の取得と投稿に限定する。
96
+ - npm tarballはコンパイル済みJavaScript、型宣言、利用者向け文書へ限定する。利用者はTypeScriptやリポジトリを必要とせずに起動できる。
95
97
 
96
- ## 設定と検証境界
98
+ ## buildと検証境界
97
99
 
98
- `wrangler.jsonc` はcompatibility date、request signal関連flag、`ALLOWED_ORIGINS`、ログ、traceを定義する。`src/worker-configuration.d.ts` はこの設定から生成される。`package.json` は公開名、version、`src/index.ts` のexport、型、tarball内容、public accessを定義する。
100
+ `tsconfig.json` は開発時の型検査、`tsconfig.build.json` は `dist/` のJavaScriptと型宣言生成を定義する。`package.json` はCLI、library export、version、tarball内容、public accessを定義する。
99
101
 
100
- 自動テストはNode上のVitestで、clients、XML、MCP handlers、Honoアダプターを検証する。Cloudflareへのdeployは行わず、Wranglerのdry-run bundleでWorkerとしてbundle可能なことを確認する。coverage要件と実行コマンドは [AGENTS.md](./AGENTS.md) を参照する。
102
+ 自動テストはNode上のVitestでclients、XML、MCP handlers、認証、stdio adapterを検証する。`scripts/smoke-stdio.mjs` はbuild済みCLIを実プロセスとして起動し、MCP initialize、13ツールの列挙、アイキャッチschemaを検証する。coverage要件と必須コマンドは [AGENTS.md](./AGENTS.md) を参照する。
package/README.en.md CHANGED
@@ -1,202 +1,97 @@
1
- # hatena-blog-mcp
2
-
1
+ # hatena-blog-mcp
2
+
3
3
  [日本語 README](./README.md) | English
4
4
 
5
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
6
 
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
- ```
7
+ > [!IMPORTANT]
8
+ > This repository is an unofficial, independently maintained fork of [Keisuke69/hatena-blog-mcp](https://github.com/Keisuke69/hatena-blog-mcp). Fork-specific changes include Hatena Fotolife support, update-conflict detection, defensive size limits, and a local stdio runtime. Report issues about these changes to [this fork](https://github.com/1llum1n4t1s/KG.hatena-blog-mcp/issues). See [CHANGELOG.md](./CHANGELOG.md) for details.
47
9
 
48
- Create `src/index.ts` and re-export the packaged Worker:
10
+ A local MCP (Model Context Protocol) server for reading and writing 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/). It communicates over stdio on Node.js and does not require an externally hosted MCP endpoint or relay.
49
11
 
50
- ```ts
51
- export { default } from "@kagayoi/hatena-blog-mcp";
52
- ```
12
+ ## Features
13
+
14
+ - 13 tools covering entries, pages, categories, and Fotolife images
15
+ - Safe partial updates in `update_entry` and `update_page`, with `expected_edited` conflict detection
16
+ - Automatic eyecatch selection via an optional first-body-image block
17
+ - No automatic retry for POST, avoiding duplicate posts and image uploads
18
+ - Defensive limits for XML, content, categories, images, and error bodies
19
+ - Credentials come from local process environment variables, never command-line arguments
53
20
 
54
- Create `wrangler.jsonc` with your own Worker name and settings:
21
+ ## Quick start
22
+
23
+ ### Requirements
24
+
25
+ - Node.js 22 or later
26
+ - Your Hatena ID
27
+ - The API key shown under Hatena Blog → Settings → Advanced → AtomPub
28
+
29
+ Register the server in any stdio-capable MCP client:
55
30
 
56
31
  ```jsonc
57
32
  {
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
33
+ "mcpServers": {
34
+ "hatena-blog": {
35
+ "command": "npx",
36
+ "args": ["--yes", "@kagayoi/hatena-blog-mcp@latest"],
37
+ "env": {
38
+ "HATENA_ID": "your-hatena-id",
39
+ "HATENA_API_KEY": "your-atompub-api-key"
40
+ }
41
+ }
68
42
  }
69
43
  }
70
44
  ```
71
45
 
72
- ```sh
73
- npx wrangler login
74
- npx wrangler deploy
75
- ```
46
+ If a Windows client cannot find `npx`, use `npx.cmd`. Prefer the client's or operating system's secret storage when available instead of keeping credentials directly in a shared configuration file.
76
47
 
77
- The npm package exports a Cloudflare Worker module. It is not a stdio server launched with `npx @kagayoi/hatena-blog-mcp`.
48
+ ### Updates
78
49
 
79
- ### Install from the source repository
50
+ The `@latest` spec resolves npm's `latest` dist-tag when the MCP process starts. The MCP does not rewrite itself or contact a custom update service while running. For reproducible installs, replace `latest` with the exact release version you intend to use.
80
51
 
81
- This method requires pnpm 10 or later.
52
+ ### Run from source
82
53
 
83
54
  ```sh
84
55
  git clone https://github.com/1llum1n4t1s/KG.hatena-blog-mcp.git
85
56
  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.
57
+ pnpm install --frozen-lockfile
58
+ pnpm build
59
+ ```
60
+
61
+ Set the client command to `node`, pass the absolute path to `dist/cli.js`, and provide the same two environment variables.
62
+
63
+ ## Authentication and data flow
64
+
65
+ At startup, the process derives an in-memory Basic Authorization header from `HATENA_ID` and `HATENA_API_KEY` for AtomPub. Fotolife requests derive a fresh WSSE header from the same credentials. The server does not persist credentials, posts, or images.
66
+
67
+ `blog_id` is the blog domain, for example `example.hatenablog.com` or `example.hateblo.jp`. On group blogs, the optional `hatena_id` tool argument overrides only the Hatena ID used in the upstream URL.
68
+
69
+ ## Tool reference
70
+
71
+ ### Entries
72
+
73
+ | Tool | Purpose | Required | Main options |
74
+ | --- | --- | --- | --- |
75
+ | `list_entries` | List entries, 7 per page | `blog_id` | `hatena_id`, `page`, `include_html` |
76
+ | `get_entry` | Get one entry | `blog_id`, `entry_id` | `hatena_id`, `include_html` |
77
+ | `create_entry` | Create an entry | `blog_id`, `title`, `content` | `content_type`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `scheduled`, `updated`, `custom_url` |
78
+ | `update_entry` | Partially update an entry | `blog_id`, `entry_id` | `title`, `content`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
79
+ | `delete_entry` | Delete an entry | `blog_id`, `entry_id` | `hatena_id` |
80
+
81
+ `update_entry` fetches the current entry and merges only explicitly supplied fields. It preserves omitted title, body, content type, publication state, categories, timestamp, and slug. Pass `categories: []` to clear categories. If `expected_edited` does not match the current value, the tool stops before PUT and reports a conflict.
82
+
83
+ A scheduled new entry requires `scheduled: true`, `draft: true`, and an `updated` publication timestamp. Existing publication timestamps change only with `touch_updated: true`.
84
+
85
+ #### Automatic eyecatch from the first body image
86
+
87
+ When `eyecatch_image_url` is supplied to `create_entry` or `update_entry`, the MCP inserts an identifiable HTML image block at the start of the body. Hatena Blog can then select the first body image automatically. This does not set Hatena's official eyecatch field directly, and the image remains visible in the article body.
193
88
 
194
89
  ```json
195
90
  {
196
91
  "name": "create_entry",
197
92
  "arguments": {
198
93
  "blog_id": "example.hatenablog.com",
199
- "title": "An article with an automatic eyecatch",
94
+ "title": "An entry with an automatic eyecatch",
200
95
  "content": "### Body\n\nThe article starts here.",
201
96
  "content_type": "text/x-markdown",
202
97
  "eyecatch_image_url": "https://cdn-ak.f.st-hatena.com/images/fotolife/example.png"
@@ -204,106 +99,58 @@ Pass the optional `eyecatch_image_url` to `create_entry` or `update_entry` to in
204
99
  }
205
100
  ```
206
101
 
207
- - You can pass the `image_url` returned by `upload_image` directly to `eyecatch_image_url`.
102
+ - You can pass the `image_url` returned by `upload_image` directly.
208
103
  - 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.
104
+ - Supplying it again replaces a block previously inserted by this MCP.
105
+ - When `content` is omitted during an update, the block is applied to the existing body.
211
106
 
212
107
  ### 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
108
 
218
- - `list_categories` → `{ categories: string[], fixed: boolean }`. `fixed: true` means new categories can't be added to this blog.
109
+ | Tool | Purpose | Required | Main options |
110
+ | --- | --- | --- | --- |
111
+ | `list_pages` | List pages, 10 per page | `blog_id` | `hatena_id`, `page`, `include_html` |
112
+ | `get_page` | Get one page | `blog_id`, `page_id` | `hatena_id`, `include_html` |
113
+ | `create_page` | Create a page | `blog_id`, `title`, `content`, `custom_url` | `content_type`, `draft`, `preview`, `updated` |
114
+ | `update_page` | Partially update a page | `blog_id`, `page_id` | `title`, `content`, `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
115
+ | `delete_page` | Delete a page | `blog_id`, `page_id` | `hatena_id` |
219
116
 
220
- ### Images (Hatena Fotolife)
117
+ ### Categories and images
221
118
 
222
- | Name | Purpose | Required | Key options |
119
+ | Tool | Purpose | Required | Main options |
223
120
  | --- | --- | --- | --- |
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
121
+ | `list_categories` | List categories and fixed state | `blog_id` | `hatena_id` |
122
+ | `get_image` | Get Fotolife image metadata | `image_id` | — |
123
+ | `upload_image` | Upload an image and return its URL and blog syntax | `title`, `content_type`, `data_base64` | `folder` (default: `Hatena Blog`) |
124
+
125
+ The official Fotolife feed does not list the private “Hatena Blog” folder populated through the blog editor, so this server does not provide an image-list tool.
126
+
127
+ ## Limits and retries
128
+
129
+ - Hatena XML response: 8 MiB
130
+ - Error body: 16 KiB
131
+ - Entry body: 4 MiB
132
+ - Decoded image: 10 MiB
133
+ - Categories: 100 entries, 256 characters each
134
+ - Upstream timeout: 30 seconds
135
+ - Automatic retry: idempotent methods such as GET, PUT, and DELETE only; never POST
136
+
137
+ ## Development and verification
138
+
139
+ ```sh
140
+ pnpm install --frozen-lockfile
141
+ pnpm verify
142
+ npm pack --dry-run --json
143
+ ```
144
+
145
+ `pnpm verify` runs Biome, TypeScript, coverage-enabled Vitest, and a stdio connection against the built CLI. See [DESIGN.md](./DESIGN.md) for architecture and invariants.
146
+
147
+ ## Security
148
+
149
+ - Remove environment values before sharing an MCP client configuration or wrapper.
150
+ - Logs exclude Authorization, API keys, upstream response bodies, and arbitrary exception messages.
151
+ - If a key leaks, rotate it from Hatena Blog's AtomPub settings.
152
+ - This is a local stdio process, but operating-system protection is still required against other processes running as the same user and against disclosure of client configuration files.
153
+
154
+ ## License
155
+
156
+ MIT © Keisuke Nishitani