amenbo

amenbo 🐜💧

English | 日本語

轻掠网页，不惊起波澜 — 一款原生适配日语网站的 MCP 服务，以低影响、节省 token 的方式采集网页：通过大纲→分节渐进式披露和仅获取差异的重新抓取，让上下文保持精简。

amenbo（アメンボ / 水黾）是一款面向 Claude Code、Codex 等编码 Agent 的 MCP 服务。它像在水面上滑行、不激起波澜的昆虫一样，以较低负载、较少 token 从 Web 收集信息。尤其针对日语网站进行了优化。没有 MCP 客户端的 shell 环境也可以将其作为 CLI 使用，共享同一核心（参见作为 CLI 使用）。

为什么选择 amenbo

许多通用抓取工具都是以英语 Web 为前提构建的，在日语网站上往往会出现以下信息遗漏。amenbo 可应对这些问题。

• 结构松散的网站：即使是有大量 div 嵌套或表格布局的日语网站，也能根据渲染结果的几何信息（视觉布局）推断正文区域
• 乱码：自动检测 Shift_JIS / EUC-JP / ISO-2022-JP
• 振假名：移除 <ruby> 中的振假名，避免正文内容重复
• 以图像呈现的信息：对于图片格式的价目表或以横幅为主的页面，如果文本提取质量较差，就会自动切换为截图
• 表格缺失或错乱：正文提取时，高链接密度的数据表（例如比较表）可能会整个丢失；amenbo 会检测并将此类表格还原到原来的位置。保留在正文中的表格也会对 colspan/rowspan 和多层表头进行规范化，防止列错位
• 标题消失：对于标题被带编辑链接的包装元素包裹的页面（例如 Wiki 类网站），正文提取时标题结构可能会整个丢失；amenbo 会检测仍有正文内容的章节标题，并将其还原到原来的位置（确保 outline / section 渐进式披露稳定运行）
• 日本主要网站：为 Qiita / Zenn / note / はてなブログ / Yahoo!ニュース / PR TIMES 提供专用适配器

与类似工具（官方 fetch MCP / Jina Reader / Playwright MCP / PixelRAG pixelshot）的实际测评对比，请参阅文章「エージェントのWeb取得、ツール次第でトークンが5000倍違った話」。测试框架和原始日志位于 bench/。

节省 token 的机制

• 渐进式披露：先通过 mode: outline 仅返回标题树和各章节的 token 数量，再通过指定 section 获取所需章节。无需将超长页面整体灌入上下文
• 支持 CJK 的正文精简：根据标点密度、字符类型比例和链接密度移除导航、广告和页脚
• 差异响应：重新获取已抓取过的 URL 时，如果没有变化则返回 unchanged；如果有变化，则仅返回发生变化的章节
• 自动切换 Markdown / 图像：仅将质量评分较低的页面转为截图，避免先读取损坏的 Markdown、再往返重新抓取
• 按字符类型估算 token：日语、韩语、西里尔文字、表情符号等字符的 token 成本比英语更高，因此会使用按字符类别划分的系数（经实测校准）计算页面拆分预算

降低对目标网站的负载

• 两阶段抓取：首先使用普通 HTTP GET。只有需要 JS 渲染的页面才会升级为 headless Chromium，因此大多数抓取都不会启动浏览器
• 礼貌的爬虫：遵守 robots.txt 和 Crawl-Delay；对同一域名串行抓取，默认每秒 1 个请求（获取 robots.txt 也计为这 1 个请求）。列举链接时优先使用 sitemap / RSS，不会逐页遍历
• 如实声明 User-Agent：明确标示自身是机器人。不会实现反反爬虫
• 缓存：使用 ETag / If-Modified-Since 重新验证，避免不必要的重复抓取。默认有效期为 15 分钟（AMENBO_CACHE_TTL_MS），且只会按延长方向采纳 Cache-Control（如果 max-age 长于 15 分钟则采用其值，上限为 24 小时；不保存 no-store）。不会通过 max-age=0 或 no-cache 缩短有效期——实测发现主要网站大多都声明了这些指令；如果遵从，每次调用工具都会重新抓取，低负载这一前提也就无法成立

安装

npm install -g amenbo

Markdown 获取（常规 fetch / links）只需此步骤即可使用。只有在需要通过浏览器（Chromium）获取内容时，例如升级处理需要 JS 渲染的 SPA 或截取屏幕截图，才需要首次运行一次（约下载 170MB）：

npx -y amenbo install-browser

或用于开发：

git clone https://github.com/Rererr/amenbo.git
cd amenbo
npm install
npm run build

注册到 MCP 客户端

Claude Code（--scope user 适用于所有项目；如果只用于单个项目，请去掉此参数）：

claude mcp add --scope user amenbo -- amenbo

Codex CLI：

codex mcp add amenbo -- amenbo

VS Code：

code --add-mcp '{"name":"amenbo","command":"amenbo"}'

对于其他客户端（Cursor / Cline 等），请在相应客户端的 MCP 设置中（Cursor：~/.cursor/mcp.json，Cline：MCP Servers 界面的 settings JSON）添加以下条目：

{
  "mcpServers": {
    "amenbo": {
      "command": "amenbo"
    }
  }
}

如果要避免全局安装，请指定 "command": "npx", "args": ["-y", "amenbo"]；如果要使用本地构建版本，请指定 "command": "node", "args": ["/path/to/amenbo/dist/server.js"]。

通过 stdio 可同时响应 MCP 2026-07-28（无状态核心）和 2025 系列的协议。无论客户端使用哪个版本，都可以使用上述设置连接。

教会 Agent 如何使用（推荐提示词）

仅靠工具定义，无法传达“通过渐进式披露获取”等使用方法。将以下内容复制到 CLAUDE.md 或 AGENTS.md 中，Agent 就能高效使用 amenbo。

## 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 対策による取得失敗は仕様(回避しない)。失敗はそのままユーザーに報告する

也可以不写入 CLAUDE.md，而仅在当前会话中加载。支持 MCP 提示词的客户端可以从服务端获取相同的使用说明，作为 usage 提示词提供（在 Claude Code 中为 /mcp__amenbo__usage）。

CLIとして使う

amenbo は MCP サーバーと同一のコア(取得、キャッシュ、politeness、抽出ロジック)を共有する CLI としても動作します。引数なし、または amenbo serve は従来通り MCP サーバーとして起動する(.mcp.json の "command": "amenbo" はそのまま動きます)ので、既存の MCP 登録には影響しません。

# ページを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 のみ返す(祖先見出しがあれば応答に section_path(› 区切りのパンくず)を付与)
page	ページ番号(既定 1)
max_tokens	1 ページの概算トークン上限(既定 8000)
force_full	true で差分応答・定型ブロック除去を無効化する(max_tokens によるページ分割は従来通り働く)

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 を防止

既知の制限

• 本文抽出は日本語チューニング：段階開示・キャッシュ・低負荷は言語非依存で、非日本語サイトでも動きます。ただし本文抽出のヒューリスティックは日本語ページで調整しているため、非日本語ページで本文が欠けて見えるときは selector 指定か mode: "screenshot" で取り直してください
• HTTP プロキシ非対応：HTTP_PROXY / HTTPS_PROXY 等の環境変数は尊重しません。SSRF 対策として接続先を検証済み IP に固定する設計(DNS rebinding 対策)と、プロキシへ名前解決を委ねる方式が両立しないためです。上流プロキシ必須のネットワークでは現状ご利用いただけません
• anti-bot 回避は実装しません：robots.txt 拒否やボット対策による取得失敗は仕様です。失敗はそのまま報告します(収集先への低負荷参照)

開発

clone 後に1回、秘密情報検査（gitleaks）の pre-commit フックを有効化する:

git config core.hooksPath githooks

npm run typecheck   # strict 型チェック
npm test            # vitest
npm run build       # dist/ へビルド

引用

記事や研究で参照する場合は Zenodo の DOI を使ってください。上のバッジの 10.5281/zenodo.21553636 は全バージョン共通の Concept DOI で、常に最新版へ解決されます。特定の版を指す場合は、その版の DOI を Zenodo のレコードから取得してください。

機械可読な引用情報は CITATION.cff にあります(GitHub の "Cite this repository" から BibTeX / APA を生成できます)。

ライセンス

MIT