@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 +47 -0
- package/DESIGN.md +96 -0
- package/LICENSE +21 -0
- package/README.en.md +309 -0
- package/README.md +317 -0
- package/package.json +72 -0
- package/src/adapters/cloudflare/index.ts +179 -0
- package/src/atompub/client.ts +224 -0
- package/src/atompub/errors.ts +53 -0
- package/src/atompub/types.ts +113 -0
- package/src/atompub/xml.ts +441 -0
- package/src/fotolife/client.ts +106 -0
- package/src/fotolife/types.ts +28 -0
- package/src/fotolife/wsse.ts +56 -0
- package/src/fotolife/xml.ts +159 -0
- package/src/index.ts +3 -0
- package/src/mcp/context.ts +48 -0
- package/src/mcp/response.ts +82 -0
- package/src/mcp/server.ts +38 -0
- package/src/mcp/tools/categories.ts +48 -0
- package/src/mcp/tools/entries.ts +477 -0
- package/src/mcp/tools/images.ts +123 -0
- package/src/mcp/tools/pages.ts +326 -0
- package/src/utils/auth.ts +48 -0
- package/src/utils/body.ts +71 -0
- package/src/utils/limits.ts +8 -0
- package/src/utils/retry.ts +166 -0
- package/src/utils/xml.ts +20 -0
- package/src/worker-configuration.d.ts +13031 -0
- package/tsconfig.json +28 -0
- package/wrangler.jsonc +25 -0
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
|
+
[](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
|