@kagayoi/hatena-blog-mcp 0.0.2 → 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.
- package/CHANGELOG.md +25 -0
- package/DESIGN.md +46 -40
- package/README.en.md +115 -268
- package/README.md +106 -267
- package/dist/adapters/stdio/index.d.ts +5 -0
- package/dist/adapters/stdio/index.d.ts.map +1 -0
- package/dist/adapters/stdio/index.js +11 -0
- package/dist/adapters/stdio/index.js.map +1 -0
- package/dist/atompub/client.d.ts +54 -0
- package/dist/atompub/client.d.ts.map +1 -0
- package/dist/atompub/client.js +159 -0
- package/dist/atompub/client.js.map +1 -0
- package/dist/atompub/errors.d.ts +18 -0
- package/dist/atompub/errors.d.ts.map +1 -0
- package/dist/atompub/errors.js +40 -0
- package/dist/atompub/errors.js.map +1 -0
- package/dist/atompub/types.d.ts +106 -0
- package/dist/atompub/types.d.ts.map +1 -0
- package/dist/atompub/types.js +2 -0
- package/dist/atompub/types.js.map +1 -0
- package/dist/atompub/xml.d.ts +35 -0
- package/dist/atompub/xml.d.ts.map +1 -0
- package/dist/atompub/xml.js +380 -0
- package/dist/atompub/xml.js.map +1 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +17 -0
- package/dist/cli.js.map +1 -0
- package/dist/fotolife/client.d.ts +23 -0
- package/dist/fotolife/client.d.ts.map +1 -0
- package/dist/fotolife/client.js +89 -0
- package/dist/fotolife/client.js.map +1 -0
- package/dist/fotolife/types.d.ts +21 -0
- package/dist/fotolife/types.d.ts.map +1 -0
- package/dist/fotolife/types.js +2 -0
- package/dist/fotolife/types.js.map +1 -0
- package/dist/fotolife/wsse.d.ts +8 -0
- package/dist/fotolife/wsse.d.ts.map +1 -0
- package/dist/fotolife/wsse.js +45 -0
- package/dist/fotolife/wsse.js.map +1 -0
- package/dist/fotolife/xml.d.ts +5 -0
- package/dist/fotolife/xml.d.ts.map +1 -0
- package/dist/fotolife/xml.js +148 -0
- package/dist/fotolife/xml.js.map +1 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +4 -0
- package/dist/index.js.map +1 -0
- package/{src/mcp/context.ts → dist/mcp/context.d.ts} +8 -26
- package/dist/mcp/context.d.ts.map +1 -0
- package/dist/mcp/context.js +28 -0
- package/dist/mcp/context.js.map +1 -0
- package/dist/mcp/response.d.ts +29 -0
- package/dist/mcp/response.d.ts.map +1 -0
- package/dist/mcp/response.js +68 -0
- package/dist/mcp/response.js.map +1 -0
- package/dist/mcp/server.d.ts +21 -0
- package/dist/mcp/server.d.ts.map +1 -0
- package/dist/mcp/server.js +35 -0
- package/dist/mcp/server.js.map +1 -0
- package/dist/mcp/tools/categories.d.ts +11 -0
- package/dist/mcp/tools/categories.d.ts.map +1 -0
- package/dist/mcp/tools/categories.js +34 -0
- package/dist/mcp/tools/categories.js.map +1 -0
- package/dist/mcp/tools/entries.d.ts +93 -0
- package/dist/mcp/tools/entries.d.ts.map +1 -0
- package/dist/mcp/tools/entries.js +340 -0
- package/dist/mcp/tools/entries.js.map +1 -0
- package/dist/mcp/tools/images.d.ts +18 -0
- package/dist/mcp/tools/images.d.ts.map +1 -0
- package/dist/mcp/tools/images.js +90 -0
- package/dist/mcp/tools/images.js.map +1 -0
- package/dist/mcp/tools/pages.d.ts +61 -0
- package/dist/mcp/tools/pages.d.ts.map +1 -0
- package/dist/mcp/tools/pages.js +230 -0
- package/dist/mcp/tools/pages.js.map +1 -0
- package/dist/utils/auth.d.ts +16 -0
- package/dist/utils/auth.d.ts.map +1 -0
- package/dist/utils/auth.js +19 -0
- package/dist/utils/auth.js.map +1 -0
- package/dist/utils/body.d.ts +11 -0
- package/dist/utils/body.d.ts.map +1 -0
- package/dist/utils/body.js +65 -0
- package/dist/utils/body.js.map +1 -0
- package/dist/utils/limits.d.ts +8 -0
- package/dist/utils/limits.d.ts.map +1 -0
- package/{src/utils/limits.ts → dist/utils/limits.js} +1 -1
- package/dist/utils/limits.js.map +1 -0
- package/dist/utils/retry.d.ts +33 -0
- package/dist/utils/retry.d.ts.map +1 -0
- package/dist/utils/retry.js +116 -0
- package/dist/utils/retry.js.map +1 -0
- package/dist/utils/xml.d.ts +2 -0
- package/dist/utils/xml.d.ts.map +1 -0
- package/dist/utils/xml.js +17 -0
- package/dist/utils/xml.js.map +1 -0
- package/package.json +24 -18
- package/src/adapters/cloudflare/index.ts +0 -179
- package/src/atompub/client.ts +0 -224
- package/src/atompub/errors.ts +0 -53
- package/src/atompub/types.ts +0 -113
- package/src/atompub/xml.ts +0 -441
- package/src/fotolife/client.ts +0 -106
- package/src/fotolife/types.ts +0 -28
- package/src/fotolife/wsse.ts +0 -56
- package/src/fotolife/xml.ts +0 -159
- package/src/index.ts +0 -3
- package/src/mcp/response.ts +0 -82
- package/src/mcp/server.ts +0 -38
- package/src/mcp/tools/categories.ts +0 -48
- package/src/mcp/tools/entries.ts +0 -477
- package/src/mcp/tools/images.ts +0 -123
- package/src/mcp/tools/pages.ts +0 -326
- package/src/utils/auth.ts +0 -48
- package/src/utils/body.ts +0 -71
- package/src/utils/retry.ts +0 -166
- package/src/utils/xml.ts +0 -20
- package/src/worker-configuration.d.ts +0 -13031
- package/tsconfig.json +0 -28
- package/wrangler.jsonc +0 -25
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,31 @@
|
|
|
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
|
+
|
|
28
|
+
## [1.0.0] - 2026-08-24
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
|
|
32
|
+
- 正式版としてnpmパッケージとMCPサーバー情報のversionを `1.0.0` に同期
|
|
33
|
+
|
|
9
34
|
## [0.0.2] - 2026-08-24
|
|
10
35
|
|
|
11
36
|
### Added
|
package/DESIGN.md
CHANGED
|
@@ -1,54 +1,59 @@
|
|
|
1
1
|
# System Design
|
|
2
2
|
|
|
3
|
-
この文書は、現在の実装から確認できる `hatena-blog-mcp`
|
|
3
|
+
この文書は、現在の実装から確認できる `hatena-blog-mcp` の設計正本である。作業規約と必須コマンドは [AGENTS.md](./AGENTS.md) を参照する。
|
|
4
4
|
|
|
5
5
|
## 目的と外部境界
|
|
6
6
|
|
|
7
|
-
本システムは、はてなブログAtomPub APIとはてなフォトライフAtom APIを、
|
|
7
|
+
本システムは、はてなブログAtomPub APIとはてなフォトライフAtom APIを、Node.js上のローカルMCP stdioサーバーとして提供する。MCPクライアントから子プロセスとして起動され、標準入力と標準出力だけでMCPメッセージを交換する。
|
|
8
8
|
|
|
9
|
-
外部境界は次の
|
|
9
|
+
外部境界は次の4つである。
|
|
10
10
|
|
|
11
|
-
- MCPクライアント:
|
|
11
|
+
- MCPクライアント: npm CLIを子プロセスとして起動し、stdioでMCPを通信する。
|
|
12
|
+
- プロセス環境: `HATENA_ID` と `HATENA_API_KEY` を起動時に渡す。
|
|
12
13
|
- はてなブログAtomPub API: エントリ、固定ページ、カテゴリを読み書きする。
|
|
13
14
|
- はてなフォトライフAtom API: 画像メタデータの取得と画像投稿を行う。
|
|
14
15
|
|
|
15
|
-
|
|
16
|
+
公開HTTP endpoint、永続ストレージ、サーバー側セッション、アプリケーションキャッシュ、独自更新サービスは使用しない。
|
|
16
17
|
|
|
17
18
|
## 主要コンポーネント
|
|
18
19
|
|
|
19
20
|
| コンポーネント | 責務 |
|
|
20
21
|
| --- | --- |
|
|
21
|
-
| `src/
|
|
22
|
-
| `src/
|
|
23
|
-
| `src/
|
|
24
|
-
| `src/mcp/
|
|
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ツール、部分更新、公開予約条件、競合検出、自動アイキャッチ |
|
|
25
28
|
| `src/mcp/tools/pages.ts` | 固定ページ5ツール、部分更新、競合検出 |
|
|
26
29
|
| `src/mcp/tools/categories.ts` | カテゴリ一覧ツール |
|
|
27
30
|
| `src/mcp/tools/images.ts` | Fotolife画像取得・投稿の2ツール |
|
|
28
|
-
| `src/atompub/client.ts` | はてなブログAtomPubのURL構築、HTTP、retry、timeout
|
|
31
|
+
| `src/atompub/client.ts` | はてなブログAtomPubのURL構築、HTTP、retry、timeout、上限付き読み取り |
|
|
29
32
|
| `src/atompub/xml.ts` | Atom/XMLと型付きモデルの相互変換 |
|
|
30
|
-
| `src/fotolife/client.ts` | FotolifeのGET/POST、WSSE、timeout
|
|
33
|
+
| `src/fotolife/client.ts` | FotolifeのGET/POST、WSSE、timeout、上限付き読み取り |
|
|
31
34
|
| `src/fotolife/xml.ts` | Fotolife XML、base64画像、記事用記法の変換 |
|
|
32
35
|
| `src/mcp/response.ts` | MCP成功結果、日本語エラー、秘密を除いた構造化ログ |
|
|
33
|
-
| `src/utils/` |
|
|
36
|
+
| `src/utils/` | 認証生成、サイズ上限、ストリーム読み取り、retry、XML 1.0文字検証 |
|
|
34
37
|
|
|
35
|
-
##
|
|
38
|
+
## プロセスとデータフロー
|
|
36
39
|
|
|
37
|
-
1.
|
|
38
|
-
2. `
|
|
39
|
-
3.
|
|
40
|
-
4.
|
|
41
|
-
5.
|
|
42
|
-
6.
|
|
43
|
-
7.
|
|
44
|
-
|
|
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用の標準出力へ診断ログを書かない。
|
|
45
49
|
|
|
46
50
|
## 認証と秘密情報
|
|
47
51
|
|
|
48
|
-
- ブログAtomPub
|
|
52
|
+
- ブログAtomPubでは、起動時に生成したBasic Authorizationを上流へ送る。
|
|
49
53
|
- Fotolifeでは、同じ認証情報からリクエストごとにWSSEヘッダを生成する。nonceは `crypto.getRandomValues`、digestはプロトコル要件に従う。
|
|
50
|
-
-
|
|
51
|
-
-
|
|
54
|
+
- `hatena_id` ツール引数はグループブログ用URLのIDだけを上書きし、APIキーは起動時の値を使う。
|
|
55
|
+
- 認証情報を引数、永続ストレージ、MCP応答、ログへ出さない。
|
|
56
|
+
- エラーログは操作名、任意のrequest ID、HTTP status、エラーカテゴリ、エラー型だけを含む。
|
|
52
57
|
|
|
53
58
|
## Atom/XML境界
|
|
54
59
|
|
|
@@ -65,32 +70,33 @@ AtomPubのPUTは部分patchではないため、`update_entry` と `update_page`
|
|
|
65
70
|
- 未指定のtitle、content、draft、preview、カテゴリを既存値から維持する。
|
|
66
71
|
- `content_type` は既存値を必ず維持し、更新による記法変更を防ぐ。
|
|
67
72
|
- `updated` は `touch_updated=true` のときだけ送る。
|
|
68
|
-
- `custom_url`
|
|
73
|
+
- `custom_url` は呼び出し側が明示したときだけ送る。
|
|
69
74
|
- `expected_edited` が指定され、GETした現在値と異なる場合はPUTしない。
|
|
70
|
-
- `expected_edited` はGET後からPUT
|
|
71
|
-
- エントリの既存 `scheduled`
|
|
72
|
-
- `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ブロックとして本文先頭へ挿入する。これは本文の最初の画像による自動選択を利用し、公式アイキャッチ項目は変更しない。再指定時は既存の自動挿入ブロックを置換する。
|
|
73
78
|
|
|
74
79
|
## retry・timeout・エラー
|
|
75
80
|
|
|
76
|
-
- 429、502、503、504
|
|
77
|
-
- 自動retryはGET、PUT、DELETE、HEAD、OPTIONS、TRACEに限定する。POST
|
|
81
|
+
- 429、502、503、504とnetwork例外をretry対象とする。
|
|
82
|
+
- 自動retryはGET、PUT、DELETE、HEAD、OPTIONS、TRACEに限定する。POSTは重複作成を防ぐため再試行しない。
|
|
78
83
|
- `Retry-After` を優先し、通常は指数backoff、jitter、最大待機時間を適用する。
|
|
79
84
|
- abortは即時伝播し、上流network例外とtimeoutは `AtomPubError` の `network_error` へ正規化する。
|
|
80
85
|
- 非成功HTTPレスポンスはstatusに対応する `AtomPubError` へ変換し、MCP層で日本語メッセージへ写像する。
|
|
81
86
|
|
|
82
87
|
## 採用済み設計判断とトレードオフ
|
|
83
88
|
|
|
84
|
-
-
|
|
85
|
-
- MCP
|
|
86
|
-
-
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
- Fotolife
|
|
90
|
-
-
|
|
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やリポジトリを必要とせずに起動できる。
|
|
91
97
|
|
|
92
|
-
##
|
|
98
|
+
## buildと検証境界
|
|
93
99
|
|
|
94
|
-
`
|
|
100
|
+
`tsconfig.json` は開発時の型検査、`tsconfig.build.json` は `dist/` のJavaScriptと型宣言生成を定義する。`package.json` はCLI、library export、version、tarball内容、public accessを定義する。
|
|
95
101
|
|
|
96
|
-
自動テストはNode上のVitest
|
|
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
|
[](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
|
-
|
|
41
|
-
|
|
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
|
-
|
|
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
|
-
|
|
51
|
-
|
|
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
|
-
|
|
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
|
-
"
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
+
### Updates
|
|
78
49
|
|
|
79
|
-
|
|
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
|
-
|
|
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
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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
|
|
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
|
|
102
|
+
- You can pass the `image_url` returned by `upload_image` directly.
|
|
208
103
|
- Omitting the option leaves the body unchanged.
|
|
209
|
-
-
|
|
210
|
-
-
|
|
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
|
-
|
|
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
|
-
###
|
|
117
|
+
### Categories and images
|
|
221
118
|
|
|
222
|
-
|
|
|
119
|
+
| Tool | Purpose | Required | Main options |
|
|
223
120
|
| --- | --- | --- | --- |
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
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
|