# Wordy Page (https://wordy.page) — Full AI Agent, MCP & API Reference

> Agent mode (custom HTML and CSS, including safe inline SVG, with a personal key): see https://wordy.page/agents/ and https://wordy.page/llms.txt. This file covers the editor format, MCP tools and publish.php.

> Free 60-second web page and multi-page site builder — built for people on phones/desktops and first-class accessible for AI web agents. No passwords, no app installs, no hosting setup.

## 1. Machine-Readable Discovery & Sample Showcase
- [AI Agent Guide (llms.txt)](https://wordy.page/llms.txt): Concise overview, formatting rules, and quickstart for AI agents.
- [Full API & Formatting Reference (llms-full.txt)](https://wordy.page/llms-full.txt): Complete payload schemas, Python/curl scripts, and formatting syntax.
- [Remote MCP Server (https://wordy.page/mcp)](https://wordy.page/mcp): Native Model Context Protocol (Streamable HTTP / JSON-RPC 2.0) server.
- [MCP Discovery Metadata (.well-known/mcp.json)](https://wordy.page/.well-known/mcp.json): Machine-readable MCP server descriptor and client config.
- [OpenAPI 3.1 Specification (openapi.json)](https://wordy.page/openapi.json): Formal JSON API schema for tool-calling, MCP, and HTTP agents.
- [A2A Agent Card (agent.json)](https://wordy.page/.well-known/agent.json): Agent-to-Agent capability and skill descriptor.
- [AI Plugin Manifest (ai-plugin.json)](https://wordy.page/.well-known/ai-plugin.json): Standard plugin manifest pointing to `/openapi.json`.
- [Live Sample Site — Lantern Hill Bakehouse](https://wordy.page/sample/): Official multi-page sample showcase built on Wordy Page with per-page Unsplash header photos, blurred header-image page backgrounds, ALL CAPS blue section headings, and per-page contact forms.
- [About Wordy Page & FAQ](https://wordy.page/about): Overview of Wordy Page (Free Page Maker, Free Site Maker, Free SEO Article Publishing, and AI Agent API/MCP) plus Frequently Asked Questions.

## 2. Plain-Text Formatting Engine & Layout Architecture
All body text fields (`description` and `sections[].text`) use Wordy Page's deterministic plain-text renderer (`inc/render.php`):

1. **ALL CAPS Blue Highlights (`<strong>`)**:
   - Any contiguous sequence of `ALL CAPS` words (at least 2 uppercase letters `[A-Z]`, where spaces and inline connectors `&`, quotes, commas, colons, slashes, hyphens, parens, or numbers between `ALL CAPS` words do not break the sequence, plus optional leading `1. ` list numbers) is automatically wrapped in `<strong>` and rendered in the theme's blue accent color (`#0b63ce` in Light mode, `#5aa0d6` in Dark mode) at **normal `400` font weight** (no heavy bold weight).
   - **Important**: Do **NOT** wrap words in Markdown `**asterisks**` — asterisks are rendered literally as plain text. Simply write subheadings or key callouts in `ALL CAPS`.
2. **Line Breaks & Blank Lines**:
   - Every newline (`\n`) is a `<br>`; a blank line (`\n\n`) simply stays a blank line. There are no `<hr>` dividers and no `##` subheadings. The only formatting is indentation and bold blue ALL CAPS.
3. **Preserved Indentation & Safe Plain-Text Code/HTML**:
   - Leading spaces, tabs (`\t` -> 4 spaces, `tab-size: 4`), and multi-space runs are preserved via non-breaking spaces (`pq_indent()`).
   - All user text is HTML-escaped (`htmlspecialchars`) before inline processing, so pasted HTML tags or code snippets display safely as inert plain text.
4. **Automatic URL & Email Linking (`pq_inline()`)**:
   - Plain `https://...`, `http://...`, `www....` URLs and email addresses (`name@example.com`) are automatically converted into clickable `<a>` links.
5. **One Header Image Per Page (`photo` / `sections[].photo`)**:
   - Set a page's `photo` to an Unsplash id (from `search_photos` or `GET /unsplash.php?q=<query>`). It renders below the page name and above the text in a full-width `#141414` box with credit. Never put images in text; legacy `[[photo:<id>]]` tokens are converted (the first becomes the page photo).
   - Editor: the **Add image** button sits between Page name and page text; a chosen image shows a thumbnail with a delete icon that removes it.
6. **Contact Form On Any Page (`cf`)**:
   - `cf: true` on the home page or any section adds a contact form (Email and Message only) at the bottom of that page. Messages are emailed to the owner; the email never appears in the HTML.
   - Images and text stack in a clean top-to-bottom vertical flow in the exact order they appear. Every image is centered horizontally (`margin: 14px auto`, natural aspect ratio, `max-width: 50%` on desktop `>=700px` with portrait `max-height` capped at `max-width`, and `max-width: 100%` on mobile `<700px`).
6. **Field Limits & Sticky Header Rules**:
   - `title`: max **36 characters**. Displayed in the sticky top bar (`68px` height), stacks up to 2 lines on mobile without changing header height, and clicks back to the site's first home page (`/<slug>/`).
   - `heading` / `sections[].heading`: max **80 characters**.
   - `description` / `sections[].text`: max **20,000 characters** each.
   - `sections`: up to **9 additional pages** (10 pages total incl. Home) (`/<slug>/<section-slug>/`).
 
## 3. Native Remote MCP Server (`https://wordy.page/mcp`)
AI agents and MCP clients (Cursor, Claude Desktop, Windsurf, Grok Bot, etc.) can connect directly to Wordy Page's remote Model Context Protocol (MCP) Streamable HTTP server — no local wrapper required:
- **MCP Endpoint**: `https://wordy.page/mcp`
- **MCP Discovery Metadata**: `https://wordy.page/.well-known/mcp.json`
- **MCP Client Config**:
  ```json
  {
    "mcpServers": {
      "wordy-page": {
        "url": "https://wordy.page/mcp"
      }
    }
  }
  ```
- **MCP Tools Provided**:
  - `check_slug`: Verify whether a 3–40 char slug is valid and available.
  - `get_page`: Read the full `.meta.json` fields (`title`, `heading`, `description`, `theme`, `photo`, `cf`, `sections` with their `photo`/`cf`) of any published site.
  - `list_pages`: List public showcase sites or all sites owned by a session token (`st`).
  - `search_photos`: Search Unsplash and automatically cache photo metadata, returning photo ids to use as a page's `photo`.
  - `create_or_update_page`: Create or update a single-page or multi-page site (without `st`: saves the draft, emails a one-tap link to `owner_email`, and returns HTTP 202 `{"ok":false,"need_link":true}` / MCP `status: "Verify email"`; the page goes live when the link is tapped or its token is redeemed via `{"action":"link","token":"..."}`, which returns a 30-day `session_token`. With a valid `st`: publishes immediately, `status: "live"`).
- **MCP Resources Provided**: `wordy://docs/llms`, `wordy://docs/llms-full`, `wordy://docs/openapi`
- **MCP Prompts Provided**: `build-website`

## 4. Complete Python & cURL Automation Example for AI Agents

```python
import subprocess, urllib.parse, json

def wp_call(path, payload=None, session_token=None):
    cmd = ["curl", "-s", "-b", "humans_21909=1"]
    if session_token:
        cmd += ["-H", f"X-PQ-Session: {session_token}"]
    if payload is not None:
        cmd += ["-H", "Content-Type: application/json", "-d", json.dumps(payload)]
    cmd.append(f"https://wordy.page{path}")
    return json.loads(subprocess.check_output(cmd).decode("utf-8"))

# 1. Search & register an Unsplash photo
photos = wp_call("/unsplash.php?q=" + urllib.parse.quote("coastal sunset") + "&page=1")
photo_id = photos["results"][0]["id"]
wp_call("/unsplash.php", {"id": photo_id})

# 2. Request a magic link for your agent's email inbox
wp_call("/publish.php", {"action": "send_link", "email": "agent@example.com"})

# 3. After reading the 32-char token from `https://wordy.page/pages?login=<TOKEN>` in the email:
auth = wp_call("/publish.php", {"action": "link", "token": "YOUR_32_CHAR_EMAIL_TOKEN"})
st = auth["token"]

# 4. Publish a multi-page site using ALL CAPS blue headings, indentation, a header photo and a contact form
res = wp_call("/publish.php", {
    "action": "publish",
    "st": st,
    "slug": "my-agent-site",
    "form": "editor",
    "owner_email": "agent@example.com",
    "data": {
        "title": "My Agent Site",
        "heading": "Welcome",
        "photo": photo_id,
        "description": "BUILT AUTONOMOUSLY\nPublished on Wordy Page (https://wordy.page).\n\nKEY HIGHLIGHTS\n• Instant multi-page publishing\n• Automatic WCAG AA contrast",
        "theme": "dark",
        "sections": [
            {"heading": "Details", "text": "MORE DETAILS\n    More information on page two."},
            {"heading": "Contact", "text": "GET IN TOUCH\nSend us a message anytime using the form below.", "cf": True}
        ]
    }
}, session_token=st)
print("Live at:", "https://wordy.page" + res["url"])
```

## 5. Detailed Endpoint & State Machine Reference

### Browser-Driving Agents vs. Direct HTTP / MCP Agents
- **Browser Agents**:
  - When signed out on `https://wordy.page/`, the Short Form (`body.short`) displays 3 fields: `#heading` (Page name), `#description` (Text, with a 2-line placeholder highlighting `CAPITAL LETTERS` in blue, also used on added page textareas), and `#owner` (Email), plus `#go` ("Publish Your Page" or "Sign In" if the email already owns a page).
  - Every page block has: Page name, an **Add image** button (`.add-img` in `.img-slot`; opens the Unsplash search lightbox; once chosen shows a `.pimg` thumbnail with a delete icon `.pimg-rm` that brings the button back), the page text, and an **Include a contact form** checkbox (`.sec-cf`; added pages show Remove page on the same row). Up to 10 pages (home + 9).
  - After clicking the emailed link (`https://wordy.page/pages?login=<token>`), the browser stores the session cookie and `localStorage.pq_st`, unlocking the Full Multi-Page Editor on `https://wordy.page/` (or `https://wordy.page/?edit=<slug>`).
- **Direct MCP / HTTP Agents**:
  - Can bypass browser rendering entirely by calling `https://wordy.page/mcp` (JSON-RPC 2.0) or `https://wordy.page/publish.php` and `https://wordy.page/unsplash.php` with `Content-Type: application/json` and `Cookie: humans_21909=1`.

### Moving / Renaming a Site Slug (`from` parameter)
- When signed in on a newly created short-form page (which receives an auto-generated slug like `honey9827`), pass `"from": "honey9827"` and `"slug": "your-new-slug"` in the `publish` payload to atomically move the site to `/your-new-slug/` and remove the old folder without creating a duplicate page.

### Managing & Cleaning Up Sites
- **List owned sites**: `POST /publish.php` with `{"action":"list","st":"<session_token>"}`
- **Load site fields for editing**: `POST /publish.php` with `{"action":"get","slug":"<slug>","st":"<session_token>"}`
- **Unpublish a single site**: `POST /publish.php` with `{"action":"unpublish","slug":"<slug>","st":"<session_token>"}`
- **Delete account and all owned sites**: `POST /publish.php` with `{"action":"delete_account","confirm":"delete","st":"<session_token>"}`