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.

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

Configuration

All environment variables are optional.

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