لاستخدامه فعليًا، قم بتغليف خادمك في إعدادات MCP الخاصة بعميلك.```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap` يجد `claude_desktop_config.json`، وينسخه إلى `claude_desktop_config.json.mcpsnoop.bak` في المرة الأولى، ويعيد كتابة إدخال ذلك الخادم الواحد فقط، بحيث لا يتغيّر تنسيقك ولا أيّ خادم آخر. داخل الإدخال المعاد كتابته تعود المفاتيح بترتيب أبجدي. `unwrap` يستعيد الملف، ويزيل النسخة الاحتياطية بمجرد عدم بقاء أي خادم مغلّف. أعد تشغيل Claude Desktop بعد أيٍّ من العمليتين، إذ تُطلق خوادم MCP مرة واحدة عند بدء التشغيل.

ثم استخدم عميلك كالمعتاد وافتح الواجهة.```bash
mcpsnoop

حالة HTTP لكل استجابة تظهر في الدفق، لذا فإن الاستجابة التي لا تحمل
أي رسالة JSON-RPC خاصة بها ما تزال إطارًا مرئيًا بدلًا من لا شيء: تحدي
401، و403 عند رفض Origin، و202 التي تؤكد إشعارًا،
و502 عندما يتعذر الوصول إلى الهدف إطلاقًا. تُحفظ ترويسة
`WWW-Authenticate` الخاصة بـ401 حرفيًا وتُعرض في المُفتش، لأنها
تشير إلى مخطط المصادقة وبيانات تعريف المورد الذي يجب الانتقال إليه بعد ذلك.
صفِّ حسب الحالة باستخدام `status:401` في TUI، أو حسب أي فشل باستخدام
`status:err`. أي استجابة 4xx أو 5xx تُحتسب كخطأ، لذا فإن التشغيل
الافتراضي لـ`mcpsnoop check` يفشل عندها.

ليس لديك خادم خاص بك؟ [جرّبه فعليًا](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md) مقابل خادم
اختبار منشور، مدفوعًا بعميلك الخاص. لتفقد جلسة بعد حدوثها،
انظر [مراجعة الجلسات السابقة من السجلات](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md).

### ملف الإعدادات

إذا أعدت استخدام نفس أعلام shim عبر مشروع، ضعها في ملف
`.mcpsnoop.toml` في دليل العمل الحالي.```toml
label = "filesystem"
trace-file = "trace.jsonl"
redact-secrets = true
redact-key = "token,authorization"
redact-value = "sk-[A-Za-z0-9]+"
redact-path = "$.params.arguments.password"
no-trace = false

### Homebrew```bash
brew install mcpsnoop

`--older-than` مطلوب (لا يوجد افتراضي يحذف أي شيء) ويقبل عدد أيام مثل `30d` أو مدة Go مثل `72h`. تُترك خطوط الأساس للأدوات كما هي، لأن خط الأساس مرتبط بتسمية الخادم وليس بالجلسة.

نظرًا لأنه يقع في الأنبوب الفعلي، وليس على الجانب مثل Inspector، فإنه يرى بالضبط ما يقوله عميلك وخادمك الحقيقيان لبعضهما البعض، مهما كانت اللغة التي كُتب بها الخادم.

## اختصارات لوحة المفاتيح

| Key | Action | | Key | Action |
|---|---|---|---|---|
| `enter` | فحص / تعمق | | `/` | تصفية |
| `esc` | رجوع | | `:` | أمر |
| `j` / `k` | تحريك | | `r` | إعادة تشغيل مكالمة |
| `g` / `G` | أعلى / أسفل | | `c` | القدرات |
| `ctrl-f` / `ctrl-b` | صفحة | | `s` | ملخص الأداة |
| `p` | إيقاف مؤقت | | `y` | نسخ |
| `shift`+`<key>` | فرز حسب العمود | | `e` | تصدير |
| `ctrl-d` | حذف الجلسة | | `f` | متابعة |
| `?` | مساعدة | | | |

اضغط `?` في التطبيق للاطلاع على القائمة الكاملة.

## تصفية التدفق

اضغط `/` في جلسة وادمج الرموز المفصولة بمسافات، بعملية AND. النص العادي يطابق الأسلوب، والأداة، والمعرّف، والحمولة.

| Token | Filters by | Example |
|---|---|---|
| `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` الخاص بالطلب معرف التتبع ومعرف الـ span الأصلية لذلك الاستدعاء، ويُرافق `_meta.tracestate` الـ span. عندما يكون 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 بينما يعمل البروكسي بتوجيهه إلى نقطة نهاية traces بصيغة OTLP/HTTP JSON. كرّر `--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|-]

يُرافق عددُ الإطارات المسقطة القطعَ الأثرية أيضًا، لذا فإن أي التقاطٍ
يُقلِّل من العدد يُفصح عن ذلك أينما فُتح: `missing_frames` في تصدير
JSON، و`log.comment` في HAR، وسمة المورد `mcpsnoop.session.missing_frames`
في OTLP.```bash
mcpsnoop check build-agent
mcpsnoop check --fail-on error,invalid artifacts/session.jsonl
mcpsnoop check --fail-on mismatch gateway-run.jsonl

### أبلغ عنه حيث ينظر CI بالفعل

`--format junit` يكتب عنصر `<testcase>` واحدًا لكل إشارة وجلسة، وتتبع حالات فشله
نفس تحديد `--fail-on` المستخدم في إخراج النص.```yaml
- name: Check captured MCP session
  run: |
    mkdir -p test-results
    mcpsnoop check --format junit artifacts/session.jsonl > test-results/mcpsnoop.xml
- name: Upload mcpsnoop JUnit report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: mcpsnoop-junit
    path: test-results/mcpsnoop.xml

### التقاط ترويسة توجيه تتعارض مع محتوى الطلب

في نقل streamable-HTTP، توجّه البوابة بناءً على `Mcp-Method` و`Mcp-Name`
بينما يقرأ الخادم محتوى الطلب، لذا فإن ترويسة تتعارض مع ذلك المحتوى تعني
أن الطرفين ينظران إلى طلبين مختلفين. تغطي إشارة `mismatch` تلك الحالة،
وترويسة ترد مع دفعة لا يمكنها توجيهها، وترويسة مطلوبة مفقودة
تمامًا.

اعتبارًا من 2026-07-28، يُعدّ غياب ترويسة التوجيه فشل تحقق، ويرفض الخادم المطابق
الطلب برمز `400` و`-32020`. لا يطلق mcpsnoop هذه الإشارة إلا بعد أن يُعرف
أن الجلسة تتحدث بذلك الإصدار أو أحدث، لأن الإصدارات السابقة
لا تعرّف هذه الترويسات إطلاقًا، وإغفالها هناك صحيح. رفض الخادم ذاته
لطلب برمز `-32020` يُحتسب كالإشارة نفسها.

الاسم أو URI للمورد الذي لن يتسع لقيمة حقل HTTP يُنقل بترميز Base64 داخل
مؤشّر `=?base64?…?=`، ويُفكّ ترميزه قبل المقارنة، لذا لا يُعلَّم
على عميل يرمّز بشكل صحيح أبدًا.

في طلبات `tools/call` عبر HTTP، يعرض mcpsnoop أيضًا كل ترويسة `Mcp-Param-{Name}`،
وعندما يكون تعريف الأداة المُعلَن المطابق معروفًا، يقارنها بمسار الوسائط
المُعلَّم. تُعالَج الخصائص المتداخلة، ومؤشّر Base64، والقيم المنطقية،
والأعداد الصحيحة الآمنة المكافئة عدديًا دون نتائج إيجابية كاذبة من مقارنة
السلاسل النصية. تبقى ترويسات الوسائط غير المعروفة والجلسات التي لا تتضمن
تعريف أداة مطابقًا ضمن نطاق الملاحظة فقط. ينطبق التنقيح القائم على المفتاح والقيمة
على قيم ترويسات الوسائط الملتقطة قبل وصولها إلى نقطة الاستهلاك، ولا يُبلَغ
أبدًا عن قيمة نظّفها mcpsnoop بنفسه على أنها تعارض.

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

أول `tools/list` كامل يُلاحَظ لوسم خادم يصبح خط الأساس الموثوق
له. تقارن الجلسات اللاحقة خط الأساس المذكور حقلًا بحقل: الوصف،
والعنوان، ومخطّطي الإدخال والإخراج، والتعليقات التوضيحية والأيقونات، بالإضافة إلى
الأدوات التي أُضيفت أو أُزيلت. التعليقات التوضيحية هي الأهم، لأن أداة اعتُمدت
مع `readOnlyHint` ثم تعلن لاحقًا عن نفسها كأداة تخريبية هي سحب البساط الذي
وُجد هذا الفحص من أجله، وتوجّه المواصفات العملاء إلى معاملة التعليقات التوضيحية
باعتبارها غير موثوقة. يُتتبَّع العنوان والأيقونات لأنهما ما يراه المستخدم، وتصنّف
المواصفات `title` الخاص بالأداة فوق `annotations.title` وفوق اسمها. يشير جدول الجلسات
وملخص الأدوات إلى الانحراف دون حظر أو تغيير حركة مرور MCP.

تُقارن التعليقات التوضيحية عبر قيمها الافتراضية في المواصفات، لذا لا يُبلَغ عن خادم
يبدأ بذكر تلميح صراحة كان يعتمد عليه أصلًا. خط الأساس المسجَّل قبل أن يتتبّع
mcpsnoop حقلًا ما يظل يعمل للحقول التي يسجلها فعلًا، ويوضح أيّها لا يمكنه
الإجابة عنه؛ أعد التسجيل باستخدام `mcpsnoop baseline --accept` بمجرد أن تثق
بالتعريفات الحالية.

تغيير ما يسجّله التنقيح يغيّر ما يقارنه فحص الانحراف. خط أساس مأخوذ
بدون `--redact-value` ثم يُفحص مقابل التقاط مأخوذ به
يُبلِغ عن الحقول المنظّفة كحقول متغيّرة، وهذا صحيح، لأن التعريف المسجَّل
تغيّر فعلًا. أعد التسجيل باستخدام `--accept` بعد تغيير إعدادات التنقيح.

استخدم `--label` ثابتًا وفريدًا لكل خادم قد يتعارض اسم أمره أو مضيفه
الهدف من دونه. تُخزَّن خطوط الأساس تحت دليل حالة mcpsnoop العادي،
فتنطبق `MCPSNOOP_HOME` و`XDG_STATE_HOME`.```bash
mcpsnoop check --fail-on drift session.jsonl
mcpsnoop baseline session.jsonl
mcpsnoop baseline --accept session.jsonl  # trust a legitimate definition change
mcpsnoop baseline --reset session.jsonl   # trust the next complete tools/list

`drift` اختياري لأمر `check`؛ وبوابة `error,invalid,warn` الافتراضية لم تتغير.

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

يُهمِل تنقيح 2026-07-28 كلاً من Roots وSampling وLogging. وستستمر في العمل لمدة عام على الأقل، لذلك يقوم mcpsnoop بوضع علامة عليها بدلاً من التعامل معها كأخطاء. ويقوم كل من التدفق (stream) ومُفحص القدرات (capability inspector) والتصدير (export) بوضع علامة عليها، ويسمّي كل مؤشر البديل.

أصبح الوصول إلى اثنتين من الثلاث غير ممكن إلا عبر طلب متعدد الجولات (multi round-trip)، حيث يقع اسم الطريقة داخل خريطة `inputRequests` الخاصة بالخادم بدلاً من أن يكون على الإطار نفسه. وهذه أيضًا يتم وضع علامة عليها، بحيث لا يتوقف الخادم الذي انتقل إلى النمط الجديد عن الإبلاغ بصمت.```bash
mcpsnoop check --fail-on deprecated session.jsonl

العمود يحمل لون التحذير ولا يحمل أبدًا اللون الأحمر لعمود ERR، وما زال mcpsnoop لا يغيّر شيئًا في حركة المرور التي يمررها.

لا يتم حل أي شيء أو جلبه. يتم التعرف على `$ref` الخارجي من شكله وحده، ولا تتم قراءة المخطط الذي يشير إليه أبدًا.

### انظر كم يكلفك الخادم في السياق

تدخل تعريفات الأدوات إلى سياق النموذج في كل محادثة، وتدخل نتائج الأدوات في كل استدعاء. يقيس ملخص الأدوات (`s`) كليهما من الجلسة التي التقطتها فعليًا.

سطر `definitions` هو التكلفة الثابتة: ما يزنه `tools/list` الخاص بهذا الخادم قبل إجراء أي استدعاء واحد. يوضح عمود `DEF` ذلك لكل أداة، و`RESULT` هو ما كلفت إجابات كل أداة حتى الآن. يبقى الجدول مرتّبًا حسب الأخطاء وزمن الاستجابة، لذلك افحص `DEF` للعثور على التعريفات المكلفة؛ يسردها التصدير من الأثقل أولًا. سطر أسفل الجدول يسمي النتيجة الأثقل المفردة، وهو ما يخفيه المجموع الإجمالي.

أرقام التعريفات هي JSON مع إزالة المسافات البيضاء غير المهمة، لذلك لا يُحتسب الخادم الذي يطبع `tools/list` الخاص به بشكل منسّق على أنه أكثر تكلفة من الذي لا يفعل ذلك، ويقيس الخادم نفسه نفس القيم عبر عمليات الالتقاط المختلفة. `RESULT` هو البايتات كما وصلت: النتيجة هي حمولة لمرة واحدة وليست عقدًا يستحق التطبيع.```bash
mcpsnoop export -T json | jq '.summary.definitions'

يقع المقبس تحت دليل الحالة الخاص بالجهاز البعيد، ويُحلّ مساره كالتالي: `MCPSNOOP_HOME`، وإلا `XDG_STATE_HOME/mcpsnoop`، وإلا `~/.local/state/mcpsnoop`. افتراضيًا، يفترض mcpsnoop أن دليل home في لينكس هو `/home/<user>` المستمد من `user@host` لديك، ويطبع تذكيرًا إلى stderr كلما لجأ إلى هذا التخمين. إذا كان الجهاز البعيد يُحلّ إلى مكان آخر، فاذكر الجزء الوحيد غير الافتراضي.```bash
# a non-Linux or custom home, macOS is /Users/<user> and root is /root
mcpsnoop remote --remote-home /Users/remote-user remote-user@remote-host

# an explicit MCPSNOOP_HOME on the remote
mcpsnoop remote --remote-mcpsnoop-home /srv/mcpsnoop remote-user@remote-host

# an explicit XDG_STATE_HOME on the remote
mcpsnoop remote --remote-xdg-state-home /var/lib/state remote-user@remote-host

للاحتفاظ بنسخة محلية بدلاً من ذلك، انسخ السجلات عبر scp إلى دليل الجلسات الخاص بك وقم بتشغيل
TUI كالمعتاد.```bash
# copy the remote logs into your local sessions directory
mkdir -p ~/.local/state/mcpsnoop/sessions
scp remote-user@remote-host:'~/.local/state/mcpsnoop/sessions/*.jsonl' \
  ~/.local/state/mcpsnoop/sessions/

# open the TUI, it backfills the copied sessions
mcpsnoop

بالنسبة لسير العمل عن بُعد، استخدم نفق SSH أو نقل الملفات عبر SSH بحيث تبقى مصادقة النقل، والتشفير، والتحقق من المضيف، وتدوير المفاتيح، وسياسة التدقيق ضمن إعداد SSH الحالي لديك.

## المساهمة

نرحب بالمشكلات وطلبات السحب. راجع [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md) للتفاصيل.

## الترخيص

[MIT](https://github.com/kerlenton/mcpsnoop/blob/HEAD/LICENSE)