Make your site understandable to every AI.

Quick start

Four steps take a site from invisible to AI-ready.

1. Publish a capability manifest at /ai2w (by hand, via an SDK, or the WordPress plugin).
2. Add the required discovery anchor at /.well-known/ai2w pointing to it.
3. Validate it and get your AI Readiness Score out of 100.
4. Agents discover the manifest, negotiate a capability set, and can act, with approval on anything sensitive.

Validate any site or manifest from the command line, or in the browser on the home page:

npx -p @ai2web/validator ai2web validate https://your-site.com
npx -p @ai2web/validator ai2web validate ./manifest.json

The manifest

One JSON document describes what your site is and can do. It is the single source of truth every transport is generated from.

{
  "protocol": "ai2w",
  "version": "0.1",
  "site": { "name": "Example Store", "url": "https://store.example.com", "type": "ecommerce" },
  "capabilities": {
    "content": true,
    "commerce": { "enabled": true, "endpoint": "/ai2w/products", "checkout": true },
    "search":   { "enabled": true, "endpoint": "/ai2w/search" },
    "actions":  { "enabled": true, "endpoint": "/ai2w/actions" }
  },
  "transports": {
    "rest": { "enabled": true, "base": "/ai2w" },
    "mcp":  { "enabled": true, "endpoint": "/ai2w/mcp" },
    "acp":  { "enabled": true }
  },
  "auth":    { "methods": ["none", "oauth2"], "oauth2": { "pkce": true, "scopes": ["checkout"] } },
  "consent": { "requires_user_approval_for": ["purchase", "payment"] },
  "actions": [
    { "name": "track_order", "id": "order.track", "method": "GET",
      "endpoint": "/ai2w/actions/track-order", "requires_auth": true,
      "requires_user_approval": false, "risk": "medium", "input_schema": { "type": "object" } }
  ],
  "contact": { "support": "[email protected]" }
}

Build it in code instead of by hand:

import { ai2web } from "@ai2web/core";

const manifest = ai2web({ name: "Example Store", url: "https://store.example.com", type: "ecommerce" })
  .capability("content")
  .capability("commerce", { checkout: true })
  .action({ name: "track_order", id: "order.track", method: "GET",
            endpoint: "/ai2w/actions/track-order", requires_auth: true,
            requires_user_approval: false, risk: "medium", input_schema: { type: "object" } })
  .consent({ requires_user_approval_for: ["purchase", "payment"] })
  .build();

Discovery & endpoints

Agents find your manifest through a fixed anchor, then talk to a small, predictable set of routes.

GET  /.well-known/ai2w    discovery anchor (required) - points to the manifest
GET  /ai2w                the capability manifest (canonical home)
POST /ai2w/negotiate      agree a capability set + transport
GET  /ai2w/{module}       content · products · actions · events · search · agent

/ai2w is the RECOMMENDED canonical endpoint; /.well-known/ai2w is the fixed anchor that carries or points to it. Discovery is read-only and safe: fetching a manifest never changes state. If a neutral cross-vendor discovery standard emerges, AI2Web is designed to be carried by it rather than competing.

Capability modules

Capabilities are a map of module -> boolean | object. A boolean declares presence; an object adds detail such as an endpoint. Commerce is one module among equals, the model is not commerce-centric.

Negotiation

The site advertises its full set; the agent uses the subset it understands. The result is the intersection, plus the chosen transport and auth.

POST /ai2w/negotiate
{ "capabilities": ["content", "commerce"], "transports": ["mcp", "rest"], "auth": ["oauth2"] }

-> { "negotiated": { "transport": "mcp", "capabilities": ["content", "commerce"],
                    "auth": "oauth2", "endpoints": { ... } },
     "unsupported": [] }

No transport is mandatory. The success of any single protocol is a tailwind, not a dependency, so a site can add or drop transports without breaking discovery.

Actions, risk & approval

Every action declares a risk tier. Discovery is safe; execution is controlled. This is the rule that lets an agent act without acting recklessly.

High-risk actions never auto-run. The flow is: discover → prepare → the site returns a preview → the user approves → execute → confirmation with an audit reference. In the reference adapters this is enforced in one shared executor, and a high-risk action previews even if a manifest tries to declare approval: false.

Transports & adapters

Describe once, generate many. One capability model projects onto whichever protocol an assistant speaks.

AI Assistant
     |
  AI2Web  (one capability model)
     |-- MCP          call declared actions as tools
     |-- ACP          checkout transport (RFC-0005 Profile 1)
     |-- REST         discovery, modules, feeds
     |-- GraphQL      the model as a schema
     |-- OpenAPI      the actions as an API document
     |-- Webhooks     event delivery
     +-- Future protocols

In the JavaScript framework these are the @ai2web/mcp-bridge, @ai2web/acp-adapter, @ai2web/graphql-adapter and @ai2web/openapi-adapter packages. The executing adapters all route through one guarded executor, so the approval, same-origin credential and SSRF rules hold uniformly across transports.

SDKs & install

Author in whatever you already use. The framework is TypeScript, JavaScript and React, with SDKs across PHP, Python, Go and .NET and a WordPress plugin. Every SDK reproduces the same conformance contract.

npm install @ai2web/core          # types, builder, validation, discovery, badge
npm install @ai2web/server        # /ai2w route handler (Node + Cloudflare)
npm install @ai2web/mcp-bridge    # expose your capabilities as an MCP server
npm install @ai2web/react         # hooks + <Ai2wBadge>

The JavaScript packages ship as standard ESM with bundled types, so they run unchanged in plain JavaScript. A build-free <ai2w-badge> web component drops into any HTML page with no bundler. Score a manifest programmatically:

import { discover, validateManifest } from "@ai2web/core";

const { manifest } = await discover("https://ai2web.dev");
const { score, tier } = validateManifest(manifest);
console.log(`${score}/100 (${tier})`);

Connect Claude & ChatGPT

An AI2Web MCP endpoint works with existing assistant connectors today, no vendor needs to adopt ai2w first.

• Claude: add your /ai2w/mcp URL as a custom connector.
• ChatGPT: add the same URL as an app in developer mode (Apps SDK / Streamable HTTP).
• Whole network: add the AI2Web connector once and it discovers and acts on any AI-ready site.

Because AI2Web ships both the website side and an agent-side connector, adoption does not depend on any single vendor moving first.

Tiers & scoring

Validation returns an AI Readiness Score out of 100 and a compliance tier.

Try it live on the home page or with npx -p @ai2web/validator ai2web validate <url>.

Security model

Make safe things easy and dangerous things explicit.

• Discovery is safe; execution is controlled. Reading a manifest never changes state.
• Approval before money or data. Purchases, refunds and data exports always return a preview to approve first.
• Least privilege. Public discovery exposes only public metadata; private data needs scoped authorization.
• Same-origin credentials. A token is never sent to an origin other than the one that issued it, and never appears in a URL.
• Audit. High-risk actions return an audit reference; logs record what ran, for whom, and whether it was approved.

The full rules are in RFC-0003 (authentication and consent), RFC-0006 (adapter conformance) and RFC-0009 (privacy, audit and retention).

Spec & RFCs

This page is the practical guide. The normative detail is versioned in the open.