# Loupe

> Loupe is an open-source visual feedback tool: reviewers pin comments, screenshots and screen recordings to elements of a live web page, a team triages them on a five-stage board, and AI agents read and act on them through the Model Context Protocol (MCP).

Key facts for Loupe 0.15.0:

- New here: start with the first-comment tutorial below, then pick the install guide for your stack: script tag, npm, Laravel or the browser extension.
- License: MIT.
- Languages: TypeScript (npm workspaces monorepo) and PHP (Laravel package).
- Published packages: `@loupekit/sdk` (embeddable widget), `@loupekit/shared` (types and helpers) and `@loupekit/mcp` (MCP server, binary `loupe-mcp`) on npm, and `loupekit/laravel` on Packagist (PHP ^8.2, Laravel 12 and 13).
- The browser extension, the local server, the dashboard and Loupe Hub are not published to npm. Run them from a checkout of the repository.
- Running from source requires Node.js 24. The server, Hub and MCP packages run `.ts` files directly with Node's built-in type stripping.
- The extension is a Manifest V3 extension, loaded unpacked from `packages/extension`.
- Every comment moves through five stages: queue, todo, in_progress, in_review, resolved.
- Agents are told to stop at in_review and leave resolving to a person. In the Node MCP server this is enforced: `mark_thread_addressed` cannot resolve, and `update_status` refuses resolved (since 0.14.1). The Laravel MCP server's `update_status` still accepts resolved, so there it is guidance only.
- The Node MCP server (`@loupekit/mcp`) exposes 19 tools.
- The Laravel MCP server exposes 4 tools: list_comments, get_comment, propose_change, update_status. Start it with `php artisan mcp:start loupe`. It needs the `laravel/mcp` package.
- The endpoints `GET /v1/org` and `GET /v1/activity` exist only in the Laravel package, under its route prefix (config key `loupe.path`, env `LOUPE_PATH`, default `loupe`). The local server does not serve them.
- Loupe Hub is a self-hosted service that groups projects into organizations and forwards tickets between them.
- Each Hub project has a project secret (`psk_`, signs traffic between the app and Hub), a webhook signing secret (`whs_`, signs deliveries to an external webhook), an optional inbound URL (where a Loupe app receives tickets) and an optional webhook URL (for a system that is not a Loupe app). A project's destination is the project its tickets go to.
- Hub delivers each ticket to the destination project's inbound URL, signed with the destination's project secret. If no destination with an inbound URL is set, it posts to the source project's webhook URL, signed with the webhook signing secret. With neither, it answers `202` with `delivery: "none"`.
- Repository: https://github.com/mohamed-ashraf-elsaed/loupe
- Site: https://loupe.mohamedashrafelsaed.com/

## Docs

- [Documentation index](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/README.md): every guide, reference page and explanation, grouped by task and by integration.
- [Leave your first comment locally](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/tutorials/first-comment-local.md): tutorial; run the local server and demo, then pin a comment on a page.
- [Route tickets between two projects with Loupe Hub](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/tutorials/hub-two-projects-local.md): tutorial; run Hub locally and send a ticket from one project to another.
- [Embed the widget with a script tag](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/embed-script-tag.md): load the IIFE (self-contained script-tag) build and call `Loupe.init()` without a build step.
- [Install the SDK from npm](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/install-npm.md): add `@loupekit/sdk` to a bundled app and call `init()`.
- [Install the Laravel package](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/laravel-install.md): `composer require loupekit/laravel`, `php artisan loupe:install`, migrate, and render `@loupeWidget`.
- [Authorize who can use Loupe in Laravel](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/laravel-authorize.md): control widget and dashboard access outside the `local` environment.
- [Use the browser extension](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/browser-extension.md): build and load the unpacked extension, then start Loupe on any tab.
- [Connect MCP clients](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/connect-mcp-clients.md): give an AI agent access to comments through `@loupekit/mcp`.
- [Run the local server](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/run-local-server.md): start the API, dashboard and demo on port 8787.
- [Use the widget](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/use-the-widget.md): pin, record, reply to and resolve feedback in the panel.
- [Self-host Loupe Hub](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/hub-self-host.md): deploy Hub on a server you control.
- [Manage Hub organizations and projects](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/hub-manage-projects.md): add members, create projects and rotate secrets.
- [Connect apps to Hub](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/hub-connect-apps.md): send tickets from one app to another through Hub.
- [Verify Hub webhook signatures](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/verify-hub-webhooks.md): check that a delivery came from your Hub.
- [Upgrade Loupe](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/how-to/upgrade.md): move to a new version and refresh assets and migrations.
- [SDK reference](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/reference/sdk.md): `init()` options, public functions and HTTP calls.
- [Laravel package reference](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/LARAVEL.md): config keys, routes, events, migrations and Artisan commands.
- [MCP server reference](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/reference/mcp.md): the 19 tools, environment variables and the local bridge.
- [Local server reference](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/reference/server.md): endpoints, environment variables and Slack/Telegram integrations.
- [Loupe Hub reference](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/reference/hub.md): signed API, environment variables and dashboard routes.
- [Browser extension reference](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/reference/extension.md): permissions, context menus and stored settings.
- [Shared types reference](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/reference/shared.md): types, constants and helpers in `@loupekit/shared`.
- [How Loupe Hub works](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/explanation/hub.md): organizations, routing and two-way sync.
- [Authentication and privacy](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/explanation/auth-and-privacy.md): identity checks, signatures and what leaves the page.
- [Troubleshooting](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/troubleshooting.md): symptoms, causes and fixes for every integration.

## Optional

- [Changelog](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/CHANGELOG.md): what changed in each version, in Keep a Changelog format.
- [Architecture](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/ARCHITECTURE.md): how the packages fit together, the re-anchoring algorithm and where data flows.
- [Single-page guide](https://loupe.mohamedashrafelsaed.com/guide/): the whole guide as one HTML page.
- [Testing](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/TESTING.md): run the test suites and read what each one covers.
- [Contributing](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/CONTRIBUTING.md): set up the repository and open a pull request.
- [Releasing](https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/RELEASING.md): version, tag and publish a release.

## Author

- Creator and maintainer: Mohamed Ashraf Elsaed.
- Website: https://mohamedashrafelsaed.com
- Project page: https://mohamedashrafelsaed.com/projects/loupe/
- GitHub: https://github.com/mohamed-ashraf-elsaed
- LinkedIn: https://www.linkedin.com/in/mohamedashrafelsaed/