maple
OfficialMaple's MCP server lets an agent read, wait on, contextualize, and resolve visual review comments left on a deployed preview's branch.
List review comments (
list_comments): fetch comments on a branch newest-first, optionally filtered toopen,resolved,needs_reverify, ororphaned.Wait for new comments (
wait_for_comments): long-poll (clamped to 55s) until a comment arrives or the wait elapses, using a timestamp cursor to fetch only newer comments; returnstimeoutinstead of failing.Get a comment's context (
get_comment_context): retrieve the anchor, viewport, surrounding markup, and any replay link needed to act on one comment, includingmock.recipe/mock.replayfor comments written under a Maple Mock.Resolve a comment (
resolve_comment): mark a comment resolved against the commit sha believed to address it, with an optional note for the reviewer.Start solo mode (
start_solo): open a localhost bridge and return a pairing link for one preview origin, so a reviewer's comments land in.maple/for the list/wait tools to read, without counting toward the merge gate.
All tools run inline (task support forbidden); list, wait, and get-context are read-only, while resolve and start_solo mutate state.
Provides a merge gate and reviewer identity on GitHub: reviewers sign in through GitHub Device Flow so every comment is written as its author (no secret in the preview), and a maple/visual-review GitHub check fails while any visual comment is unresolved—optionally until a reviewer approves—holding the pull request merge until reviews are resolved.
A reviewer points at something on a preview deployment and says what is wrong. Maple captures where they pointed, what they were looking at and who they are, hands it to a coding agent in a form it can act on, and holds the merge until every comment is resolved.
Status: 0.x. All eight packages are published, with provenance, through a trusted publisher. 0.x makes no compatibility promise: a public interface is broken when breaking it is the right shape, and the changeset says what broke.
How it works
Mount: One route in your application, and one script in the preview build.
Comment: A reviewer points to an issue on the app. Maple records all the context needed for the agent to pick it up.
Fix: Your agent monitors new comments via the MCP, implements a fix and marks it as resolved.
Gate: A CI check holds the merge until all comments are resolved, and all visual gates pass.
Code got fast. Planning, definitions of done and edge cases did not, so they get skipped and surface in testing. Maple moves that review to the preview, where the comment can still be acted on.
Related MCP server: redpen
What it does
Each package's README shows the rest: the CLI, the design lint, flags and roles in a mock and the connectors.
Why another one
Pincushion, Vercel Toolbar, Chromatic, BugHerd and Marker.io each do some of this. None combines all four of:
Open source, Apache-2.0, with no hosted service required.
Deployed previews. Maple runs on the preview URL your CI already builds, so anyone with the link can comment — a designer, a product manager, a client. Tools like Agentation run against
localhost, which means the only person who can leave a comment is the person running the build.A merge gate — CI blocks while a visual comment is unresolved, and optionally until somebody says they looked. See
docs/gate.md.An agent loop — the agent reads comments, fixes, and resolves them.
Pick a setup
The SDK route has no default store: without one, its comment endpoints answer 404. Smallest setup first:
Add it to an app
The quickest wiring, for trying Maple on your own machine. Sharing a preview needs a store per reviewer: see Pick a setup.
npm install @maple-kit/core @maple-kit/ui @babel/core@babel/core is an optional peer, and the tagger is what needs it: leave it out
and tagger: true has nothing to transform with.
Mount the route and the tagger from the build, then render the overlay:
// vite.config.ts
import { createCommentStore } from "@maple-kit/core";
import { githubStore } from "@maple-kit/core/connectors";
import { maple } from "@maple-kit/core/vite";
const preview = process.env.MAPLE_PREVIEW === "1";
export default defineConfig({
plugins: [
react(),
maple({
tagger: preview,
route: {
// Local trial only: every comment is written as this one token.
// The route has no default store; without one its comment endpoints 404.
store: createCommentStore(
githubStore({ owner: "acme", repo: "web", token: process.env.GITHUB_TOKEN! }),
),
},
}),
],
});// main.tsx
import { Maple } from "@maple-kit/ui/maple";
createRoot(root).render(
<>
<App />
<Maple branch={import.meta.env.VITE_MAPLE_BRANCH} />
</>,
);The shared GITHUB_TOKEN is for a local trial only. A preview other people
review builds the store per request from each reviewer's own token, through the
resolver in docs/github-auth.md, so a comment is
authored by whoever wrote it and no GitHub secret sits in the preview.
Next.js uses withMaple from @maple-kit/core/next and a catch-all route at
app/api/maple/[...maple]/route.ts; examples/next-app
has both. The setup-maple-org skill walks through the GitHub App a reviewer
signs in with.
Use with Claude Code
The Maple plugin bundles the skills that set Maple up and act on its comments, the MCP server that reads and resolves them, and the Stop hook that keeps an agent working while they are open:
/plugin marketplace add maple-kit/maple
/plugin install maple@maple-kitThe server and the hook read GITHUB_TOKEN, MAPLE_GITHUB_OWNER and
MAPLE_GITHUB_REPO from the environment Claude Code starts in. In a project
where the last two are unset, the hook lets every stop through.
To install only the skills, for Claude Code or any other agent the
skills CLI supports, run npx skills add maple-kit/maple.
Vendor-agnostic by construction
Maple stores nothing itself. A connector is one file implementing plain Promise-returning methods:
import type { StoreConnector } from "@maple-kit/core/connectors";
export function myStore(options: MyOptions): StoreConnector {
return {
name: "my-store",
async list(query) {
/* … */
},
async append(comment) {
/* … */
},
};
}There are six kinds — store, media, observability, identity, gate and
classifier — and a connector's capabilities are exactly the methods it defines.
Run maple connectors to print the matrix from the code, or see
docs/connectors.md.
Packages
Package | What it is |
Server SDK, overlay controller, connector contracts, build plugins. | |
The marks, the island and the composer: the overlay a reviewer uses. | |
Hooks over the controller, for an overlay in your own design system. | |
The MCP server an agent talks to, and a Stop hook. | |
The | |
Rewrites a page's API responses, flags and role into a named state. | |
Scores a comment as it is written, and plans a mock from a sentence. | |
Design-system rules read off the page the browser laid out. |
Documentation
maple review: the overlay on a running app, nothing wired inConfiguration: every environment variable, and which are secrets
Preview environments: tell Maple which session a deployment serves, starting with mirrord
Examples: Vite and Next: real applications Maple mounts into
The CLI:
review,solo,setup,connectors,mock plan
Solo mode: a guest's comments on their own machine
Drafts and publishing: why a comment is unsent until it is not
The JSX tagger: how a comment becomes
file:lineAnchoring a region: how a dragged box finds its content again
Screenshots: the picture taken at pick time
Replies: decided, not built
The agent loop: the MCP tools and the Stop hook
@maple-kit/mcp: the server and the hooksetup-maple-agent-loop: connect and verify an agentmaple-review: turn a pull request's comments into a worklist
The merge gate: what blocks a merge, what approving does, which App to pin
Maple Mock: a model picks the state, code writes every byte
@maple-kit/mock: flags, roles and the runtimeThe assist tier: what a score is, and what it is never allowed to be
@maple-kit/classifier: scoring and mock planningDesign lint: the rendered rules and the tiers around them
@maple-kit/lint: the rules as a package
@maple-kit/core: server SDK, overlay controller, connector contracts@maple-kit/ui: the overlay a reviewer uses@maple-kit/react: hooks for an overlay in your own design systemcontribute-connector: scaffold a connector and run the contract suite
Deploying Maple in an organisation: trust boundaries and a hardening checklist
GitHub authentication: Device Flow, the two Apps, the cookie, revocation
setup-maple-org: register and install the AppThe overlay and CSP: what Maple asks of your policy
What a comment carries: the page text a comment stores
SECURITY.md: reporting a vulnerability
Releasing: changesets, trusted publishing, a new package name
Evals, with cases for assist, doc drift and mock plans
Demo recorder: how the clip above is made
Ported helpers, network mocks and the AI tier notes
Security
Report a vulnerability privately, as SECURITY.md describes. To run
Maple in an organisation, read docs/security.md: who
trusts what, which secrets exist where, and a checklist to work through before a
preview is shared.
See it running
The project site is maple-kit.org. To run the Vite example yourself:
nvm use
pnpm install
pnpm --filter @maple-kit/example-vite dev # http://localhost:5173A real Vite application with three comments already on it: marks on the page,
the island in the corner, and all three picks working against an SDK route the
dev server mounts. examples/vite-app says what it does
and does not prove.
Development
nvm use # or fnm use, mise install — .nvmrc pins the version
pnpm install
pnpm hooks
pnpm lint && pnpm typecheck && pnpm testRequires Node 24, the active LTS, and pnpm 10. Switch before the install:
pnpm 10 and 11 load node:sqlite, which Node 23 does not have, so on the wrong
version pnpm crashes rather than telling you the version is wrong. See
CONTRIBUTING.md.
Licence
Apache-2.0. Contributions are accepted under the
Developer Certificate of Origin — sign off with git commit -s. There is
no CLA.
Available Tools
5 toolsget_comment_contextGet a comment's contextARead-only
Return everything needed to act on one comment: anchor, viewport, surrounding markup and any replay link. A comment written under a Maple Mock carries mock.recipe and mock.replay, a link to the page in that state.
Inputs: id (required), branch (required).
list_commentsList review commentsBRead-only
Return the review comments on a branch, newest first.
Inputs: branch (required), statuses.
resolve_commentResolve a review commentB
Mark a comment resolved, recording the commit that addressed it.
Inputs: id (required), sha (required), note.
start_soloKeep a preview's comments on this machineA
Start a bridge on localhost and return the link that pairs a deployed preview with it. The reviewer opens the link in their browser and the comments they write there land in .maple/ for list_comments and wait_for_comments to read. They never count toward the merge gate.
Inputs: previewUrl (required).
wait_for_commentsWait for review commentsARead-only
Block until a new comment arrives or the wait elapses. Returns status "timeout" rather than failing when nothing arrives.
Inputs: branch (required), cursor, timeoutMs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation in the review-comment workflow: listing existing comments, blocking for new ones, resolving a comment, fetching detailed context for one comment, and starting a local bridge. There is no meaningful overlap between these purposes.
All tool names use snake_case and follow a verb-led pattern (list_comments, wait_for_comments, resolve_comment, get_comment_context, start_solo). The convention is consistent throughout.
Five tools is well-scoped for a specialized review-comment bridge server. Each tool serves a clear, non-redundant role in the workflow.
The surface covers reading, waiting for, resolving, and getting context on comments, plus starting the bridge. Minor gaps exist, such as no explicit unresolve or reply operation, but core workflows are fully supported.
Maintenance
Related MCP Connectors
Comment on AI-generated webpages; feedback flows back to your coding agent. Free, MIT, local-first.
Visual feedback from your website's visitors as tasks for your coding agent.
Read, reply to and resolve website feedback threads from your coding agent.
Client feedback on websites, images and PDFs: read, answer and pin comments from your AI agent.
Related MCP Servers
- AlicenseAqualityBmaintenanceTurns product feedback pinned to a live UI into an actionable backlog for Claude Code — list comments, open one with its target element's HTML, computed styles and screenshot, and update its status.1971,500,813 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to capture pixel-accurate screenshots and DOM state from localhost apps, receive user-drawn instructions and reference images, and manage implementation review cycles.7 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to pull structured UI feedback captured in the browser — including element selectors, bounding boxes, computed styles, screenshots, and annotations — and to mark issues as fixed.MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to read locally submitted code-review comments and diff context over MCP, so they can fix the code and request another review.Apache 2.0