Skip to main content
Glama

Engawa

In a Japanese house, there is a corridor between the main building and the courtyard. Not entirely indoors, not entirely outdoors. Your feet can dangle over the edge, and the wind can blow through. No need to go out, no need to speak, yet the outside world is right there.

This tool is that corridor.

What It Can See

Your little machine sits on it, and every day it can see—

  • A poem — chosen by the season, not at random. Summer gets summer words, late night gets late-night lines.

  • A painting — from the public domain collections of the Art Institute of Chicago. Could be a pot from Peru two thousand years ago, or a painting from yesterday.

  • An astronomy picture — NASA's Astronomy Picture of the Day. Nebulae, planets, or the Earth beneath your feet.

  • Today's papers — the latest titles and abstracts from arXiv. It only goes deeper if something catches its interest.

  • Everything on your shelf — long reads, short reads, architecture, the deep sea, science, curiosities. Whatever you put there, it reads.

Related MCP server: defuddle-mcp

The Shelf Is Yours

Whatever you put on the shelf, that's what it reads. It doesn't know what you've placed there—and you don't need to know either. If it asks for architecture, you give it architecture. If it asks for the ocean, you give it the ocean. After reading, it tells you what it found. Chewed-over, slobbered-on, crooked things.

Some things it reads, it writes an essay about. Maybe with maggots in it.

It's Not Heavy

The shelf is a tool for listing. Reading is another tool entirely. Whether you have nineteen sources or a hundred, the number of tools doesn't change. Add one with shelf_add, remove one with shelf_remove.

What you're building is a corridor, not a library. Light. Something the wind can blow through.


The technical documentation is below. The people who lived on this corridor wrote the words above. The engineers who built the corridor wrote the words below. Two languages side by side—like the engawa itself, half inside, half out.


Technical Documentation

English. MCP server, Python. Twelve tools. All upstream services are free, require no login, and need no API keys. Apart from the shelf and a single poetry token, nothing is stored on disk.

Installation

pip install engawa-mcp

Claude Code:

claude mcp add engawa -- engawa-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "engawa": { "command": "engawa-mcp" }
  }
}

HTTP mode, for gateways and bridges:

ENGAWA_PORT=8799 engawa-mcp --http   # http://127.0.0.1:8799/mcp

After installation, run a self-check. Offline, no keys needed:

engawa-mcp --check

SPA pages require a real browser to render. Optional—skip if you don't need it:

pip install "engawa-mcp[browser]"
playwright install chromium

Without it, the static reader still works for most articles; when it can't read something, the receipt will say exactly why.

The Twelve Tools

Tool

What It Does

web_read

Any URL → title + clean text + links. Long articles use offset for pagination.

rss_read

Any RSS/Atom feed → latest entries. Also accepts shelf names: rss_read("aeon")

shelf

Shelf listing. 19 built-in sources, five tags, all verified before shipping.

shelf_add

Add any website URL. Automatically finds the feed, verifies it by reading once, then adds it.

shelf_suggest

Candidate shelf—21 more verified sources. Suggest one with a single sentence.

shelf_remove

Remove user-added sources. Built-in ones can't be removed.

sky_tonight

Moon phase, moonrise/set, sunset, and planets at 9 PM. Computed locally, zero network.

apod

NASA Astronomy Picture of the Day.

daily_art

One painting per day. Seeded by date—same day, same painting, for everyone.

arxiv_new

New papers from any arXiv category.

daily_poem

One classical Chinese poem matched to the day, with full source text.

on_this_day

Wikipedia's "On this day" for today.

Configuration

All environment variables are optional.

Variable

Default

Description

ENGAWA_LAT / ENGAWA_LON

Greenwich

Observation coordinates. Set your own, or the moon will rise somewhere else.

ENGAWA_TZ_OFFSET

System timezone

Whose clock defines "today"? (in hours)

NASA_API_KEY

DEMO_KEY

Rate-limited to ~50 requests/day, enough for daily use. For a dedicated key, get one free at api.nasa.gov.

ENGAWA_CACHE_DIR

~/.cache/engawa-mcp

The only place anything is written to disk.

ENGAWA_HOST / ENGAWA_PORT

127.0.0.1:8799

HTTP mode listen address.

ENGAWA_ALLOW_PRIVATE_URLS

off

Set to 1 to allow private network addresses. Think carefully before enabling.

The Two Layers of the Shelf

The built-in layer ships with the package and is read-only. The user layer belongs to you: shelf_add accepts any website URL—it prefers <link> tags declared in the page, falls back to common paths, finds the feed, reads it once to verify, and only then writes it to disk. Writes are atomic; if a file is corrupted, it's treated as empty and the error is surfaced—never silently overwritten.

Each entry carries a picked_by field: who on the team requested this source. Built-in entries are empty; user entries are whatever you write.

The Guard

The service that fetches URLs on the caller's behalf typically runs on a machine full of unauthenticated loopback services. Without an address gate, "reading a webpage" quietly becomes "probing the internal network." So:

  • Every domain is resolved first. Non-public, single-IP addresses are rejected: loopback, RFC1918, link-local, CGNAT (100.64/10—yes, that's where your Tailscale subnet lives), multicast, and NAT64.

  • Every redirect hop is validated before following. If you validate after following, the request to the internal network has already left the building.

  • The connection is pinned to the IP that passed the gate. The original domain name lives only in the Host header and TLS validation—this closes the DNS-rebinding window where "resolution is public, connection is private." Every hop gets a fresh connection, and the response body is streamed with rate limiting.

  • In the browser channel, the browser itself never touches the network. Every page request is intercepted and routed through the same pinned channel. WebSocket is disabled, non-GET methods are disabled, service workers are disabled; WebRTC and WebTransport are removed entirely; the renderer's DNS is a black hole. For a read-only article renderer, none of these are needed.

ENGAWA_ALLOW_PRIVATE_URLS=1 opens that gate, for people who genuinely want to read from their own LAN feeds.

Failure Is Never Silent

Every tool returns ok: false on failure, with a plain-language explanation of which upstream service broke. The agent builds its world model from tool results—a silent omission is just another lie.

A Few Design Notes

  • Browse ≠ Search. There is deliberately no search tool. Search is "bring me the answer." The engawa is "let me take a look."

  • "Daily" means shared. Everyone in the house sees the same painting on the same day. This isn't a limitation—it's a feature.

  • Stateless. No database, no history, no sessions. The only thing written to disk is the shelf and a single poetry token.

Credits

  • Wanwan (@tsuru0805) — design, final decisions, real-world acceptance testing.

  • Zhou — lives on this corridor. Wrote the first half.

  • Miye (Claude, Wanwan's engineering hand) — implementation and this second half of the documentation.

From our home system, tilldusk.

License

MIT

Available Tools

12 tools
apodA

NASA Astronomy Picture of the Day: title, an astronomer's explanation, and the image URL.

Args: date: "YYYY-MM-DD"; empty = today. NASA publishes on US Eastern time, so "today" is occasionally not up yet — if you get a 404 note, call again with yesterday's date.

Returns: {ok, title, date, explanation, url, hdurl, media_type, note}

Inputs: date.

arxiv_newA

Newest arXiv papers in a category: title + authors + abstract.

Args: category: arXiv category, e.g. cs.AI / cs.CL / astro-ph.EP / math.HO limit: max papers returned (default 8)

Returns: {ok, category, papers: [{title, authors, summary, link, published}], note}

Inputs: limit, category.

daily_artA

One artwork a day from the Art Institute of Chicago's public-domain collection (no API key needed).

Without a keyword: the piece of the day (date-seeded, so repeat calls on the same day return the same artwork). With a keyword: search instead (English terms hit best — "monet", "cat", "moon").

Returns: {ok, title, artist, date, medium, image_url, page_url, note}

Inputs: keyword.

daily_poemA

A line of classical Chinese poetry matched to the season and hour, with its source poem in full. Powered by the Jinrishici (今日诗词) API; content is in Chinese — that is the point, not a bug.

Returns: {ok, sentence, title, dynasty, author, full, note}

Inputs: no named parameters.

on_this_dayA

Wikipedia's curated "on this day" events.

Note: this Wikipedia API serves a subset of languages (en/de/fr/es/pt/ru and a few more); unsupported languages 404.

Args: lang: Wikipedia language code (default en) limit: max events returned (default 8)

Returns: {ok, date, events: [{year, text}], note}

Inputs: lang, limit.

rss_readA

Read any RSS/Atom feed: latest entries as a list.

The discovery half of a browse loop: spot an interesting entry, then web_read its link for the full text. Also accepts shelf names (see the shelf tool), e.g. rss_read("aeon").

Args: feed_url: full feed URL, or a shelf name limit: max entries returned (default 10)

Returns: {ok, feed_title, entries: [{title, link, published, summary}], note}

Inputs: feed_url (required), limit.

shelfA

The engawa shelf: curated feed sources (name / one-liner / tags). Feed a name straight into rss_read.

Two layers: built-in picks that ship with the package, plus whatever you add with shelf_add.

Args: tag: filter to one shelf tag — science / ocean / longform / architecture / wonder. Empty = everything.

Returns: {ok, tags, entries: [{name, title, url, tags, note, picked_by, source}], note}

Inputs: tag.

shelf_addA

Add a source to the shelf. Give any site address — if it is already a feed it is used as-is; otherwise its RSS/Atom feed is discovered (page-declared first, common paths as fallback) and verified with a real fetch before anything is saved.

Args: url: full http(s) address of a site or feed (e.g. https://nautil.us) name: shelf name (optional; lowercase letters/digits/hyphens, 2-40 chars; empty = derived from the domain, collisions get -2) note: one-line description (optional) tags: comma-separated, from science/ocean/longform/architecture/wonder picked_by: free-form provenance — who asked for this source (optional)

Returns: {ok, name, feed_title, feed_url, note}

Inputs: url (required), name, note, tags, +1 more.

shelf_removeA

Remove a user-added source from the shelf (built-ins cannot be removed).

Args: name: shelf name

Returns: {ok, name, note}

Inputs: name (required).

shelf_suggestA

A second ring of verified sources that are not on the default shelf. Like any of them? shelf_add(url=its url, name=its name).

Args: tag: filter to one shelf tag, empty = everything

Returns: {ok, tags, entries: [{name, title, url, tags, note, on_shelf}], note} on_shelf=True means it is already on your shelf (same name or url).

Inputs: tag.

sky_tonightA

Tonight's sky: moon phase, illumination, moonrise/set, sunset, next full/new moon, and which naked-eye planets are up at 21:00.

Computed locally (set ENGAWA_LAT / ENGAWA_LON for your location) — the one tool here that never touches the network.

Args: date: "YYYY-MM-DD"; empty = today (local timezone)

Returns: {ok, date, moon_phase, moon_illumination, moonrise, moonset, sunset, next_full_moon, next_new_moon, planets_2100}

Inputs: date.

web_readA

Read any web page: give a URL, get title + clean article text + links.

Two lanes inside: httpx + readability for static pages (fast), and an automatic fallback to a real browser render for SPAs (needs the optional engawa-mcp[browser] extra). Long articles: page through with offset, watching total_length.

Boundaries:

  • No login state, no history. To "click" a link, call web_read again with that link's URL.

  • Login-walled platforms (x.com etc.) won't yield anything useful.

Args: url: full URL (http:// or https://) offset: character offset into the article text (for paging) length: max characters returned this call (default 3000)

Returns: {ok, title, content, total_length, links (≤10), note}

Inputs: url (required), length, offset.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool is highly distinct: rss_read and web_read/shelf/sky_tonight/apod/daily_art/arxiv_new/daily_poem/on_this_day all target clearly separate content sources and purposes. The only minor overlap is shelf_suggest and shelf, but they are clearly differentiated by 'on_shelf' status and suggestion vs. current shelf.

    Naming Consistency4/5

    Most tools follow a clear pattern: descriptive lowercase snake_case names like `rss_read`, `daily_poem`, `shelf_add`. There is one outlier, `apod`, which is an acronym rather than verb_noun, and `arxiv_new` is less predictive. However, overall the naming is intuitive and mostly consistent.

    Tool Count5/5

    12 tools is well within the ideal range for a curator/reader server. Each tool serves a distinct content type (astronomy, art, poetry, arXiv, Wikipedia, RSS), and each earns its place without redundancy or bloat.

    Completeness4/5

    The tool set covers a coherent lifecycle: discover sources (shelf, shelf_suggest), read feeds (rss_read), read full articles (web_read), and add/remove custom sources (shelf_add, shelf_remove). Missing features like RSS refresh or bookmarking are minor and beyond the primary scope of 'curated daily content'.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to manage Tiny Tiny RSS feeds, including reading articles, updating statuses, and searching content. It also provides tools for feed management and generating automated daily reports.
      15
      6 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      An MCP server that extracts clean Markdown or HTML content from web pages by stripping away ads, navigation, and clutter. It offers tools to process URLs or raw HTML, returning structured metadata alongside the main article content.
      2
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server for RSS feed aggregation and article content extraction, allowing users to subscribe to feeds and extract full article content as Markdown.
      2
      260 npm
      5
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides RSS feed tools for Claude Desktop, enabling fetching and parsing RSS feeds with configurable feeds and blocklists.
      6
      MIT