@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
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
import { MAX_XML_RESPONSE_BYTES, readErrorText, readTextWithLimit } from "../utils/body.js";
|
|
2
|
+
import type { RetryOptions } from "../utils/retry.js";
|
|
3
|
+
import { fetchWithRetry } from "../utils/retry.js";
|
|
4
|
+
import { AtomPubError } from "./errors.js";
|
|
5
|
+
import type {
|
|
6
|
+
CategoryDocument,
|
|
7
|
+
Entry,
|
|
8
|
+
EntryList,
|
|
9
|
+
EntryWritePayload,
|
|
10
|
+
Page,
|
|
11
|
+
PageList,
|
|
12
|
+
PageWritePayload,
|
|
13
|
+
} from "./types.js";
|
|
14
|
+
import {
|
|
15
|
+
buildEntryXml,
|
|
16
|
+
buildPageXml,
|
|
17
|
+
parseCategories,
|
|
18
|
+
parseEntry,
|
|
19
|
+
parseFeed,
|
|
20
|
+
parsePage,
|
|
21
|
+
parsePageFeed,
|
|
22
|
+
} from "./xml.js";
|
|
23
|
+
|
|
24
|
+
export interface AtomPubCredentials {
|
|
25
|
+
/**
|
|
26
|
+
* The full `Basic <base64>` header value from the MCP client. Relayed to
|
|
27
|
+
* Hatena unchanged — we never store the decoded secret on our side.
|
|
28
|
+
*/
|
|
29
|
+
authHeader: string;
|
|
30
|
+
/** Hatena ID used as the first path segment of the AtomPub URL. */
|
|
31
|
+
hatenaId: string;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export interface AtomPubClientOptions {
|
|
35
|
+
credentials: AtomPubCredentials;
|
|
36
|
+
/**
|
|
37
|
+
* The blog identifier, e.g. `example_user.hatenablog.com`. This appears as
|
|
38
|
+
* the second path segment in every AtomPub URL.
|
|
39
|
+
*/
|
|
40
|
+
blogId: string;
|
|
41
|
+
fetchImpl?: typeof fetch;
|
|
42
|
+
retry?: RetryOptions;
|
|
43
|
+
signal?: AbortSignal;
|
|
44
|
+
requestTimeoutMs?: number;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const ATOMPUB_BASE = "https://blog.hatena.ne.jp";
|
|
48
|
+
const CONTENT_TYPE_XML = "application/xml; charset=utf-8";
|
|
49
|
+
const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
|
|
50
|
+
|
|
51
|
+
export class AtomPubClient {
|
|
52
|
+
private readonly credentials: AtomPubCredentials;
|
|
53
|
+
private readonly blogId: string;
|
|
54
|
+
private readonly fetchImpl: typeof fetch;
|
|
55
|
+
private readonly retry: RetryOptions;
|
|
56
|
+
private readonly signal: AbortSignal | undefined;
|
|
57
|
+
private readonly requestTimeoutMs: number;
|
|
58
|
+
|
|
59
|
+
constructor(opts: AtomPubClientOptions) {
|
|
60
|
+
this.credentials = opts.credentials;
|
|
61
|
+
this.blogId = opts.blogId;
|
|
62
|
+
this.fetchImpl = opts.fetchImpl ?? fetch;
|
|
63
|
+
this.retry = opts.retry ?? {};
|
|
64
|
+
this.signal = opts.signal;
|
|
65
|
+
this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// ------------------------------------------------------------------ URLs
|
|
69
|
+
|
|
70
|
+
private collectionUrl(kind: "entry" | "page"): string {
|
|
71
|
+
return `${ATOMPUB_BASE}/${encode(this.credentials.hatenaId)}/${encode(this.blogId)}/atom/${kind}`;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
private memberUrl(kind: "entry" | "page", id: string): string {
|
|
75
|
+
return `${this.collectionUrl(kind)}/${encode(id)}`;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
private categoryUrl(): string {
|
|
79
|
+
return `${ATOMPUB_BASE}/${encode(this.credentials.hatenaId)}/${encode(this.blogId)}/atom/category`;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// ------------------------------------------------------------------ Entries
|
|
83
|
+
|
|
84
|
+
async listEntries(opts: { page?: string } = {}): Promise<EntryList> {
|
|
85
|
+
const url = buildUrlWithPage(this.collectionUrl("entry"), opts.page);
|
|
86
|
+
const xml = await this.requestXml("GET", url);
|
|
87
|
+
return parseFeed(xml);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
async getEntry(entryId: string): Promise<Entry> {
|
|
91
|
+
const xml = await this.requestXml("GET", this.memberUrl("entry", entryId));
|
|
92
|
+
return parseEntry(xml);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
async createEntry(payload: EntryWritePayload): Promise<Entry> {
|
|
96
|
+
const body = buildEntryXml(payload, { creating: true });
|
|
97
|
+
const xml = await this.requestXml("POST", this.collectionUrl("entry"), body);
|
|
98
|
+
return parseEntry(xml);
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
async updateEntry(entryId: string, payload: EntryWritePayload): Promise<Entry> {
|
|
102
|
+
const body = buildEntryXml(payload, { creating: false });
|
|
103
|
+
const xml = await this.requestXml("PUT", this.memberUrl("entry", entryId), body);
|
|
104
|
+
return parseEntry(xml);
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
async deleteEntry(entryId: string): Promise<void> {
|
|
108
|
+
await this.request("DELETE", this.memberUrl("entry", entryId));
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// ------------------------------------------------------------------ Pages
|
|
112
|
+
|
|
113
|
+
async listPages(opts: { page?: string } = {}): Promise<PageList> {
|
|
114
|
+
const url = buildUrlWithPage(this.collectionUrl("page"), opts.page);
|
|
115
|
+
const xml = await this.requestXml("GET", url);
|
|
116
|
+
return parsePageFeed(xml);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
async getPage(pageId: string): Promise<Page> {
|
|
120
|
+
const xml = await this.requestXml("GET", this.memberUrl("page", pageId));
|
|
121
|
+
return parsePage(xml);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
async createPage(payload: PageWritePayload): Promise<Page> {
|
|
125
|
+
const body = buildPageXml(payload, { creating: true });
|
|
126
|
+
const xml = await this.requestXml("POST", this.collectionUrl("page"), body);
|
|
127
|
+
return parsePage(xml);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
async updatePage(pageId: string, payload: PageWritePayload): Promise<Page> {
|
|
131
|
+
const body = buildPageXml(payload, { creating: false });
|
|
132
|
+
const xml = await this.requestXml("PUT", this.memberUrl("page", pageId), body);
|
|
133
|
+
return parsePage(xml);
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
async deletePage(pageId: string): Promise<void> {
|
|
137
|
+
await this.request("DELETE", this.memberUrl("page", pageId));
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// ------------------------------------------------------------------ Categories
|
|
141
|
+
|
|
142
|
+
async listCategories(): Promise<CategoryDocument> {
|
|
143
|
+
const xml = await this.requestXml("GET", this.categoryUrl());
|
|
144
|
+
return parseCategories(xml);
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
// ------------------------------------------------------------------ Core
|
|
148
|
+
|
|
149
|
+
private async request(method: string, url: string, body?: string): Promise<Response> {
|
|
150
|
+
const headers: Record<string, string> = {
|
|
151
|
+
Authorization: this.credentials.authHeader,
|
|
152
|
+
Accept: "application/xml",
|
|
153
|
+
};
|
|
154
|
+
if (body !== undefined) {
|
|
155
|
+
headers["Content-Type"] = CONTENT_TYPE_XML;
|
|
156
|
+
}
|
|
157
|
+
let response: Response;
|
|
158
|
+
try {
|
|
159
|
+
response = await fetchWithRetry(
|
|
160
|
+
url,
|
|
161
|
+
{
|
|
162
|
+
method,
|
|
163
|
+
headers,
|
|
164
|
+
signal: this.createRequestSignal(),
|
|
165
|
+
...(body !== undefined ? { body } : {}),
|
|
166
|
+
},
|
|
167
|
+
{ ...this.retry, fetchImpl: this.fetchImpl },
|
|
168
|
+
);
|
|
169
|
+
} catch (cause) {
|
|
170
|
+
throw new AtomPubError("Hatena AtomPub network request failed", {
|
|
171
|
+
status: 0,
|
|
172
|
+
code: "network_error",
|
|
173
|
+
cause,
|
|
174
|
+
});
|
|
175
|
+
}
|
|
176
|
+
if (!response.ok) {
|
|
177
|
+
const text = await readErrorText(response);
|
|
178
|
+
throw new AtomPubError(describeStatus(response.status), {
|
|
179
|
+
status: response.status,
|
|
180
|
+
body: text,
|
|
181
|
+
});
|
|
182
|
+
}
|
|
183
|
+
return response;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
private async requestXml(method: string, url: string, body?: string): Promise<string> {
|
|
187
|
+
const response = await this.request(method, url, body);
|
|
188
|
+
try {
|
|
189
|
+
return await readTextWithLimit(response, MAX_XML_RESPONSE_BYTES);
|
|
190
|
+
} catch (cause) {
|
|
191
|
+
throw new AtomPubError("Hatena AtomPub response exceeded the XML size limit", {
|
|
192
|
+
status: 0,
|
|
193
|
+
code: "parse_error",
|
|
194
|
+
cause,
|
|
195
|
+
});
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
private createRequestSignal(): AbortSignal {
|
|
200
|
+
const timeout = AbortSignal.timeout(this.requestTimeoutMs);
|
|
201
|
+
return this.signal ? AbortSignal.any([this.signal, timeout]) : timeout;
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// ---------------------------------------------------------------------------
|
|
206
|
+
|
|
207
|
+
function buildUrlWithPage(base: string, page: string | undefined): string {
|
|
208
|
+
if (page === undefined) return base;
|
|
209
|
+
const sep = base.includes("?") ? "&" : "?";
|
|
210
|
+
return `${base}${sep}page=${encode(page)}`;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
function encode(segment: string): string {
|
|
214
|
+
return encodeURIComponent(segment);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
function describeStatus(status: number): string {
|
|
218
|
+
if (status === 401) return "Hatena AtomPub authentication failed (401)";
|
|
219
|
+
if (status === 403) return "Hatena AtomPub forbade the request (403)";
|
|
220
|
+
if (status === 404) return "Hatena AtomPub resource not found (404)";
|
|
221
|
+
if (status === 429) return "Hatena AtomPub rate limit exceeded (429)";
|
|
222
|
+
if (status >= 500) return `Hatena AtomPub server error (${status})`;
|
|
223
|
+
return `Hatena AtomPub returned ${status}`;
|
|
224
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Error thrown for any non-2xx response from the Hatena AtomPub API, plus
|
|
3
|
+
* parse failures. The MCP layer maps these into user-facing Japanese messages;
|
|
4
|
+
* the raw body is kept here only for logging and never surfaced to clients.
|
|
5
|
+
*/
|
|
6
|
+
export class AtomPubError extends Error {
|
|
7
|
+
readonly status: number;
|
|
8
|
+
readonly bodySnippet: string;
|
|
9
|
+
readonly code: AtomPubErrorCode;
|
|
10
|
+
|
|
11
|
+
constructor(
|
|
12
|
+
message: string,
|
|
13
|
+
opts: {
|
|
14
|
+
status: number;
|
|
15
|
+
body?: string;
|
|
16
|
+
code?: AtomPubErrorCode;
|
|
17
|
+
cause?: unknown;
|
|
18
|
+
},
|
|
19
|
+
) {
|
|
20
|
+
super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
|
|
21
|
+
this.name = "AtomPubError";
|
|
22
|
+
this.status = opts.status;
|
|
23
|
+
this.bodySnippet = truncate(opts.body ?? "", 500);
|
|
24
|
+
this.code = opts.code ?? inferCode(opts.status);
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export type AtomPubErrorCode =
|
|
29
|
+
| "unauthorized"
|
|
30
|
+
| "forbidden"
|
|
31
|
+
| "not_found"
|
|
32
|
+
| "rate_limited"
|
|
33
|
+
| "server_error"
|
|
34
|
+
| "bad_request"
|
|
35
|
+
| "parse_error"
|
|
36
|
+
| "network_error"
|
|
37
|
+
| "unknown";
|
|
38
|
+
|
|
39
|
+
function inferCode(status: number): AtomPubErrorCode {
|
|
40
|
+
if (status === 401) return "unauthorized";
|
|
41
|
+
if (status === 403) return "forbidden";
|
|
42
|
+
if (status === 404) return "not_found";
|
|
43
|
+
if (status === 429) return "rate_limited";
|
|
44
|
+
if (status >= 500) return "server_error";
|
|
45
|
+
if (status >= 400) return "bad_request";
|
|
46
|
+
if (status === 0) return "network_error";
|
|
47
|
+
return "unknown";
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function truncate(s: string, max: number): string {
|
|
51
|
+
if (s.length <= max) return s;
|
|
52
|
+
return `${s.slice(0, max)}…[truncated ${s.length - max} chars]`;
|
|
53
|
+
}
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Content type recognised by Hatena AtomPub.
|
|
3
|
+
*
|
|
4
|
+
* NOTE: On update, the existing value MUST be preserved — the API will coerce
|
|
5
|
+
* the body to match whatever `type` you send, so changing it silently rewrites
|
|
6
|
+
* the content's rendering rules.
|
|
7
|
+
*/
|
|
8
|
+
export type ContentType = "text/x-markdown" | "text/x-hatena-syntax" | "text/html" | "text/plain";
|
|
9
|
+
|
|
10
|
+
export interface EntryControl {
|
|
11
|
+
draft: boolean;
|
|
12
|
+
preview: boolean;
|
|
13
|
+
/** Only meaningful for entries (not for pages). */
|
|
14
|
+
scheduled: boolean;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export interface Entry {
|
|
18
|
+
/** Numeric id from <link rel="edit">, used in `.../atom/entry/{id}`. */
|
|
19
|
+
id: string;
|
|
20
|
+
/** Full atom `<id>` (urn-like) — kept for round-trip fidelity. */
|
|
21
|
+
atomId: string;
|
|
22
|
+
title: string;
|
|
23
|
+
authorName: string;
|
|
24
|
+
/** Raw body as authored. */
|
|
25
|
+
content: string;
|
|
26
|
+
contentType: ContentType | undefined;
|
|
27
|
+
/** Rendered HTML (from `hatena:formatted-content`). Only populated when explicitly requested. */
|
|
28
|
+
formattedContent?: string;
|
|
29
|
+
categories: string[];
|
|
30
|
+
control: EntryControl;
|
|
31
|
+
/** ISO-8601. */
|
|
32
|
+
updated: string;
|
|
33
|
+
/** ISO-8601. May be absent on newly created entries. */
|
|
34
|
+
published?: string;
|
|
35
|
+
/** ISO-8601. Last edit timestamp (`app:edited`). */
|
|
36
|
+
edited?: string;
|
|
37
|
+
/** Public permalink (`link rel="alternate" type="text/html"`). */
|
|
38
|
+
url?: string;
|
|
39
|
+
/** Edit URI (`link rel="edit"`). */
|
|
40
|
+
editUrl?: string;
|
|
41
|
+
/** `hatenablog:custom-url`. Absent when the blog uses the default URL format. */
|
|
42
|
+
customUrl?: string;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Pages never carry categories or scheduling. */
|
|
46
|
+
export interface Page {
|
|
47
|
+
id: string;
|
|
48
|
+
atomId: string;
|
|
49
|
+
title: string;
|
|
50
|
+
authorName: string;
|
|
51
|
+
content: string;
|
|
52
|
+
contentType: ContentType | undefined;
|
|
53
|
+
formattedContent?: string;
|
|
54
|
+
control: Omit<EntryControl, "scheduled">;
|
|
55
|
+
updated: string;
|
|
56
|
+
published?: string;
|
|
57
|
+
edited?: string;
|
|
58
|
+
url?: string;
|
|
59
|
+
editUrl?: string;
|
|
60
|
+
/** Required on create for pages. */
|
|
61
|
+
customUrl?: string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export interface EntryList {
|
|
65
|
+
entries: Entry[];
|
|
66
|
+
/**
|
|
67
|
+
* The `page` query-string value for the next page, or null when there is no
|
|
68
|
+
* next page. Carries just the epoch number — not a full URL — so callers
|
|
69
|
+
* can pass it straight back into `list_entries({ page })`.
|
|
70
|
+
*/
|
|
71
|
+
nextPage: string | null;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
export interface PageList {
|
|
75
|
+
pages: Page[];
|
|
76
|
+
nextPage: string | null;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export interface CategoryDocument {
|
|
80
|
+
categories: string[];
|
|
81
|
+
/** When true, new categories cannot be added to this blog. */
|
|
82
|
+
fixed: boolean;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Payload used when POSTing a new entry or PUTting an existing one. Every
|
|
87
|
+
* field is optional at this layer; the MCP tool layer decides which to set.
|
|
88
|
+
*
|
|
89
|
+
* The XML builder interprets `undefined` fields as "omit" — callers rely on
|
|
90
|
+
* that for two update edge-cases:
|
|
91
|
+
* - omitting `updated` preserves the published timestamp
|
|
92
|
+
* - omitting `customUrl` preserves the slug
|
|
93
|
+
*/
|
|
94
|
+
export interface EntryWritePayload {
|
|
95
|
+
title?: string;
|
|
96
|
+
authorName?: string;
|
|
97
|
+
content?: string;
|
|
98
|
+
contentType?: ContentType;
|
|
99
|
+
categories?: string[];
|
|
100
|
+
control?: Partial<EntryControl>;
|
|
101
|
+
updated?: string;
|
|
102
|
+
customUrl?: string;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
export interface PageWritePayload {
|
|
106
|
+
title?: string;
|
|
107
|
+
authorName?: string;
|
|
108
|
+
content?: string;
|
|
109
|
+
contentType?: ContentType;
|
|
110
|
+
control?: Partial<Omit<EntryControl, "scheduled">>;
|
|
111
|
+
updated?: string;
|
|
112
|
+
customUrl?: string;
|
|
113
|
+
}
|