Skip to main content
Glama

Loupe

Loupe is an open-source visual feedback tool. You pin comments to elements of a live web page, and an AI agent such as Claude Code picks them up over MCP (Model Context Protocol, the standard that lets an agent call external tools).

Screenshot of a Loupe comment thread with a screenshot, a reply with an @mention, and a thumbs-up reaction

Contents

Related MCP server: uigrep

What you can do

  • Pin feedback where it belongs. Comment on a single element, drag a region, or leave a free note on the page. Pins re-anchor after a redeploy: Loupe finds the same element again, even when its markup changes.

  • Capture what you see. Attach a screenshot or a short screen recording of a region. Elements marked with data-loupe-redact are left out of every screenshot. Screen recordings capture the real pixels, redacted elements included.

  • Discuss in threads. Reply under each comment, @mention teammates, and react with ๐Ÿ‘ ๐ŸŽ‰ ๐Ÿ‘€ ๐Ÿ™ โค๏ธ ๐Ÿš€.

  • Triage on a five-stage board. Move comments through Queue, To Do, In Progress, In Review and Resolved.

  • Hand the backlog to an agent. The @loupekit/mcp server gives Claude Code 19 tools, including list_comments, get_comment, propose_change and update_status. The Laravel package ships its own MCP server with those 4 core tools when the optional laravel/mcp package is installed (php artisan mcp:start loupe).

  • Run it inside Laravel. The loupekit/laravel package stores comments in your database, uses your authentication and gates, and serves the board on your routes.

  • Route tickets between apps. Loupe Hub, a separate server you host, sends a comment from one project to another in the same organization (a group of projects in Hub), and syncs status changes and replies both ways.

Choose how to install

Integration

Use it when

Guide

Script tag

You want the widget on any page without a build step.

Embed Loupe with a script tag

npm package

Your app uses a bundler: React, Vue, or any single-page app.

Install Loupe from npm

Laravel

Your app is built on Laravel 12 or 13.

Install Loupe in a Laravel app

Browser extension

You want to comment on a site you cannot change.

Use the browser extension

MCP clients

You want Claude Code, or another MCP client, to work through the comments.

Connect MCP clients

Local server and dashboard

You want the Node API and the Kanban board (columns that comment cards move across) on your machine.

Run the local server

Loupe Hub

You want to route tickets between several apps.

Self-host Loupe Hub

Try it in five minutes

This quick start runs the local server, leaves one comment on the demo page, and shows it on the board.

Prerequisites

  • Node 24. The local server runs its TypeScript files directly with node index.ts, which needs Node 24. Run node --version. You should see v24 followed by a minor version.

  • npm, which comes with Node.

  • git, to clone the repository.

Steps

  1. Clone the repository and move into it:

    git clone https://github.com/mohamed-ashraf-elsaed/loupe.git
    cd loupe

    Run every later command from this folder.

  2. Install the workspace dependencies:

    npm install

    You should see npm finish with an added ... packages summary.

  3. Build the packages:

    npm run build

    You should see the command finish with no line that starts with npm error.

  4. Create the demo project:

    npm run seed

    You should see Seeded project: pk_demo_acme, followed by an admin key line. The admin key is the project secret. The dashboard asks for it in its address. Its default value is sk_demo_acme_0f3b9c.

  5. Start the server:

    npm start

    You should see:

    [loupe] API + static on http://localhost:8787  (dashboard: /dashboard/ ยท demo: /demo/)

    Leave this terminal running.

  6. In your browser, open http://localhost:8787/demo/.

    You should see the Q3 Performance Overview page with the Loupe panel open on the right and a short tour. Click Next through the tour, then click Done.

  7. Leave a comment:

    1. In the panel, on the Home tab, click โœ› Pin feedback on this page.

    2. Click the Send invite button in the invite form.

    3. Type a title and a description, then click Comment.

    You should see a numbered pin, 1, on the Send invite button.

  8. In a new browser tab, open the board:

    http://localhost:8787/dashboard/?key=<ADMIN_KEY>

    Replace <ADMIN_KEY> with the admin key that npm run seed printed in step 4.

    You should see the board with five columns: Queue, To Do, In Progress, In Review and Resolved. Your comment is a card in the Queue column.

Troubleshooting

Symptom

Cause

Fix

npm start fails, or the server does not start on port 8787.

Another program is using port 8787.

Stop the other program, or start on another port with PORT=9000 npm start.

npm start fails on node index.ts.

Your Node version is older than 24.

Install Node 24, check it with node --version, then run npm start again.

Clicking Comment on the demo page fails.

You ran npm run seed with LOUPE_DEMO_SECRET set. The demo page signs requests with the default secret.

Unset LOUPE_DEMO_SECRET, run npm run seed again, then reload the demo page.

The board is empty.

You have not left a comment yet.

Do step 7, then reload the board.

Next steps

Packages

Package

Registry

What it is

@loupekit/sdk

npm

The embeddable widget: inspect, comment, capture, re-anchor.

@loupekit/shared

npm

Shared types, board stages and helpers used by every package.

@loupekit/mcp

npm (bin loupe-mcp)

The MCP server over stdio (standard input and output, which Claude Code uses to start and talk to a local server), plus a local bridge on 127.0.0.1: a small HTTP server that lets the widget reach the agent, for example in its Chat tab.

loupekit/laravel

Packagist

The Laravel package. Mirrored from packages/laravel to loupe-laravel.

Extension

Not published; load unpacked (see the guide)

The Manifest V3 browser extension. A private workspace.

Server

Not published; run from this repo

The Node API that also serves the dashboard and the demo.

Dashboard

Not published; run from this repo

The Kanban triage board.

Hub

Not published; run from this repo

Loupe Hub: organizations, projects and ticket routing. See How Loupe Hub works.

Documentation

Contributing

Author

Loupe is created and maintained by Mohamed Ashraf Elsaed, technical lead and backend architect in Cairo. Project page and more tools: mohamedashrafelsaed.com/projects/loupe/.

License

MIT ยฉ Mohamed Ashraf Elsaed. See LICENSE.

Available Tools

19 tools
add_thread_messageA

Reply on a thread without changing its status โ€” progress notes, questions, or the preview URL when it goes live. The status is left exactly as it was.

Inputs: message (required), thread_id (required).

create_pr_for_threadA

Open a pull request for a fix โ€” or, more usually, add it to the one the repo already has. One working branch per repo accumulates every fix as its own commit, and the PR body keeps a table of them. If that PR was merged or closed, a fresh branch is started automatically. Use get_element_context first to find the file, then pass the full new contents of each file you changed.

Inputs: repo (required), files (required), thread_id (required), description (required), +3 more.

find_source_for_selectionA

Just the ranked source files for the current selection or a stored thread โ€” for when you only need to know where the component lives. Heuristic: verify the top candidate before editing it.

Inputs: thread_id, selection_id.

get_activity_summaryA

What this machine's agent sessions have been doing: sessions, tool-call counts, files touched, and whether a session is still live. Use it to understand what has already been tried before starting, or to answer "what have you been working on?".

Inputs: limit, session_id.

get_commentA

Get the full context for one comment: the request, the page, the target element's HTML, and its computed styles โ€” everything needed to make the change.

Inputs: id (required).

get_companion_messagesA

Read what the person watching has said while you were working. Messages are ALSO delivered automatically on every other tool result, so you rarely need this โ€” use it when you want to check before finishing a task, or when someone asked you to wait for their input.

Inputs: drain.

get_dashboard_urlA

The local URL of the live activity dashboard โ€” a page a person can open to watch what the agent is doing right now. Give them this when they ask to see progress.

Inputs: no named parameters.

get_element_contextA

Full context for one element: the element, the page, its key computed styles, the ranked source files that probably render it, and a ready-made edit prompt. Pass thread_id to work from a stored comment, or nothing to use the latest live selection. Call this before editing anything.

Inputs: thread_id, selection_id, include_prompt.

get_files_touchedA

Every file the agent has touched in the recorded sessions, in first-seen order. Use it to see the blast radius of the work so far before adding to it.

Inputs: no named parameters.

get_latest_selectionA

What the user last selected in the browser, with its element, computed styles and the source files most likely to render it. Use this when someone says "this element" or "what I'm looking at" and no thread exists yet.

Inputs: no named parameters.

get_recent_eventsA

The raw agent event stream โ€” tool calls, prompts, session starts and stops โ€” newest first. Use it when you need to know exactly what has run, rather than a summary.

Inputs: type, limit.

get_selection_historyA

The recent element selections, newest first โ€” useful when the user clicked a few things and you need to pick the right one.

Inputs: limit.

get_thread_conversationA

The whole conversation on a thread: the original request, then every reply with its author. Read it before answering so you are not repeating something already said.

Inputs: thread_id (required).

install_agent_hooksA

Install the Claude Code hooks that report tool use, prompts and sessions to Loupe. Idempotent (running it twice changes nothing), backed up before writing, and it never touches another tool's hook entries. Opt-in: nothing installs these on its own.

Inputs: path.

list_commentsA

List Loupe product-feedback comments for the project as a task backlog. Each item carries its board stage, priority and change type, so you can start with the most urgent. Use this to see what a PM has flagged, then work through the items.

Inputs: url, repo, branch, status, +2 more.

mark_thread_addressedA

Hand a thread back to a human: it moves to In Review and, optionally, posts your closing note. Use this when the change is ready. It CANNOT resolve a thread โ€” only a person does that โ€” which is why there is no status argument.

Inputs: thread_id (required), message.

propose_changeA

Submit the modified UI for a comment: the rewritten HTML (and optional CSS) that resolves the PM's request. This stores your proposal on the comment so the dev team can review the code and a live preview in the dashboard. Use get_comment first to see the original element, its computed styles, and the screenshot.

Inputs: id (required), html (required), css, notes.

reply_to_companionA

Answer the person watching, in the panel they are looking at. Use this when a companion message needs a response, when you need a decision before continuing, or when you finish something they asked about.

Inputs: body (required), inReplyTo.

update_statusA

Move a comment along the board. Set In Progress when you start it, and In Review when the change is ready for a human โ€” only a person resolves a comment, so never set Resolved yourself.

Inputs: id (required), status (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.9/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools target distinct resources or actions, but there is some overlap among the context-gathering tools: get_element_context, get_comment, get_latest_selection, and find_source_for_selection can all return element or source context. The detailed descriptions help clarify when to use each, though an agent could still hesitate between get_comment and get_element_context with a thread_id.

    Naming Consistency5/5

    All tool names use snake_case and begin with a verb (get_, list_, update_, add_, create_, etc.), following a predictable verb_noun pattern. Minor variations like prepositions or abbreviations (create_pr_for_thread) are still consistent and readable.

    Tool Count4/5

    With 19 tools, the set is slightly heavy for a single server, but it covers several distinct domains: agent activity monitoring, companion messaging, feedback thread management, element selection, and PR creation. Each tool appears to earn its place, though the count is at the upper edge of what feels well-scoped.

    Completeness4/5

    The tools cover core workflows for activity tracking, companion chat, comment/thread interaction, element context retrieval, change proposals, and PR creation. A few gaps exist, such as creating or deleting comments directly and searching/filtering comments, but agents can work around these in most scenarios.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables visual browser feedback collection directly into Claude Code. Users can point at elements in their browser and send annotated feedback that Claude can act on immediately.
      12
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Bridges UI feedback captured by a browser extension on localhost apps into a Claude Code session, queueing picked elements, comments and rewrite requests as batches that the coding agent can claim and act on. It also lets Claude report progress and per-item results back to the extension, and can import batches exported as JSON.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to search your team's design and issue comment threads from Figma, Jira, and Notion, answer questions with citations, surface feedback relevant to the code you're editing, and post replies or close threads after your confirmation.
      MIT