Engawa 縁側

Get Your Website Agent-Ready.

The open toolkit for agent-native websites. Bring your agent.

In traditional Japanese architecture, an engawa (縁側) is the narrow transitional space running between the interior of a building and the outside — often between rooms and a garden. It is neither fully inside nor fully outside: it is a threshold that connects the two.

Engawa brings that idea to the web. It exposes the same human-public information your site already shows people through clean, bounded agent-facing representations—and optional read-only retrieval interfaces.

Agents can read HTML. Browser pages are optimized for people: layout, navigation, scripts, cookie banners, and presentation markup often surround the public prose an agent actually needs. Engawa does not claim HTML is unreadable. It offers a cleaner, smaller, more deterministic representation of the same public content, with explicit corpus boundaries you control.

Agent-ready means an agent can retrieve the site's intended public content through deterministic machine-readable representations—without relying only on reverse-engineering browser presentation.

Engawa makes your website agent-ready. It adds intentional machine-readable surfaces alongside your existing human website—structured public content, Markdown, MCP, and Bring Your Agent UX—while you keep control of what is exposed.

One website. Two first-class interfaces: HTML for people, structured interfaces for agents—not because HTML is unreadable, but because both audiences deserve an appropriate surface.

Engawa does not replace your website. Engawa does not replace your CMS. Engawa does not add another proprietary chatbot. Engawa does not replace schema.org, sitemaps, robots.txt, or OpenAPI where those already solve your problem. Engawa gives the existing website a deliberate agent interface.

What Engawa does

With Engawa, your website can:

• Expose the same public content through clean, intentional agent-facing documents instead of relying only on full browser HTML retrieval.

• Publish explicit machine-readable entry points such as llms.txt and Markdown metadata. Consumer support varies; Engawa does not assume automatic discovery.

• Expose structured content as deterministic Markdown resources (additive to HTML, not a replacement).

• Offer a safe public MCP interface for resource listing, reading, and bounded search_site when agents are explicitly connected.

• Support Bring Your Agent so visitors can use the AI tool they already trust.

• Stay under your control — your adapter defines the public corpus and Engawa is read-only by default.

Discovery note: Publishing an agent surface does not guarantee a particular AI provider will automatically discover, fetch, or use it. SURFACE EXISTS ≠ SURFACE FETCHED ≠ SURFACE USED ≠ OUTPUT IMPROVED. Measure provider behavior rather than assuming it.

Engawa runtime does not phone home. The Distribution Map product is discontinued (distribution-map.md).

See Do you need Engawa? if you are deciding whether to adopt Engawa at all.

Related MCP server: webserver-mcp

Agent surfaces

flowchart TB
  subgraph site [YourWebsite]
    human[HumanRoutes_HTML]
    engawaLayer[EngawaIntegration]
  end
  subgraph agentSurface [AgentInterface]
    md[MarkdownRoutes]
    llms[llms.txt]
    mcp[MCP_read_only]
    bya[BringYourAgent_UI]
  end
  human --> visitors[HumanVisitors]
  engawaLayer --> md
  engawaLayer --> llms
  engawaLayer --> mcp
  engawaLayer --> bya
  md --> agents[VisitorAgents]
  llms --> agents
  mcp --> agents
  bya --> agents

5-minute quick start (npm)

This uses published packages from the public npm registry—not a clone of this monorepo.

Requirements: Node.js 24+.

npm install \
  @thierry-gilgen-ict/engawa-core@0.1.1 \
  @thierry-gilgen-ict/engawa-discovery@0.2.0 \
  @thierry-gilgen-ict/engawa-mcp@0.1.1

import {
  createEngawa,
  StaticContentAdapter,
  validateEngawaConfig,
} from "@thierry-gilgen-ict/engawa-core";
import { generateLlmsTxt } from "@thierry-gilgen-ict/engawa-discovery";
import { createEngawaPublicMcpHandler } from "@thierry-gilgen-ict/engawa-mcp";

const config = validateEngawaConfig({
  site: {
    name: "My Site",
    canonicalUrl: "https://www.example.com",
    description: "A small public website with an agent interface.",
    language: "en",
  },
  agentInterface: { enabled: true, public: true },
  security: { publicDefault: "read-only" },
  metadata: { version: "0.1.1" },
});

const adapter = new StaticContentAdapter(config.site.canonicalUrl, [
  {
    id: "about",
    title: "About",
    path: "/about.md",
    content: "# About\n\nPublic about page content.",
  },
  {
    id: "services",
    title: "Services",
    path: "/services.md",
    content: "# Services\n\nWhat we offer.",
  },
]);

const engawa = createEngawa(config, adapter);

// llms.txt body
const resources = await engawa.listResources();
const llmsTxt = generateLlmsTxt(engawa.config, resources);

// MCP handler — wire to your HTTP route (see complete example below)
const mcpHandler = createEngawaPublicMcpHandler(engawa);
// return mcpHandler.fetch(request);

Wire llmsTxt to GET /llms.txt and MCP to /mcp with host guards and rate limits. Complete Next.js App Router example: docs/examples/nextjs-mcp-app-router.md. See also Getting started and Next.js integration.

React UI (optional):

npm install @thierry-gilgen-ict/engawa-react@0.1.0 react react-dom

See @thierry-gilgen-ict/engawa-react.

Packages

Not shipped: engawa-nextjs. Next.js sites integrate via documented patterns—see docs/integrations/nextjs.md. Operator-local observability is a recipe (not an npm package)—see docs/observability.md.

npm install @thierry-gilgen-ict/engawa-cli@0.1.0

See @thierry-gilgen-ict/engawa-cli.

Production examples

Both sites run Engawa from npm packages with site-specific adapters (no Engawa core forks).

Details: docs/production-references.md.

Bring Your Agent

Engawa's React components implement provider-neutral connection UX:

• ChatGPT

• Claude

• Grok

• Cursor

• Other MCP client (canonical fallback)

Engawa does not claim one-click remote MCP setup for every provider. When a vendor has no documented deep link, the UI offers copy actions, setup instructions, and generic MCP—see provider capability matrix.

Provider availability and setup can vary by provider plan, workspace policy, and product version. See capability matrix.

Security defaults

PUBLIC · READ-ONLY · NO MUTATIONS BY DEFAULT

• Public MCP exposes only resources your adapter registers.

• v0.1 ships one public tool: search_site (bounded query and results).

• No unauthenticated write tools, no env/secret access, no arbitrary filesystem reads.

Critical integration rule: Engawa's public corpus must match what anonymous human visitors see—not merely what exists in a CMS or database. See Content publication rule.

Full model: docs/security-model.md.

Status

• Current npm registry: @thierry-gilgen-ict/engawa-core@0.1.1, @thierry-gilgen-ict/engawa-discovery@0.2.0, @thierry-gilgen-ict/engawa-mcp@0.1.1, @thierry-gilgen-ict/engawa-react@0.1.0, @thierry-gilgen-ict/engawa-cli@0.1.0.

• Early v0.x foundation on npm; packages may diverge by semver; API may change before 1.0.

• Node.js 24+ required for published packages.

• Two production reference integrations on Next.js (see above).

• Public read-only MCP only in v0.1 — no authenticated or mutating MCP shipped.

• Engawa runtime does not phone home.

• Distribution Map is discontinued — registry offline; @thierry-gilgen-ict/engawa-map is deprecated on npm. Historical policy: distribution-map.md.

Public announcement blurb: ANNOUNCE.md. Security: SECURITY.md.

Monorepo development

Clone this repository to work on Engawa itself or run the included example:

pnpm install
pnpm build
pnpm --filter minimal-site start

Example endpoints: http://127.0.0.1:3847/llms.txt, http://127.0.0.1:3847/mcp. See CONTRIBUTING.md.

Choose your path

Documentation

Contributing

See CONTRIBUTING.md. Code of conduct: CODE_OF_CONDUCT.md.

License

• Source code: MIT

• Documentation and profiles: CC BY 4.0

Copyright Thierry Gilgen ICT, 2026.