A document layer for the agentic web

actdown_

Reader mode for agents. Turn any web page into a clean, canonical document your agent can read, inspect, and use.

Get started Open playground

Spec draft 0.1. Development preview.

reader / transcode HTTP + MCP

GEThttps://docs.example/releases

<article>
  <h1>Release notes</h1>
  <p>Version 2.4 adds <strong>faster search</strong>
  and safer retries.</p>
  <ul>
    <li>Search indexes update automatically</li>
    <li>Retries use exponential backoff</li>
  </ul>
  <a href="/docs/migration">
    Read the migration guide
  </a>
  <script>trackPageView()</script>
</article>

# Release notes

Version 2.4 adds **faster search** and safer retries.

- Search indexes update automatically
- Retries use exponential backoff

```ad-link
id: h5f34cf9112
role: link
href: /docs/migration
---
Read the migration guide

```

{
  "ad": "0.1",
  "nodes": [
    {
      "kind": "prose",
      "md": "# Release notes\n\nVersion 2.4 adds..."
    },
    {
      "kind": "block",
      "type": "link",
      "id": "h5f34cf9112",
      "role": "link",
      "attrs": {},
      "fields": { "href": "/docs/migration" },
      "body": "Read the migration guide",
      "line": 0
    }
  ]
}

Conversion completeScript removedStable block ID

Runtime dependencies: Zero
Interface: MCP + HTTP + CLI
Implementations: TypeScript + Rust
License: Apache-2.0

01 / Fetch

Read a public web page with guarded redirects and response limits.

02 / Convert

Keep semantic content. Drop scripts, styles, and recognized hidden markup.

03 / Use

Return canonical text, a JSON AST, or rendered HTML with conversion notes.

The premise 01 / 05

Less page noise.
More useful context.

Agents do not need to execute a web page to read it. actdown separates meaning from presentation and delivers content in a format designed for inspection, not execution.

01Reader over MCP	Give your agent a reading tool, not a browser workload. The stdio server exposes seven tools for transcoding, conversion, rendering, and document review.
02Canonical output	Stable text makes useful diffs. A defined AST, assigned block IDs, and an idempotent printer give people and agents one shared representation.
03Network boundaries	Fetching has limits. Private targets are refused by default, every redirect is checked, and the default socket stays pinned to the validated address.
04Visible provenance	Know what changed. Conversion is intentionally lossy. Scripts and styles are removed, and conversion notes report detected legacy behavior and hidden markup.
05Small by design	No framework required. The TypeScript implementation has zero runtime dependencies. The Rust port shares byte-exact conformance fixtures and can run as WebAssembly.

The format 02 / 05

Markdown you know.
Structure an agent can use.

Prose stays Markdown. Fenced ad-* blocks add state, semantic structure, forms, and named actions. The host owns behavior. The document never supplies JavaScript.

AST is the contract: Canonical text and the JSON AST describe the same document.
Human review stays possible: A proposed state change or capability is visible in a text diff.
Capability, not code: Actions name host-granted operations. Hosts must validate their arguments.
Graceful by default: Unknown block types remain readable fenced Markdown.

approval.ad / a document with intent

```ad-state
approved: false
service: checkout
```

```ad-manifest
name: deploy.approve
scopes: ["deploy:write", "audit:write"]
```

```ad-action?name=deploy.approve
id: approve
role: primary
when: {!approved}
---
Approve deploy
```

The host grants the capability.
The document cannot implement it.

Get started 03 / 05

From a URL to structured context.

Use the MCP reader, convert existing HTML through the CLI, or embed the library directly. Requires Node.js 20 or newer.

01 / Connect

Run the MCP server.

Start the packaged stdio server. No separate MCP wrapper is needed.

npx -y -p actdown actdown-mcp

02 / Read

Ask for a page.

The agent supplies a URL and a format. The result includes source, notes, and the converted document.

actdown_transcode
{
  "url": "https://example.com",
  "format": "canonical"
}

03 / Inspect

Work locally.

Clone the repository and explore the format in the dependency-free WebAssembly playground.

git clone
https://github.com/Omodaka9375/
actdown.git

Development preview: install actdown from npm with the standard latest tag. From a checkout, run pnpm build and node dist/mcp.js.

The boundary 04 / 05

Useful conversion.
Explicit trust.

Page content is untrusted.

actdown does not decide whether a page is honest. Converted text, including visible text, remains data. Agents must not treat it as instructions from the user or host. Hidden-markup filtering is best effort, not prompt-injection prevention.

A development preview.

The HTTP gateway is intended for controlled development. Public deployments need a TLS proxy, explicit access policy, and production hardening. Read the security boundaries before connecting an exposed service.

The project 05 / 05

One format.
Two implementations.

Read the specification, inspect the conformance vectors, or try the Rust-powered browser playground. actdown is open source under Apache-2.0.

Read the specification Try the playground View the source

The web, in a form agents can use

Keep the meaning.
Leave the scripts behind.

Canonical documents for agents. Inspectable content for people.

Open playground Star on GitHub