@kagayoi/hatena-blog-mcp 1.0.7 → 1.0.9

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 (49) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/DESIGN.md +4 -4
  3. package/README.de.md +160 -0
  4. package/README.es.md +160 -0
  5. package/README.fr.md +160 -0
  6. package/README.ja.md +156 -0
  7. package/README.ko.md +160 -0
  8. package/README.md +78 -74
  9. package/README.pt-BR.md +160 -0
  10. package/README.zh-CN.md +160 -0
  11. package/README.zh-TW.md +160 -0
  12. package/dist/cli.js +4 -2
  13. package/dist/cli.js.map +1 -1
  14. package/dist/fotolife/client.js +1 -1
  15. package/dist/fotolife/client.js.map +1 -1
  16. package/dist/fotolife/xml.js +4 -4
  17. package/dist/fotolife/xml.js.map +1 -1
  18. package/dist/i18n.d.ts +15 -0
  19. package/dist/i18n.d.ts.map +1 -0
  20. package/dist/i18n.js +75 -0
  21. package/dist/i18n.js.map +1 -0
  22. package/dist/locales/de.json +4 -0
  23. package/dist/locales/en.json +4 -0
  24. package/dist/locales/es.json +4 -0
  25. package/dist/locales/fr.json +4 -0
  26. package/dist/locales/ja.json +4 -0
  27. package/dist/locales/ko.json +4 -0
  28. package/dist/locales/pt-BR.json +4 -0
  29. package/dist/locales/zh-CN.json +4 -0
  30. package/dist/locales/zh-TW.json +4 -0
  31. package/dist/mcp/response.js +9 -9
  32. package/dist/mcp/response.js.map +1 -1
  33. package/dist/mcp/server.d.ts +1 -1
  34. package/dist/mcp/server.js +1 -1
  35. package/dist/mcp/tools/categories.js +1 -1
  36. package/dist/mcp/tools/categories.js.map +1 -1
  37. package/dist/mcp/tools/entries.d.ts.map +1 -1
  38. package/dist/mcp/tools/entries.js +15 -15
  39. package/dist/mcp/tools/entries.js.map +1 -1
  40. package/dist/mcp/tools/images.d.ts.map +1 -1
  41. package/dist/mcp/tools/images.js +10 -5
  42. package/dist/mcp/tools/images.js.map +1 -1
  43. package/dist/mcp/tools/pages.d.ts.map +1 -1
  44. package/dist/mcp/tools/pages.js +10 -10
  45. package/dist/mcp/tools/pages.js.map +1 -1
  46. package/dist/utils/xml.js +1 -1
  47. package/dist/utils/xml.js.map +1 -1
  48. package/package.json +2 -2
  49. package/README.en.md +0 -160
package/CHANGELOG.md CHANGED
@@ -6,6 +6,20 @@
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [1.0.9] - 2026-11-18
10
+
11
+ ### Changed
12
+
13
+ - 利用者に見える変更はありません。配信の起動を release ブランチの push から、main のコミットに付けた版タグ(v1.0.9)の push へ変更しました(MCP サーバーの動作に変更なし)。
14
+
15
+ ## [1.0.8] - 2026-11-15
16
+
17
+ ### Changed
18
+
19
+ - MCPツールの説明・入力スキーマの説明・AIへ返すエラー文を英語に統一しました(ツール名・引数・応答の形は変更なし)。
20
+ - CLIの起動時メッセージを9言語(ja・en・zh-CN・zh-TW・ko・es・fr・de・pt-BR)に対応し、`HATENA_BLOG_MCP_LANGUAGE` またはOSのロケールで切り替わるようにしました。
21
+ - README を英語の `README.md` 正本と8言語版(`README.ja.md` など)へ再編しました。`README.en.md` は `README.md` に統合しました。
22
+
9
23
  ## [1.0.7] - 2026-11-15
10
24
 
11
25
  ### Changed
package/DESIGN.md CHANGED
@@ -19,7 +19,7 @@
19
19
 
20
20
  | コンポーネント | 責務 |
21
21
  | --- | --- |
22
- | `src/cli.ts` | npmの実行入口。stdioサーバーを起動し、秘密を含まない起動エラーだけをstderrへ出す |
22
+ | `src/cli.ts` | npmの実行入口。stdioサーバーを起動し、秘密を含まない起動エラーだけを、実行環境の言語(`src/i18n.ts`・`src/locales/*.json` の9言語)でstderrへ出す |
23
23
  | `src/index.ts` | npmのライブラリ公開入口。サーバーfactory、認証helper、server情報をexportする |
24
24
  | `src/adapters/stdio/index.ts` | 環境変数から認証contextを作り、`StdioServerTransport` とMCPサーバーを接続する |
25
25
  | `src/mcp/server.ts` | MCP initializeで公開するサーバー名とversionを保持し、1つの `McpServer` へ13ツールを登録する |
@@ -32,7 +32,7 @@
32
32
  | `src/atompub/xml.ts` | Atom/XMLと型付きモデルの相互変換 |
33
33
  | `src/fotolife/client.ts` | FotolifeのGET/POST、WSSE、timeout、上限付き読み取り |
34
34
  | `src/fotolife/xml.ts` | Fotolife XML、base64画像、記事用記法の変換 |
35
- | `src/mcp/response.ts` | MCP成功結果、日本語エラー、秘密を除いた構造化ログ |
35
+ | `src/mcp/response.ts` | MCP成功結果、英語エラー(AIが読む文言は英語固定)、秘密を除いた構造化ログ |
36
36
  | `src/utils/` | 認証生成、サイズ上限、ストリーム読み取り、retry、XML 1.0文字検証 |
37
37
 
38
38
  ## プロセスとデータフロー
@@ -87,7 +87,7 @@ AtomPubのPUTは部分patchではないため、`update_entry` と `update_page`
87
87
  - 上流network例外と、最終試行まで失敗したtimeoutは `AtomPubError` の `network_error` へ正規化する。
88
88
  - 本文読込中の通信切断・timeoutも `network_error` とし、サイズ上限超過は `parse_error` のまま維持する。本文読込失敗による再試行は追加しない。
89
89
  - FotolifeのGETは各試行で新しいWSSEヘッダを生成する。
90
- - 非成功HTTPレスポンスはstatusに対応する `AtomPubError` へ変換し、MCP層で日本語メッセージへ写像する。
90
+ - 非成功HTTPレスポンスはstatusに対応する `AtomPubError` へ変換し、MCP層で英語メッセージへ写像する。
91
91
 
92
92
  ## 採用済み設計判断とトレードオフ
93
93
 
@@ -102,7 +102,7 @@ AtomPubのPUTは部分patchではないため、`update_entry` と `update_page`
102
102
 
103
103
  ## buildと検証境界
104
104
 
105
- npm公開用publish.ymlは、npm Trusted Publishingとprovenanceのcloud-hosted build要件に合わせ、install・検証・build・pack・公開をGitHub-hosted ubuntu-latest内で実行します。通常のdependency-validationはM3 Linux ARM64を使います。保存公開tokenは使わず、OIDCと--provenanceを維持します。一回packした同じtarballのSHA-512と既存版のintegrityを確認し、作り直さず公開します。workflow filenameと従来のrelease/manual条件を維持します。
105
+ npm公開用publish.ymlは、npm Trusted Publishingとprovenanceのcloud-hosted build要件に合わせ、install・検証・build・pack・公開をGitHub-hosted ubuntu-latest内で実行します。通常のdependency-validationはM3 Linux ARM64を使います。保存公開tokenは使わず、OIDCと--provenanceを維持します。一回packした同じtarballのSHA-512と既存版のintegrityを確認し、作り直さず公開します。workflow filenameと手動再実行の条件を維持し、公開は main のコミットに付けた軽量タグ `vX.Y.Z` の push で起動します(タグ・厳密な形・軽量タグが実行 commit を指すこと・既定ブランチの祖先であること・`v<package.json の版>` との一致を検査します)。
106
106
 
107
107
  `tsconfig.json` は開発時の型検査、`tsconfig.build.json` は `dist/` のJavaScriptと型宣言生成を定義する。`package.json` はCLI、library export、npm配布version、tarball内容、public accessを定義する。MCP initializeで公開するversionは `src/mcp/server.ts` の `SERVER_INFO.version` が保持し、同一リリースを表すためnpm配布versionと常に一致させる。
108
108
 
package/README.de.md ADDED
@@ -0,0 +1,160 @@
1
+ # hatena-blog-mcp
2
+
3
+ [English](./README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [한국어](./README.ko.md) | [Español](./README.es.md) | [Français](./README.fr.md) | **Deutsch** | [Português (Brasil)](./README.pt-BR.md)
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@kagayoi/hatena-blog-mcp)](https://www.npmjs.com/package/@kagayoi/hatena-blog-mcp)
6
+
7
+ > [!IMPORTANT]
8
+ > Dieses Repository ist ein inoffizieller, unabhängig gepflegter Fork von [Keisuke69/hatena-blog-mcp](https://github.com/Keisuke69/hatena-blog-mcp). Zu den fork-spezifischen Änderungen gehören die Unterstützung von Hatena Fotolife, die Erkennung von Aktualisierungskonflikten, defensive Größenbeschränkungen und eine lokale stdio-Laufzeit. Probleme zu diesen Änderungen melden Sie bitte an [diesen Fork](https://github.com/1llum1n4t1s/KG.hatena-blog-mcp/issues). Details finden Sie in [CHANGELOG.md](./CHANGELOG.md).
9
+
10
+ Ein lokaler MCP-Server (Model Context Protocol) zum Lesen und Schreiben über die [Hatena Blog AtomPub API](https://developer.hatena.ne.jp/ja/documents/blog/apis/atom) und die [Hatena Fotolife Atom API](https://developer.hatena.ne.jp/ja/documents/fotolife/apis/atom/). Er kommuniziert über stdio unter Node.js und benötigt keinen extern gehosteten MCP-Endpunkt und kein Relay.
11
+
12
+ ## Funktionen
13
+
14
+ - 13 Tools für Beiträge, Seiten, Kategorien und Fotolife-Bilder
15
+ - Sichere partielle Aktualisierungen in `update_entry` und `update_page` mit Konflikterkennung über `expected_edited`
16
+ - Automatische Auswahl des Eyecatch-Bildes über einen optionalen Block mit dem ersten Bild im Beitragstext
17
+ - Keine automatische Wiederholung bei POST, um doppelte Beiträge und Bild-Uploads zu vermeiden
18
+ - Defensive Limits für XML, Inhalte, Kategorien, Bilder und Fehler-Bodys
19
+ - Zugangsdaten stammen aus lokalen Umgebungsvariablen des Prozesses, nie aus Kommandozeilenargumenten
20
+
21
+ ## Schnellstart
22
+
23
+ ### Voraussetzungen
24
+
25
+ - Node.js 22 oder neuer
26
+ - Ihre Hatena-ID
27
+ - Der API-Schlüssel, der unter Hatena Blog → Einstellungen → Erweitert → AtomPub angezeigt wird
28
+
29
+ Registrieren Sie den Server in einem beliebigen MCP-Client mit stdio-Unterstützung:
30
+
31
+ ```jsonc
32
+ {
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
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ Findet ein Windows-Client `npx` nicht, verwenden Sie `npx.cmd`. Nutzen Sie nach Möglichkeit den Geheimnisspeicher des Clients oder des Betriebssystems, anstatt die Zugangsdaten direkt in einer gemeinsam genutzten Konfigurationsdatei abzulegen.
47
+
48
+ ### Updates
49
+
50
+ Die Angabe `@latest` wird beim Start des MCP-Prozesses auf den npm-Dist-Tag `latest` aufgelöst. Der MCP schreibt sich nicht selbst um und kontaktiert zur Laufzeit keinen eigenen Update-Dienst. Für reproduzierbare Installationen ersetzen Sie `latest` durch die genaue Release-Version, die Sie verwenden möchten.
51
+
52
+ Wenn Sie den Server bereits mit einer festen Version registriert haben (zum Beispiel `@kagayoi/hatena-blog-mcp@1.0.6`), ändern Sie das Paketargument in dieser Registrierung auf `@kagayoi/hatena-blog-mcp@latest`. Die Aktualisierung dieser README ändert bestehende Registrierungen nicht, aber nach dieser Anpassung verwendet jeder Start automatisch das neueste Release.
53
+
54
+ ### Aus dem Quellcode ausführen
55
+
56
+ ```sh
57
+ git clone https://github.com/1llum1n4t1s/KG.hatena-blog-mcp.git
58
+ cd KG.hatena-blog-mcp
59
+ pnpm install --frozen-lockfile
60
+ pnpm build
61
+ ```
62
+
63
+ Setzen Sie den Client-Befehl auf `node`, übergeben Sie den absoluten Pfad zu `dist/cli.js` und geben Sie dieselben zwei Umgebungsvariablen an.
64
+
65
+ ## Authentifizierung und Datenfluss
66
+
67
+ Beim Start leitet der Prozess aus `HATENA_ID` und `HATENA_API_KEY` einen Basic-Authorization-Header für AtomPub ab, der nur im Arbeitsspeicher gehalten wird. Für Fotolife-Anfragen wird aus denselben Zugangsdaten jeweils ein frischer WSSE-Header erzeugt. Der Server speichert weder Zugangsdaten noch Beiträge oder Bilder dauerhaft.
68
+
69
+ `blog_id` ist die Domain des Blogs, zum Beispiel `example.hatenablog.com` oder `example.hateblo.jp`. Bei Gruppenblogs überschreibt das optionale Tool-Argument `hatena_id` ausschließlich die Hatena-ID, die in der Upstream-URL verwendet wird.
70
+
71
+ ## Tool-Referenz
72
+
73
+ ### Beiträge
74
+
75
+ | Tool | Zweck | Erforderlich | Wichtige Optionen |
76
+ | --- | --- | --- | --- |
77
+ | `list_entries` | Beiträge auflisten, 7 pro Seite | `blog_id` | `hatena_id`, `page`, `include_html` |
78
+ | `get_entry` | Einen Beitrag abrufen | `blog_id`, `entry_id` | `hatena_id`, `include_html` |
79
+ | `create_entry` | Einen Beitrag erstellen | `blog_id`, `title`, `content` | `content_type`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `scheduled`, `updated`, `custom_url` |
80
+ | `update_entry` | Einen Beitrag partiell aktualisieren | `blog_id`, `entry_id` | `title`, `content`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
81
+ | `delete_entry` | Einen Beitrag löschen | `blog_id`, `entry_id` | `hatena_id` |
82
+
83
+ `update_entry` ruft den aktuellen Beitrag ab und übernimmt nur ausdrücklich angegebene Felder. Nicht angegebene Werte für Titel, Text, Inhaltstyp, Veröffentlichungsstatus, Kategorien, Zeitstempel und Slug bleiben erhalten. Übergeben Sie `categories: []`, um die Kategorien zu leeren. Stimmt `expected_edited` nicht mit dem aktuellen Wert überein, bricht das Tool vor dem PUT ab und meldet einen Konflikt.
84
+
85
+ Ein neuer, geplanter Beitrag erfordert `scheduled: true`, `draft: true` und einen Veröffentlichungszeitstempel in `updated`. Lässt Hatena `scheduled` in einer GET-Antwort weg, wird das Feld auch im Ergebnis und im Update-XML weggelassen, statt als `false` erzeugt zu werden. Bestehende Veröffentlichungszeitstempel ändern sich nur mit `touch_updated: true`.
86
+
87
+ #### Automatisches Eyecatch-Bild aus dem ersten Bild im Beitragstext
88
+
89
+ Wird `eyecatch_image_url` an `create_entry` oder `update_entry` übergeben, fügt der MCP am Anfang des Beitragstextes einen eindeutig erkennbaren HTML-Bildblock ein. Hatena Blog kann dann automatisch das erste Bild im Beitragstext auswählen. Das Eyecatch-Feld von Hatena wird dadurch nicht direkt gesetzt, und das Bild bleibt im Beitragstext sichtbar.
90
+
91
+ ```json
92
+ {
93
+ "name": "create_entry",
94
+ "arguments": {
95
+ "blog_id": "example.hatenablog.com",
96
+ "title": "Ein Beitrag mit automatischem Eyecatch",
97
+ "content": "### Text\n\nHier beginnt der Artikel.",
98
+ "content_type": "text/x-markdown",
99
+ "eyecatch_image_url": "https://cdn-ak.f.st-hatena.com/images/fotolife/example.png"
100
+ }
101
+ }
102
+ ```
103
+
104
+ - Sie können die von `upload_image` zurückgegebene `image_url` direkt übergeben.
105
+ - Wird die Option weggelassen, bleibt der Beitragstext unverändert.
106
+ - Wird sie erneut angegeben, ersetzt sie einen zuvor von diesem MCP eingefügten Block.
107
+ - Wird bei einer Aktualisierung `content` weggelassen, wird der Block auf den vorhandenen Beitragstext angewendet.
108
+
109
+ ### Seiten
110
+
111
+ | Tool | Zweck | Erforderlich | Wichtige Optionen |
112
+ | --- | --- | --- | --- |
113
+ | `list_pages` | Seiten auflisten, 10 pro Seite | `blog_id` | `hatena_id`, `page`, `include_html` |
114
+ | `get_page` | Eine Seite abrufen | `blog_id`, `page_id` | `hatena_id`, `include_html` |
115
+ | `create_page` | Eine Seite erstellen | `blog_id`, `title`, `content`, `custom_url` | `content_type`, `draft`, `preview`, `updated` |
116
+ | `update_page` | Eine Seite partiell aktualisieren | `blog_id`, `page_id` | `title`, `content`, `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
117
+ | `delete_page` | Eine Seite löschen | `blog_id`, `page_id` | `hatena_id` |
118
+
119
+ ### Kategorien und Bilder
120
+
121
+ | Tool | Zweck | Erforderlich | Wichtige Optionen |
122
+ | --- | --- | --- | --- |
123
+ | `list_categories` | Kategorien und ihren Fixierungsstatus auflisten | `blog_id` | `hatena_id` |
124
+ | `get_image` | Metadaten eines Fotolife-Bildes abrufen | `image_id` | — |
125
+ | `upload_image` | Ein Bild hochladen und seine URL sowie die Blog-Syntax zurückgeben | `title`, `content_type`, `data_base64` | `folder` (Standard: `Hatena Blog`) |
126
+
127
+ Der offizielle Fotolife-Feed listet den privaten Ordner „Hatena Blog“, der über den Blog-Editor befüllt wird, nicht auf. Deshalb stellt dieser Server kein Tool zum Auflisten von Bildern bereit.
128
+
129
+ ## Limits und Wiederholungen
130
+
131
+ - Hatena-XML-Antwort: 8 MiB
132
+ - Fehler-Body: 16 KiB
133
+ - Beitragstext: 4 MiB
134
+ - Dekodiertes Bild: 10 MiB
135
+ - Kategorien: 100 Einträge, je 256 Zeichen
136
+ - Upstream-Timeout: 30 Sekunden pro Versuch
137
+ - Automatische Wiederholung: nur für idempotente Methoden wie GET, PUT und DELETE, niemals für POST
138
+ - Der Abbruch einer MCP-Anfrage wird an Upstream-Anfragen und Wartezeiten zwischen Wiederholungen weitergegeben. Bereits gesendete Schreibvorgänge lassen sich nicht zurückrollen.
139
+ - Timeouts beim Response-Body und Verbindungsfehler werden als Netzwerkfehler gemeldet, getrennt von übergroßen Bodys und XML-Parsing-Fehlern.
140
+
141
+ ## Entwicklung und Verifikation
142
+
143
+ ```sh
144
+ pnpm install --frozen-lockfile
145
+ pnpm verify
146
+ npm pack --dry-run --json
147
+ ```
148
+
149
+ `pnpm verify` führt Biome, TypeScript, Vitest mit aktivierter Coverage, eine stdio-Verbindung gegen die gebaute CLI sowie E2E-Prüfungen für Bildlimits, Abbruch, partielle Aktualisierungen und Fehler beim Response-Body aus. Führen Sie nach dem Build `node scripts/smoke-behavior.mjs --report <output.json>` aus, um die Ergebnisse zu speichern. Architektur und Invarianten finden Sie in [DESIGN.md](./DESIGN.md).
150
+
151
+ ## Sicherheit
152
+
153
+ - Entfernen Sie Umgebungswerte, bevor Sie eine MCP-Client-Konfiguration oder einen Wrapper weitergeben.
154
+ - Logs enthalten weder Authorization, API-Schlüssel, Upstream-Response-Bodys noch beliebige Ausnahmemeldungen.
155
+ - Wenn ein Schlüssel offengelegt wurde, erneuern Sie ihn in den AtomPub-Einstellungen von Hatena Blog.
156
+ - Es handelt sich um einen lokalen stdio-Prozess, dennoch ist Schutz auf Betriebssystemebene erforderlich, und zwar gegen andere Prozesse desselben Benutzers sowie gegen die Offenlegung von Client-Konfigurationsdateien.
157
+
158
+ ## Lizenz
159
+
160
+ MIT © Keisuke Nishitani
package/README.es.md ADDED
@@ -0,0 +1,160 @@
1
+ # hatena-blog-mcp
2
+
3
+ [English](./README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [한국어](./README.ko.md) | **Español** | [Français](./README.fr.md) | [Deutsch](./README.de.md) | [Português (Brasil)](./README.pt-BR.md)
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@kagayoi/hatena-blog-mcp)](https://www.npmjs.com/package/@kagayoi/hatena-blog-mcp)
6
+
7
+ > [!IMPORTANT]
8
+ > Este repositorio es un fork no oficial, mantenido de forma independiente, de [Keisuke69/hatena-blog-mcp](https://github.com/Keisuke69/hatena-blog-mcp). Los cambios propios de este fork incluyen la compatibilidad con Hatena Fotolife, la detección de conflictos de actualización, límites de tamaño defensivos y un entorno de ejecución stdio local. Informa de los problemas relacionados con estos cambios en [este fork](https://github.com/1llum1n4t1s/KG.hatena-blog-mcp/issues). Consulta [CHANGELOG.md](./CHANGELOG.md) para más detalles.
9
+
10
+ Un servidor MCP (Model Context Protocol) local para leer y escribir mediante la [API AtomPub de Hatena Blog](https://developer.hatena.ne.jp/ja/documents/blog/apis/atom) y la [API Atom de Hatena Fotolife](https://developer.hatena.ne.jp/ja/documents/fotolife/apis/atom/). Se comunica por stdio sobre Node.js y no requiere un endpoint MCP alojado externamente ni un relé.
11
+
12
+ ## Características
13
+
14
+ - 13 herramientas para entradas, páginas, categorías e imágenes de Fotolife
15
+ - Actualizaciones parciales seguras en `update_entry` y `update_page`, con detección de conflictos mediante `expected_edited`
16
+ - Selección automática de la imagen destacada (eyecatch) mediante un bloque opcional con la primera imagen del cuerpo
17
+ - Sin reintentos automáticos para POST, lo que evita publicaciones y subidas de imágenes duplicadas
18
+ - Límites defensivos para XML, contenido, categorías, imágenes y cuerpos de error
19
+ - Las credenciales proceden de variables de entorno del proceso local, nunca de argumentos de línea de comandos
20
+
21
+ ## Inicio rápido
22
+
23
+ ### Requisitos
24
+
25
+ - Node.js 22 o posterior
26
+ - Tu ID de Hatena
27
+ - La clave de API que aparece en Hatena Blog → Configuración → Avanzado → AtomPub
28
+
29
+ Registra el servidor en cualquier cliente MCP compatible con stdio:
30
+
31
+ ```jsonc
32
+ {
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
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ Si un cliente de Windows no encuentra `npx`, usa `npx.cmd`. Siempre que sea posible, utiliza el almacén de secretos del cliente o del sistema operativo en lugar de guardar las credenciales directamente en un archivo de configuración compartido.
47
+
48
+ ### Actualizaciones
49
+
50
+ La especificación `@latest` se resuelve con la dist-tag `latest` de npm cuando se inicia el proceso MCP. El MCP no se reescribe a sí mismo ni contacta con ningún servicio de actualización propio mientras se ejecuta. Para instalaciones reproducibles, sustituye `latest` por la versión exacta que quieras usar.
51
+
52
+ Si ya registraste el servidor con una versión fijada (por ejemplo, `@kagayoi/hatena-blog-mcp@1.0.6`), cambia el argumento del paquete en ese registro a `@kagayoi/hatena-blog-mcp@latest`. Actualizar este README no modifica los registros existentes, pero tras esa edición cada arranque usará automáticamente la última versión.
53
+
54
+ ### Ejecutar desde el código fuente
55
+
56
+ ```sh
57
+ git clone https://github.com/1llum1n4t1s/KG.hatena-blog-mcp.git
58
+ cd KG.hatena-blog-mcp
59
+ pnpm install --frozen-lockfile
60
+ pnpm build
61
+ ```
62
+
63
+ Configura el comando del cliente como `node`, pasa la ruta absoluta a `dist/cli.js` y proporciona las mismas dos variables de entorno.
64
+
65
+ ## Autenticación y flujo de datos
66
+
67
+ Al iniciarse, el proceso genera en memoria una cabecera Basic Authorization a partir de `HATENA_ID` y `HATENA_API_KEY` para AtomPub. Las solicitudes a Fotolife generan una cabecera WSSE nueva con las mismas credenciales. El servidor no almacena de forma persistente credenciales, publicaciones ni imágenes.
68
+
69
+ `blog_id` es el dominio del blog, por ejemplo `example.hatenablog.com` o `example.hateblo.jp`. En los blogs de grupo, el argumento opcional `hatena_id` de la herramienta reemplaza únicamente el ID de Hatena usado en la URL del servicio de origen.
70
+
71
+ ## Referencia de herramientas
72
+
73
+ ### Entradas
74
+
75
+ | Herramienta | Propósito | Obligatorios | Opciones principales |
76
+ | --- | --- | --- | --- |
77
+ | `list_entries` | Lista entradas, 7 por página | `blog_id` | `hatena_id`, `page`, `include_html` |
78
+ | `get_entry` | Obtiene una entrada | `blog_id`, `entry_id` | `hatena_id`, `include_html` |
79
+ | `create_entry` | Crea una entrada | `blog_id`, `title`, `content` | `content_type`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `scheduled`, `updated`, `custom_url` |
80
+ | `update_entry` | Actualiza parcialmente una entrada | `blog_id`, `entry_id` | `title`, `content`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
81
+ | `delete_entry` | Elimina una entrada | `blog_id`, `entry_id` | `hatena_id` |
82
+
83
+ `update_entry` obtiene la entrada actual y fusiona únicamente los campos indicados de forma explícita. Conserva el título, el cuerpo, el tipo de contenido, el estado de publicación, las categorías, la marca de tiempo y el slug que se hayan omitido. Pasa `categories: []` para vaciar las categorías. Si `expected_edited` no coincide con el valor actual, la herramienta se detiene antes del PUT y notifica un conflicto.
84
+
85
+ Una entrada nueva programada requiere `scheduled: true`, `draft: true` y una marca de tiempo de publicación en `updated`. Cuando Hatena omite `scheduled` en una respuesta GET, el campo también se omite del resultado y del XML de actualización, en lugar de sintetizarse como `false`. Las marcas de tiempo de publicación existentes solo cambian con `touch_updated: true`.
86
+
87
+ #### Eyecatch automático a partir de la primera imagen del cuerpo
88
+
89
+ Cuando se proporciona `eyecatch_image_url` a `create_entry` o `update_entry`, el MCP inserta al inicio del cuerpo un bloque de imagen HTML identificable. Hatena Blog puede entonces seleccionar automáticamente la primera imagen del cuerpo. Esto no establece directamente el campo oficial de eyecatch de Hatena, y la imagen sigue siendo visible en el cuerpo del artículo.
90
+
91
+ ```json
92
+ {
93
+ "name": "create_entry",
94
+ "arguments": {
95
+ "blog_id": "example.hatenablog.com",
96
+ "title": "Una entrada con eyecatch automático",
97
+ "content": "### Cuerpo\n\nAquí comienza el artículo.",
98
+ "content_type": "text/x-markdown",
99
+ "eyecatch_image_url": "https://cdn-ak.f.st-hatena.com/images/fotolife/example.png"
100
+ }
101
+ }
102
+ ```
103
+
104
+ - Puedes pasar directamente el `image_url` devuelto por `upload_image`.
105
+ - Si omites la opción, el cuerpo no se modifica.
106
+ - Si la vuelves a proporcionar, se reemplaza el bloque insertado previamente por este MCP.
107
+ - Si se omite `content` durante una actualización, el bloque se aplica al cuerpo existente.
108
+
109
+ ### Páginas
110
+
111
+ | Herramienta | Propósito | Obligatorios | Opciones principales |
112
+ | --- | --- | --- | --- |
113
+ | `list_pages` | Lista páginas, 10 por página | `blog_id` | `hatena_id`, `page`, `include_html` |
114
+ | `get_page` | Obtiene una página | `blog_id`, `page_id` | `hatena_id`, `include_html` |
115
+ | `create_page` | Crea una página | `blog_id`, `title`, `content`, `custom_url` | `content_type`, `draft`, `preview`, `updated` |
116
+ | `update_page` | Actualiza parcialmente una página | `blog_id`, `page_id` | `title`, `content`, `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
117
+ | `delete_page` | Elimina una página | `blog_id`, `page_id` | `hatena_id` |
118
+
119
+ ### Categorías e imágenes
120
+
121
+ | Herramienta | Propósito | Obligatorios | Opciones principales |
122
+ | --- | --- | --- | --- |
123
+ | `list_categories` | Lista las categorías y su estado de fijación | `blog_id` | `hatena_id` |
124
+ | `get_image` | Obtiene los metadatos de una imagen de Fotolife | `image_id` | — |
125
+ | `upload_image` | Sube una imagen y devuelve su URL y su sintaxis para el blog | `title`, `content_type`, `data_base64` | `folder` (por defecto: `Hatena Blog`) |
126
+
127
+ El feed oficial de Fotolife no lista la carpeta privada «Hatena Blog» que se llena desde el editor del blog, por lo que este servidor no ofrece una herramienta para listar imágenes.
128
+
129
+ ## Límites y reintentos
130
+
131
+ - Respuesta XML de Hatena: 8 MiB
132
+ - Cuerpo de error: 16 KiB
133
+ - Cuerpo de una entrada: 4 MiB
134
+ - Imagen decodificada: 10 MiB
135
+ - Categorías: 100 elementos, de 256 caracteres cada uno
136
+ - Tiempo de espera del servicio de origen: 30 segundos por intento
137
+ - Reintento automático: solo métodos idempotentes como GET, PUT y DELETE; nunca POST
138
+ - La cancelación de una solicitud MCP se propaga a las solicitudes al servicio de origen y a las esperas de reintento. Las escrituras ya enviadas no pueden revertirse.
139
+ - Los tiempos de espera agotados del cuerpo de la respuesta y los fallos de conexión se notifican como errores de red, por separado de los cuerpos demasiado grandes y de los errores de análisis de XML.
140
+
141
+ ## Desarrollo y verificación
142
+
143
+ ```sh
144
+ pnpm install --frozen-lockfile
145
+ pnpm verify
146
+ npm pack --dry-run --json
147
+ ```
148
+
149
+ `pnpm verify` ejecuta Biome, TypeScript, Vitest con cobertura, una conexión stdio contra la CLI compilada y comprobaciones E2E de límites de imagen, cancelación, actualizaciones parciales y fallos en el cuerpo de la respuesta. Tras compilar, ejecuta `node scripts/smoke-behavior.mjs --report <output.json>` para guardar los resultados. Consulta [DESIGN.md](./DESIGN.md) para la arquitectura y los invariantes.
150
+
151
+ ## Seguridad
152
+
153
+ - Elimina los valores de entorno antes de compartir la configuración de un cliente MCP o un wrapper.
154
+ - Los registros excluyen Authorization, las claves de API, los cuerpos de respuesta del servicio de origen y los mensajes de excepción arbitrarios.
155
+ - Si se filtra una clave, rótala desde la configuración AtomPub de Hatena Blog.
156
+ - Se trata de un proceso stdio local, pero sigue siendo necesaria la protección del sistema operativo frente a otros procesos que se ejecuten con el mismo usuario y frente a la divulgación de los archivos de configuración del cliente.
157
+
158
+ ## Licencia
159
+
160
+ MIT © Keisuke Nishitani
package/README.fr.md ADDED
@@ -0,0 +1,160 @@
1
+ # hatena-blog-mcp
2
+
3
+ [English](./README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [한국어](./README.ko.md) | [Español](./README.es.md) | **Français** | [Deutsch](./README.de.md) | [Português (Brasil)](./README.pt-BR.md)
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@kagayoi/hatena-blog-mcp)](https://www.npmjs.com/package/@kagayoi/hatena-blog-mcp)
6
+
7
+ > [!IMPORTANT]
8
+ > Ce dépôt est un fork non officiel, maintenu de manière indépendante, de [Keisuke69/hatena-blog-mcp](https://github.com/Keisuke69/hatena-blog-mcp). Les modifications propres à ce fork comprennent la prise en charge de Hatena Fotolife, la détection des conflits de mise à jour, des limites de taille défensives et un environnement d'exécution stdio local. Signalez les problèmes liés à ces modifications sur [ce fork](https://github.com/1llum1n4t1s/KG.hatena-blog-mcp/issues). Consultez [CHANGELOG.md](./CHANGELOG.md) pour plus de détails.
9
+
10
+ Un serveur MCP (Model Context Protocol) local pour lire et écrire via l'[API AtomPub de Hatena Blog](https://developer.hatena.ne.jp/ja/documents/blog/apis/atom) et l'[API Atom de Hatena Fotolife](https://developer.hatena.ne.jp/ja/documents/fotolife/apis/atom/). Il communique par stdio sur Node.js et ne nécessite ni point de terminaison MCP hébergé à l'extérieur ni relais.
11
+
12
+ ## Fonctionnalités
13
+
14
+ - 13 outils couvrant les articles, les pages, les catégories et les images Fotolife
15
+ - Mises à jour partielles sûres dans `update_entry` et `update_page`, avec détection des conflits via `expected_edited`
16
+ - Sélection automatique de l'image d'accroche (eyecatch) grâce à un bloc facultatif contenant la première image du corps
17
+ - Aucune nouvelle tentative automatique pour POST, afin d'éviter les publications et les envois d'images en double
18
+ - Limites défensives pour le XML, le contenu, les catégories, les images et les corps d'erreur
19
+ - Les identifiants proviennent des variables d'environnement du processus local, jamais des arguments de ligne de commande
20
+
21
+ ## Démarrage rapide
22
+
23
+ ### Prérequis
24
+
25
+ - Node.js 22 ou version ultérieure
26
+ - Votre identifiant Hatena
27
+ - La clé d'API affichée dans Hatena Blog → Paramètres → Avancé → AtomPub
28
+
29
+ Enregistrez le serveur dans n'importe quel client MCP compatible avec stdio :
30
+
31
+ ```jsonc
32
+ {
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
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ Si un client Windows ne trouve pas `npx`, utilisez `npx.cmd`. Lorsque c'est possible, privilégiez le stockage de secrets du client ou du système d'exploitation plutôt que de conserver les identifiants directement dans un fichier de configuration partagé.
47
+
48
+ ### Mises à jour
49
+
50
+ La spécification `@latest` est résolue vers la dist-tag `latest` de npm au démarrage du processus MCP. Le MCP ne se réécrit pas lui-même et ne contacte aucun service de mise à jour personnalisé pendant son exécution. Pour des installations reproductibles, remplacez `latest` par la version exacte que vous souhaitez utiliser.
51
+
52
+ Si vous avez déjà enregistré le serveur avec une version figée (par exemple `@kagayoi/hatena-blog-mcp@1.0.6`), remplacez l'argument du paquet dans cet enregistrement par `@kagayoi/hatena-blog-mcp@latest`. La mise à jour de ce README ne modifie pas les enregistrements existants, mais après cette modification, chaque lancement utilise automatiquement la dernière version.
53
+
54
+ ### Exécuter depuis les sources
55
+
56
+ ```sh
57
+ git clone https://github.com/1llum1n4t1s/KG.hatena-blog-mcp.git
58
+ cd KG.hatena-blog-mcp
59
+ pnpm install --frozen-lockfile
60
+ pnpm build
61
+ ```
62
+
63
+ Définissez la commande du client sur `node`, transmettez le chemin absolu vers `dist/cli.js` et fournissez les deux mêmes variables d'environnement.
64
+
65
+ ## Authentification et flux de données
66
+
67
+ Au démarrage, le processus dérive en mémoire un en-tête Basic Authorization à partir de `HATENA_ID` et `HATENA_API_KEY` pour AtomPub. Les requêtes Fotolife dérivent un nouvel en-tête WSSE à partir des mêmes identifiants. Le serveur ne conserve de façon persistante ni les identifiants, ni les articles, ni les images.
68
+
69
+ `blog_id` est le domaine du blog, par exemple `example.hatenablog.com` ou `example.hateblo.jp`. Sur les blogs de groupe, l'argument facultatif `hatena_id` de l'outil remplace uniquement l'identifiant Hatena utilisé dans l'URL du service amont.
70
+
71
+ ## Référence des outils
72
+
73
+ ### Articles
74
+
75
+ | Outil | Rôle | Obligatoires | Options principales |
76
+ | --- | --- | --- | --- |
77
+ | `list_entries` | Liste les articles, 7 par page | `blog_id` | `hatena_id`, `page`, `include_html` |
78
+ | `get_entry` | Récupère un article | `blog_id`, `entry_id` | `hatena_id`, `include_html` |
79
+ | `create_entry` | Crée un article | `blog_id`, `title`, `content` | `content_type`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `scheduled`, `updated`, `custom_url` |
80
+ | `update_entry` | Met à jour partiellement un article | `blog_id`, `entry_id` | `title`, `content`, `eyecatch_image_url`, `categories`, `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
81
+ | `delete_entry` | Supprime un article | `blog_id`, `entry_id` | `hatena_id` |
82
+
83
+ `update_entry` récupère l'article actuel et ne fusionne que les champs explicitement fournis. Il conserve le titre, le corps, le type de contenu, l'état de publication, les catégories, l'horodatage et le slug lorsqu'ils sont omis. Passez `categories: []` pour vider les catégories. Si `expected_edited` ne correspond pas à la valeur actuelle, l'outil s'arrête avant le PUT et signale un conflit.
84
+
85
+ Un nouvel article programmé exige `scheduled: true`, `draft: true` et un horodatage de publication dans `updated`. Lorsque Hatena omet `scheduled` dans une réponse GET, le champ est également omis du résultat et du XML de mise à jour, au lieu d'être synthétisé sous la forme `false`. Les horodatages de publication existants ne changent qu'avec `touch_updated: true`.
86
+
87
+ #### Eyecatch automatique à partir de la première image du corps
88
+
89
+ Lorsque `eyecatch_image_url` est fourni à `create_entry` ou `update_entry`, le MCP insère au début du corps un bloc d'image HTML identifiable. Hatena Blog peut alors sélectionner automatiquement la première image du corps. Cela ne renseigne pas directement le champ eyecatch officiel de Hatena, et l'image reste visible dans le corps de l'article.
90
+
91
+ ```json
92
+ {
93
+ "name": "create_entry",
94
+ "arguments": {
95
+ "blog_id": "example.hatenablog.com",
96
+ "title": "Un article avec eyecatch automatique",
97
+ "content": "### Corps\n\nL'article commence ici.",
98
+ "content_type": "text/x-markdown",
99
+ "eyecatch_image_url": "https://cdn-ak.f.st-hatena.com/images/fotolife/example.png"
100
+ }
101
+ }
102
+ ```
103
+
104
+ - Vous pouvez transmettre directement l'`image_url` renvoyée par `upload_image`.
105
+ - Si l'option est omise, le corps reste inchangé.
106
+ - La fournir à nouveau remplace un bloc précédemment inséré par ce MCP.
107
+ - Lorsque `content` est omis lors d'une mise à jour, le bloc est appliqué au corps existant.
108
+
109
+ ### Pages
110
+
111
+ | Outil | Rôle | Obligatoires | Options principales |
112
+ | --- | --- | --- | --- |
113
+ | `list_pages` | Liste les pages, 10 par page | `blog_id` | `hatena_id`, `page`, `include_html` |
114
+ | `get_page` | Récupère une page | `blog_id`, `page_id` | `hatena_id`, `include_html` |
115
+ | `create_page` | Crée une page | `blog_id`, `title`, `content`, `custom_url` | `content_type`, `draft`, `preview`, `updated` |
116
+ | `update_page` | Met à jour partiellement une page | `blog_id`, `page_id` | `title`, `content`, `draft`, `preview`, `custom_url`, `touch_updated`, `expected_edited` |
117
+ | `delete_page` | Supprime une page | `blog_id`, `page_id` | `hatena_id` |
118
+
119
+ ### Catégories et images
120
+
121
+ | Outil | Rôle | Obligatoires | Options principales |
122
+ | --- | --- | --- | --- |
123
+ | `list_categories` | Liste les catégories et leur état d'épinglage | `blog_id` | `hatena_id` |
124
+ | `get_image` | Récupère les métadonnées d'une image Fotolife | `image_id` | — |
125
+ | `upload_image` | Envoie une image et renvoie son URL et sa syntaxe pour le blog | `title`, `content_type`, `data_base64` | `folder` (par défaut : `Hatena Blog`) |
126
+
127
+ Le flux officiel de Fotolife ne liste pas le dossier privé « Hatena Blog » alimenté par l'éditeur du blog ; ce serveur ne fournit donc pas d'outil de liste des images.
128
+
129
+ ## Limites et nouvelles tentatives
130
+
131
+ - Réponse XML de Hatena : 8 MiB
132
+ - Corps d'erreur : 16 KiB
133
+ - Corps d'un article : 4 MiB
134
+ - Image décodée : 10 MiB
135
+ - Catégories : 100 entrées, 256 caractères chacune
136
+ - Délai d'attente du service amont : 30 secondes par tentative
137
+ - Nouvelle tentative automatique : uniquement pour les méthodes idempotentes telles que GET, PUT et DELETE ; jamais pour POST
138
+ - L'annulation d'une requête MCP se propage aux requêtes vers le service amont et aux attentes avant nouvelle tentative. Les écritures déjà envoyées ne peuvent pas être annulées.
139
+ - Les dépassements de délai du corps de la réponse et les échecs de connexion sont signalés comme des erreurs réseau, séparément des corps trop volumineux et des erreurs d'analyse XML.
140
+
141
+ ## Développement et vérification
142
+
143
+ ```sh
144
+ pnpm install --frozen-lockfile
145
+ pnpm verify
146
+ npm pack --dry-run --json
147
+ ```
148
+
149
+ `pnpm verify` exécute Biome, TypeScript, Vitest avec couverture, une connexion stdio contre la CLI compilée, ainsi que des contrôles E2E des limites d'image, de l'annulation, des mises à jour partielles et des échecs sur le corps de la réponse. Après la compilation, exécutez `node scripts/smoke-behavior.mjs --report <output.json>` pour enregistrer les résultats. Consultez [DESIGN.md](./DESIGN.md) pour l'architecture et les invariants.
150
+
151
+ ## Sécurité
152
+
153
+ - Supprimez les valeurs d'environnement avant de partager la configuration d'un client MCP ou un wrapper.
154
+ - Les journaux excluent Authorization, les clés d'API, les corps de réponse du service amont et les messages d'exception arbitraires.
155
+ - Si une clé fuite, renouvelez-la depuis les paramètres AtomPub de Hatena Blog.
156
+ - Il s'agit d'un processus stdio local, mais une protection au niveau du système d'exploitation reste nécessaire contre les autres processus exécutés sous le même utilisateur et contre la divulgation des fichiers de configuration du client.
157
+
158
+ ## Licence
159
+
160
+ MIT © Keisuke Nishitani