ما هو خادم MCP من PinSay؟

هو خادم Model Context Protocol يعمل على جهازك ويُشغَّل بالأمر npx @pinsay/cli mcp، ويعطي وكيل الذكاء الاصطناعي عشر أدوات محددة الأنواع ليقرأ ملاحظات الموقع ويُنشئ commit للإصلاحات ويعلّم التعليقات «مُطبَّقة».

مع أي MCP clients يعمل؟

مع أي MCP client يستطيع تشغيل خادم محلي عبر stdio. تعطي الوثائق الإعداد لكل من Claude Code وCursor وWindsurf وOpenCode، وهو سطر JSON نفسه للجميع.

هل يُرسَل مفتاح PinSay API إلى النموذج؟

لا. تقرأ عملية CLI المحلية المفتاح وتستبدله برمز وصول قصير العمر، ولا يظهر المفتاح في مدخلات الأدوات ولا مخرجاتها.

هل يستطيع الوكيل تنفيذ push أو تغيير إعدادات المشروع؟

لا. ينشئ الخادم commits محلية فقط، ولا ينفّذ push ولا merge ولا rebase. إعدادات المشروع للقراءة فقط عبر MCP، ولا يستطيع الوكيل إنشاء تعليقات.

كيف يتعامل الوكيل مع prompt injection داخل التعليقات؟

يعود كل ما كتبه أصحاب المصلحة (نص التعليق والردود ولقطات DOM) تحت المفتاح untrusted، ويطلب وصف الأدوات من الوكيل ألّا ينفّذ أي تعليمات داخله. وتأتي قواعد مساحة العمل والموجّهات تحت trusted.

هل أضيف إعداد MCP إلى commit في المستودع؟

لا. أضفه إلى ملف إعدادات المستخدم. الإعداد المحفوظ في المستودع يفرض أداة واحدة على الفريق وقد يسرّب بيانات الدخول.

هل يصلح PinSay كأداة لتتبّع الأخطاء عبر Model Context Protocol؟

يغطي الجزء الذي يحتاجه الوكيل: يعلّم الناس الأخطاء والطلبات على التطبيق وهو يعمل، ويقرأ الوكيل ويصلح ويُنشئ commit ويردّ عبر MCP. وعند تفعيل التقاط الأخطاء في المشروع، يمكن لتعليق الخطأ أن يتضمّن طلبات الـ network وأخطاء الـ console وخطوات المستخدم.

خادم MCP لملاحظات المواقع: 10 أدوات على جهازك

ماذا يفعل؟

يضغط أعضاء فريقك على عنصر في التطبيق ويكتبون ما يريدون تغييره. يحمل كل تعليق CSS selector العنصر، وقواعد CSS المطبّقة عليه، وroute، وviewport، ولقطة DOM منقّاة. ويسلّم خادم MCP هذه القائمة إلى الوكيل على شكل استدعاءات أدوات محددة الأنواع، فلا يحتاج إلى سكربتات curl ولا إلى موجّه منسوخ. يستطيع الوكيل أن يعرض التعليقات، ويجلب قائمة التعليقات الجاهزة، ويُنشئ commit لتعديلاته، ويعلّم التعليقات «مُطبَّقة»، ويردّ على صاحب الطلب.

البداية السريعة

1. ثبّت PinSay في المستودع

npx @pinsay/cli@latest init

يكتشف التقنيات المستخدمة، ويضيف الودجت، ويثبّت مهارات الوكيل. ويقرأ خادم MCP إعداد المشروع من .pinsay/config.json وبيانات الدخول من .pinsay/credentials.env في مجلد العمل الحالي.

2. أضف الخادم إلى MCP client

يعمل الإعداد نفسه مع Claude Code ‏(~/.claude.json) وCursor ‏(~/.cursor/mcp.json) وWindsurf وOpenCode:

{
  "mcpServers": {
    "pinsay": {
      "command": "npx",
      "args": ["-y", "@pinsay/cli@latest", "mcp"]
    }
  }
}

ضعه في إعدادات المستخدم، لا في ملف تضيفه إلى commit. الإعداد المحفوظ في المستودع يفرض أداة واحدة على الفريق كله، وقد يسرّب بيانات الدخول.

3. اطلب من الوكيل

«Apply the ready PinSay comments.» يقرأ الوكيل القائمة، ويعدّل الكود، ويُنشئ commit على جهازك، ويعلّم كل تعليق «مُطبَّقًا» ويربطه بالـ commit.

الأدوات العشر

الأداة	ماذا تفعل
`pinsay_list_comments`	تعرض تعليقات المشروع في ملخّص مختصر، مع تصفية حسب الحالة والبيئة.
`pinsay_get_queue`	تجلب التعليقات الجاهزة للتطبيق، ومعها العنصر وسياق الصفحة وقواعد الذكاء الاصطناعي والموجّهات المعرّفة مسبقًا في مساحة العمل.
`pinsay_get_comment`	تجلب تعليقًا واحدًا برقمه، مع العنصر والردود وتفاصيل التطبيق.
`pinsay_mark_applied`	تعلّم تعليقًا واحدًا «مُطبَّقًا» وتنشر ردًّا، دون تشغيل git (حين يُنشئ شخص الـ commit).
`pinsay_commit_and_mark`	تجهّز الملفات وتُنشئ commit محليًا وتعلّم التعليقات «مُطبَّقة» وتربطها بالـ commit. لا تُنفّذ push أبدًا.
`pinsay_reply`	تنشر ردًّا يراه صاحب التعليق، دون تغيير حالته.
`pinsay_set_status`	تنقل التعليق إلى open أو ready أو archived أو حالة مخصّصة.
`pinsay_resolve_source`	تحوّل الـ source hash للعنصر إلى مسار ملف واسم component من الـ manifest المحلي.
`pinsay_doctor`	تشغّل فحوص سلامة التثبيت وتعرض نتائجها. للقراءة فقط.
`pinsay_list_projects`	تعرض كل مشاريع PinSay المعرّفة في المستودع.

ويوفّر الخادم أيضًا الـ resource ‏pinsay://project (إعداد المشروع المدمج، للقراءة فقط)، والـ prompt ‏pinsay_apply_instructions الذي يولّد تعليمات التطبيق نفسها التي يولّدها npx @pinsay/cli apply.

نموذج الأمان

أي أداة ملاحظات تتحدث مع وكيل ذكاء اصطناعي تنقل نصوص أشخاص آخرين إلى الكود الخاص بك. لذلك بُني الخادم على هذا الأساس.

يبقى مفتاح API في العملية المحلية

تقرأ عملية CLI المحلية مفتاح API وتستبدله برمز وصول قصير العمر. لا يُمرَّر المفتاح إلى النموذج أبدًا، ولا يظهر في مدخلات الأدوات ولا مخرجاتها.

نص أصحاب المصلحة موسوم بأنه غير موثوق

تعود نصوص التعليقات والردود ولقطات DOM تحت المفتاح untrusted في كل استجابة، ويطلب وصف الأدوات من الوكيل ألّا ينفّذ أي تعليمات مكتوبة داخلها. أما قواعد الذكاء الاصطناعي والموجّهات المعرّفة مسبقًا في مساحة العمل فتأتي تحت trusted.

يعمل على جهازك

يعمل الخادم عبر stdio كعملية محلية يشغّلها الـ MCP client. ويعدّل الوكيل ويُنشئ commit في مستودعك.

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

إنشاء تعليقات. الملاحظات يكتبها فقط من يستخدم تطبيقك.
تغيير إعدادات المشروع. روابط المشروع والـ origins المسموح بها وإعدادات مساحة العمل للقراءة فقط عبر MCP.
تنفيذ push. ينشئ commits محلية بـ git commit، ولا يُنفّذ push ولا merge ولا rebase أبدًا. أنت من يُنفّذ push.

PinSay نفسه لا يشغّل أي ذكاء اصطناعي ولا ينشر التغييرات. بعد النشر، يعلّم الأمر npx @pinsay/cli status --deployed تعليقات هذا الـ build على أنها منشورة. التعليق الذي عُلّم بـ pinsay_mark_applied لا يُسجَّل له commit، فلا يصبح منشورًا بهذه الطريقة؛ استخدم pinsay_commit_and_mark حين يُنشئ الوكيل الـ commit.

MCP أم CLI؟

استخدم خادم MCP إذا كانت أداتك تدعم MCP وتريد استدعاءات أدوات محددة الأنواع. واستخدم CLI ‏(npx @pinsay/cli apply، ومعه --mark ليُنشئ commit ويعلّم التعليقات «مُطبَّقة») إذا كان وكيلك يعمل عبر الطرفية. كلاهما يقرأ القائمة نفسها، وتستطيع التبديل متى شئت. الدورة كاملة في صفحة وكلاء البرمجة بالذكاء الاصطناعي.

خادم MCP لملاحظات المواقع