mcpsnoop

Wireshark لـ MCP. وكيل شفاف يُظهر كل استدعاء أداة حقيقي بين عميل الذكاء الاصطناعي الخاص بك وخوادم MCP الخاصة بك، مباشرة في طرفيتك.

mcpsnoop demo

المشكلة

يتصل MCP Inspector الرسمي كعميل خاص به، لذا لا يرى أبدًا ما يرسله عميلك (Cursor، Claude Code، Codex) فعليًا إلى خادمك. وأي شيء ينتظر وصول طلب لا يمكنه إظهار الاستدعاء الذي لم يقم به النموذج أبدًا، أو قام به بوسائط خاطئة. عندما لا يتم استدعاء أداة بصمت، أو لا تتوافق القدرات، أو يتعطل استدعاء ما، تظل عالقًا في البحث في السجلات والتخمين.

بدلاً من ذلك، يجلس mcpsnoop في مسار البيانات الحقيقي. لفّ أمر الخادم الخاص بك به وشاهد كل إطار JSON-RPC مباشرة، بينما يتحدث عميلك وخادمك الحقيقيان.

كرر `redact-key` و `redact-value` و `redact-path` في أسطر منفصلة لإضافة أكثر من واحد من كل منها. هذه هي جميع المفاتيح التي يدعمها. يتم البحث عن الملف فقط في دليل العمل الحالي، وليس في الدلائل الأصلية. تتجاوز خيارات سطر الأوامر الصريحة القيم الواردة من ملف الإعدادات. ## الأوامر | الأمر | ما يفعله | |---|---| | `mcpsnoop -- <server>` | يغلّف خادم stdio كطبقة وسيطة شفافة | | `mcpsnoop` | يفتح واجهة TUI المباشرة | | `mcpsnoop http --target <url>` | يمرّر عبر خادم HTTP قابل للبث | | `mcpsnoop export` | يعرض جلسة بصيغة json أو html أو text أو har أو otlp | | `mcpsnoop check` | يفشل CI عند وجود أخطاء أو إطارات غير صالحة أو تحذيرات أو عدم تطابق في التوجيه أو استدعاءات معلّقة أو نتائج متأخرة أو تجاوز ميزانية زمن الاستجابة | | `mcpsnoop baseline` | يعاين أو يقبل أو يعيد تعيين تعريفات الأدوات الموثوقة | | `mcpsnoop diff` | يقارن الأدوات والاستدعاءات عبر جلستين ملتقطتين | | `mcpsnoop open` | يفتح جلسة محفوظة في واجهة TUI | | `mcpsnoop inventory` | يسرد كل خادم تم تشغيله عبر mcpsnoop على هذا الجهاز | | `mcpsnoop stats` | يدمج كل لقطة مخزنة في صف واحد لكل خادم وأداة | | `mcpsnoop prune` | يحذف سجلات الجلسات المحفوظة الأقدم من حد زمني | | `mcpsnoop wrap <server>` | يوجّه أحد خوادم Claude Desktop عبر mcpsnoop | | `mcpsnoop unwrap <server>` | يعيد إدخال ذلك الخادم إلى حالته الأصلية | | `mcpsnoop remote <user@host>` | يطبع أمر نفق SSH | | `mcpsnoop demo` | يشغّل جلسة مكتوبة مسبقًا | شغّل `mcpsnoop help` للحصول على القائمة الكاملة، أو `mcpsnoop help <command>` لمعرفة خيارات أمر معيّن. ## كيف يقارن | | MCP Inspector | mcpsnoop | |---|:---:|:---:| | يرى حركة مرور عميلك وخادمك الفعلية | لا | نعم | | يعلّم على الاستدعاءات المعلّقة وأخطاء البث | لا | نعم | | يعلّم على المخرجات الشاردة التي تفسد البث | لا | نعم | | يعلّم على إطارات JSON-RPC غير الصالحة | لا | نعم | | يكتشف انحراف تعريف الأداة بعد الموافقة | لا | نعم | | واجهة طرفية تفاعلية | لا | نعم | | بدون إعداد، بدون خيارات أو ترتيب | لا | نعم | | فاحص القدرات | جزئي | نعم | | إعادة تشغيل استدعاء ملتقط | لا | نعم، عبر stdio وعبر HTTP | | تصدير الجلسة (json / html / text / otlp) | لا | نعم | | ملف ثنائي واحد، بدون تبعيات وقت تشغيل | لا | نعم | ## التثبيت ### npm لا حاجة إلى سلسلة أدوات Go. معظم خوادم MCP مكتوبة بلغة Node أو Python، لذا هذه هي الطريقة الأقصر للبدء.```bash npx mcpsnoop -- node build/index.js

`--older-than` مطلوب (لا يوجد افتراضي قد يحذف أي شيء) ويقبل عدد أيام مثل `30d` أو مدة بصيغة Go مثل `72h`. تُترك خطوط الأساس للأدوات دون تغيير، لأن خط الأساس مرتبط بتسمية الخادم وليس بالجلسة. نظرًا لأنه يقع داخل خط الأنابيب الفعلي، وليس جانبًا مثل Inspector، فإنه يرى بالضبط ما يقوله عميلك وخادمك الحقيقيان لبعضهما البعض، مهما كانت اللغة التي كُتب بها الخادم. ## اختصارات لوحة المفاتيح | المفتاح | الإجراء | | المفتاح | الإجراء | |---|---|---|---|---| | `enter` | فحص / التعمق | | `/` | تصفية | | `esc` | رجوع | | `:` | أمر | | `j` / `k` | تحريك | | `r` / `R` | إعادة تشغيل / تعديل وإعادة تشغيل | | `g` / `G` | أعلى / أسفل | | `c` | القدرات | | `ctrl-f` / `ctrl-b` | صفحة | | `s` | ملخص الأداة | | `p` | إيقاف مؤقت | | `y` | نسخ | | `shift`+`<key>` | فرز حسب العمود | | `e` | تصدير | | `ctrl-d` | حذف الجلسة | | `f` | متابعة | | `?` | مساعدة | | | | اضغط `?` داخل التطبيق للحصول على القائمة الكاملة. ## تصفية التدفق اضغط `/` في جلسة واجمع الرموز المميزة المفصولة بمسافات، مع منطق AND. النص العادي يطابق الطريقة والأداة والمعرف والحمولة. | الرمز | التصفية حسب | مثال | |---|---|---| | `tool:` | اسم الأداة | `tool:search` | | `method:` | طريقة JSON-RPC | `method:tools/call` | | `id:` | معرف الطلب، وأي إعادة محاولة تكمله | `id:7` | | `task:` | معرف المهمة | `task:01J...` | | `dir:` | الاتجاه (`c2s`, `s2c`) | `dir:s2c` | | `kind:` | نوع الإطار (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` | | `status:` | نتيجة الاستدعاء (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch`, أو حالة HTTP مثل `401`) | `status:error` | كدّس الرموز للحصول على نتائج محددة.```text tool:search status:pending # in-flight calls to one search tool status:cancel # calls the client gave up on (status:cancelled is a cancelled task) status:late # results that arrived after the cancellation method:tools/call status:error # tool calls that failed dir:s2c kind:req # server-initiated requests (servers before 2026-07-28)

| الصيغة | ما الذي ستحصل عليه | |---|---| | `json` | استدعاءات مترابطة، عدد مرات الاستخدام لكل أداة، زمن الاستجابة p50/p95/p99، أبطأ الاستدعاءات، القدرات، والإطارات الخام | | `html` | ملف متصفح مستقل بذاته مع بحث وJSON قابل للطي | | `text` | تفريغ نصي بسيط وأنيق | | `har` | إدخال واحد لكل استدعاء مترابط، قابل للفتح في أدوات مطوري المتصفح وأي شيء آخر يقرأ HAR | | `otlp` | JSON بصيغة OTLP مع فترة زمنية (span) لكل استدعاء مترابط، مع سياق تتبع W3C الذي يربط تتبعات المُستدعي حيثما كان موجودًا، وتتبع واحد لكل جلسة بخلاف ذلك | MCP ليس HTTP، لذا فإن عنوان URL لإدخال HAR ورمز الحالة والتوقيتات هي تعيين متعمّد لكل استدعاء وليست نسخة حرفية من الأسلاك. بالنسبة لـ OTLP، يوفر `_meta.traceparent` الخاص بالطلب تتبع ذلك الاستدعاء ومعرّفات الفترة الزمنية الأصلية، بينما ينتقل `_meta.tracestate` مع الفترة الزمنية. عندما يكون traceparent غائبًا أو غير صالح، يحتفظ mcpsnoop بالتتبع المشتق من الجلسة ولا يحمل أي حالة. يراقب mcpsnoop ولا يشارك، لذا فهو لا يضيف أي إدخال خاص بالبائع ويمرر حالة المُستدعي دون تغيير.```bash mcpsnoop export -T html -o out.html # an HTML file to open in a browser mcpsnoop export -T text server.py-48213-7f3a1c9e2b04 # a specific session, as text mcpsnoop export -T json | jq # the newest session, piped to jq mcpsnoop export -T har -o session.har # a HAR file to open in browser devtools mcpsnoop export -T otlp -o trace.json # import into an OTLP-compatible tracing backend

هذه العلامات تعيد كتابة الملف المُصدَّر أو عرض TUI في الذاكرة، ولا تلمس أبدًا ملف JSONL المصدر. يرفض `export` مخرجًا يسمّي نفس الملف الذي هو مدخله، ويكتب عبر ملف مؤقت يُعاد تسميته إلى مكانه، لذا فإن أي تشغيل يفشل يترك الملف السابق سليمًا. يُترك `inputSchema` و`outputSchema` الخاصان بالأداة، كما هو مُعلَن في نتيجة `tools/list`، دون مساس من قِبل `--redact-key` و`--redact-secrets`، لثلاثة أسباب. - الاسم داخل المخطط هو إعلان نوع وليس قيمة. - الاسم نفسه يبقى في السجل في كلتا الحالتين. - تنظيف المخطط الفرعي تحت خاصية تُدعى `token` سيأخذ فحوصات الأداة نفسها معه. الاستثناء هو ذلك الموضع فقط، لذا فإن أي وسيط يصادف أن يُدعى `inputSchema` يُنظَّف مثل أي وسيط آخر، ويتوقف عند `default` و`const` و`examples` و`enum`، التي تحمل بيانات وليست بنية. استخدم `--redact-path` لتسمية شيء داخل مخطط، أو `--redact-value`، الذي يطابق النص أينما وُجد باستثناء الكلمتين المفتاحيتين اللتين يحللهما mcpsnoop، وهما `type` و`x-mcp-header`. ما يصل إليه كل علم يختلف، لذا تحقق من النتيجة بدلًا من الافتراض. جميع الأعلام الأربعة تنظف حمولات JSON-RPC، و`--redact-key` و`--redact-path` و`--redact-secrets` تصل فقط إلى تلك. فقط `--redact-value` ينظف أيضًا stderr، والنصوص الأخرى غير JSON، وداخل السلسلة النصية. يُنظَّف ترويسة `Mcp-Param-*` جنبًا إلى جنب مع قيمة الجسم التي تعكسها. بيانات الغلاف الوصفية الأخرى، تسميات الخادم، و`Mcp-Name` و`Mcp-Method` وحالة HTTP، تُترك كما التُقطت. التنظيف هو جهد بأفضل ما يمكن، لذا استخدم مسار مخرج منفصل واقرأ النتيجة قبل مشاركتها. ### بث الاستدعاءات المكتملة إلى مجمّع OTLP أرسل spans أثناء تشغيل الوكيل بتوجيهه إلى نقطة نهاية OTLP/HTTP JSON لتتبعات traces. كرر `--otlp-header` لمصادقة المجمّع أو ترويسات المستأجر.```bash mcpsnoop \ --otlp-endpoint http://localhost:4318/v1/traces \ --otlp-header "Authorization=Bearer $OTLP_TOKEN" \ -- node build/index.js mcpsnoop http \ --target http://localhost:3000/mcp \ --otlp-endpoint http://localhost:4318/v1/traces

التقرير يعرض الأدوات التي تمت إضافتها أو إزالتها، ووصفها وتغييرات `inputSchema`، واستدعاءات الأدوات المتطابقة التي تغيّرت حالتها، وتحولات المدة الملحوظة. تتم مطابقة الاستدعاءات حسب اسم الأداة والوسائط، لذا فإن الاستدعاءات المعاد ترتيبها لا تزال تُقارن بشكل صحيح. افتراضيًا، يجب أن يختلف تغيّر المدة بمقدار 100 مللي ثانية على الأقل وبمعامل 2x. استخدم `--duration-threshold` و`--duration-ratio` لضبط هذه الحدود. مرّر `--exit-code` لتفعيل البوابة في CI عند حدوث تراجعات. يخرج برمز غير صفري عندما تكون الجلسة "بعد": - تُسقط أداة - تغيّر وصف أداة أو عنوانها أو مخطط الإدخال أو مخطط الإخراج أو التعليقات التوضيحية - تحتوي على استدعاء تدهورت حالته - تتباطأ تغيير الأيقونة لا يُحتسب، لأنه يعدّل مظهر الأداة دون تغيير وظيفتها. التحسينات، أي الأدوات المضافة والاستدعاءات المُصححة وتسريع الأداء، لا تزال تخرج برمز صفري. ## فحص الجلسات في CI قم بتقييد جلسة وكيل مسجّلة بناءً على الأخطاء، أو تلف التدفق، أو تحذيرات البروتوكول، أو عدم تطابق ترويسات التوجيه، أو الاستدعاءات التي لم تتلقَ استجابة أبدًا، أو الإطارات المسقطة التي تترك الالتقاط غير مكتمل، أو انحراف تعريف الأداة، أو استخدام ميزات بروتوكول قديمة.```bash mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

ثبّت إصدارًا محددًا، أي إصدار تريده. الأحدث موجود في [صفحة الإصدارات](https://github.com/kerlenton/mcpsnoop/releases). لا يوجد إصدار عائم `v1`، وهذا مقصود. الإصدار المثبّت هو أيضًا الثنائي الذي يثبّته الإجراء، لذلك لا يمكن أن يختلف الاثنان أبدًا ولا يوجد إصدار افتراضي يصبح قديمًا. | الإدخال | | |---|---| | `session` | ملف الالتقاط `.jsonl` للفحص، نسبةً إلى جذر المستودع. مطلوب | | `fail-on` | كما في `--fail-on`، مع افتراض ما يفعله سطر الأوامر افتراضيًا | | `args` | أي علامات `check` أخرى، مكتوبة بين علامتي اقتباس كما في سطر الأوامر. يُرفض `--format`، لأن الإجراء يقرأ التقرير | | `upload-sarif` | إرسال التقرير إلى فحص الكود. `true` | | `category` | مساحة اسم فحص الكود. `mcpsnoop`. غيّرها لكل مسار من مسارات المصفوفة، وإلا فستستبدل المسارات بعضها البعض | | `fail-on-findings` | إفشال المهمة عند وجود نتيجة. `true`. اضبطها على `false` لتسجيل التنبيهات والسماح لفحص الكود الإلزامي باتخاذ القرار | | `version` | أي إصدار من mcpsnoop سيتم تثبيته. الافتراضي هو الإصدار الذي ثبّته | | `install` | `false` عندما يكون mcpsnoop موجودًا بالفعل في PATH، وهو الطريقة على منصة لا يوجد لها إصدار مُصدر | المخرجات هي `outcome` و`sarif` و`exit-code`. `outcome` تكون `passed` أو `findings` أو `error`، والثالث يستحق معالجة منفصلة. يعني أن شيئًا لم يتم فحصه، وهو ليس نفس معنى عدم العثور على شيء. **التشغيل الذي لا يمكنه الفحص يُفشل المهمة بغض النظر عن `fail-on-findings`**، لأن خط أنابيب يتحول إلى أخضر بعد التحقق من لا شيء أسوأ من خط يفشل. تحتاج المهمة إلى `security-events: write`، وإلا سيرجع الرفع برمز 403. اضبط `upload-sarif: false` في مستودع بدون فحص كود. ### أو اربطها بنفسك الإجراء هو أربع خطوات وبدون أي سحر. القيام بذلك يدويًا يتطلب نفس العناية التي يتطلبها. يجب أن يعمل الرفع على التشغيلات التي لديها تقرير، وهي تلك التي خرجت برمز 0 أو 1 وليس تلك التي خرجت برمز 2، والخطوة التي تُفشل المهمة يجب أن تأتي بعده، وإلا فلن تصل النتائج أبدًا إلى التبويب الذي وُجدت من أجله.```yaml permissions: # required for all workflows security-events: write # only required for workflows in private repositories actions: read contents: read steps: - name: Check captured MCP session id: check run: | code=0 mcpsnoop check --format sarif artifacts/session.jsonl > mcpsnoop.sarif || code=$? echo "exit-code=$code" >> "$GITHUB_OUTPUT" # 2 means the check never happened, so there is no report to publish and # nothing was verified. Stop here rather than uploading an empty file. [ "$code" -le 1 ] || exit 1 - name: Upload mcpsnoop SARIF report if: ${{ !cancelled() }} uses: github/codeql-action/upload-sarif@v4 with: sarif_file: mcpsnoop.sarif category: mcpsnoop - name: Fail on findings # Separate, and after the upload, so the findings reach the Security tab on # exactly the runs that have some. if: ${{ !cancelled() && steps.check.outputs.exit-code == '1' }} run: exit 1

مثل `drift`، فإن `deprecated` اختياري. التشغيل الافتراضي يُبلغ عن العدد ويبقى أخضر، لذا فإن جلسة تستخدم ميزة مهملة لا تزال قانونية لا تجعل CI يتحول إلى الأحمر من تلقاء نفسه. ### بنى المخطط التي تتعامل معها العملاء بشكل سيئ يمكن أن يكون الخادم صالحًا تمامًا ومع ذلك يكون صعبًا على الوكيل استخدامه. تختلف العملاء في مقدار دعمهم الفعلي لـ JSON Schema، والأداة التي يستمر النموذج في استدعائها بشكل خاطئ غالبًا ما تكون أداة طلب مخططها أكثر مما يقدمه العميل. ملخص الأدوات، الذي يُفتح بـ `s`، يحتوي على عمود SCHEMA يسمي أبرز ما في مخطط كل أداة معلنة، مع `+` في النهاية عندما يكون هناك أكثر من نوع واحد. | المعروض | المعنى | |---|---| | `no root` | `inputSchema` غائب، أو ليس كائن JSON، أو له نوع جذر غير `"object"` | | `dialect` | `$schema` تسمي لهجة غير 2020-12 التي تفترضها المراجعة افتراضيًا | | `ext ref` | `$ref` يشير خارج المستند، وهي الحالة التي تحذر المواصفات المنفذين من اتباعها بشكل أعمى | | `oneOf`, `anyOf`, `allOf`, `not` | كلمة تركيب، تُعالج بشكل غير متسق عبر العملاء | | `ref` | `$ref` يشير داخل نفس المستند | | `untyped` | خاصية لا تعلن عن نوع ولا عن أي طريقة أخرى لقول ما تقبله | كل ما عدا الأول هو ملاحظات وليس أحكامًا. مخطط يستخدم `oneOf` ليس خاطئًا، فقط من المرجح أن يُقرأ بشكل مختلف من قبل عملاء مختلفين، والمخطط قد يعلن أي لهجة يريدها. `no root` هو الاستثناء: تعريف `Tool` يتطلب `inputSchema` ويثبت نوع جذره على `"object"`، لذا فإن العميل الذي يتحقق من صحة القائمة يرفض تلك الأداة تمامًا ولا تصبح قابلة للاستدعاء أبدًا، دون أي شيء على الشبكة يوضح السبب. `no root` يتصدر العمود لهذا السبب، والمخطط الذي نقّحه mcpsnoop الخاص به لا يُبلغ عنه أبدًا، لأن المخطط غير القابل للقراءة ليس مخططًا خاطئًا. هذا التقسيم يحدد ما يفعله `check` بها. `no root` هو تحذير على إطار `tools/list`، لذا يفشل بوابة `error,invalid,warn` الافتراضية دون أي علم على الإطلاق، وهذا هو الهدف: الخادم الذي يرسل أداة غير قابلة للاستخدام يجيب على كل مصافحة بشكل طبيعي ولا يتلقى ببساطة `tools/call` أبدًا. الملاحظات تُحسب كـ `schema_findings` وتُبلغ تحت `schema findings:`، ولا تفشل التشغيل إلا عندما تضيف `schema` إلى `--fail-on`. كلاهما يصل إلى `--format junit` و`--format sarif`، و`export` يحمل قائمة كل أداة تحت `summary.definitions.per_tool[].findings`.```bash mcpsnoop check session.jsonl # a non-object root already fails this mcpsnoop check --fail-on schema session.jsonl # and now so do the observations

بدون `--replay-target`، تُشير جلسة HTTP إلى ذلك بدلاً من تقديم مفتاح لا يمكن أن يعمل. ومع وجوده، لا يزال `r` يطلب التأكيد قبل الإرسال الأول للجلسة، بنفس الطريقة التي يُطلب بها تأكيد أمر مُسجَّل قبل تنفيذه. تصل بيانات الاعتماد إلى الخادم عبر `--replay-header` ولا شيء غير ذلك. لا يسجّل mcpsnoop أي ترويسة `Authorization` ولا يعيد تشغيل أيًا منها، لذا لا يوجد شيء مُلتقَط يمكن أن يُسرّبه إعادة التشغيل. يحمل طلب POST المُعاد تشغيله ما يفرضه النقل كأمر إلزامي، وهو ما لا يفعله طلب POST للجسم المُلتقَط المجرّد: `MCP-Protocol-Version`، وترويسة `Accept` تُدرج كلاً من `application/json` و`text/event-stream`، و`Mcp-Method`، و`Mcp-Name` حيث تتطلبه المواصفات، وكل `Mcp-Param-*` مُلتقَط. تُعاد إرسال تلك الترويسات حرفيًا من الالتقاط، بما في ذلك الحارس المشفَّر base64، لذا لا يمكن أن تتعارض مع الجسم بالطريقة التي قد يحدث بها إعادة اشتقاق. الترويسة الوحيدة التي لا تُنسخ هي إصدار البروتوكول، لأن الجسم المُعاد تشغيله يُعلن عن المراجعة التي يتحدث بها mcpsnoop ويجب أن تطابق الترويسة الجسم. يُشتق `Mcp-Name` من الجسم المُرسَل بدلاً من نسخه، لأن المواصفات تستمدّه من `params.name` أو `params.uri` وتتطلب من الخادم رفض ترويسة تتعارض مع الجسم، لذا فإن التعديل الذي يعيد تسمية الأداة كان سيرسل الاسم القديم بخلاف ذلك. تعكس ترويسات `Mcp-Param-*` الوسائط المُلتقَطة، لذا فإن إعادة تشغيل مُعدَّلة لا ترسل أيًا منها بدلاً من تأكيد شيء عن جسم أعاد شخص ما كتابته. لا يمكن للالتقاط تعيين ترويسات إلا في تلك العائلة الواحدة. السجل هو ملف يتداوله الأشخاص، والسماح له بتسمية أي ترويسة كان سيسمح له بالكتابة فوق الترويسات الإلزامية أو إضافة بيانات اعتماد لم يمررها أحد. توقف `Mcp-Param-*` التي نظّفتها قاعدة تنقيح إعادة التشغيل مع ذكر سبب. إرسال العنصر النائب كان سيضع بايتات mcpsnoop الخاصة على خادم حي كما لو كان مستخدم قد كتبها. يُرفض إعادة التوجيه بدلاً من اتباعها. العنوان هو الذي سمّيته وأجبت عنه، واتباع 307 كان سيسلّم ذلك الاختيار إلى الطرف البعيد، مع إعادة إرسال الجسم، وعلى قفزة تغيّر المنفذ فقط، بيانات الاعتماد أيضًا. يُبلغ mcpsnoop عن المكان الذي أراد الخادم إرساله إليه ويترك لك قرار تسمية ذلك المكان بدلاً منه. يُقرأ كل من الإجابة التي تصل ككائن JSON واحد وتلك التي تصل كتدفق أحداث، ويُسمّى الفشل بدلاً من ترقيمه: - يُبلغ رمز 401 عن المخطط الذي طلبه الخادم - يُبلغ `-32020` عن الشيء الذي اعترض عليه - يُشير رمز 400 أو 404 غير الخاص بـ JSON-RPC إلى أن العنوان ليس نقطة نهاية HTTP قابلة للبث من هذه المراجعة ### تمييز زمن استجابة الخادم عن زمن المستخدم في طلبات متعددة الجولات، تكون استدعاء الأداة الواحدة عدة طلبات، وتقع الثواني التي قضاها شخص في الإجابة على استفسار داخل تلك الفترة. هذا مقصود، لأن تلك الفترة عادةً هي التي تريد رؤيتها أكثر من غيرها، لكنه يعني أن رقمًا واحدًا لا يمكنه الإجابة على السؤالين معًا. في سلسلة `book_flight` حيث عمل الخادم 1.2 ثانية بينما استغرق المستخدم 37، يُلقي `check --max-duration 5s` اللوم على الأداة لمدة 38.2 ثانية. وما زال يفعل ذلك، لأن تغيير معنى ذلك العلم كان سيُرخي كل خط أنابيب يضبطه بالفعل. بدلاً من ذلك، يسمّي شقيقان ما يقيسانه.```bash mcpsnoop check --max-server-duration 1s session.jsonl # the server's share alone mcpsnoop check --max-round-trips 2 session.jsonl # how chatty a tool is

كلاهما معطّل افتراضيًا، لذا فإن تشغيل `check` الافتراضي لا يتأثر، وكلاهما يُقرأ من طوابع الإطارات ومن رابطٍ كان mcpsnoop قد استنتجه بالفعل، لذا لا يخمّن أيٌّ منهما النية. اضغط `i` في واجهة TUI للحصول على التفصيل، أو اقرأ `interactions` في تصديرات json والنص وhtml. كل إدخال هو عملية منطقية واحدة مع عدد جولاتها ذهابًا وإيابًا، وإجماليها، وحصة الخادم من الاحتفاظ بها، وحصة انتظارها على العميل، بالإضافة إلى سطر لكل قفزة يسمّي ما طلبته كل إجابة. يكتسب ملخص كل أداة عمود `TRIPS` بحيث تظهر الأداة كثيرة الكلام دون فتح أي شيء. يضع `export --format har` حصة الخادم في `wait` والباقي في `blocked`، وهذا هو الغرض من ذلك الحقل، بحيث يتوقف العارض عن رسم انتظار خادم دام 38 ثانية ولم يحدث أبدًا. تُجمَّع الأعداد والحصتان مع وصول الإطارات بدلًا من اشتقاقها عند الطلب، لأن المخزن المباشر يحرر الإطارات القديمة ليبقى ضمن ميزانيته، وكانت الإجابة المشتقة ستكون نافذة بصمت بدلًا من سلسلة. يُقرأ تفصيل كل قفزة من الإطارات التي ما زالت محفوظة، ويُذكر ذلك عندما يكون جزءًا من قفزة واحدة فقط. `ServerTime + ClientTurnaround` يساوي الإجمالي بالبناء لا بحسابٍ على أحد أن يثق به. يحكم `--max-round-trips` على سلسلة ما زالت قيد التشغيل، لأن كل طلب قدّمته بالفعل قابل للعدّ، والخادم الذي يطلب مرارًا وتكرارًا ينتج بالضبط العملية التي لا يُنهيها أحد أبدًا. ينتظر `--max-server-duration` نهايةً، وهي القاعدة التي يطبّقها `--max-duration` بالفعل، لأن العملية التي ما زالت مفتوحة لا تملك زمن استجابة ليُحكَم عليه. العملية التي لم يستطع mcpsnoop ربطها تبقى إدخالها الخاص بقفزة واحدة. يرفض `matchRetry` رابطًا غامضًا عن قصد، ولا يسدّ هذا العرض تلك الفجوة. العملية التي استغرقت طلبًا واحدًا لا تحمل تفصيل قفزات، لأن القفزة الواحدة تعيد صياغة الإجماليات أعلاه كلمةً بكلمة. تبلغ السلسلة عن قفزة واحدة لكل طلب، وتذكر ذلك عندما لا يعود المخزن يحمل كل إطار أو عندما تستقر العملية خارج زوج الطلب والإجابة الذي تتكوّن منه القفزة، وهو ما يفعله مقبض المهمة. ### انظر ما طلبه خادم من مستخدمك الاستجواب هو المسار الوحيد في MCP حيث يكتب شخص بيانات إلى خادم، وتحت MRTR لم يعودا السؤال والجواب نصفين لتبادلٍ واحد. السؤال مدفون في `InputRequiredResult`، ويعود الجواب داخل `inputResponses` عند إعادة محاولة بمعرّف مختلف، والشيء الوحيد الذي يربطهما هو الرابط الذي يستنتجه mcpsnoop بالفعل. بدون ذلك الاقتران، يظهر طلب كلمة مرور مرفوض كخطأ أداة عادي.``` tools/call login_legacy [form] creds: decline after 3s password string

صف واحد لكل خادم وليس لكل جلسة. مفتاح الصف هو الأمر المسجَّل ودليل العمل، وليس التسمية أبدًا، لأن التسمية تأتي من آخر عنصر مسار في الأمر و`node ~/one/build/index.js` و `node ~/two/build/index.js` كلاهما يشتقان `index.js`. جلسة HTTP تُفتح بمفتاح على نقطة النهاية التي وكّلها بدلًا من ذلك، لأن mcpsnoop لم يُطلق شيئًا هناك. القراءة هي مغلّف واحد لكل سجل، وهو الإطار الوصفي الذي يكتبه الوكيل أولًا، لذا يبقى هذا رخيصًا عبر دليل من التقاطات كبيرة. `--tools` هو الاستثناء ويقرأ سجلًا واحدًا لكل خادم، وهو أحدث تشغيل لكلٍّ منها، ولهذا هو علامة وليس عمودًا. وحتى عندها تكون القراءة محدودة، لأن جرد الأدوات هو حالة جلسة يطويها المخزن أثناء تقدمه، لذا فإن التقاطًا بمئة ميغابايت يُقرأ عبر نافذة ثابتة بدلًا من الاحتفاظ به كاملًا لإنتاج عدد صحيح واحد. عندما لا يوجد عدد، يذكر الصف أيٌّ من ثلاثة أشياء حدث، لأن السجل الذي تعذّرت قراءته ليس خادمًا لم يُعلن عن شيء، وجملة واحدة لكليهما ستجعل mcpsnoop يذكر أمرًا خاطئًا. أمر أعادت كتابته قاعدة `--redact` يُطبع كما سُجِّل ويُعلَّم، بدلًا من تمريره كالأمر الذي نُفِّذ. تشغيلان لخادم واحد، أحدهما مُنقَّح والآخر ليس كذلك، هما صفّان. لا يمكن لـ mcpsnoop معرفة ما استبدله العنصر النائب، ودمجهما سيعني تخمين أن النصفين المخفيين متطابقان. خادم واحد يعمل تحت قيمتين لـ `--label` هو صف واحد يحمل الاسمين، لأن المفتاح هو الأمر وليس الاسم. لا شيء في الصف يكتبه mcpsnoop. الأمر يأتي من whoever ثبّت الخادم، ودليل العمل يأتي من نظام الملفات، والتسمية المشتقة تأتي من الأمر. قيمة تحمل حرف تحكم تُقتبس بدلًا من طبعها خامًا، لذا لا يمكن لدليل يحتوي اسمه على سطر جديد أن يُغلق الحقل الذي يُطبع فيه ويجعل الأسطر التالية تُقرأ كخوادم لم تعمل أبدًا. وسيطة تحتوي على مسافة تُقتبس أيضًا، لأن `node "~/My Project/build/index.js"` لا يمكن تمييزها بخلاف ذلك عن وسيطتين. أي شيء لم يستطع المسح طيّه يُذكر في الترويسة بدلًا من إسقاطه. السجلات الفارغة تُحسب منفصلة عن التالفة، لأن السجل صفر البايت هو بقايا عادية لتشغيل فشل فيه exec أو لوكيل HTTP لم يستدعه أحد. المخرجات تُرتَّب بالاسم وليس بالأحدثية بحيث ينتج تشغيلان على دليل واحد نفس البايتات، وهو ما يجعلها قابلة للاستخدام كخط أساس للمقارنة لاحقًا. ثغرتان موجودتان بالتصميم وليس بالإغفال. تشغيل مع `--trace-file` كتب خارج دليل الجلسات ولن يظهر، و `prune` يحذف السجلات، لذا فإن أول ظهور لا يكون أقدم أبدًا مما هو ما زال على القرص. يبلّغ mcpsnoop عما عمل على هذا الجهاز عبره. لا يفحص شبكة، ولا يقرأ إعداد عميل لم يُوجَّه إليه، ولا يحكم على شيء. ### التمييز بين خادم معطوب وأداة تقول لا أداة تجيب بـ `result.isError` تعمل. لقد نظرت ولم تجد شيئًا، أو رفضت المدخلات. خادم يجيب بخطأ JSON-RPC معطوب. كلاهما كان رقمًا واحدًا في ملخص الأدوات، مما جعل أداة حسنة السلوك تبلّغ عن إخفاقات المجال تبدو تمامًا كخادم معطوب، وتُرتب فوقه. عمود `ERR` يفصل بينهما. الأحمر هو جانب الخادم، وهو خطأ JSON-RPC أو مهمة انتهت بالفشل دون ذكر السبب. اللون التحذيري هو `isError` الخاص بالأداة نفسها. أداة تحمل كليهما تُظهر العدّين موصولين، الأحمر أولًا، وسطر تحت الجدول يسمّي الإجماليين كلما وُجد رقم تحذيري لشرحه. يحمل التصدير نفس التقسيم كـ `protocol_errors` و `tool_errors` بجانب إجمالي `errors` الذي يصلان إليه دائمًا. `check --fail-on error` لم يتغيّر وما زال يعمل على أيٍّ منهما، لأن بوابة تتجاهل أحدهما ستكون بوابة يمكن لخادم إيقافها بإرجاع الآخر.```bash mcpsnoop export -T json | jq '.summary.tools[] | {name, errors, protocol_errors, tool_errors}'

التصدير يحمل نفس الأرقام، لكل أداة ومقسّمة إلى وصف و بايتات المخطط، لذا فإن الوصف الضخم والمخطط الضخم يبقيان قابلين للفصل ويمكن تتبّع أيٍّ منهما عبر اللقطات. يخبرك `mcpsnoop diff` ما إذا كان الوصف أو المخطط قد تغيّر بين جلستين. التصدير هو المكان الذي يعيش فيه حجم ذلك التغيير. **هذه بايتات، وليست رموزًا.** يعتمد عدد الرموز على النموذج، لذا فقياسها يعني تضمين محلل رموز واختيار أي نموذج. البايتات دقيقة ويمكنك تطبيق النسبة الخاصة بك عليها. يُبلّغ `tools/list` غير المكتمل بما رآه كحد أدنى ويوضح ذلك، بدلًا من تمرير مجموع جزئي على أنه الإجمالي. ### كشف عميل يعبث بحالة الخادم في نمط الرحلات المتعددة ذهابًا وإيابًا، يسلّم الخادم للعميل قيمة `requestState` غير شفافة ويجب على العميل إعادتها كما هي دون تغيير عند إعادة المحاولة. يُطلب من الخادم معاملتها كمدخل يتحكم فيه المهاجم، لأن العميل الذي يعبث بها قد يحاول تغيير سلوك الخادم أو تجاوز فحص التفويض. وبكونه في منتصف الاتصال، يرى mcpsnoop القيمة تغادر وتعود، لذا يمكنه القول متى انتهك العقد. هناك ثلاث طرق يمكن أن ينتهك بها، كل واحدة تُبلَّغ كتحذير بروتوكول عند إعادة المحاولة. | المُبلَّغ | المعنى | |---|---| | `MRTR retry changed requestState` | أرسل العميل شيئًا مختلفًا عمّا أصدره الخادم | | `MRTR retry is missing requestState` | أصدر الخادم قيمة وحذفها إعادة المحاولة | | `MRTR retry invented requestState` | حملت إعادة المحاولة قيمة لم يصدرها الخادم أبدًا | هذه انتهاكات بروتوكول من جانب العميل وليست ملاحظات من جانبنا، لذا فهي تسلك مسار إشارة التحذير العادي و**يفشل تشغيل `check` الافتراضي عند حدوث واحدة**. هذا مقصود. العميل الذي يعبث بحالة الخادم يستحق إيقاف البناء من أجله. لا يتم عرض القيمة نفسها أو تسجيلها أبدًا، ولا شيء يفك ترميزها أو يحللها. قد تكون كتلة مشفرة تحمل هوية ورموزًا، ومقارنة البايتات غير الشفافة هي الفحص بأكمله. هناك حالة واحدة خارج النطاق. عندما يجيب الخادم بقيمة `requestState` دون `inputRequests`، فإن إعادة المحاولة العابثة لا تطابق شيئًا ولا تجيب عن أي مفاتيح، لذا لا يبقى ما يربطها بالطلب الأصلي وتُقرأ كاستدعاء غير مرتبط بدلًا من انتهاك. التبادل المهجور لا يزعج التالي، ولا يُحتفظ به إلى الأبد أيضًا. أربعة وستون تبادلًا مفتوحًا أكثر بكثير مما يملكه أي عميل في وقت واحد، لذا فالجلسة التي تحمل أكثر من ذلك تحمل تبادلات لن يُنهيها أحد، ويُتقاعد الأقدم لأن المواصفات تطلب من الخوادم منح تلك الحالة صلاحية قصيرة و رفضها بعد ذلك. التقاعد يُحسب بدلًا من أن يكون صامتًا. يُظهر تذييل الدفق `N unlinked` ويحمل التصدير `session.retired_exchanges`، لأن إعادة المحاولة التي تصل لعملية متقاعدة تُقرأ كاستدعاء خاص بها، والقارئ الذي يقارن الأعداد يستحق أن يُخبَر. تقاعد واحدة يسمح أيضًا للمخزن الحي بتحريرها. تبقى العملية المتوقفة قيد الانتظار عن قصد، لذا يمتد مداها عبر التبادل بأكمله، ويرفض المخزن نسيان استدعاء معلق لأن الاستجابة قد لا تزال قادمة. بمجرد أن يتقاعد الحد الأقصى عمليةً، لا يمكن لأي شيء الإجابة عنها، لذا فإن الاحتفاظ بها يُبقي استدعاءً حيًا لا يمكن لأي قارئ الوصول إليه. ما تُبلغ عنه الجلسة لا يتغير. لا يزال يُحسب كاستدعاء معلق وما زال يُحسب في `N unlinked`، لأن مقدار الذاكرة التي يشغلها السجل وما يقوله السجل سؤالان مختلفان. التبادل المهجور لا يزعج التالي. يخبر MRTR الخوادم بأنه يجب ألا تفترض أن العميل سيعيد المحاولة أبدًا، لذا فإن المستخدم الذي يرفض استدراجًا يترك عمليةً لن تسوّيها أي إطارات لاحقة أبدًا. يبحث mcpsnoop أولًا بين العمليات التي يتوافق وجود `requestState` فيها مع إعادة المحاولة، وهو ما تجعله المواصفات قاعدة في الاتجاهين، لذا فإن إعادة المحاولة المطابقة لا تزال تجد العملية الوحيدة التي تواصلها حتى عندما يجلس تبادل مهجور على نفس الأداة بجانبها. الفحص الذي يُبلّغ عن الانتهاكات الثلاثة أعلاه يعمل فقط عندما لا يتوافق شيء، لذا فإن إعادة المحاولة غير المطابقة حقًا لا تزال تُسمّى. ## المراقبة من جهاز آخر أبقِ الالتقاط محليًا على الجهاز الذي يحدث فيه حركة المرور واستخدم SSH للقفزة عبر الشبكة، لذا لا يحتاج mcpsnoop أبدًا إلى نقل عن بُعد خاص به. ### العرض المباشر شغّل واجهة TUI على محطة عملك ومرّر مقبس mcpsnoop الخاص بالجهاز البعيد إليها. يستخدم النفق المباشر توجيه مقبس SSH عبر Unix، لذا يجب أن يعمل كلا الطرفين على Linux أو macOS. على Windows، استخدم نسخة السجل بعد الوفاة أدناه.```bash # on your workstation, start the TUI mcpsnoop # create the remote socket directory once ssh remote-user@remote-host 'mkdir -p ~/.local/state/mcpsnoop' # print the tunnel command, then run the printed ssh -R line mcpsnoop remote remote-user@remote-host # on the remote host, wrap your server as usual mcpsnoop -- node build/index.js

## الأمان يشغّل mcpsnoop أمر الخادم الذي تغلّفه، لذا لا تغلّف إلا الخوادم التي تثق بها، وشغّل غير الموثوقة داخل حاوية. لا ينفّذ أبدًا أي شيء لم تضعه في إعدادات عميلك. بالنسبة لسير العمل عن بُعد، استخدم نفق SSH أو نقل ملفات SSH بحيث تبقى مصادقة النقل والتشفير والتحقق من المضيف وتدوير المفاتيح وسياسة التدقيق ضمن إعداد SSH الحالي لديك. ### تنقيح ما تلتقطه يمكن أن تتضمن الإطارات الملتقطة المطالبات ووسائط الأدوات وبيانات الاعتماد ونتائج الأدوات. إذا كانت الحمولات قد تحمل أسرارًا، فاختر الاشتراك في التنقيح لتنظيف نسخ التتبّع المرصودة بينما تظل البايتات المُمرَّرة عبر الوكيل تمر دون تغيير. يستبدل التنقيح المستند إلى المفاتيح القيم الكاملة تحت مفاتيح JSON المطابقة، وتُطبَّق نفس مجموعة المفاتيح بأفضل جهد على وسائط سطر الأوامر للخادم المغلَّف، لذا يتم تنظيف `--api-key=sk-x` و`--token sk-x` تحت `--redact-secrets`. لا يمكن اكتشاف وسيطة تحمل سرًا دون اسم علم مميّز. لا تعد نقطة نهاية HTTP جزءًا من أيٍّ من ذلك، لأنها ليست حمولة اخترت إرسالها. `--target` علم يجب تمريره لتشغيل الوكيل أصلًا، لذا سيصل عنوانه إلى سجل الجلسة مهما كانت إعدادات التنقيح لديك. يكتبه mcpsnoop مع إزالة معلومات المستخدم وكل قيمة استعلام والجزء المقتطع دائمًا، بالبناء لا بالنمط. تبقى مفاتيح الاستعلام، لأنها ما يميّز نقطتي نهاية لمضيف واحد، ويُسقَط الجزء المقتطع لأنه لم يصل إلى الخادم أصلًا. ما يُسجَّل يحدد الخادم وليس عنوانًا للاتصال به. يستبدل التنقيح المستند إلى المسار فقط القيم المحددة بتعبير JSONPath، وهو مفيد عندما يكون اسم مفتاح شائع حساسًا في موضع واحد وآمنًا في آخر. كرّر `--redact-path` لتنظيف أكثر من موضع واحد. يطبّق التنقيح المستند إلى القيمة تعبيرات منتظمة على قيم السلاسل المرصودة ونص stderr وإطارات النص غير JSON. كلها بأفضل جهد. قد تفوت التعبيرات المنتظمة أسرارًا، أو تطابق نصًا غير ضار بشكل مفرط، أو تفشل في رؤية القيم المحوَّلة أو المشفَّرة. لا يتحول التنقيح أبدًا إلى اتهام. كل فحص يقارن شيئًا مرصودًا بآخر، أو ترويسة توجيه بالجسم، أو قيمة `Mcp-Param` بالوسيطة التي تعكسها، أو مخطط أداة بما يتطلبه التنقيح منها، يعرف متى كان mcpsnoop هو الجانب الذي أعاد كتابة البايتات ويبقى صامتًا بدلًا من الإبلاغ عن خادم بسبب إعداد الخصوصية الخاص بالمستخدم. انحراف تعريف الأداة هو الاستثناء، وعمدًا، لأن تشغيل التنقيح يغيّر ما يُسجَّل وبالتالي ما يحمله خط الأساس. انظر [اكتشاف انحراف تعريف الأداة](#detect-tool-definition-drift).```bash # built-in preset of common secret keys mcpsnoop --redact-secrets -- node build/index.js # or name your own keys mcpsnoop --redact-key token,api_key,password -- node build/index.js # scrub one location without redacting every field named password mcpsnoop --redact-path '$.params.arguments.password' -- node build/index.js # wildcards scrub every matching array element mcpsnoop --redact-path '$.params.arguments.accounts[*].password' -- node build/index.js # scrub obvious token-shaped values outside known keys mcpsnoop --redact-value 'sk-[A-Za-z0-9]+' -- node build/index.js # combine the layers in http mode mcpsnoop http --target http://localhost:3000/mcp --redact-secrets --redact-value 'Bearer\s+\S+'

الإشارة	تفشل عند
`error`	مكالمة يُرد عليها بخطأ JSON-RPC، أو نتيجة موسومة بـ `isError`، أو مهمة انتهت بفشل
`invalid`	إطار على قناة البروتوكول ليس JSON-RPC صالحًا، عادةً ما يكون خادمًا يسجّل إلى stdout
`warn`	إطار يخالف توقعًا تحدده مواصفات MCP أو JSON-RPC
`mismatch`	ترويسة توجيه تتعارض مع الجسم، أو تركب دفعة، أو تغيب حيث يتطلبها الإصدار
`pending`	طلب ما زال مفتوحًا عند انتهاء الالتقاط، فتُرك المتصل في انتظار
`late-result`	استجابة وصلت بعد إلغاء طلبها
`drift`	تعريف أداة معلن يتغير بعد اعتماد خط الأساس
`deprecated`	ميزة أوقفتها المواصفات
`incomplete`	إطارات أُسقطت من المصب، مما يجعل كل عدد آخر حدًا أدنى وليس إجمالًا
`schema`	مخطط معلن يستخدم بنية أو لهجة تنتقل بشكل سيئ عبر العملاء

العلامة	تفشل عندما
`--max-duration <dur>`	تجاوز استدعاء أداة واحد أو أكثر من الاستدعاءات المكتملة الميزانية، مع الإبلاغ عن عددها وأسوأ استدعاء
`--expect-tool <name>`	لم يتم استدعاء الأداة المسماة أبدًا (قابلة للتكرار)
`--forbid-tool <name>`	تم استدعاء الأداة المسماة (قابلة للتكرار)

القاعدة	تُبلَّغ كـ
يجب على العميل إرسال `Accept` يسرد كلاً من `application/json` و`text/event-stream`	`warn` على الطلب
يجب على الخادم الذي يرد على طلب JSON-RPC إرجاع `Content-Type: application/json` أو `text/event-stream`	`warn` على الاستجابة

mcpsnoop

الأكثر شعبية

في CI

ملف الإعداد

Go```bash

إكمالات الصدفة

كيف يعمل

تصدير الجلسات

التنقيح

مقارنة الجلسات

تأكيد ما يجب وما لا يجب أن يحدث

a contract for the run: search must run, delete must not, nothing over 2s

إجراء GitHub

التقاط ترويسة توجيه تتعارض مع الجسم

التحقق من ترويسات النقل التي تفرضها المواصفة

اكتشاف انجراف تعريف الأداة

المتطلبات الأساسية

التثبيت من المصدر

التحقق من التثبيت

وضع علامة على ميزات البروتوكول المهجورة

إعادة تشغيل استدعاء تم التقاطه عبر HTTP

الاستخدام

أمثلة متقدمة

التكوين

استكشاف الأخطاء وإصلاحها

الترخيص

ابحث عن الأداة التي تفشل مرة واحدة من كل أربع

معرفة أي الخوادم شُغّلت فعلًا هنا

تعرّف على ما يكلّفك الخادم في السياق

a non-Linux or custom home, macOS is /Users/ and root is /root

an explicit MCPSNOOP_HOME on the remote

an explicit XDG_STATE_HOME on the remote

copy the remote logs into your local sessions directory

open the TUI, it backfills the copied sessions

المساهمة

الترخيص