استخدام Loupe: ملاحظات مرئية لـ Claude Code

هذه ترجمة آلية لم تُراجَع بعد. الأصل الإنجليزي هو المرجع. اقرأ الأصل الإنجليزي

Loupe أداة ملاحظات مرئية مفتوحة المصدر: تثبّت التعليقات على عناصر في صفحة ويب حية، ووفق وثائق Loupe يستطيع وكيل ذكاء اصطناعي مثل Claude Code التقاطها عبر MCP (Model Context Protocol، معيار مفتوح المصدر لربط تطبيقات الذكاء الاصطناعي بأنظمة خارجية). تتبع هذه المقالة درس Loupe نفسه: تعليق على صفحة، وبطاقة على لوحة، وخطوات لتدع الوكيل يقرؤه. يبيّن قسم “ما الذي فحصته” بالضبط أي الخطوات شغّلتها.

ما الذي تستطيع فعله به

• ثبّت الملاحظة حيث تنتمي. علّق على عنصر واحد، أو اسحب منطقة، أو اترك ملاحظة حرة. يحاول Loupe إيجاد العنصر نفسه بعد إعادة النشر؛ وتحت درجة 0.5 ينفصل التعليق وتظهر شارة “moved”.
• التقط ما تراه. أرفق لقطة شاشة أو تسجيل شاشة قصيرًا. العناصر الموسومة بـ data-loupe-redact تُستبعد من لقطات الشاشة التي يلتقطها الالتقاط المدمج في Loupe (للصور فقط). أما تسجيلات الشاشة فتلتقط البكسلات الحقيقية، بما فيها العناصر المحجوبة.
• ناقش في محادثات. ردّ تحت كل تعليق، وأشر إلى زملائك بـ @، وتفاعل برمز تعبيري.
• افرز على لوحة من خمس مراحل. Queue وTo Do وIn Progress وIn Review وResolved.
• سلّم قائمة المهام إلى وكيل. يعطي خادم @loupekit/mcp الأداة Claude Code 19 أداة، منها list_comments وget_comment وpropose_change وupdate_status.

اختر طريقة التثبيت

تستخدم بقية المقالة الخادم المحلي، لأنه المسار الذي يسلكه درس Loupe.

الخطوة 1: شغّل الخادم المحلي

تحتاج إلى Node 24 (الإصدار الموثّق) وnpm وgit.

git clone https://github.com/mohamed-ashraf-elsaed/loupe.git
cd loupe
npm install
npm run build
npm run seed
npm start

الأمر npm run seed ينشئ مشروعًا تجريبيًا ويطبع مفاتيحه:

Seeded project: pk_demo_acme
  admin key   (dashboard ?key= / X-Loupe-Admin): sk_demo_acme_0f3b9c

والأمر npm start يطبع العناوين ويظل يعمل:

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

الخطوة 2: افتح الصفحة التجريبية

افتح http://localhost:8787/demo/. ترى صفحة تحليلات مختلقة، ولوحة Loupe مثبّتة على اليمين، وجولة قصيرة.

الخطوة 3: ثبّت تعليقًا على عنصر

1. انقر Skip في الجولة إن كانت ما زالت ظاهرة، لأن بطاقتها تغطي الزر. في تبويب Home انقر Pin feedback on this page. تعمل أداة Inspect.
2. مرّر المؤشر فوق زر Send invite. يحيطه Loupe بإطار ويعرض اسم الوسم.
3. انقر عليه. يفتح محرر صغير، ويذكر رأسه العنصر الذي اخترته.
4. اكتب عنوانًا ووصفًا. يبقى الزر Comment معطلًا حتى يحتوي الحقلان على نص.
5. اترك Attach screenshot محددًا وانقر Comment.

يظهر على الزر تعليق مرقّم، ويظهر التعليق في أعلى قائمة Comments. كل تعليق محادثة: انقر عليه، وردّ، وأشر إلى الناس بـ @.

الخطوة 4: افرز على اللوحة

افتح http://localhost:8787/dashboard/?key=sk_demo_acme_0f3b9c في تبويب جديد. المفتاح هو مفتاح المدير الذي طبعه npm run seed. تعليقك بطاقة في عمود Queue. استخدم Move forward لنقله إلى To Do.

الخطوة 5: اربط Claude Code

يتيح خادم MCP في Loupe لـ Claude Code قراءة التعليقات وكتابة التغييرات المقترحة. في مجلد مشروع فارغ، أنشئ .mcp.json:

{
  "mcpServers": {
    "loupe": {
      "command": "npx",
      "args": ["-y", "@loupekit/mcp"],
      "env": {
        "LOUPE_API": "http://localhost:8787",
        "LOUPE_PROJECT_KEY": "pk_demo_acme",
        "LOUPE_ADMIN_KEY": "sk_demo_acme_0f3b9c"
      }
    }
  }
}

تسمّي المتغيرات الثلاثة خادمك، والمشروع المراد قراءته، وسر المشروع. أبقِ هذا الملف خارج التحكم بالإصدارات إن احتوى يومًا على سر حقيقي. شغّل Claude Code في ذلك المجلد، ووافق على خادم loupe، ثم نفّذ /mcp: يجب أن يظهر loupe متصلًا. وتعرض صفحة Connect Claude في اللوحة المقتطف نفسه، مملوءًا مسبقًا بعنوانك ومفتاح مشروعك.

الخطوة 6: دع Claude يقرؤه ويقترح إصلاحًا

اسأل Claude Code:

List the Loupe comments.

يستدعي list_comments ويجيب بهذا الشكل:

1 comment(s):

- [To Do] Medium · Other · #<COMMENT_ID> — Invite button is hard to see: Make the Send invite button stand out more.
    ↳ [data-testid="btn-invite"] on /demo/ (by Sara (PM))

ثم اطلب منه السياق الكامل واقتراح تغيير. يعيد get_comment التعليق والصفحة وHTML العنصر وأنماطه المحسوبة ولقطة الشاشة. ويحفظ propose_change شيفرة HTML وCSS كمعاينة قبل وبعد على البطاقة. تعمل المعاينة في إطار معزول مع تعطيل السكربتات، فتعرض الشيفرة والأنماط فقط.

الخطوة 7: يحسمه إنسان

أدوات MCP مبنية ليتوقف الوكيل عند In Review: الأداة mark_thread_addressed ليس لها معامل للحالة وتضبط In Review دائمًا. ويقول الدرس صراحة إن هذا تعليمات للوكيل، لا فحص صلاحية. يراجع شخص المعاينة وينقر Resolve في الأداة أو على اللوحة.

ما الذي فحصته وما الذي لم أفحصه

في 2026-10-31 شغّلت الخطوتين 1 و2 وجزء الخادم من الخطوة 4 من نسخة مستنسخة جديدة من Loupe 0.14.2، مع Node v26.7.0 (الإصدار الموثّق هو Node 24): npm install وnpm run build وnpm run seed وnpm start، على المنفذ 8795 (PORT=8795 npm start) لأبتعد عن المنفذ الافتراضي. تطابق ناتج seed مع ما ورد أعلاه، وأجابت الصفحة التجريبية واللوحة كلتاهما بـ HTTP 200. وتحمّلت الأداة في متصفح حقيقي. أظهرت وحدة تحكم المتصفح ثلاث استجابات 404 (الأيقونة المصغّرة و/v1/org و/v1/activity)، وسببها في الشيفرة: تعامل الأداة 404 من /v1/org و/v1/activity على أنه “هذا الخادم لا يملكها”، وخادم Node ليس فيه هذان المساران ولا مسار للأيقونة المصغّرة.

لم أشغّل Claude Code على هذا الخادم من أجل هذه المقالة. مقتطف .mcp.json وشكل ناتج list_comments ومسارا Laravel وHub مأخوذة من وثائق Loupe نفسها. ولقطات الشاشة الأخرى من وثائق المشروع أيضًا. إصدار @loupekit/mcp 0.14.0 المنشور يفشل عند البدء بالخطأ ERR_MODULE_NOT_FOUND؛ وتقول الوثائق إن هذا أُصلح في 0.14.1. وكان أحدث إصدار على npm في 2026-10-31 هو 0.14.1، ونسختي المستنسخة 0.14.2 غير منشورة، فالأمر npx -y @loupekit/mcp يثبّت إصدارًا لم أشغّله.

ما الذي كنت سأفعله بشكل مختلف

1. عرض سر المشروع بتهاون أقل. يظهر السر التجريبي في الدرس وفي عنوان اللوحة وفي .mcp.json. هو قيمة تجريبية، لكن سر مشروع حقيقي يجب ألا يوجد في ملف قد يرفعه الناس. لم أختبر طريقة أخرى لتمريره.
2. قول “تعليمات لا صلاحية” مبكرًا. تعرض اللوحة خمسة أعمدة، ولا شيء عليها يبيّن أن قاعدة In Review تقع في أدوات MCP. كنت سأضع هذه الجملة بجانب الأعمدة.

كُتبت مسودة هذه المقالة بمساعدة الذكاء الاصطناعي. راجعت كل ادعاء ونفذت الأوامر المعروضة.

عن المشروع: Loupe.

Mohamed Ashraf Elsaed
قائد تقني في Convertedin، القاهرة. أبني أدوات لوكلاء البرمجة بالذكاء الاصطناعي وأكتب عن لارافيل وNode والهندسة.