npm package: @p2k0/agentlens-mcp
Description: AgentLens MCP Server - Local bridge between browser extension and AI assistants
Author: p2k0
Latest version: 3.1.0

# AgentLens MCP Server

## Local Bridge for AI Visual Perception

[<a href="./README_zh-CN.md">中文</a>] | English

AgentLens MCP Server is a local bridge that connects your AI Assistant (Cursor, Claude Desktop, Windsurf, etc.) with the AgentLens Browser Extension. It enables your AI to "see" visual feedback, bug reports, and DOM elements marked in the browser.

## Features

- **Visual Context**: Retrieve annotations, comments, and bug reports associated with specific DOM elements.
- **Snapshots**: Access visual snapshots (screenshots) of the reported issues.
- **Issue Management**: Mark issues as resolved directly from your IDE/AI chat.
- **Smart Analysis**: Auto-categorize feedback into Bugs, UI/UX issues, or Feature requests.

### Method 1: Quick Start (Recommended)

If you have Node.js, you can run it directly using `npx` (requires package published to NPM):

```json
{
	"mcpServers": {
		"agentlens": {
			"command": "npx",
			"args": ["-y", "@p2k0/agentlens-mcp"]
		}
	}
}
```

### Method 2: Manual Installation (Zip/Offline)

1. **Download**: Get `mcp-release.zip` from the [GitHub Releases](https://github.com/p2k0/agentlens/releases).
2. **Unzip**: Extract to a local directory (e.g., `~/agentlens-mcp`).
3. **Install Dependencies**:
   ```bash
   cd ~/agentlens-mcp
   npm install --production
   ```
4. **Configure**:

```json
{
	"mcpServers": {
		"agentlens": {
			"command": "node",
			"args": ["/absolute/path/to/agentlens-mcp/dist/index.js"]
		}
	}
}
```

## Available Tools

AgentLens MCP provides the following tools for AI to retrieve page context and manage annotations:

| Tool Name                  | Description                                                                                                                  | Parameters                                                                               |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `get_page_annotations`     | Retrieve all unresolved annotations for a URL. Returns structured JSON.                                                      | `url`: Page URL                                                                          |
| `get_annotation_snapshot`  | Get the visual snapshot (base64 image) for a specific annotation.                                                            | `url`: Page URL<br>`annotationId`: Annotation ID                                         |
| `get_annotations_markdown` | Get a token-efficient Markdown summary of annotations (optimized for LLM context).                                           | `url`: Page URL                                                                          |
| `analyze_annotations`      | Smart analysis to categorize issues (Bug/UI/UX/Feature) and sort by priority.                                                | `url`: Page URL                                                                          |
| `fix_page_issues`          | **Core Diagnostic Tool**: Generates a comprehensive report with visual context, CSS styles, and snapshots to guide AI fixes. | `url`: Page URL, `autoMode`: Enable auto analysis (default: true)                        |
| `resolve_annotation`       | Mark a specific annotation as resolved/fixed.                                                                                | `url`: Page URL, `annotationId`: Annotation ID, `resolution`: Fix description (optional) |
| `resolve_all_annotations`  | Batch mark _all_ unresolved annotations on a page as resolved.                                                               | `url`: Page URL, `resolution`: Batch fix description (optional)                          |
| `clear_annotations`        | Permanently delete all annotation records for a page (Use with caution).                                                     | `url`: Page URL                                                                          |

## Resources

- `agentlens://annotations/list`: Returns a JSON list of all URLs that have stored annotations.
- `agentlens://server/status`: Get Sidecar service runtime status (PID, Port, etc).
- `agentlens://store/raw`: Get full raw annotations.json data.