⚠️ تم نقل هذا المستودع. يستمر التطوير النشط في ScopeBlind/scopeblind-gateway.

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

protect-mcp

بوابة أمان لخوادم MCP. يسجل وضع الظل افتراضيًا، وسياسات لكل أداة، وإيصالات Ed25519 محلية اختيارية، ومخرجات تدقيق قابلة للتحقق.

مسار CLI الحالي: لف أي خادم MCP قياسي (stdio) كوكيل شفاف. في وضع الظل يسجل كل طلب tools/call ويسمح بكل شيء. أضف ملف سياسة لفرض قواعد لكل أداة. قم بتشغيل protect-mcp init لإنشاء مفاتيح توقيع محلية وتكوين حتى تتمكن البوابة من إصدار إيصالات موقعة أيضًا.

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

# لف تكوين OpenClaw / MCP موجود في حزمة قابلة للاستخدام
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# وضع الظل — سجل كل استدعاء أداة، لا تُطبق شيئًا
npx protect-mcp -- node my-server.js

# إنشاء مفاتيح + قالب تكوين للتوقيع المحلي
npx protect-mcp init

# وضع الظل مع تمكين التوقيع المحلي
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# وضع الإجبار
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# تصدير حزمة تدقيق قابلة للتحقق دون اتصال
npx protect-mcp bundle --output audit.json

ماذا يفعل

يجلس protect-mcp بين عميل MCP والخادم كوكيل stdio:

عميل MCP ←stdin/stdout→ protect-mcp ←stdin/stdout→ خادم MCP الخاص بك

يعترض طلبات JSON-RPC من نوع tools/call ويقوم بما يلي:

• وضع الظل (افتراضي): يسجل كل استدعاء أداة ويسمح بكل شيء
• وضع الإجبار: يطبق قواعد السياسة لكل أداة مثل block و rate_limit و min_tier
• التوقيع المحلي الاختياري: عند تكوين التوقيع، يصدر إيصالًا موقعًا بـ Ed25519 إلى جانب السجل المنظم

جميع رسائل MCP الأخرى (initialize، tools/list، الإشعارات) تمر بشفافية.

ما يتم توفيره اليوم

• سياسات لكل أداة — احظر الأدوات المدمرة، حدد معدل الأدوات باهظة الثمن، وأرفق متطلبات المستوى الأدنى
• سجلات قرارات منظمة — يتم إصدار كل قرار إلى stderr مع [PROTECT_MCP]
• إيصالات موقعة محلية اختيارية — يتم توليدها عند التشغيل بسياسة تحتوي على signing.key_path، وتخزينها في .protect-mcp-receipts.jsonl، وعرضها على http://127.0.0.1:9876/receipts
• التحقق دون اتصال — تحقق من الإيصالات أو الحزم باستخدام npx @veritasacta/verify
• لا حاجة لحساب — مفاتيح محلية، سياسة محلية، عملية محلية

حدود القدرات الحالية

هذه مهمة قبل نشر هذا أو التحدث إلى المستخدمين:

• التوقيع ليس تلقائيًا على مسار npx protect-mcp -- ... العاري. هذا المسار يسجل القرارات في وضع الظل. للتوقيع المحلي، قم بتشغيل npx protect-mcp init ثم ابدأ البوابة بملف السياسة المُنشأ.
• فحوصات السياسة المدركة للمستوى نشطة، لكن قبول البيان (manifest admission) غير موصول بالمسار الافتراضي CLI/stdio. الـ CLI يعيّن الجلسات افتراضيًا إلى unknown ما لم يستدعي تكامل المضيف واجهة برمجة القبول برمجيًا.
• تكوين بيانات الاعتماد حاليًا يتحقق من مراجع بيانات الاعتماد المدعومة بالـ env ويسجل تسميات بيانات الاعتماد في السجلات/الإيصالات. الحقن العام لكل استدعاء في أدوات stdio التعسفية خاص بالمحول ولا يتم تنفيذه بواسطة مسار الوكيل الافتراضي.
• محولات PDP الخارجية وأدوات حزمة التدقيق موجودة كوظائف مساعدة مُصدرة. لم يتم توصيلها بالكامل بعد إلى مسار CLI الافتراضي.

ملف السياسة

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  },
  "credentials": {
    "internal_api": {
      "inject": "env",
      "name": "INTERNAL_API_KEY",
      "value_env": "INTERNAL_API_KEY"
    }
  }
}

قواعد السياسة

تطابق أسماء الأدوات تمامًا، مع "*" كبديل شامل.

تكوين عميل MCP

Claude Desktop

أضف إلى claude_desktop_config.json:

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

نفس النمط — استبدل أمر الخادم بـ protect-mcp يلفه.

خيارات CLI

protect-mcp [options] -- <command> [args...]
protect-mcp init

الأوامر:
  init              إنشاء زوج مفاتيح Ed25519 + قالب تكوين
  status            عرض إحصائيات القرار وهوية جواز السفر المحلي
  digest            إنشاء ملخص محلي قابل للقراءة البشرية
  receipts          عرض أحدث الإيصالات الموقعة المخزنة
  bundle            تصدير حزمة تدقيق قابلة للتحقق دون اتصال

الخيارات:
  --policy <path>   ملف JSON للسياسة/التكوين
  --slug <slug>     معرف الخدمة للسجلات/الإيصالات
  --enforce         تفعيل وضع الإجبار (الافتراضي: الظل)
  --verbose         تفعيل تسجيل التصحيح
  --help            عرض المساعدة

الروابط البرمجية

توفر المكتبة أيضًا البدائيات التي لم تُوصل بعد إلى مسار CLI الافتراضي:

import {
  ProtectGateway,
  loadPolicy,
  evaluateTier,
  meetsMinTier,
  resolveCredential,
  initSigning,
  signDecision,
  queryExternalPDP,
  buildDecisionContext,
  createAuditBundle,
} from 'protect-mcp';

استخدمها إذا كنت تريد إضافة:

• قبول البيان قبل بدء الجلسة
• PDP خارجي (OPA، Cerbos، أو خطاف HTTP عام)
• تكاملات وسيطة مخصصة لبيانات الاعتماد
• تصدير حزمة تدقيق حول مخزن الإيصالات الخاص بك

سجلات القرار والإيصالات

كل استدعاء أداة يصدر JSON منظم إلى stderr:

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}

عند تكوين التوقيع، يتبعه إيصال موقع:

[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}

تحقق باستخدام CLI: npx @veritasacta/verify receipt.json تحقق في المتصفح: scopeblind.com/verify

حزم التدقيق

تصدر الحزمة أداة مساعدة لحزم التدقيق المستقلة:

{
  "format": "scopeblind:audit-bundle",
  "version": 1,
  "tenant": "my-service",
  "receipts": ["..."],
  "verification": {
    "algorithm": "ed25519",
    "signing_keys": ["..."]
  }
}

استخدم createAuditBundle() حول مجموعة الإيصالات الموقعة التي جمعتها.

الفلسفة

• الظل أولاً. شاهد ما تفعله الوكلاء قبل أن تفرض أي شيء.
• الإيصالات تتفوق على سجلات اللوحات فقط. يجب أن تكون القطع الأثرية الموقعة قابلة للتحقق بشكل مستقل.
• حافظ على صرامة الادعاءات. مسار CLI الافتراضي لا يفعل بعد كل ما ستدعمه البنية المستقبلية.
• أضف طبقة فوق المصادقة الحالية. لا تقم بإزالة مجموعتك التقنية الحالية فقط لإضافة التحكم والأدلة.

حزم السياسات المرتكزة على الحوادث

يأتي مع protect-mcp — كل واحدة تمنع هجومًا حقيقيًا:

npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js

التعيين الكامل لـ OWASP Agentic Top 10: scopeblind.com/docs/owasp

BYOPE: محركات السياسات الخارجية

يدعم OPA و Cerbos و Cedar (AWS AgentCore) ونقاط نهاية HTTP عامة:

{
  "policy_engine": "hybrid",
  "external": {
    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
    "format": "cedar",
    "timeout_ms": 200,
    "fallback": "deny"
  }
}

المعايير والملكية الفكرية

• مسودة إنترنت IETF: draft-farley-acta-signed-receipts-00 — إيصالات القرارات الموقعة للتحكم في الوصول بين الآلات
• حالة البراءة: 4 طلبات براءة اختراع أسترالية مؤقتة معلقة (2025-2026) تغطي إيصالات القرار مع الكشف القابل للتكوين، وبوابة استدعاء الأدوات، وبيانات الوكيل، والهوية المحمولة
• التحقق: MIT-مرخص — npx @veritasacta/verify --self-test

الترخيص

MIT — مجاني للاستخدام والتعديل والتوزيع والبناء عليه دون قيود.

scopeblind.com · npm · GitHub · مسودة IETF