@loupekit/mcp 0.14.0-next.80 → 0.14.0-next.82
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +186 -75
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,121 +1,232 @@
|
|
|
1
|
-
|
|
1
|
+
# @loupekit/mcp
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@loupekit/mcp)
|
|
4
|
+
|
|
5
|
+
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
`@loupekit/mcp` is an MCP (Model Context Protocol) server for [Loupe](https://github.com/mohamed-ashraf-elsaed/loupe). It gives a coding agent, such as Claude Code, the visual feedback that people pin on your site. For each comment the agent gets the request, the target element's HTML and computed styles, and the screenshot.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
as an actionable, fully-contextualized backlog — request + element HTML + styles + screenshot.</p>
|
|
9
|
+
The server talks to your MCP client over stdio: the client starts the server as a child process and exchanges messages with it over standard input and output.
|
|
11
10
|
|
|
12
|
-
|
|
13
|
-
<a href="https://www.npmjs.com/package/@loupekit/mcp"><img src="https://img.shields.io/npm/v/@loupekit/mcp?color=4a55d6&label=npm" alt="npm version" /></a>
|
|
14
|
-
<a href="https://www.npmjs.com/package/@loupekit/mcp"><img src="https://img.shields.io/npm/dm/@loupekit/mcp?color=4a55d6" alt="npm downloads" /></a>
|
|
15
|
-
<img src="https://img.shields.io/npm/l/@loupekit/mcp?color=4a55d6" alt="MIT license" />
|
|
16
|
-
<img src="https://img.shields.io/badge/MCP-stdio-4a55d6" alt="MCP stdio server" />
|
|
17
|
-
<a href="https://glama.ai/mcp/servers/mohamed-ashraf-elsaed/loupe"><img src="https://glama.ai/mcp/servers/mohamed-ashraf-elsaed/loupe/badges/score.svg" alt="Loupe MCP server on Glama" /></a>
|
|
18
|
-
</p>
|
|
11
|
+
> **Warning — known issue in 0.14.0:** the published package fails to start with `ERR_MODULE_NOT_FOUND` for `@loupekit/shared`. This affects `npx -y @loupekit/mcp` and the global `loupe-mcp` command. The compiled server imports `@loupekit/shared` at runtime, but the package lists it only as a development dependency, so npm does not install it. Until a fixed release is out, follow [Install from a source checkout](#install-from-a-source-checkout).
|
|
19
12
|
|
|
20
|
-
|
|
21
|
-
<a href="https://mohamed-ashraf-elsaed.github.io/loupe/"><b>Website</b></a> ·
|
|
22
|
-
<a href="https://mohamed-ashraf-elsaed.github.io/loupe/guide/"><b>Docs</b></a> ·
|
|
23
|
-
<a href="https://github.com/mohamed-ashraf-elsaed/loupe"><b>GitHub</b></a> ·
|
|
24
|
-
<a href="https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/CHANGELOG.md"><b>Changelog</b></a> ·
|
|
25
|
-
<a href="https://www.npmjs.com/package/@loupekit/sdk"><b>SDK</b></a>
|
|
26
|
-
</p>
|
|
13
|
+
## Contents
|
|
27
14
|
|
|
28
|
-
|
|
15
|
+
- [Prerequisites](#prerequisites)
|
|
16
|
+
- [Install](#install)
|
|
17
|
+
- [Configure your MCP client](#configure-your-mcp-client)
|
|
18
|
+
- [Verify](#verify)
|
|
19
|
+
- [Tools at a glance](#tools-at-a-glance)
|
|
20
|
+
- [Environment](#environment)
|
|
21
|
+
- [The bridge and the /monitor page](#the-bridge-and-the-monitor-page)
|
|
22
|
+
- [Troubleshooting](#troubleshooting)
|
|
23
|
+
- [Links](#links)
|
|
24
|
+
- [License](#license)
|
|
29
25
|
|
|
30
|
-
|
|
26
|
+
## Prerequisites
|
|
31
27
|
|
|
32
|
-
|
|
28
|
+
- **Node.js 24 or later.** The package is built for Node.js 24. It does not declare an `engines` field, so npm does not warn you on an older version.
|
|
29
|
+
- **A running Loupe server.** This is the backend that stores comments and serves the API the MCP server calls, for example the Node server `@loupekit/server`. To run one on your machine, see [Run the local server and dashboard](https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/docs/how-to/run-local-server.md).
|
|
30
|
+
- **A project key and its project secret.** A *project* is the unit Loupe groups comments under. It has a public *project key*, such as `pk_demo_acme`, and a private *project secret*. The project secret is the admin key: the server accepts it in the `X-Loupe-Admin` header. For the demo project that `npm run seed` creates, the key is `pk_demo_acme` and the seed prints the secret as `admin key`.
|
|
31
|
+
- **An MCP client**, such as Claude Code.
|
|
32
|
+
- **git and npm**, to install from a source checkout while the 0.14.0 issue is open.
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
[Loupe SDK](https://www.npmjs.com/package/@loupekit/sdk) or browser extension. This MCP
|
|
36
|
-
server lets **Claude Code read that feedback**, open each comment with everything needed to
|
|
37
|
-
make the change, and flow the status back when the work is done — closing the loop.
|
|
34
|
+
## Install
|
|
38
35
|
|
|
39
|
-
|
|
40
|
-
<img src="https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/store/screenshot-3-claude.jpg" alt="Claude Code reading Loupe comments via MCP" width="90%" />
|
|
41
|
-
</div>
|
|
36
|
+
### Install from a source checkout
|
|
42
37
|
|
|
43
|
-
|
|
38
|
+
Use this method for 0.14.0.
|
|
44
39
|
|
|
45
|
-
|
|
46
|
-
the target element (stable id / CSS path), its outer HTML, a curated slice of computed
|
|
47
|
-
styles, and a screenshot URL. No more _"the header looks off somewhere"_ — Claude knows the
|
|
48
|
-
element, its state, and the page.
|
|
40
|
+
1. Clone the repository:
|
|
49
41
|
|
|
50
|
-
|
|
42
|
+
```bash
|
|
43
|
+
git clone https://github.com/mohamed-ashraf-elsaed/loupe.git
|
|
44
|
+
```
|
|
51
45
|
|
|
52
|
-
|
|
53
|
-
| --- | --- |
|
|
54
|
-
| `list_comments(status?, priority?, changeType?, repo?, branch?, url?)` | List comments, optionally filtered by stage (`queue` / `todo` / `in_progress` / `in_review` / `resolved`), priority (`critical` / `high` / `medium` / `low`), change type (`frontend` / `backend` / `api` / `other`), repository, branch or page URL. The legacy status names `open` / `done` are accepted too. |
|
|
55
|
-
| `get_comment(id)` | The full Claude-ready package for one comment: request + element HTML + computed styles + the **screenshot as an image** + any screen-recording URL. |
|
|
56
|
-
| `propose_change(id, html, css?, notes?)` | Write your **modified HTML/CSS** back onto the comment. The dashboard renders it as code plus a live before/after preview for the dev team. |
|
|
57
|
-
| `update_status(id, status)` | Move a comment along the board (`queue` → `todo` → `in_progress` → `in_review` → `resolved`) so triage state stays in sync. Move to `in_review` when a change is ready — only a person resolves. |
|
|
46
|
+
You should see a new `loupe` folder.
|
|
58
47
|
|
|
59
|
-
|
|
48
|
+
2. Go into the folder:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
cd loupe
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
3. Install the dependencies:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm install
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The command finishes without errors and creates `node_modules`.
|
|
61
|
+
|
|
62
|
+
4. Build the shared package:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
npm run build:shared
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
You should see `tsc -p tsconfig.json` in the output, and the command exits without errors.
|
|
69
|
+
|
|
70
|
+
5. Print the full path of the folder:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
pwd
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
You should see an absolute path that ends in `/loupe`. You use it as `<ABSOLUTE_PATH_TO_LOUPE>` when you configure your client. Node.js 24 runs the TypeScript entry `packages/mcp/index.ts` directly, so you do not need to build the MCP package.
|
|
77
|
+
|
|
78
|
+
### Install from npm
|
|
79
|
+
|
|
80
|
+
Use this method once a release that fixes the 0.14.0 issue is out.
|
|
81
|
+
|
|
82
|
+
Run it without installing:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
npx -y @loupekit/mcp
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Or install it globally. This adds the `loupe-mcp` command:
|
|
60
89
|
|
|
61
90
|
```bash
|
|
62
|
-
npm
|
|
91
|
+
npm install -g @loupekit/mcp
|
|
63
92
|
```
|
|
64
93
|
|
|
65
|
-
|
|
66
|
-
> `@mohamed-ashraf-elsaed:registry=https://npm.pkg.github.com` to your `.npmrc` to install from there.
|
|
94
|
+
## Configure your MCP client
|
|
67
95
|
|
|
68
|
-
|
|
96
|
+
Add a `loupe` server to your client's MCP configuration. For Claude Code, this is `.mcp.json` in your project root.
|
|
69
97
|
|
|
70
|
-
|
|
98
|
+
For a source checkout:
|
|
71
99
|
|
|
72
100
|
```json
|
|
73
101
|
{
|
|
74
102
|
"mcpServers": {
|
|
75
103
|
"loupe": {
|
|
76
|
-
"command": "
|
|
104
|
+
"command": "node",
|
|
105
|
+
"args": ["<ABSOLUTE_PATH_TO_LOUPE>/packages/mcp/index.ts"],
|
|
77
106
|
"env": {
|
|
78
|
-
"LOUPE_API": "
|
|
79
|
-
"LOUPE_PROJECT_KEY": "
|
|
80
|
-
"LOUPE_ADMIN_KEY": "
|
|
107
|
+
"LOUPE_API": "<API_URL>",
|
|
108
|
+
"LOUPE_PROJECT_KEY": "<PROJECT_KEY>",
|
|
109
|
+
"LOUPE_ADMIN_KEY": "<PROJECT_SECRET>"
|
|
81
110
|
}
|
|
82
111
|
}
|
|
83
112
|
}
|
|
84
113
|
}
|
|
85
114
|
```
|
|
86
115
|
|
|
87
|
-
|
|
116
|
+
For an npm install, set `"command": "npx"` and `"args": ["-y", "@loupekit/mcp"]` instead.
|
|
88
117
|
|
|
89
|
-
|
|
118
|
+
Replace the placeholders:
|
|
90
119
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
120
|
+
- `<ABSOLUTE_PATH_TO_LOUPE>`: the path that `pwd` printed in step 5 of the install.
|
|
121
|
+
- `<API_URL>`: the base URL of your Loupe server, for example `http://localhost:8787`.
|
|
122
|
+
- `<PROJECT_KEY>`: the project whose comments the agent works on, for example `pk_demo_acme`.
|
|
123
|
+
- `<PROJECT_SECRET>`: that project's secret. `LOUPE_ADMIN_KEY` holds the project secret, and the server sends it as the `X-Loupe-Admin` header. Keep the file out of version control if it holds a real secret.
|
|
124
|
+
|
|
125
|
+
For other MCP clients, see [Connect Claude Code and other MCP clients](https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/docs/how-to/connect-mcp-clients.md).
|
|
126
|
+
|
|
127
|
+
## Verify
|
|
128
|
+
|
|
129
|
+
1. Start the server by hand, with the same values as your client configuration:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
LOUPE_API=<API_URL> LOUPE_PROJECT_KEY=<PROJECT_KEY> LOUPE_ADMIN_KEY=<PROJECT_SECRET> node <ABSOLUTE_PATH_TO_LOUPE>/packages/mcp/index.ts
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
You should see this line on standard error:
|
|
96
136
|
|
|
97
|
-
|
|
137
|
+
```text
|
|
138
|
+
[loupe-mcp] connected · project=<PROJECT_KEY> · api=<API_URL> · bridge=http://127.0.0.1:9800
|
|
139
|
+
```
|
|
98
140
|
|
|
99
|
-
The
|
|
141
|
+
The line ends in `bridge=disabled` when `LOUPE_BRIDGE_PORT` is `0` or the port is busy. Press `Ctrl+C` to stop the server, so the client's own copy can use port 9800.
|
|
100
142
|
|
|
101
|
-
|
|
102
|
-
<img src="https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/store/screenshot-2-board.jpg" alt="Loupe triage board" width="90%" />
|
|
103
|
-
</div>
|
|
143
|
+
2. Start your client. In Claude Code, run `/mcp`.
|
|
104
144
|
|
|
105
|
-
|
|
145
|
+
You should see `loupe` listed as connected, with 19 tools.
|
|
106
146
|
|
|
107
|
-
|
|
108
|
-
[`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk).
|
|
109
|
-
The published package ships compiled JS (`dist/index.js`), so `npm i -g @loupekit/mcp`
|
|
110
|
-
exposes a working `loupe-mcp` binary. From a source checkout it also runs directly with
|
|
111
|
-
`node index.ts` (Node 24+ native type-stripping).
|
|
147
|
+
3. Ask your agent:
|
|
112
148
|
|
|
113
|
-
|
|
149
|
+
```text
|
|
150
|
+
List my Loupe comments.
|
|
151
|
+
```
|
|
114
152
|
|
|
115
|
-
|
|
153
|
+
You should see the agent call `list_comments` and reply with a line such as `3 comment(s):`, then one line per comment. If the project has no matching comments, you see `No comments match.`
|
|
154
|
+
|
|
155
|
+
## Tools at a glance
|
|
156
|
+
|
|
157
|
+
The server exposes 19 tools.
|
|
158
|
+
|
|
159
|
+
| Purpose | Tools |
|
|
116
160
|
| --- | --- |
|
|
117
|
-
|
|
|
118
|
-
|
|
|
161
|
+
| Comments (the feedback backlog) | `list_comments`, `get_comment`, `update_status`, `propose_change` |
|
|
162
|
+
| Selections and element context | `get_latest_selection`, `get_selection_history`, `get_element_context`, `find_source_for_selection` |
|
|
163
|
+
| Companion chat with the person watching | `get_companion_messages`, `reply_to_companion` |
|
|
164
|
+
| Agent activity | `get_activity_summary`, `get_recent_events`, `get_files_touched`, `get_dashboard_url`, `install_agent_hooks` |
|
|
165
|
+
| Threads and pull requests | `get_thread_conversation`, `add_thread_message`, `mark_thread_addressed`, `create_pr_for_thread` |
|
|
166
|
+
|
|
167
|
+
Terms used in the table:
|
|
168
|
+
|
|
169
|
+
- **Companion chat**: messages that the person watching the page sends to the agent from the widget's Chat tab, and the agent's replies.
|
|
170
|
+
- **Thread**: the conversation on a piece of feedback: the original request, then every reply with its author.
|
|
171
|
+
|
|
172
|
+
`create_pr_for_thread` needs a GitHub token in `GITHUB_TOKEN` or `GH_TOKEN`, or a signed-in `gh` CLI.
|
|
173
|
+
|
|
174
|
+
`install_agent_hooks` edits your user-level Claude Code settings, `$HOME/.claude/settings.json`, unless you set `LOUPE_CLAUDE_SETTINGS` or pass a `path`. Before it writes, it copies the existing file to `settings.json.loupe-backup` in the same folder. It leaves other hook entries alone. To undo it, restore the backup:
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
cp "$HOME/.claude/settings.json.loupe-backup" "$HOME/.claude/settings.json"
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
> **Known issue in 0.14.0:** `get_recent_events` fails on every call with `Cannot access 'events' before initialization`. Use `get_activity_summary` or `get_files_touched` instead, or open the [/monitor page](#the-bridge-and-the-monitor-page).
|
|
181
|
+
|
|
182
|
+
For each tool's arguments and output, see the [MCP reference](https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/docs/reference/mcp.md).
|
|
183
|
+
|
|
184
|
+
## Environment
|
|
185
|
+
|
|
186
|
+
The defaults point at the local demo server. Set these three variables whenever you use another server or project:
|
|
187
|
+
|
|
188
|
+
| Variable | Type | Default | Purpose | Example |
|
|
189
|
+
| --- | --- | --- | --- | --- |
|
|
190
|
+
| `LOUPE_API` | URL | `http://localhost:8787` | Base URL of the Loupe server. | `https://tracker.example.com` |
|
|
191
|
+
| `LOUPE_PROJECT_KEY` | string | `pk_demo_acme` | The project the agent works on. | `pk_demo_acme` |
|
|
192
|
+
| `LOUPE_ADMIN_KEY` | string | empty | The project secret, sent as `X-Loupe-Admin`. | `sk_demo_acme_0f3b9c` |
|
|
193
|
+
|
|
194
|
+
Other variables control the bridge port, the workspace, the hooks and GitHub. See [Environment variables](https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/docs/reference/mcp.md#environment-variables).
|
|
195
|
+
|
|
196
|
+
## The bridge and the /monitor page
|
|
197
|
+
|
|
198
|
+
The server also runs a local HTTP bridge on `127.0.0.1`, port `9800` by default. Set `LOUPE_BRIDGE_PORT` to change the port, or to `0` to turn the bridge off. The comment tools work without the bridge.
|
|
199
|
+
|
|
200
|
+
The Loupe *widget* is the feedback panel that [`@loupekit/sdk`](https://www.npmjs.com/package/@loupekit/sdk) adds to your page. It uses the bridge only when you configure it to:
|
|
201
|
+
|
|
202
|
+
- Set the widget's `bridge` option to `'http://127.0.0.1:9800'` to send element selections and show *presence*, the list of people who have the page open. Without it, the widget hides the peer list.
|
|
203
|
+
- Also set `chat: true` to turn on the Chat tab for companion chat. It is off by default.
|
|
204
|
+
|
|
205
|
+
If you run `install_agent_hooks`, Claude Code also reports its tool calls, prompts and sessions to the bridge. Open `http://127.0.0.1:9800/monitor` to watch that activity live on a read-only page.
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
## Troubleshooting
|
|
210
|
+
|
|
211
|
+
| Symptom | Cause | Fix |
|
|
212
|
+
| --- | --- | --- |
|
|
213
|
+
| The server exits at start with `ERR_MODULE_NOT_FOUND` for `@loupekit/shared`. | The published 0.14.0 package does not declare `@loupekit/shared` as a runtime dependency. | [Install from a source checkout](#install-from-a-source-checkout). |
|
|
214
|
+
| A tool fails with an error such as `GET /v1/comments?projectKey=pk_demo_acme → 401`. | `LOUPE_ADMIN_KEY` is empty or is not the project secret. | Set `LOUPE_ADMIN_KEY` to the project secret, then restart the client. |
|
|
215
|
+
| The log shows `[loupe] bridge port 9800 is busy after 6 attempts — continuing without it`. | Another process, often a second Loupe MCP server, holds port 9800. | Stop the other process, or set `LOUPE_BRIDGE_PORT` to a free port. The comment tools work either way. |
|
|
216
|
+
| `get_recent_events` fails with `Cannot access 'events' before initialization`. | A defect in 0.14.0. | Use `get_activity_summary` or `get_files_touched`, or open `/monitor`. |
|
|
217
|
+
| Claude Code does not list `loupe` in `/mcp`. | `.mcp.json` is not in the folder where you started Claude Code, or you declined the trust prompt. | Start Claude Code from the project root and approve the server. |
|
|
218
|
+
|
|
219
|
+
For more cases, see [Troubleshooting in Connect Claude Code and other MCP clients](https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/docs/how-to/connect-mcp-clients.md#troubleshooting).
|
|
220
|
+
|
|
221
|
+
## Links
|
|
222
|
+
|
|
223
|
+
- [Loupe on GitHub](https://github.com/mohamed-ashraf-elsaed/loupe)
|
|
224
|
+
- [Website and guide](https://mohamed-ashraf-elsaed.github.io/loupe/)
|
|
225
|
+
- [Connect Claude Code and other MCP clients](https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/docs/how-to/connect-mcp-clients.md)
|
|
226
|
+
- [MCP reference](https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/docs/reference/mcp.md)
|
|
227
|
+
- [Changelog](https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/CHANGELOG.md)
|
|
228
|
+
- [`@loupekit/sdk`](https://www.npmjs.com/package/@loupekit/sdk), the widget that captures the feedback
|
|
229
|
+
- [Report an issue](https://github.com/mohamed-ashraf-elsaed/loupe/issues)
|
|
119
230
|
|
|
120
231
|
## License
|
|
121
232
|
|
package/package.json
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
"email": "m.ashraf.saed@gmail.com",
|
|
6
6
|
"url": "https://www.linkedin.com/in/mohamedashrafelsaed/"
|
|
7
7
|
},
|
|
8
|
-
"version": "0.14.0-next.
|
|
8
|
+
"version": "0.14.0-next.82",
|
|
9
9
|
"description": "MCP server that exposes Loupe comments to Claude Code as an actionable, fully-contextualized backlog.",
|
|
10
10
|
"keywords": [
|
|
11
11
|
"loupe",
|
|
@@ -47,6 +47,6 @@
|
|
|
47
47
|
"zod": "^3.24.1"
|
|
48
48
|
},
|
|
49
49
|
"devDependencies": {
|
|
50
|
-
"@loupekit/shared": "0.14.0-next.
|
|
50
|
+
"@loupekit/shared": "0.14.0-next.82"
|
|
51
51
|
}
|
|
52
52
|
}
|