Annot 网站反馈 MCP 服务器

annot-mcp

An MCP (Model Context Protocol) server for Annot — receive website feedback and apply changes directly from your IDE.

What it does

Annot lets stakeholders leave visual feedback on live websites. This MCP server connects your AI coding assistant (Cursor, Windsurf, Claude Desktop, etc.) to Annot so you can:

• List pending changes — see all feedback ready to be applied
• Get change details — retrieve the full generated prompt with context (element selectors, styles, screenshots)
• Track progress — mark changes as processing, applied, or failed

Setup

1. Get an API key

Generate an API key from your Annot account settings page.

2. Configure your MCP client

Add the following to your MCP client configuration.

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "annot": {
      "command": "npx",
      "args": ["-y", "annot-mcp"],
      "env": {
        "ANNOT_API_KEY": "ak_your_api_key_here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "annot": {
      "command": "npx",
      "args": ["-y", "annot-mcp"],
      "env": {
        "ANNOT_API_KEY": "ak_your_api_key_here"
      }
    }
  }
}

3. Start using it

Ask your AI assistant to check for pending changes:

"Check Annot for any pending feedback changes"

Available tools

Batch workflow

For multiple changes on one project, prefer the batch tools over the single-item flow:

flowchart LR
  claim["claim_changes"] --> work["Apply changes in IDE"]
  work --> complete["complete_changes"]

1. claim_changes(project_id) — atomically claim up to 20 ready briefs. Returns each brief_id with its full generated_prompt. Claimed briefs are already processing; do not call start_change on them.
2. Apply the changes in your IDE.
3. complete_changes(results) — report each brief as applied or failed, with optional notes or error messages.

Do not mix paths on the same brief: if you claimed it in a batch, finish it with complete_changes (or the single-item tools), not start_change.

For one-off changes, use the single-item flow: list_pending_changes → get_change_details → start_change → complete_change / fail_change.

Automation

Projects can be configured with automation modes that affect how briefs flow through the MCP server:

• Auto-stage — when enabled, new feedback briefs appear in list_pending_changes automatically, with no manual staging step.
• Auto-resolve — when enabled, completing a change with complete_change may resolve the underlying Annot comment automatically. The tool response includes "Comment resolved automatically." when this happens.

Use list_projects to see each project's auto_stage and auto_resolve settings. In list_pending_changes, briefs include a Source field (auto or manual) when available so you can tell how they were created.

Environment variables

Publishing

This package is published manually to npm. From a clean checkout:

1. npm version patch (or minor / major as appropriate)
2. npm publish --access public — runs prepublishOnly (npm run build then scripts/check-endpoint.mjs, which fails the publish if dist/api.js does not point at the production Supabase project)
3. git push --follow-tags

License

MIT