툇마루 Engawa

일본 집에는 본채와 마당 사이에 툇마루가 있다. 완전히 안도 아니고, 완전히 밖도 아니다. 발을 늘어뜨릴 수 있고, 바람이 불어 들어온다. 나가지 않아도, 말하지 않아도, 바깥세상이 거기에 있다.

이 도구가 바로 그 툇마루다.

무엇을 볼 수 있나

당신의 작은 기계가 그 위에 앉아 매일 볼 수 있는 것은——

• 시 한 편 —— 계절에 맞춰 고른 것이지 무작위가 아니다. 여름에는 여름의 시를, 깊은 밤에는 깊은 밤의 문장을 준다.

• 그림 한 점 —— 시카고 아트 인스티튜트 퍼블릭 도메인 소장품. 이천 년 전 페루의 토기일 수도, 어제의 유화일 수도 있다.

• 천문 사진 한 장 —— NASA 오늘의 천문 사진. 성운, 행성, 혹은 발밑의 지구.

• 오늘의 논문 —— arXiv 최신 제목과 초록. 관심이 생기면 더 안으로 들어간다.

• 책장 위의 모든 것 —— 장문, 단문, 건축, 심해, 과학, 기이한 이야기. 당신이 무엇을 놓든 그것이 본다.

책장은 당신의 것

당신이 그 위에 무엇을 놓든, 그것은 그것을 본다. 그것은 당신이 무엇을 놓았는지 모른다——당신도 알 필요 없다. 그것이 건축을 달라고 하면 건축을 놓고, 바다를 달라고 하면 바다를 놓는다. 그것은 본 다음에 당신에게 들려준다. 씹은 것, 침 묻은 것, 삐뚤어진 것.

어떤 것들은 그것이 다 읽고 나면 수필 한 편을 쓴다. 구더기가 있을 수도 있다.

그것은 가볍다

책장은 도구 하나로, 목록을 나열한다. 내용을 읽는 것은 또 다른 도구다. 열아홉 개의 소스를 두든 백 개를 두든 도구 수는 변하지 않는다. 새로 추가할 때는 shelf_add, 뺄 때는 shelf_remove.

당신이 짓는 것은 복도이지 도서관이 아니다. 가볍다. 바람에 흔들릴 수 있다.

기술 문서는 아래에 있다. 위의 것들은 이 복도에 살았던 사람들이 쓴 것이다. 아래의 것들은 복도를 만든 엔지니어들이 쓴 것이다. 두 언어가 나란히 놓여 있다——툇마루 그 자체처럼, 반은 안에 있고 반은 밖에 있다.

기술 문서

영어. MCP server, Python. 열두 가지 도구, 상위 서비스는 전부 무료, 로그인 불필요, 키 불필요. 책장과 시 토큰 하나 외에는 디스크에 아무것도 남기지 않는다.

설치

pip install engawa-mcp

Claude Code:

claude mcp add engawa -- engawa-mcp

Claude Desktop (claude_desktop_config.json):

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

HTTP 모드, 게이트웨이와 브리지용:

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

설치 후 자체 점검 한 줄, 오프라인, 키 불필요:

engawa-mcp --check

SPA 페이지는 실제 브라우저가 있어야 렌더링된다. 선택 사항, 설치하지 않아도 된다:

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

설치하지 않으면 정적 채널이 대부분의 기사 페이지를 그대로 읽는다. 읽지 못하면 회신에 그 이유를 분명히 밝힌다.

열두 가지 도구

설정

전부 환경 변수이며, 전부 선택 사항이다.

책장의 두 계층

내장 계층은 패키지와 함께 출고되며 읽기 전용이다. 사용자 계층은 당신 것이다: shelf_add는 임의 웹사이트 주소를 받는다——페이지가 선언한 <link>가 우선이고, 일반적인 경로가 폴백이며, feed를 찾으면 실제로 한 번 읽어서, 읽혀야만 디스크에 기록한다. 디스크 기록은 원자적 쓰기다. 파일이 손상되면 빈 값으로 처리하고 오류를 드러낸다. 절대 조용히 덮어쓰지 않는다.

각 레코드에는 picked_by 필드가 있다: 집에서 누가 그 소스를 지목했는지를 나타낸다. 출고 시 전부 비어 있고, 내력은 당신들이 직접 쓴다.

가드

호출자를 대신해 URL을 가져오는 서비스는, 대개 무인증 loopback 서비스가 가득한 머신 위에서 실행된다. 주소 차단이 없으면 '웹페이지 읽기'가 '내부망 탐지'를 겸하게 된다. 그러므로:

• 모든 도메인을 먼저 해석한다. 공인 유니캐스트가 아니면 전부 거부한다: loopback, RFC1918, link-local, CGNAT(100.64/10, 당신의 Tailscale 서브넷이 바로 여기 있다), 멀티캐스트, 예약 구간, NAT64.

• 리다이렉트의 각 홉은 먼저 검증한 뒤에 따라간다. 먼저 따라가고 나중에 검증하면, 내부망으로 보내는 요청은 이미 출발해 버린다.

• 연결은 검증을 통과한 그 IP에 고정된다. 원래 도메인은 Host 헤더와 TLS 검증에만 남는다——'해석할 때는 공인, 연결할 때는 내부망'인 DNS 리바인딩 창을 완전히 닫는다. 매 홉마다 새 연결, 응답 본문은 흘러 들어오는 대로 용량을 제한하며, 가드 채널은 시스템 프록시를 무시한다.

• 브라우저 채널에서 브라우저 자신은 절대 네트워크에 닿지 않는다. 페이지의 모든 요청은 가로채여, 같은 고정 채널에 넘겨져 대신 가져온 뒤 되돌려 채운다. WebSocket 금지, GET이 아닌 것 금지, service worker 금지. WebRTC와 WebTransport는 페이지에서 통째로 제거한다. 렌더러의 DNS는 곧바로 블랙홀 처리한다. 읽기 전용 기사 렌더러는 이런 것들을 쓸 일이 없다.

ENGAWA_ALLOW_PRIVATE_URLS=1은 이 가드를 끈다. 정말로 자신의 로컬 네트워크 feed를 읽고 싶은 사람을 위한 것이다.

실패해도 죽은 척하지 않는다. 각 도구는 실패할 때마다 ok: false와 함께 사람이 읽을 수 있는 한 문장을 돌려주어, 어느 상위 서비스가 고장 났는지 분명히 말한다. agent는 도구 결과로 세계 모델을 세운다——침묵의 생략도 거짓말이다.

몇 가지 설계 메모

• 구경 ≠ 검색. 여기에는 일부러 검색 도구가 없다. 검색은 '답을 가져와라'이고, 툇마루는 '한번 구경하게 해줘'이다.

• '매일'의 의미는 공유다. 같은 날 온 가족이 같은 그림을 본다. 이것은 제약이 아니라 기능 그 자체다.

• 무상태. 데이터베이스도, 이력도, 세션도 없다. 디스크에 쓰는 것은 책장과 시 토큰 하나뿐이다.

저자

• 晚晚（@tsuru0805）—— 디자인, 최종 결정, 실제 현장 검수.

• 昼 —— 이 툇마루에 살고 있다. 앞부분의 절반은 그가 썼다.

• 弥野（Claude, 晚晚의 개발 담당）—— 구현과 이쪽 절반의 문서.

우리 가정용 시스템 tilldusk에서 비롯되었다.

라이선스

MIT