# @layerdock/mcp

Read your LayerDock website feedback — with the CSS selector, the screenshot,
and the console/network trace captured at report time — directly in your coding
agent. Fix the bug, reply on the thread, mark it resolved, without leaving the
editor.

## Setup

1. Create a token at https://www.layerdock.io/dashboard/integrations/mcp
2. **Warm the cache first**, once, in a terminal:

   ```bash
   npx -y @layerdock/mcp --version
   ```

   `npx` downloads the package on first use, and a cold download can take
   longer than an editor's MCP connect timeout (30s in Claude Code) — so the
   very first connection fails with `CONNECT_TIMEOUT` on a server that is
   working perfectly. Running it once puts it in the npx cache; every launch
   after that is instant. Skip this and you may simply need to restart your
   editor once.
3. Add the config for your client below.

The three clients below are the short version. The full walkthrough — config for
Claude Code, Cursor, Codex CLI, Antigravity, Windsurf, VS Code and Zed, how to
verify the connection, and what to check when the server does not appear — is at
https://www.layerdock.io/docs/connect-your-coding-agent

### Claude Code

`.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "layerdock": {
      "command": "npx",
      "args": ["-y", "@layerdock/mcp"],
      "env": { "LAYERDOCK_TOKEN": "ldk_..." }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` — same JSON as above.

### Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.layerdock]
command = "npx"
args = ["-y", "@layerdock/mcp"]
env = { LAYERDOCK_TOKEN = "ldk_..." }
```

## Tools

| Tool | What it does |
|---|---|
| `list_docks` | Your sites, with any codebase hints their owner declared (framework, source root, CMS) |
| `list_feedback` | Pins, filterable by status. **`dockId` is optional** — omit it to see open work across every dock you can reach, which is the whole answer to "what needs my attention?" in one call |
| `get_feedback` | One pin as a fix brief, plus the screenshot as an image. Takes `detail`: `auto` (default), `minimal`, `full` |
| `update_feedback_status` | Move a pin through the workflow |
| `reply_to_feedback` | Post a reply on the thread, attributed to you *and* labelled as coming via a coding agent |

## What `get_feedback` actually returns

A fix brief, ordered by how actionable each part is:

- **What the reporter wants changed**, plus the reply thread
- **The component**, when the reviewed site is a dev/unminified build — sometimes
  the source file and line
- **A repetition warning** when the pinned element is one of N identical
  siblings, so an agent doesn't hardcode a one-item fix into the shared
  component that renders all of them
- **A search string that actually matches source** — one contiguous run of
  literal text from a single text node, whitespace collapsed, never cut
  mid-word. This is deliberately *not* the element's `innerText`: that spans
  child nodes, so it carries newlines and fragments that appear in no source
  file and a literal grep for it never matches
- **Where it is** — page URL, section, CSS selector, and the full visible text
  marked explicitly as context rather than as something to grep for
- **Structure and computed styles** at pin time
- **Console errors and failed/slow requests** from the moment of capture, each
  stamped with how long before the report it happened
- **The screenshot**, as an image block the agent can actually look at —
  downscaled server-side, and when a pin has no capture the brief says so
  instead of instructing the agent to consult an image that was never attached

It also states what it *cannot* tell you — the brief never claims to know your
repository layout, and it instructs the agent to locate and confirm the file
before editing rather than guessing. That includes the case where the fix is not
in the repository at all: if the visible text appears nowhere in the codebase,
the content is probably CMS- or API-driven and the fix belongs in the content
source. Set a dock's `cms` field and the brief names the system directly.

### Payload size

`get_feedback` defaults to `detail: "auto"`. A pin that reads as a pure copy
change ("fix this wording") does not need ~20 computed CSS properties, device
memory, hardware concurrency and network downlink — so those are dropped, and
the brief says it dropped them. A layout or behaviour bug keeps everything. Pass
`detail: "full"` to override, or `"minimal"` to always trim.

## Permissions

The token acts as you, and says so. A reply posted through `reply_to_feedback`
is attributed to the person the token belongs to **and** labelled as arriving via
a coding agent — the reviewer reading the thread is deciding whether to re-check
the page themselves, and a person promising "fixed this" is not the same claim as
an agent asserting it. Both facts are stamped server-side from the authenticated
token, so neither can be chosen by the client. Do not sign the message text
yourself.

Anything you cannot do in the dashboard, the agent cannot
do either — role gating is enforced server-side, not here. A `member` who is not
assigned to a pin cannot change its status, and nobody can read a dock they have
no relationship to.

## Configuration

| Env var | Purpose |
|---|---|
| `LAYERDOCK_TOKEN` | Required. Your personal access token (`ldk_...`). |
| `LAYERDOCK_API_URL` | Optional. Defaults to `https://www.layerdock.io`. Point it at a local dev server when working on LayerDock itself. |

## Security

Tokens are stored as a SHA-256 hash — the plaintext is shown once, at creation,
and is never recoverable afterwards. Revoke a token from the same settings page;
revocation takes effect immediately.

An authentication failure names its actual cause — malformed, unknown, deleted,
or expired — and echoes the first 12 characters of the token the server received
(`received "ldk_AbCd-EfG…"`). That prefix is the same non-secret value the
dashboard already displays next to each token, and it is what tells a stale
client process still holding a replaced token apart from a genuinely bad one.

Note that on a dev build, `sourceFile` in a brief may be an absolute path from
the machine that built the reviewed site. That stays within the dock's own
trust boundary, but it is worth knowing before sharing a brief outside your team.

## License

MIT