amenbo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rererr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# amenbo 🐜💧
+
+**Skims the web without making waves** — a Japanese-web-native MCP server for low-impact, token-efficient web collection.
+
+amenbo(アメンボ / water strider)は、Claude Code や Codex のようなコーディングエージェント向けの [MCP](https://modelcontextprotocol.io) サーバーです。水面に波を立てずに滑る虫のように、**収集先に負荷をかけず・少ないトークンで** Web から情報を集めます。とりわけ**日本語サイト**に最適化しています。MCP クライアントを持たないシェル環境からは、同じコアを共有する CLI としても使えます([CLIとして使う](#cliとして使う)参照)。
+
+## なぜ amenbo か
+
+汎用のスクレイピングツールの多くは英語圏の Web を前提に作られており、日本語サイトでは次のような取りこぼしが起きがちです。amenbo はこれらを正面から扱います。
+
+- **構造化が甘いサイト** — div の入れ子やテーブルレイアウトが多い日本語サイトでも、レンダリング結果のジオメトリ(見た目の配置)から本文領域を推定します
+- **文字化け** — Shift_JIS / EUC-JP / ISO-2022-JP を自動判別
+- **ふりがな** — `<ruby>` の振り仮名を除去し、本文の二重化を防止
+- **画像で出す情報** — 画像化された料金表やバナー中心のページは、テキスト抽出が貧弱なとき自動でスクリーンショットに切り替え
+- **国内主要サイト** — Qiita / Zenn / note / はてなブログ / Yahoo!ニュース / PR TIMES / Wikipedia 日本語版に専用アダプタ
+
+類似ツール(公式 fetch MCP / Jina Reader / Playwright MCP / PixelRAG pixelshot)との実測比較は、記事「[エージェントのWeb取得、ツール次第でトークンが5000倍違った話](https://zenn.dev/rererr_engineer/articles/e571e5b6eb1d53)」を参照してください。ハーネスと生ログは [`bench/`](./bench/) にあります。
+
+## トークンを節約する仕組み
+
+- **段階開示** — `mode: outline` で見出しツリーと各節のトークン量だけ先に返し、必要な節だけ `section` 指定で取得。長大なページを丸ごと流し込みません
+- **CJK 対応の本文プルーニング** — 句読点密度・文字種比率・リンク密度でナビ/広告/フッターを除去
+- **差分応答** — 一度取得した URL の再取得時、変更が無ければ `unchanged`、あれば変更された節だけを返します
+- **自動 Markdown/画像切替** — 品質スコアが低いページだけスクリーンショットにし、壊れた Markdown を読ませて取り直す往復を避けます
+- **CJK トークン見積り** — 日本語は英語よりトークン単価が重いため、文字種別の係数でページ分割の予算を計算します
+
+## 収集先への低負荷
+
+- **二段フェッチ** — まず素の HTTP GET。JS 描画が必要なページだけ headless Chromium に昇格するので、大半の取得でブラウザを起動しません
+- **礼儀正しいクローラ** — robots.txt と Crawl-Delay を尊重、同一ドメインへは直列 + 既定 1 req/秒。リンク列挙は sitemap / RSS を優先しページを舐めません
+- **正直な User-Agent** — ボットであることを明示します。**anti-bot 回避は実装しません**
+- **キャッシュ** — ETag / If-Modified-Since で再検証し、無駄な再取得を避けます
+
+## インストール
+
+```bash
+npm install -g amenbo
+# postinstall で Chromium が入ります(SPA描画・スクリーンショット用)
+```
+
+または開発用途:
+
+```bash
+git clone https://github.com/Rererr/amenbo.git
+cd amenbo
+npm install
+npm run build
+```
+
+### Claude Code への登録
+
+`.mcp.json`(またはグローバル設定)に追加します:
+
+```json
+{
+  "mcpServers": {
+    "amenbo": {
+      "command": "amenbo"
+    }
+  }
+}
+```
+
+ローカルビルドを使う場合は `"command": "node", "args": ["/path/to/amenbo/dist/server.js"]`。
+
+### エージェントに使い方を教える(推奨プロンプト)
+
+ツール定義だけでは「段階開示で取る」といった使い方の作法までは伝わりません。以下を `CLAUDE.md` や `AGENTS.md` にコピペすると、エージェントが amenbo を効率よく使うようになります。
+
+```markdown
+## Web取得は amenbo を使う
+
+- ページ取得は `fetch`(mode 既定 `auto`)。長そうなページや一部しか要らないページは、
+  まず `mode: "outline"` で見出しと各節のトークン量を確認し、必要な節だけ `section` 指定で取得する
+- 同じ URL の再取得で `unchanged` / `diff` が返るのは正常(変更なし / 変更節のみ)。
+  全文が必要なときだけ `force_full: true` を使う
+- サイト内のページを探すときは URL を推測せず `links`(`filter` で絞り込み)で列挙する
+- シェルが使える環境で、キーワードで探したいだけの長いページや複数ページの一括収集は、
+  CLI で `amenbo fetch <url> > page.md` に落として grep / 部分読みする(本文をコンテキストに入れない)。
+  構造を見ながら判断したいページは従来どおり MCP の outline → section が向く
+- 日本語以外のサイトにも使える(段階開示・キャッシュ・低負荷は言語非依存)。ただし本文抽出は
+  日本語向けに調整しているため、非日本語ページで本文が欠けて見えるときは `selector` 指定か
+  `mode: "screenshot"` で取り直す
+- 料金表・レイアウトなど視覚情報が目的なら `screenshot`。`scale: 0.5` 程度で画像トークンを減らせる
+- robots.txt 拒否や bot 対策による取得失敗は仕様(回避しない)。失敗はそのままユーザーに報告する
+```
+
+## CLIとして使う
+
+`amenbo` は MCP サーバーと同一のコア(取得・キャッシュ・politeness・抽出ロジック)を共有する CLI としても動作します。引数なし、または `amenbo serve` は従来通り MCP サーバーとして起動する(`.mcp.json` の `"command": "amenbo"` はそのまま動きます)ので、既存の MCP 登録には影響しません。
+
+```bash
+# ページをMarkdownとして取得(標準出力へ)
+amenbo fetch https://example.com/
+
+# 長いページはまずoutlineで見出しとトークン量だけ確認
+amenbo fetch https://example.com/ --mode outline
+
+# 出力をファイルに落として grep や部分読み(head/sed)する
+amenbo fetch https://example.com/ > page.md
+grep -A3 "料金" page.md
+
+# サイト内のリンクを列挙(sitemap/RSS優先)
+amenbo links https://example.com/ --filter "blog/*"
+
+# スクリーンショット(タイルPNGは--out-dirへ保存され、パスが標準出力に列挙される)
+amenbo screenshot https://example.com/ --viewport-only --scale 0.5 --out-dir ./shots
+```
+
+各サブコマンドの詳細は `amenbo <fetch|links|screenshot> --help` を参照してください。
+
+**MCP と CLI の使い分け**:
+
+- **MCP** — エージェントの主経路。ブラウザ(Chromium)がプロセス内でウォームに保たれ、スクリーンショット等の画像を会話へ直接返せる。claude.ai のようにシェルを持たないホストのエージェントにも届く
+- **CLI** — シェルスクリプト・CI・デバッグ用途、出力をファイルに落として `grep`/部分読みしたい場合、または MCP 非対応のエージェント/ツールチェーンから使う場合に向く。1 コマンド= 1 プロセスのためブラウザは毎回起動する
+
+キャッシュ・差分応答(`unchanged`/`diff`)・レート制御(robots.txt/ドメイン毎の直列アクセス)の状態は MCP サーバーと CLI で共有されます(同じ `~/.cache/amenbo` を使うため)。ただしレート制御のプロセス間共有はベストエフォートです。同一ドメインへの直列化は各プロセス内でのみ厳密に保証され、MCP サーバーと複数の CLI 実行が同時に同じドメインへアクセスした場合、最小間隔が多少すり抜けることがあります。
+
+## ツール
+
+### `fetch` — ページを取得
+| パラメータ | 説明 |
+|---|---|
+| `url` | 取得対象 URL(http/https のみ。PDF 可) |
+| `mode` | `auto`(既定・品質スコアで Markdown/screenshot 自動切替) / `markdown` / `outline`(見出し要約) / `screenshot` |
+| `selector` | 本文を絞り込む CSS セレクタ |
+| `section` | outline で得た section ID。その節の Markdown のみ返す |
+| `page` | ページ番号(既定 1) |
+| `max_tokens` | 1 ページの概算トークン上限(既定 8000) |
+| `force_full` | true で差分応答・定型ブロック除去を無効化し常に全文を返す |
+
+### `links` — リンクを列挙
+| パラメータ | 説明 |
+|---|---|
+| `url` | 起点 URL |
+| `filter` | URL/リンクテキストの部分一致、または `*` を使った glob |
+
+sitemap → RSS/Atom → ページ内リンクの順で探索します。
+
+### `screenshot` — スクリーンショット
+| パラメータ | 説明 |
+|---|---|
+| `url` | 撮影対象 URL(http/https のみ) |
+| `fullPage` | 既定 true。false で最初のビューポート分のみ |
+| `width` | タイル幅 px(既定 1280) |
+| `scale` | 解像度スケール 0.5〜1.0(既定 1.0)。小さいほど画像トークン減 |
+
+## 環境変数
+
+| 変数 | 既定 | 説明 |
+|---|---|---|
+| `AMENBO_CACHE_DIR` | `~/.cache/amenbo` | キャッシュ(SQLite + PNG)の保存先 |
+| `AMENBO_CACHE_TTL_MS` | `900000`(15分) | キャッシュの有効期限 |
+| `AMENBO_MAX_BODY_BYTES` | `20971520`(20MB) | 取得ボディの上限サイズ |
+
+## セキュリティ
+
+- **SSRF 対策** — http/https 以外のスキーム(`file:`, `ftp:` 等)を拒否。DNS 解決した接続先が private / loopback / link-local / 予約アドレスなら拒否。DNS rebinding(TOCTOU)対策として実接続を検証済み IP に固定します
+- **ボディサイズ上限** — 巨大レスポンスによる OOM を防止
+
+## 開発
+
+```bash
+npm run typecheck   # strict 型チェック
+npm test            # vitest
+npm run build       # dist/ へビルド
+```
+
+## ライセンス
+
+[MIT](./LICENSE)

package/dist/adapters/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * adapters/index.ts — J7 国内サイトアダプタの初期セット。
+ *
+ * plan.md指定の初期セット(Qiita/Zenn/note/はてなブログ系/Yahoo!ニュース/PR TIMES)を実装する。
+ * 各セレクタは実際に対象サイトのHTMLを取得して確認済み(2026-07時点)。
+ * サイトのマークアップ変更で機能しなくなった場合は、contentSelectorsが1件もヒットせず
+ * 通常のReadabilityパスへフォールバックする(extract/markdown.ts側の挙動)ため、
+ * アダプタの陳腐化が抽出失敗に直結しない設計になっている。
+ *
+ * 設計判断: plan.mdは「e-Gov等」にも触れているが、e-Govは法令検索という性質上
+ * ページ構造がクエリ毎に大きく異なり単一セレクタでの決定的抽出が難しいため、
+ * Phase 3の初期セットからは見送り、確認が取れた6サイトのみを実装する。
+ *
+ * Phase 4追加: ja.wikipedia.org。Readabilityが記事中の全<h2>-<h6>見出しを剥ぎ落として
+ * しまう(MediaWikiが見出しを`<div class="mw-heading">`等でラップし編集リンクを併記する
+ * 構造をReadabilityの本文整形ロジックが正しく扱えないため)ことを実機検証で確認しており、
+ * アダプタでReadabilityを完全にバイパスすることで見出し構造を保つ(outlineモードの実用性に直結)。
+ */
+import type { SiteAdapter } from "./types.js";
+export declare const SITE_ADAPTERS: SiteAdapter[];
+/** ホスト名(document.location.hostname相当)に一致するアダプタを探す。無ければnull。 */
+export declare function findAdapter(hostname: string): SiteAdapter | null;

package/dist/adapters/index.js

@@ -0,0 +1,51 @@
+export const SITE_ADAPTERS = [
+    {
+        name: "qiita",
+        hostPattern: /(^|\.)qiita\.com$/i,
+        contentSelectors: [".it-MdContent", "article"],
+        notes: "記事本文。.it-MdContentはQiita記法のレンダリング結果。",
+    },
+    {
+        name: "zenn",
+        hostPattern: /(^|\.)zenn\.dev$/i,
+        contentSelectors: [".znc", "article"],
+        notes: "記事本文。.zncはZenn Markdownのレンダリング結果。",
+    },
+    {
+        name: "note",
+        hostPattern: /(^|\.)note\.com$/i,
+        contentSelectors: [".note-common-styles__textnote-body", ".p-article__body", "article"],
+        notes: "note記事本文。textnote-bodyが本文のみに最も絞られたコンテナ。",
+    },
+    {
+        name: "hatenablog",
+        hostPattern: /(^|\.)hatenablog\.com$|(^|\.)hateblo\.jp$/i,
+        contentSelectors: [".entry-content", "article"],
+        removeSelectors: [".hatena-module-ad", ".advertisement-unit"],
+        notes: "はてなブログの記事本文(*.hatenablog.com / *.hateblo.jp)。",
+    },
+    {
+        name: "yahoo-news",
+        hostPattern: /(^|\.)news\.yahoo\.co\.jp$/i,
+        contentSelectors: [".article_body", "article#uamods", "article"],
+        notes: "Yahoo!ニュース個別記事の本文。",
+    },
+    {
+        name: "prtimes",
+        hostPattern: /(^|\.)prtimes\.jp$/i,
+        contentSelectors: ["#press-release-body", "article"],
+        notes: "PR TIMESリリース本文。",
+    },
+    {
+        name: "wikipedia-ja",
+        hostPattern: /(^|\.)ja\.wikipedia\.org$/i,
+        contentSelectors: [".mw-parser-output"],
+        removeSelectors: [".mw-editsection", ".navbox", ".ambox", ".hatnote", ".noprint", ".mw-empty-elt"],
+        notes: "Wikipedia日本語版の本文(MediaWiki出力)。Readabilityが見出しを剥がすため必須のアダプタ。",
+    },
+];
+/** ホスト名(document.location.hostname相当)に一致するアダプタを探す。無ければnull。 */
+export function findAdapter(hostname) {
+    return SITE_ADAPTERS.find((adapter) => adapter.hostPattern.test(hostname)) ?? null;
+}
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C;QACE,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,oBAAoB;QACjC,gBAAgB,EAAE,CAAC,eAAe,EAAE,SAAS,CAAC;QAC9C,KAAK,EAAE,sCAAsC;KAC9C;IACD;QACE,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,mBAAmB;QAChC,gBAAgB,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;QACrC,KAAK,EAAE,mCAAmC;KAC3C;IACD;QACE,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,mBAAmB;QAChC,gBAAgB,EAAE,CAAC,oCAAoC,EAAE,kBAAkB,EAAE,SAAS,CAAC;QACvF,KAAK,EAAE,yCAAyC;KACjD;IACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,4CAA4C;QACzD,gBAAgB,EAAE,CAAC,gBAAgB,EAAE,SAAS,CAAC;QAC/C,eAAe,EAAE,CAAC,mBAAmB,EAAE,qBAAqB,CAAC;QAC7D,KAAK,EAAE,+CAA+C;KACvD;IACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,6BAA6B;QAC1C,gBAAgB,EAAE,CAAC,eAAe,EAAE,gBAAgB,EAAE,SAAS,CAAC;QAChE,KAAK,EAAE,oBAAoB;KAC5B;IACD;QACE,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,qBAAqB;QAClC,gBAAgB,EAAE,CAAC,qBAAqB,EAAE,SAAS,CAAC;QACpD,KAAK,EAAE,iBAAiB;KACzB;IACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,4BAA4B;QACzC,gBAAgB,EAAE,CAAC,mBAAmB,CAAC;QACvC,eAAe,EAAE,CAAC,iBAAiB,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,CAAC;QAClG,KAAK,EAAE,6DAA6D;KACrE;CACF,CAAC;AAEF,+DAA+D;AAC/D,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,IAAI,CAAC;AACrF,CAAC"}

package/dist/adapters/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * adapters/types.ts — J7 国内サイトアダプタの型定義。
+ *
+ * 宣言的なTSオブジェクトでドメイン→本文セレクタを定義する(plan.md記載は「宣言的YAML」だが、
+ * 型チェック・IDE補完の恩恵と外部パーサ追加不要という理由からTSオブジェクトで実装する)。
+ */
+export interface SiteAdapter {
+    /** メタデータ `adapter: <name>` に出力される識別名。 */
+    name: string;
+    /** ホスト名にマッチする正規表現。 */
+    hostPattern: RegExp;
+    /**
+     * 本文として採用するCSSセレクタ候補(先頭から順に試し、最初に要素が見つかったものを使う)。
+     * Readabilityより優先される。
+     */
+    contentSelectors: string[];
+    /** 本文セレクタでマッチした要素の中から、さらに除去するCSSセレクタ(コメント欄・広告枠等)。 */
+    removeSelectors?: string[];
+    /** 補足メモ(保守用、実行時には使わない)。 */
+    notes?: string;
+}

package/dist/adapters/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":""}

package/dist/cache.d.ts

@@ -0,0 +1,90 @@
+export type CacheStatus = "fresh" | "revalidated" | "miss";
+export type ScreenshotCacheStatus = "fresh" | "miss";
+export interface CacheEntry {
+    url: string;
+    etag: string | null;
+    lastModified: string | null;
+    contentHash: string;
+    markdown: string;
+    /** メタデータ(title/finalUrl/tier等)をJSON文字列として保存したものをパースした値。 */
+    metadata: Record<string, unknown>;
+    fetchedAt: number;
+}
+export interface CacheWriteInput {
+    url: string;
+    etag: string | null;
+    lastModified: string | null;
+    markdown: string;
+    metadata: Record<string, unknown>;
+}
+export declare function hashContent(content: string): string;
+/** スクリーンショットのキャッシュキー(url+撮影パラメータの組)を計算する。 */
+export declare function computeScreenshotCacheKey(url: string, width: number, scale: number, fullPage: boolean): string;
+export interface ScreenshotCacheEntry {
+    cacheKey: string;
+    url: string;
+    tilePaths: string[];
+    metadata: Record<string, unknown>;
+    fetchedAt: number;
+}
+export interface ScreenshotWriteInput {
+    cacheKey: string;
+    url: string;
+    tiles: Buffer[];
+    metadata: Record<string, unknown>;
+}
+export declare class PageCache {
+    private readonly db;
+    private readonly cacheDir;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options?: {
+        dbPath?: string;
+        cacheDir?: string;
+        ttlMs?: number;
+        now?: () => number;
+    });
+    /**
+     * M3: TTL超過エントリを削除する(ディスク無制限増加の防止)。起動時に自動実行される。
+     * screenshotsはSQLite行に加え、対応するPNGファイル(タイル)もあわせて削除する。
+     */
+    private pruneExpired;
+    /** 保存済みエントリを取得する(TTL判定は行わない。判定は isFresh を使う)。 */
+    get(url: string): CacheEntry | undefined;
+    /** エントリ(ページ/スクリーンショットいずれも可)がTTL内(再検証不要)かどうかを判定する。 */
+    isFresh(entry: {
+        fetchedAt: number;
+    }): boolean;
+    /** 保存済みスクリーンショットエントリを取得する(TTL判定は isFresh を使う)。 */
+    getScreenshot(cacheKey: string): ScreenshotCacheEntry | undefined;
+    /** スクリーンショットのタイル群をファイル保存し、パスをSQLiteへ記録する。 */
+    setScreenshot(input: ScreenshotWriteInput): ScreenshotCacheEntry;
+    /** 新規取得結果を保存(既存があれば上書き)する。 */
+    set(input: CacheWriteInput): CacheEntry;
+    /** 304再検証成功時: 本文は変えず取得時刻のみ更新する(再変換しない)。 */
+    touch(url: string): void;
+    /** Phase 4テンプレート学習: このページの(除去前・全)ブロックハッシュ集合をドメイン別に記録する。 */
+    recordDomainPageBlocks(domain: string, url: string, blockHashes: string[]): void;
+    /**
+     * 直近recentPages件のページ全てに共通して出現したブロックハッシュを定型ブロック
+     * (ヘッダ/フッタ/定型ナビ等)とみなして返す。まだrecentPages件分のページ履歴が
+     * 無い場合(コールドスタート)は誤除去を避けるため空集合を返す。
+     */
+    getTemplateBlockHashes(domain: string, recentPages?: number): Set<string>;
+    /**
+     * CLI併設対応: ホスト(例 "example.com")の最終リクエスト時刻を返す(未記録ならnull)。
+     * PolitenessManagerのstoreオプションとして注入し、プロセス間でレート制御状態を共有するために使う。
+     */
+    getHostLastRequestAt(host: string): number | null;
+    /**
+     * ホストの最終リクエスト時刻を記録する。
+     *
+     * code-reviewer指摘: MCPサーバー/CLIの複数プロセスが同一ホストへほぼ同時にwaitTurnを
+     * 実行すると、「読み取り→待機→書き込み」の3ステップがプロセス間でアトミックではないため
+     * 後勝ちの書き込みが古い時刻で新しい時刻を上書きし、最小間隔がすり抜けうる
+     * (完全な直列化はプロセス内のみ。プロセス間はベストエフォート。PolitenessManagerの
+     * store JSDoc参照)。せめて時刻が巻き戻らないよう、SQL側でMAXを取って単調増加を保証する。
+     */
+    setHostLastRequestAt(host: string, at: number): void;
+    close(): void;
+}