Maple

@maple-kit/mcp

The Model Context Protocol server that hands a coding agent the review comments Maple collected on a preview deployment.

Pre-release. Every package here is 0.x and makes no compatibility promise.

[A terminal: the agent waits for comments, receives one naming a file and line, edits one line, and resolves the comment in a commit.]

The agent waits for a comment, reads it with its context — file:line from the tagger, the viewport, the screenshot, the mock it was written under — makes the change, and resolves it against the commit that fixed it. The reviewer's half is the overlay; the two meet in the store.

Install

npm install @maple-kit/mcp

Two binaries ship: maple-mcp, the server, and maple-stop-hook, which stops an agent from calling itself finished while comments are still open.

Connect an agent

A client starts the server with no arguments, so it is configured through the environment. In Claude Code's .mcp.json:

{  "mcpServers": {    "maple": {      "command": "npx",      "args": ["-y", "-p", "@maple-kit/mcp", "maple-mcp"],      "env": { "MAPLE_GITHUB_OWNER": "acme", "MAPLE_GITHUB_REPO": "web" }    }  }}

and run the client under op run --env-file so GITHUB_TOKEN never lands in a file. A missing value fails at startup rather than on the first tool call.

With no forge

Set none of GITHUB_TOKEN, MAPLE_GITHUB_OWNER and MAPLE_GITHUB_REPO and the server reads and writes the comments fileStore() keeps under .maple/ in its working directory's repository, so the loop works on a laptop with no pull request. MAPLE_STORE=file says so explicitly. It is a laptop's store, not a preview pod's: docs/connectors.md has the argument. The Stop hook reads the same folder for the branch checked out in the session's working directory, and stays silent where there is no .maple/ folder, no comments for the branch or no repository.

Tools

wait_for_comments is clamped to 55 seconds because every coding client cuts a tool call off at 60, and it emits notifications/progress every 15 seconds. A timeout is a result: an agent that treats one as an error stops looping the first time nobody is looking. Its cursor is a timestamp; omit it on the first call to drain whatever is already waiting.

The Stop hook

MCP gives a server no way to interrupt a client, so the loop is closed from the other end. Claude Code's Stop hook runs when the agent believes it is finished, and Maple's answers with the comments still open:

{  "hooks": {    "Stop": [      { "hooks": [{ "type": "command", "command": "npx -y -p @maple-kit/mcp maple-stop-hook" }] }    ]  }}

The Maple Claude Code plugin registers it for you. It blocks while a comment is open or needs_reverify, at most eight stops in a row per session; on the ninth it lets the session end and says what is still open, which beats an agent resolving comments to escape. The count is kept per session_id in the system temp directory, and a stop no block caused starts it again.

The hook does not see .mcp.json's env. That block is handed to the MCP server alone; a hook runs in the client's own environment. So MAPLE_GITHUB_OWNER, MAPLE_GITHUB_REPO and GITHUB_TOKEN have to be set where the client itself starts — under the same op run --env-file — or the hook fails naming the one missing. With neither of the first two set, it reads the comments under .maple/ for the current branch instead, and lets every stop through where there are none. MAPLE_BRANCH defaults to the branch checked out in the session's working directory.

Resolving clears the gate

[A pull request's checks: maple/visual-review fails with two comments open, they resolve, the check passes and the merge button wakes up.]

With MAPLE_URL set to a deployed route's mount URL, such as https://web-482.preview.acme.dev/api/maple, resolve_comment asks that route to republish maple/visual-review, so an agent that resolves the last comment with nothing left to push does not leave the check holding on finished work. The request carries the branch and GITHUB_TOKEN, which must be able to push to the repository. The route decides the verdict and publishes with the gate App's own credentials, which never leave it. A failed refresh is logged to stderr and the resolve is still recorded.

MAPLE_GATE_TOKEN is the other way, for CI: a gate App installation token the server publishes with directly. It expires an hour after it is minted, so it suits a job, not a session. Setting both fails at startup.

Documentation

• The agent loop
• The merge gate
• The maple-review skill turns a pull request's ```maple comments into a worklist without the server.

Licence

Apache-2.0. See LICENSE and NOTICE.