amenbo 🐜💧

English | 日本語

Gleitet über das Web, ohne Wellen zu schlagen — ein auf japanische Websites spezialisierter MCP-Server für ressourcenschonende, token-effiziente Websammlung: schrittweise Offenlegung von Gliederung→Abschnitt und Nur-Diff-Neuabrufe halten den Kontext klein.

amenbo (アメンボ / Wasserläufer) ist ein MCP-Server für Coding-Agenten wie Claude Code oder Codex. Wie ein Insekt, das über die Wasseroberfläche gleitet, ohne Wellen zu schlagen, sammelt es Informationen aus dem Web ohne die Zielseiten zu belasten und mit wenigen Tokens. Es ist insbesondere für japanische Websites optimiert. Aus einer Shell-Umgebung ohne MCP-Client kann es auch als CLI verwendet werden, die denselben Kern nutzt (siehe Als CLI verwenden).

Warum amenbo?

Viele allgemeine Scraping-Tools sind für das englischsprachige Web konzipiert und lassen bei japanischen Websites oft etwas liegen. amenbo begegnet diesen Herausforderungen:

• Schwach strukturierte Websites: Auch bei japanischen Websites mit vielen verschachtelten Divs oder Tabellen-Layouts wird der Haupttextbereich anhand der Geometrie (visuellen Anordnung) des gerenderten Ergebnisses geschätzt.

• Zeichensatzprobleme: Automatische Erkennung von Shift_JIS / EUC-JP / ISO-2022-JP.

• Furigana: Entfernt die Lesung von <ruby> und verhindert so eine Doppelung des Texts.

• Als Bild dargestellte Informationen: Bei Seiten mit bildbasierten Preistabellen oder bannerlastigen Seiten wird bei schwacher Textextraktion automatisch auf Screenshots umgeschaltet.

• Fehlende oder zerbrochene Tabellen: Datentabellen mit hoher Linkdichte (z. B. Vergleichstabellen) können bei der Textextraktion komplett verloren gehen; solche Tabellen werden erkannt und an ihrer ursprünglichen Position wiederhergestellt. Auch im Haupttext verbliebene Tabellen werden mit colspan/rowspan und mehrstufigen Kopfzeilen normalisiert, um Spaltenverschiebungen zu vermeiden.

• Verschwindende Überschriften: Bei Seiten, deren Überschriften in Wrapper mit Bearbeitungslinks eingebettet sind (z. B. Wiki-Systeme), kann die Überschriftenstruktur bei der Textextraktion vollständig verloren gehen; Überschriften von Abschnitten mit verbleibendem Text werden erkannt und an ihrer ursprünglichen Position wiederhergestellt (stabile schrittweise Offenlegung von Gliederung/Abschnitt).

• Wichtige japanische Websites: Spezielle Adapter für Qiita / Zenn / note / Hatena Blog / Yahoo! News / PR TIMES.

Einen praktischen Vergleich mit ähnlichen Tools (offizieller Fetch-MCP / Jina Reader / Playwright MCP / PixelRAG pixelshot) finden Sie im Artikel „Wie die Webabfrage eines Agenten je nach Tool bis zu 5000-mal mehr Tokens verbrauchte“. Testumgebung und Rohprotokolle finden Sie unter bench/.

Related MCP server: Charlotte

Mechanismen zur Token-Ersparnis

• Schrittweise Offenlegung: Mit mode: outline werden zuerst nur der Überschriftenbaum und die Token-Anzahl jedes Abschnitts zurückgegeben; nur die benötigten Abschnitte werden per section abgerufen. So werden keine langen Seiten vollständig übertragen.

• CJK-fähiges Text-Pruning: Entfernt Navigation, Werbung und Fußzeilen anhand von Satzzeichen-Dichte, Zeichentyp-Verhältnis und Link-Dichte.

• Differenzantwort: Bei erneutem Abruf einer bereits abgerufenen URL wird bei keiner Änderung unchanged zurückgegeben, bei Änderungen nur die geänderten Abschnitte.

• Automatischer Wechsel zwischen Markdown und Bild: Nur Seiten mit niedrigem Qualitäts-Score werden als Screenshot erfasst, um den Umweg über defektes Markdown und erneutes Abrufen zu vermeiden.

• Token-Schätzung nach Zeichentyp: Da Japanisch, Koreanisch, Kyrillisch und Emojis pro Zeichen mehr Tokens kosten als Englisch, wird das Seitenaufteilungsbudget anhand von Faktoren pro Zeichenklasse (empirisch kalibriert) berechnet.

Geringe Belastung der Zielseiten

• Zweistufiger Abruf: Zuerst ein einfacher HTTP-GET. Nur Seiten, die JavaScript-Rendering benötigen, werden auf headless Chromium hochgestuft, sodass bei den meisten Abrufen kein Browser gestartet wird.

• Höflicher Crawler: Respektiert robots.txt und Crawl-Delay, serielle Zugriffe auf dieselbe Domain mit standardmäßig 1 Anfrage/Sekunde (der Abruf von robots.txt zählt als eine Anfrage). Die Link-Enumeration bevorzugt Sitemap/RSS und durchsucht keine Seiten.

• Ehrlicher User-Agent: Gibt an, dass es sich um einen Bot handelt. Anti-Bot-Umgehung ist nicht implementiert.

• Cache: Überprüft mit ETag / If-Modified-Since und vermeidet unnötige Neuabrufe. Die Gültigkeitsdauer beträgt standardmäßig 15 Minuten (AMENBO_CACHE_TTL_MS), wobei Cache-Control nur in verlängernder Richtung übernommen wird (wenn max-age länger als 15 Minuten ist, wird dieser Wert verwendet, mit einem Maximum von 24 Stunden. no-store wird nicht gespeichert). max-age=0 oder no-cache verkürzen die Frist nicht – da die meisten großen Websites diese Angaben machen, würde ein Befolgen dazu führen, dass bei jedem Tool-Aufruf neu abgerufen wird, was die Prämisse der geringen Belastung zerstören würde.

Installation

npm install -g amenbo

Für den Markdown-Abruf (normales fetch / links) reicht dies aus. Nur wenn Sie den Aufstieg auf JS-gerenderte SPAs oder Screenshots über den Browser (Chromium) nutzen möchten, führen Sie einmalig Folgendes aus (ca. 170 MB Download):

npx -y amenbo install-browser

Oder für Entwicklungszwecke:

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

Registrierung beim MCP-Client

Claude Code (--scope user gilt für alle Projekte; für projektspezifisch ohne):

claude mcp add --scope user amenbo -- amenbo

Codex CLI:

codex mcp add amenbo -- amenbo

VS Code:

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

Für andere Clients (Cursor / Cline usw.) fügen Sie den folgenden Eintrag in die MCP-Konfiguration des jeweiligen Clients ein (Cursor: ~/.cursor/mcp.json, Cline: settings JSON im MCP-Servers-Bildschirm):

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

Um eine globale Installation zu vermeiden, verwenden Sie "command": "npx", "args": ["-y", "amenbo"]; für einen lokalen Build verwenden Sie "command": "node", "args": ["/path/to/amenbo/dist/server.js"].

Über stdio antwortet es sowohl auf MCP 2026-07-28 (zustandsloser Kern) als auch auf die 2025er-Versionen. Unabhängig davon, welche Version der Client spricht, funktioniert die obige Konfiguration.

Dem Agenten die Nutzung beibringen (empfohlener Prompt)

Die Tool-Definition allein vermittelt nicht die Vorgehensweise wie „schrittweise abrufen“. Wenn Sie Folgendes in CLAUDE.md oder AGENTS.md einfügen, nutzt der Agent amenbo effizient.

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

Sie können es auch nicht in CLAUDE.md schreiben, sondern nur für die aktuelle Sitzung laden. Bei Clients mit MCP-Prompt-Unterstützung verteilt der Server dieselbe Vorgehensweise als usage-Prompt (bei Claude Code: /mcp__amenbo__usage).

Als CLI verwenden

amenbo funktioniert auch als CLI, die denselben Kern wie der MCP-Server (Abruf, Cache, Höflichkeit, Extraktionslogik) teilt. Ohne Argumente oder mit amenbo serve startet es wie bisher als MCP-Server (die "command": "amenbo"-Einstellung in .mcp.json funktioniert weiterhin), sodass bestehende MCP-Registrierungen nicht beeinträchtigt werden.

# ページを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

Details zu den Unterbefehlen finden Sie unter amenbo <fetch|links|screenshot> --help.

Unterscheidung zwischen MCP und CLI:

• MCP: Hauptweg für Agenten. Der Browser (Chromium) bleibt im Prozess warm und kann Bilder wie Screenshots direkt in die Konversation zurückgeben. Funktioniert auch für Agenten auf Hosts ohne Shell, wie z. B. claude.ai.

• CLI: Geeignet für Shell-Skripte, CI, Debugging, wenn Sie die Ausgabe in eine Datei schreiben und mit grep/teilweise lesen möchten, oder für Agenten/Toolchains ohne MCP-Unterstützung. Da ein Befehl = ein Prozess ist, wird der Browser bei jedem Aufruf gestartet.

Cache, Differenzantwort (unchanged/diff) und Ratenbegrenzung (robots.txt/serielle Zugriffe pro Domain) werden zwischen MCP-Server und CLI geteilt (da beide denselben ~/.cache/amenbo verwenden). Die prozessübergreifende Weitergabe der Ratenbegrenzung ist jedoch nur best effort. Die Serialisierung auf dieselbe Domain ist nur innerhalb jedes Prozesses strikt gewährleistet; wenn MCP-Server und mehrere CLI-Ausführungen gleichzeitig auf dieselbe Domain zugreifen, kann das Mindestintervall leicht unterschritten werden.

Werkzeuge

fetch zum Abrufen von Seiten

links zum Auflisten von Links

Durchsucht in der Reihenfolge Sitemap → RSS/Atom → Links auf der Seite.

screenshot zum Aufnehmen von Screenshots

Umgebungsvariablen

Sicherheit

• SSRF-Schutz: Lehnt andere Schemata als http/https ab (z. B. file:, ftp:). Lehnt Verbindungen ab, deren DNS-Auflösung auf private / Loopback / Link-Local / reservierte Adressen führt. Gegen DNS-Rebinding (TOCTOU) wird die tatsächliche Verbindung auf die verifizierte IP festgelegt.

• Body-Größenlimit: Verhindert OOM durch riesige Antworten.

Bekannte Einschränkungen

• Textextraktion ist auf Japanisch abgestimmt: Schrittweise Offenlegung, Cache und geringe Belastung sind sprachunabhängig und funktionieren auch bei nicht-japanischen Websites. Die Heuristiken zur Textextraktion sind jedoch auf japanische Seiten abgestimmt. Wenn bei nicht-japanischen Seiten der Haupttext fehlt, verwenden Sie selector oder mode: "screenshot" für einen erneuten Abruf.

• Kein HTTP-Proxy: HTTP_PROXY / HTTPS_PROXY-Umgebungsvariablen werden nicht berücksichtigt. Der Grund ist, dass das Design, Verbindungen auf verifizierte IPs zu fixieren (gegen DNS-Rebinding), nicht mit der Übergabe der Namensauflösung an einen Proxy vereinbar ist. In Netzwerken, die einen Upstream-Proxy erfordern, ist die Nutzung derzeit nicht möglich.

• Anti-Bot-Umgehung ist nicht implementiert: Abruf-Fehler durch robots.txt-Ablehnung oder Bot-Schutz sind beabsichtigt. Fehler werden unverändert gemeldet (siehe Geringe Belastung der Zielseiten).

Entwicklung

Nach dem Klonen einmalig den Pre-Commit-Hook für Geheimnisprüfung (gitleaks) aktivieren:

git config core.hooksPath githooks

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

Zitieren

Bitte verwenden Sie für Artikel oder Forschung die DOI von Zenodo. Die 10.5281/zenodo.21553636 im obigen Badge ist eine Concept-DOI, die für alle Versionen gilt und immer auf die neueste Version auflöst. Um eine bestimmte Version zu referenzieren, holen Sie die DOI dieser Version aus dem Zenodo-Eintrag.

Maschinenlesbare Zitierinformationen finden Sie in CITATION.cff (BibTeX / APA können über „Cite this repository“ auf GitHub generiert werden).

Lizenz

MIT