point-by-point

# point-by-point Reply to Claude or ChatGPT **point by point**. The assistant shows its response in a read-only interface; you click any sentence (or select any passage), write your reply or question under it, and send everything back in a single message. **Contents** - [Install](#install) - [In Claude, as a plugin (recommended)](#in-claude-as-a-plugin-recommended) - [In Claude, without the plugin](#in-claude-without-the-plugin) - [In ChatGPT](#in-chatgpt) - [Try it](#try-it) - [If it doesn't work](#if-it-doesnt-work) - [Run your own copy of the server](#run-your-own-copy-of-the-server) - [For an organisation](#for-an-organisation) - [Anthropic's plugin directory](#anthropics-plugin-directory) - [How it works](#how-it-works) - [What the interface does](#what-the-interface-does) - [Privacy and security](#privacy-and-security) - [Development](#development) - [Testing in claude.ai](#testing-in-claudeai) - [Mobile diagnostic](#mobile-diagnostic) - [Deploy](#deploy) - [Release](#release) - [License](#license) **1. Click a sentence or select a passage, and write under it.** Pointing at a sentence highlights what a click will annotate. <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/annotate-dark.png"> <img src="docs/images/annotate-light.png" width="720" alt="A response from Claude in the point-by-point interface: one sentence and one passage are highlighted, each with a note written under it, and the Send button below."> </picture> **2. Draft your reply.** Your notes go to your message box as one message, in the order of the response, and stay in place in the interface: ``` `First we migrate the database.` Back it up first. `switch traffic` When exactly? Not during business hours. ``` **3. Claude answers each point**, under a quote of your note, in a new interface you can annotate again. <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/answer-dark.png"> <img src="docs/images/answer-light.png" width="720" alt="Claude's next response: each of the user's notes is shown as a bubble, followed by Claude's answer to it."> </picture> The interface follows the app's light or dark theme (the images above follow yours). It is an [MCP App](https://claude.com/blog/interactive-tools-in-claude): an MCP server that declares one tool, `annotate_response`, whose interface is rendered inline in the conversation by hosts that support MCP Apps (claude.ai, Claude Desktop, the Claude mobile apps, and ChatGPT on the web and in its desktop app). ## Install The server is hosted once for everyone (or [run your own copy](#run-your-own-copy-of-the-server)); there is nothing to install on your computer. Add it once to your account, in a browser: it then applies everywhere you use that account (web, desktop and mobile apps). For Claude, do it on [claude.ai](https://claude.ai); for ChatGPT, see [In ChatGPT](#in-chatgpt). ### In Claude, as a plugin (recommended) The plugin brings the **connector** (the server) and the **skill** (which tells Claude to use it) together, and keeps the skill up to date with each release. 1. Go to **Customize → Plugins → Add → Add marketplace** and enter: ``` alexisjamet/point-by-point ``` 2. Install the **point-by-point** plugin, which now appears among the plugins. 3. **Connect the connector.** Installing the plugin does not connect it: until you do, Claude has no `annotate_response` tool and answers in the chat as usual, without saying why. Open the plugin, go to its **Connectors** tab, where `point-by-point` shows **Not added**, and click **Connect**. <img src="docs/images/plugin-connect.png" width="720" alt="The point-by-point plugin page, Connectors tab: the point-by-point connector shows Not added, with a Connect button on its right."> 4. Check it in a new chat: `point-by-point` appears, turned on, in the chat's tools menu. **Try in chat** only uses point-by-point once the connector is connected. To get each release without doing anything, turn on **Sync automatically** for the marketplace. If you installed the connector or the skill by hand before, remove them from **Customize → Connectors** and **Customize → Skills**, so they do not appear twice. ### In Claude, without the plugin If your plan or organisation does not offer plugins, add the connector by hand: it tells Claude how to use it on its own. 1. **Add the connector.** Go to **Settings → Connectors → Add custom connector**, give it a name (for example `point-by-point`) and paste this URL: ``` https://point-by-point.brols.workers.dev/mcp ``` 2. **Optional: add the skill.** It holds the same rules as the connector and makes Claude follow them more reliably. Download [`point-by-point-skill.zip`](https://github.com/alexisjamet/point-by-point/releases/latest/download/point-by-point-skill.zip), then upload it in **Settings → Capabilities → Skills**. Upload the `.zip` as it is: do not unzip it (if your browser unzipped it on its own, zip the `point-by-point` folder again). A skill uploaded this way does not update itself: upload the new archive to get a later release. Menu names move from time to time; look for "Plugins", "Connectors" and "Skills" in the settings. ### In ChatGPT ChatGPT shows MCP Apps on the web and in its desktop app. Add the server once as a custom MCP server: it carries its own instructions, so no skill is needed. 1. In ChatGPT, open **Plugins** ([chatgpt.com/plugins](https://chatgpt.com/plugins)), select **+**, then **Add custom MCP server**. 2. Name it `point-by-point`. Under **Connection**, choose **Public endpoint** and paste: ``` https://point-by-point.brols.workers.dev/mcp ``` 3. Leave authentication off: the server needs no account. Review the warning, select **I understand and want to continue**, then **Create as a plugin**. 4. In a new chat, type `@` and pick **point-by-point**. If **Add custom MCP server** is missing, turn on **Developer mode** in ChatGPT's settings (under **Apps & Connectors → Advanced**, or **Security** on some accounts). Custom MCP servers depend on your plan, and in a Business, Enterprise or Edu workspace an admin may have to allow them. **Experimental: with the skill, in the ChatGPT desktop app.** This repository is also a plugin marketplace in the portable format that ChatGPT's desktop app and Codex read. With the [Codex CLI](https://developers.openai.com/codex) installed, run `codex plugin marketplace add alexisjamet/point-by-point`, restart the ChatGPT desktop app, and install **point-by-point** from the Plugins Directory, under that marketplace. ### Try it Start a **new conversation** and ask anything. Instead of plain text, the answer appears in an interface: 1. Click a sentence (or select a passage) and type your reply under it. Repeat for as many sentences as you like. 2. Press **Draft my reply** (in ChatGPT, **Send**). In Claude the message lands in your message box: press Enter to send it. 3. The assistant answers each of your points, in a new interface. ### If it doesn't work - **Claude answers in plain text.** Check that the connector is connected (the plugin's **Connectors** tab must not say **Not added**, or **Customize → Connectors**) and turned on for this conversation (the tools menu in the message box), then start a new conversation. With the plugin or the skill, Claude says so in its first response when the connector is missing. Without the plugin, if it still happens, add the skill, or check that it is turned on in **Customize → Skills**. - **ChatGPT answers in plain text.** Pick **point-by-point** with `@` in a new chat. After a new release, open the plugin in **Plugins** and select **Refresh**, so ChatGPT reads the current tool. - **The connector says it has no tools.** Open the connector in the tools menu and refresh its tool list. Releases before 0.20.1 could leave claude.ai with an empty list until that refresh. - **No "Plugins", "Skills" or "Add custom connector" in the settings.** These depend on your plan, and in a Team or Enterprise organisation an admin may have to allow them. Skills may also require code execution to be turned on in **Settings → Capabilities**. In ChatGPT, custom MCP servers need **Developer mode** (see [In ChatGPT](#in-chatgpt)). - **The interface is blank or shows an error.** Reload the page; your notes are kept as a draft. ### Run your own copy of the server The hosted server sees the text of Claude's responses (see [Privacy and security](#privacy-and-security)). To keep it to yourself, deploy your own copy on a free [Cloudflare](https://dash.cloudflare.com/sign-up) account. You need Node 22 or later and a terminal: ```sh git clone https://github.com/alexisjamet/point-by-point.git cd point-by-point npm install -g pnpm pnpm install pnpm --filter @point-by-point/server exec wrangler login # opens Cloudflare in your browser pnpm run deploy ``` The last command prints your server's address, `https://point-by-point.<your-subdomain>.workers.dev`. On a new Cloudflare account you may first have to choose that subdomain, under **Workers & Pages** in the dashboard. Then follow [In Claude, without the plugin](#in-claude-without-the-plugin) (or [In ChatGPT](#in-chatgpt)) with your address plus `/mcp` as the connector URL; the skill is the same. To get a new release later: `git pull && pnpm run deploy`. ### For an organisation A Team or Enterprise admin adds the plugin from this repository to the organisation's plugin catalogue; skill and connector reach everyone at once. ### Anthropic's plugin directory Planned once the v1 is stable, through the [plugin directory submission form](https://clau.de/plugin-directory-submission). ## How it works 1. Claude calls `annotate_response` with its response in markdown, instead of writing it in the chat. 2. The host loads the interface resource (`ui://point-by-point/annotate-v<major>.<minor>.html`) in a sandboxed iframe and passes it the markdown. 3. The interface renders the markdown (sanitised), splits it into sentences and lets you annotate. 4. The button hands the composed message to the host, which puts it in the message box (Claude) or sends it (ChatGPT) as if you had typed it. 5. Claude reads the quotes, answers each point, and responds through the tool again. The tool is declared to every client. Clients that render MCP Apps get the interface: those that announce the extension (`io.modelcontextprotocol/ui`), and ChatGPT, recognised by the `openai/` hints it adds to its requests. Anywhere else — Claude Code in a terminal, the API without an MCP Apps host — the tool answers that the interface cannot be shown, and the model writes its response in the chat, so you never end up with an invisible response. ### What the interface does - Click a sentence, or select a passage of more than two characters, to open a note under its paragraph. Click an annotated sentence again to return to its note. - Every note hangs on a sentence or a passage; empty notes are ignored. The button only shows once a note has text, and then the hint goes away. In ChatGPT, from two notes on, it says how many it sends ("Send 2 annotations"). - Notes are sent in document order; backticks in quotes become apostrophes. - The bubble icon in a note's corner starts a **new conversation** about that passage: it copies the passage and your note to your clipboard, and on claude.ai and in ChatGPT it also opens a new conversation in the app you are in, prefilled with them (through the host, as a link: desktop apps may open it in your browser). The note stays in place. A very long passage is shortened in the link, to keep it under 8,000 characters, never in the copy; your note never is. Claude Desktop asks to confirm a claude.ai link and then opens nothing, so there the button only copies: start a new conversation and paste. - The button hands the message to the host. Claude places it in your message box (Claude Desktop under a caution banner it shows for every message an interactive app proposes), so the button reads **Draft my reply**; read it and press Enter to send it. ChatGPT sends it, so the button reads **Send**. - The notes stay in place after a send, and are kept with the response's draft: the response keeps them as a record, and if you discard the message, the button hands it over again. A mark says where the message went, until you change a note. A widget from an earlier response can still send: its message starts with "(About an earlier response)". - Every keystroke is saved as a draft and restored if the page reloads. - Keyboard: Tab / Shift+Tab move between sentences, Enter opens a note, Escape leaves a note, Cmd/Ctrl+Enter sends. - Mobile: creating a note does not open the keyboard; fields are 16 px (no iOS zoom). Opening a note asks the host for fullscreen; if the host refuses, a focus mode keeps only the quote, the field and a **Done** button above the keyboard. In fullscreen, **Done** shows the whole response at the note, still fullscreen, so you can go on to the next point; the send button or **Back to the conversation** returns inline. - English and French, following the host's locale. Light and dark, following the host's theme. - Links open through the host. Images are shown as links (the interface loads nothing remote). ## Privacy and security The text of Claude's responses goes through the server, and so do your notes whenever Claude quotes them back. Your notes themselves go from the interface to the conversation through the host, not through the server. The guarantees below hold for the code in this repository. The hosted server (`point-by-point.brols.workers.dev`) is run by the author, and nothing lets you check that it runs this code: using it means trusting the author, as you trust Anthropic with the conversation itself. To trust no one but Cloudflare, [run your own copy](#run-your-own-copy-of-the-server). What the code guarantees: - **No storage, no content logs.** No KV, D1, R2 or Durable Objects. The Worker logs a few diagnostic lines: the name of an error, each tool list or call from a client that does not show interfaces, and each 2025-protocol request (method name, protocol version, status, whether the client shows interfaces). These lines are built from fixed strings only: never the markdown or anything else from the request. Cloudflare keeps them for a few days (Workers Logs), without the request URLs or headers. - **No outbound calls**, from the server or the interface. Everything is inlined in one HTML file: no CDN script, font or image. The new conversation button only asks the host to open a link to claude.ai or chatgpt.com: the passage and the note in that link go to the app you are using, never to this server. - **Sanitised rendering.** Markdown goes through `marked` then DOMPurify with a strict allow-list; if DOMPurify cannot run, the text is shown as plain text, never as raw HTML. - **No authentication and no personal data.** A Cloudflare rate limit (1000 requests per minute per IP — generous, because claude.ai users share a few Anthropic egress IPs) caps abusive clients. - **Minimal, pinned dependencies** (exact versions, lockfile), reviewed before each update. - **MIT licence**, reproducible build from this repository. Drafts are kept in the interface's own `localStorage` (inside the host's sandbox, on your device) and deleted after a successful send. ## Development TypeScript monorepo, pnpm workspaces, Node 22+. ``` packages/ server/ Cloudflare Worker: MCP server (tool + interface resource) ui/ the annotation interface, built to a single HTML file plugin/ the plugin: skills/point-by-point, plus two manifests for the same plugin: .claude-plugin/plugin.json + .mcp.json (Claude), plugin.json + mcp.json (portable Agent Plugins format: ChatGPT, Codex) .claude-plugin/marketplace.json this repository as a plugin marketplace ``` ```sh pnpm install pnpm build # interface → packages/ui/dist/index.html, embedded into the Worker pnpm test # unit tests (segmentation, message format, drafts, server guards) pnpm e2e # Playwright: the built interface in a test host (desktop and mobile) pnpm dev # wrangler dev on http://localhost:8787/mcp pnpm --filter @point-by-point/ui shots # after a build: the README screenshots, light and dark ``` The server answers both MCP protocol eras without keeping state: 2026-07-28 requests carry the client capabilities in every request; for 2025 clients the session id handed out at `initialize` encodes whether the client renders interfaces. ### Testing in claude.ai The real iframe and host context only exist in a real host. Expose the dev server with a Cloudflare tunnel and add the tunnel URL as a custom connector: ```sh pnpm dev cloudflared tunnel --url http://localhost:8787 # add https://<random>.trycloudflare.com/mcp as a custom connector in claude.ai ``` ### Mobile diagnostic Ask Claude to call `annotate_response` with the markdown `/point-by-point-diagnostic`. Instead of a response, the widget shows the display modes and device capabilities the host announces, can request fullscreen, and can send its report back to the conversation. ### Deploy ```sh pnpm run deploy # builds, then wrangler deploy; prints the workers.dev URL ``` A fork deployed to another Cloudflare account gets its own URL: put it (with `/mcp`) in `plugin/.mcp.json` and in your custom connector. ### Release Bump `version` in `package.json`, `plugin/.claude-plugin/plugin.json`, `plugin/plugin.json` and `.claude-plugin/marketplace.json`, then push a `v<version>` tag. The release workflow runs every check, builds the interface under its versioned URI (a new URI per release, so no host serves a stale cached interface), deploys the Worker and attaches the skill archive to the GitHub release. The URIs of earlier releases keep being served, with the current interface, so widgets already in conversations keep loading. Deploying needs the `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` repository secrets; without them the release is still published, the deploy step is skipped with a warning, and the Worker is deployed by hand with `pnpm run deploy`. ## License [MIT](LICENSE)