@loupekit/mcp 0.2.0 → 0.2.1-next.2

package/README.md

@@ -1,30 +1,57 @@
-# @loupekit/mcp
+<div align="center">
 
-**Model Context Protocol (MCP) server that hands [Loupe](https://github.com/mohamed-ashraf-elsaed/loupe)
-comments to Claude Code as an actionable, fully-contextualized backlog.**
+<a href="https://mohamed-ashraf-elsaed.github.io/loupe/">
+  <img src="https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/store/promo-marquee-1400x560.jpg" alt="Loupe — Pin feedback to the live UI. Hand it to Claude." width="100%" />
+</a>
+
+<h1>@loupekit/mcp</h1>
+
+<p><strong>The Model Context Protocol server that hands Loupe comments to Claude Code</strong><br />
+as an actionable, fully-contextualized backlog — request + element HTML + styles + screenshot.</p>
+
+<p>
+  <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>
+  <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>
+  <img src="https://img.shields.io/npm/l/@loupekit/mcp?color=4a55d6" alt="MIT license" />
+  <img src="https://img.shields.io/badge/MCP-stdio-4a55d6" alt="MCP stdio server" />
+</p>
+
+<p>
+  <a href="https://mohamed-ashraf-elsaed.github.io/loupe/"><b>Website</b></a> ·
+  <a href="https://github.com/mohamed-ashraf-elsaed/loupe"><b>GitHub</b></a> ·
+  <a href="https://github.com/mohamed-ashraf-elsaed/loupe/blob/main/CHANGELOG.md"><b>Changelog</b></a> ·
+  <a href="https://www.npmjs.com/package/@loupekit/sdk"><b>SDK</b></a>
+</p>
+
+</div>
+
+---
+
+## Overview
 
 Product managers pin visual feedback on the live product with the
 [Loupe SDK](https://www.npmjs.com/package/@loupekit/sdk) or browser extension. This MCP
 server lets **Claude Code read that feedback**, open each comment with everything needed to
-make the change — the request, the target element's HTML, its computed styles, and a
-screenshot — and flow the status back when the work is done.
+make the change, and flow the status back when the work is done — closing the loop.
 
----
+<div align="center">
+  <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%" />
+</div>
 
 ## What Claude gets
 
 Each comment arrives as a ready-to-act package: the natural-language request, the page URL,
 the target element (stable id / CSS path), its outer HTML, a curated slice of computed
-styles, and a screenshot URL. No more "the header looks off somewhere" — Claude knows the
+styles, and a screenshot URL. No more _"the header looks off somewhere"_ — Claude knows the
 element, its state, and the page.
 
 ## Tools
 
-| Tool                        | Description                                                                                                   |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `list_comments(status?, url?)` | List comments, optionally filtered by status (`open` / `in_progress` / `done`) or page URL.               |
-| `get_comment(id)`           | The full Claude-ready package for one comment: request + element HTML + computed styles + screenshot URL.     |
-| `update_status(id, status)` | Move a comment across the workflow (`open` → `in_progress` → `done`) so triage state stays in sync.           |
+| Tool | Description |
+| --- | --- |
+| `list_comments(status?, url?)` | List comments, optionally filtered by status (`open` / `in_progress` / `done`) or page URL. |
+| `get_comment(id)` | The full Claude-ready package for one comment: request + element HTML + computed styles + screenshot URL. |
+| `update_status(id, status)` | Move a comment across the workflow (`open` → `in_progress` → `done`) so triage state stays in sync. |
 
 ## Install
 
@@ -32,8 +59,8 @@ element, its state, and the page.
 npm i -g @loupekit/mcp     # exposes the `loupe-mcp` binary
 ```
 
-> Also mirrored to **GitHub Packages** as `@mohamed-ashraf-elsaed/mcp`. To install from there,
-> add `@mohamed-ashraf-elsaed:registry=https://npm.pkg.github.com` to your `.npmrc`.
+> Also mirrored to **GitHub Packages** as `@mohamed-ashraf-elsaed/mcp` — add
+> `@mohamed-ashraf-elsaed:registry=https://npm.pkg.github.com` to your `.npmrc` to install from there.
 
 ## Configure Claude Code
 
@@ -58,11 +85,19 @@ Then ask Claude Code: _"List the open Loupe comments and fix the first one."_
 
 ## Environment variables
 
-| Variable            | Default                   | Description                                                          |
-| ------------------- | ------------------------- | -------------------------------------------------------------------- |
-| `LOUPE_API`         | `http://localhost:8787`   | Base URL of the Loupe backend API.                                   |
-| `LOUPE_PROJECT_KEY` | `pk_demo_acme`            | The project whose comments to expose.                                |
-| `LOUPE_ADMIN_KEY`   | _(empty)_                 | The project secret — authenticates the server as admin (`X-Loupe-Admin`). Required against a real backend. |
+| Variable | Default | Description |
+| --- | --- | --- |
+| `LOUPE_API` | `http://localhost:8787` | Base URL of the Loupe backend API. |
+| `LOUPE_PROJECT_KEY` | `pk_demo_acme` | The project whose comments to expose. |
+| `LOUPE_ADMIN_KEY` | _(empty)_ | The project secret — authenticates the server as admin (`X-Loupe-Admin`). Required against a real backend. |
+
+## Where the comments come from
+
+The dashboard is the human side of the same backlog Claude reads:
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/mohamed-ashraf-elsaed/loupe/main/docs/store/screenshot-2-board.jpg" alt="Loupe triage board" width="90%" />
+</div>
 
 ## Transport
 
@@ -72,9 +107,10 @@ Node 24+ runs the TypeScript entry directly (native type-stripping) — no build
 
 ## Related packages
 
-- [`@loupekit/sdk`](https://www.npmjs.com/package/@loupekit/sdk) — the embeddable widget that
-  captures the feedback.
-- [`@loupekit/shared`](https://www.npmjs.com/package/@loupekit/shared) — the canonical types.
+| Package | Description |
+| --- | --- |
+| [`@loupekit/sdk`](https://www.npmjs.com/package/@loupekit/sdk) | The embeddable widget that captures the feedback. |
+| [`@loupekit/shared`](https://www.npmjs.com/package/@loupekit/shared) | The canonical TypeScript types shared across the platform. |
 
 ## License
 

package/package.json

@@ -1,21 +1,40 @@
 {
   "name": "@loupekit/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1-next.2",
   "description": "MCP server that exposes Loupe comments to Claude Code as an actionable, fully-contextualized backlog.",
-  "keywords": ["loupe", "mcp", "model-context-protocol", "claude", "claude-code", "visual-feedback", "product-management", "ai"],
+  "keywords": [
+    "loupe",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "visual-feedback",
+    "product-management",
+    "ai"
+  ],
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/mohamed-ashraf-elsaed/loupe.git", "directory": "packages/mcp" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mohamed-ashraf-elsaed/loupe.git",
+    "directory": "packages/mcp"
+  },
   "homepage": "https://mohamed-ashraf-elsaed.github.io/loupe/",
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
-  "files": ["index.ts"],
-  "bin": { "loupe-mcp": "./index.ts" },
+  "files": [
+    "index.ts"
+  ],
+  "bin": {
+    "loupe-mcp": "./index.ts"
+  },
   "scripts": {
     "start": "node index.ts",
     "test:client": "node test-client.ts"
   },
   "dependencies": {
-    "@loupekit/shared": "^0.2.0",
+    "@loupekit/shared": "0.2.1-next.2",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.1"
   }