# tell.st — Full Technical Specification & LLM Context (llms-full.txt)

> Install a single script to open a conversation space on your website. Visitors share feedback without registering. Verified owners can reply, manage private reports and update status; followers can receive updates. A homepage badge works without JavaScript, and a meta tag verifies ownership without adding an entry.

## 1. System Overview & Core Mechanics

1. **Address-Bar Prefix Routing (`https://tell.st/[domain]`)**:
   - Prepending `https://tell.st/` to any domain or full URL resolves the canonical site using the Mozilla Public Suffix List (PSL).
   - Standard subdomains (e.g., `docs.linear.app`) roll up to the canonical root (`linear.app`) while preserving `filterHost` and `filterPath`.
   - Multi-tenant public hosts (`github.io`, `vercel.app`, `pages.dev`, `netlify.app`, `workers.dev`, `notion.site`, `substack.com`, `webflow.io`, `framer.website`) remain strictly isolated at the tenant subdomain level to prevent cross-tenant claiming.

2. **Explicit Homepage Ownership Verification**:
   - Sign in to the dashboard and publish the account-specific code on the homepage, then click Verify. Visitor requests never claim ownership automatically. Options include a homepage badge anchor linking to `https://tell.st/YOUR_DOMAIN` with `data-tellst-key="YOUR_WIDGET_KEY"`, or `<script defer src="https://tell.st/w.js" data-key="ts_xxx"></script>` (or `<meta name="tell.st" content="ts_xxx">`) on their root homepage `https://{domain}/`.
   - Verification parses bounded root HTML with an HTML5 parser (HTTPS-only, 5-second timeout, max 3 same-site redirects, 2 MiB stream cap with prefix parsing).
   - Claiming unlocks `isPrivate: true` reports, supports an optional embedded interaction space (host shell: 20 KiB gzip budget), and enables Slack/Discord/Feishu/JSON Webhooks.

3. **Widget Customization Attributes**:
   - `data-key`: Public deployment identifier, never a private API credential (e.g., `ts_xxx`).
   - `data-variant`: `"solid"` (default brand fill with automatic text contrast), `"soft"` (warm light card with subtle border and accent icon), `"dark"` (dark surface for dark-mode sites), `"outline"` (crisp bordered), or `"glass"` (frosted glass).
   - `data-accent`: Custom CSS hex color (e.g., `"#10b981"`).
   - `data-bg` / `data-color`: Optional exact hex background and foreground overrides (`"#rrggbb"`).
   - `data-position`: `"bottom-right"` (default), `"bottom-left"`, `"right-center"`, or `"left-center"`.
   - `data-offset`: Edge offset in px (e.g., `"72"` or `"24,72"`) to avoid sticky footers or corner buttons.
   - `data-collapse` / `data-collapse-offset`: Scroll behavior: `"scroll"` (default: shrinks to an icon on scroll down, expands on scroll up/top/hover), `"edge"` (also tucks toward screen edge), `"hide"` (hides while scrolling down), `"icon"` (always compact icon, expands on hover), or `"never"`. `data-collapse-offset` sets the scroll threshold in px (default `64`).
   - `data-delay` / `data-trigger` / `data-entrance`: Entrance timing and motion: `data-delay` in ms (default `1000`; `0` for immediate), `data-trigger` (`"delay"` | `"scroll"` | `"immediate"`), `data-entrance` (`"fade-up"` | `"scale"` | `"slide"` | `"none"`).
   - `data-radius` / `data-size` / `data-shadow` / `data-icon` / `data-mobile`: Geometry and details: `data-radius` (`"pill"` | `"rounded"` | `"sharp"` | `"<0-32>px"`), `data-size` (`"sm"` | `"md"` | `"lg"`), `data-shadow` (`"sm"` | `"md"` | `"lg"` | `"none"`), `data-icon` (`"chat"` | `"sparkle"` | `"message"` | `"bulb"` | `"none"`), `data-mobile` (`"auto"` | `"icon"` | `"hidden"`).
   - `data-locale` / `data-label`: Language (`"en"` | `"zh"`) and custom button text (e.g., `"Feedback"`).
   - Keyboard shortcut: `Alt+T` starts optional DOM marking. `tellst:open` opens the interaction space; `tellst:start-picker` starts marking. Images can be uploaded or pasted. The full page, permalink and embedded space share one responsive list/detail/composer implementation. New feedback opens inline, without another dialog. The frame is loaded on first open and retains drafts while closed. Host sites must allow https://tell.st in frame-src; blocked frames offer a full-page fallback.

Feedback has one generic model and no category. Ratings and reviews are deferred. Static feedback badges have no rating, counts or verification claims; a plain Markdown/README badge cannot prove website ownership.

On-platform access to private feedback and attachments is available to the authorized author, verified site owner, platform administrator and tools holding a valid private token for the site. An agent connected to the owner’s account can read private feedback through MCP. On claimed sites, new private reports and visitor comments can reach the owner and configured alert addresses by email with the report text and original page path. Private Webhooks redact report and comment text, author details, original path and markers. See [privacy](https://tell.st/privacy#private-feedback).

## 2. Model Context Protocol (MCP) Server Specification

Endpoint: `POST https://tell.st/api/mcp` (JSON-RPC 2.0)

Use tools/list for current input schemas. Tool results are returned as MCP text content.

### Available MCP Tools
Register https://tell.st/api/mcp in the agent's user-level configuration once. For account access, use the HTTP 401 challenge and protected resource metadata to start OAuth with PKCE. The user signs in and consents on tell.st. Reuse the connection across repositories. The two account tools take a domain:
- `get_site_setup` returns the account-specific public script (accepting optional style adaptation parameters such as `accent`, `variant`, `position`, `offset`, `collapse`, `delay`, `radius`, `size`, `icon`, `locale`, `label`) along with a `customization` catalog, or indicates that the current account already owns the site.
- `verify_site_claim` checks the published root homepage and returns the ownership status and space URL. Retry after an actual publication. A different owner cannot be replaced.

1. `list_site_pins`:
   - Arguments: `{ "domain"?: "string", "status"?: "open" | "planned" | "in_progress" | "completed" | "closed", "limit"?: integer, "cursor"?: "string" }`
   - Returns: Parse `result.content[0].text` as JSON to get `{domain, count, nextCursor, pins}`. Each item includes its status, page path and feedback text subject to access checks. A visible report with a marker can include a selector. For recorded bounding boxes, use `get_pin_fix_prompt`. Supply the domain in the tool arguments or the server URL. The page size defaults to 25 and accepts integers from 1 to 100. Continue with the same filters and the returned cursor.
2. `get_pin_fix_prompt`:
   - Arguments: `{ "shortId": "string" }`
   - Returns: Structured AI prompt with feedback text, page URL, optional selector, viewport metrics, and discussion context.
3. `resolve_pin`:
   - Arguments: `{ "shortId": "string", "status": "open" | "planned" | "in_progress" | "completed" | "closed", "isPrivate"?: "boolean", "comment"?: "string" }`
   - Returns: A text confirmation. Without a comment, it reports how many email notifications were queued. With a comment, it confirms the official reply and includes no delivery count. Requires a connected owner account or a site token with manage permission.
4. `delete_pin`:
   - Arguments: `{ "shortId": "string" }`
   - Returns: A text confirmation of deletion. Requires a connected owner account or a site token with manage permission.
5. `create_pin`:
   - Arguments: `{ "pageUrl"?: "string", "submissionId"?: "UUID v4", "content": "string", "selector"?: "string", "isPrivate"?: "boolean" }`
   - Returns: A text confirmation with the shortId, the site board URL and the feedback permalink `https://tell.st/p/{shortId}`. Supply a page URL or configure a default domain in the MCP server URL.

## 3. REST API Reference

Feedback lists default to 25 items (limit 1–100). Pass nextCursor as cursor with unchanged filters. Exports return at most 100 items per page; follow the Link response header or X-Next-Cursor. Private access is reauthorized on every page.

- `GET /api/pins?domain={domain}`: Fetch site metadata, feedback and its processing status (pass `Authorization: Bearer` header to unlock private pins).
- `POST /api/pins`: Create a pin (`pageUrl`, `submissionId` (optional retry UUID v4), `content`, `domMeta`, `screenshotDataUrl`, `isPrivate`).
- `PATCH /api/pins/{shortId}`: Update pin `status` (owner session or `Authorization: Bearer YOUR_PRIVATE_API_TOKEN` header), edit `content` (pin author), or toggle `isPrivate` visibility (owner or author).
- `DELETE /api/pins/{shortId}`: Delete a pin (requires owner session, pin author session, or `Authorization: Bearer YOUR_PRIVATE_API_TOKEN` header).
- `GET / POST / DELETE /api/pins/{shortId}/comments`: List, post, or delete discussion comments (supports owner session, author session, or `Authorization: Bearer YOUR_PRIVATE_API_TOKEN` header).
- `POST /api/pins/{shortId}/vote`: Upvote or subscribe to a pin (`DELETE` to unfollow).
- `GET /api/pins/export?domain={domain}&format={md|csv|json}`: Bulk export feedback (supports `Authorization: Bearer` header for private pins).
- `GET /api/badge/{domain}`: Static feedback-link SVG badge. Supports locale=en|zh and style=pill|flat.
- `GET /api/feed/{domain}`: Per-domain RSS 2.0 XML feed.
- `GET /feed.xml`: Global RSS 2.0 XML feed.

## 4. Selected site boards and public feedback

This directory shows up to 40 sites and up to 15 public reports per listed site.

### realtest.org (✓ Official Claimed Site)
- Board URL: https://tell.st/realtest.org
- RSS Feed: https://tell.st/api/feed/realtest.org
- Export Markdown: https://tell.st/api/pins/export?domain=realtest.org&format=md
- Total Pins: 1 (Private Locked: 0)
  - **[#dc2136314c39386b](https://tell.st/p/dc2136314c39386b)** on `realtest.org/` (Status: `open`, Upvotes: 1): Great Job ～

### cle.st (✓ Official Claimed Site)
- Board URL: https://tell.st/cle.st
- RSS Feed: https://tell.st/api/feed/cle.st
- Export Markdown: https://tell.st/api/pins/export?domain=cle.st&format=md
- Total Pins: 1 (Private Locked: 0)
  - **[#c01a8e585124b2bc](https://tell.st/p/c01a8e585124b2bc)** on `cle.st/` (Status: `open`, Upvotes: 1): 👍 期待！

### tell.st (✓ Official Claimed Site)
- Board URL: https://tell.st/tell.st
- RSS Feed: https://tell.st/api/feed/tell.st
- Export Markdown: https://tell.st/api/pins/export?domain=tell.st&format=md
- Total Pins: 1 (Private Locked: 0)
  - **[#ed5681a0c0420a72](https://tell.st/p/ed5681a0c0420a72)** on `tell.st/` (Status: `open`, Upvotes: 1): Hello World！

### nologin.tools (✓ Official Claimed Site)
- Board URL: https://tell.st/nologin.tools
- RSS Feed: https://tell.st/api/feed/nologin.tools
- Export Markdown: https://tell.st/api/pins/export?domain=nologin.tools&format=md
- Total Pins: 0 (Private Locked: 0)
  - No public pins yet.

### 30s.to (✓ Official Claimed Site)
- Board URL: https://tell.st/30s.to
- RSS Feed: https://tell.st/api/feed/30s.to
- Export Markdown: https://tell.st/api/pins/export?domain=30s.to&format=md
- Total Pins: 0 (Private Locked: 0)
  - No public pins yet.