mcp-doorman

البوابة الأمنية لخوادم MCP — كل استدعاء أداة يتم فحصه عند الباب.

CI npm License: Apache-2.0 PRs welcome

mcp-doorman هو وكيل (proxy) قابل للتضمين يجلس بين وكيل الذكاء الاصطناعي الخاص بك (Claude Desktop، Claude Code، Cursor، VS Code، أي عميل MCP) وخوادم MCP التي يستخدمها. أمر واحد، بدون بنية تحتية، وكل استدعاء لـ tools/list و tools/call يمر عبر خط أنابيب حماية:

• 🛂 محرك السياسات — قواعد السماح / الرفض / طلب الموافقة لكل أداة، مطابقة بالأنماط العالمية (glob)
• 🕵️ إخفاء الأسرار — مفاتيح AWS، رموز GitHub/Slack/Stripe/OpenAI/Anthropic، المفاتيح الخاصة، JWTs، أرقام البطاقات (مدققة بـ Luhn)… يتم مسحها من نتائج الأدوات قبل وصولها إلى النموذج
• 💉 فحص حقن الأوامر — وضع علامات أو حظر على نتائج الأدوات (وأوصاف الأدوات — تسميم الأدوات) التي تحاول إعطاء تعليمات للنموذج
• 📌 كشف السحب المفاجئ (Rug-pull) — يتم تثبيت تعريفات الأدوات بناءً على بصمة (hash) في أول استخدام؛ إذا قام الخادم بتغيير الوصف بهدوء، يتم حظر الأداة حتى يقوم إنسان بإعادة التثبيت
• 🚦 تحديد المعدل — دلاء رمزية لكل أداة تحد من نصف قطر الانفجار لحلقة وكيل جامحة
• 🙋 بوابات موافقة بشرية — الأدوات الحساسة تؤدي إلى ظهور طلب موافقة تفاعلي عبر MCP elicitation، مباشرة في عميلك
• 🧾 سجل التدقيق — كل استدعاء، رفض، إخفاء، وعلامة يتم تسجيله في ملف JSONL للإلحاق فقط

لماذا هذا موجود

الجميع على بُعد npx some-random-mcp-server واحدة من تسليم مفاتيح API الخاصة بهم وخط اتصال مباشر إلى نافذة سياق النموذج الخاص بهم إلى عملية غير مدققة. فئات الهجوم الموثقة حقيقية، وليست افتراضية:

بوابات MCP المؤسسية موجودة لفرق المنصات التي لديها مجموعات Kubernetes. لا شيء خفيف الوزن يحمي كمبيوتر المطور الفردي — المكان الذي يعمل فيه 99% من خوادم MCP فعليًا. هذه هي الفجوة التي يملأها هذا المشروع.

بداية سريعة (60 ثانية)

# 1. إنشاء إعدادات
npx -y mcp-doorman init

# 2. تحرير ملف doorman.config.json — ضع خوادمك الحقيقية فيه

# 3. تثبيت تعريفات الأدوات الحالية (الثقة عند أول استخدام)
npx -y mcp-doorman pin --config doorman.config.json

ثم وجه عميلك إلى البوابة بدلاً من خوادمك. Claude Desktop / Claude Code / Cursor:

// BEFORE — every server talks straight to the model
{
  "mcpServers": {
    "github":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/repos"] }
  }
}

// AFTER — one doorman guards them all
{
  "mcpServers": {
    "doorman": {
      "command": "npx",
      "args": ["-y", "mcp-doorman", "run", "--config", "/absolute/path/to/doorman.config.json"]
    }
  }
}

تظهر الأدوات مع مساحة اسم مثل github__create_issue، filesystem__read_file، إلخ، بالإضافة إلى أداتين مدمجتين: doorman__status و doorman__recent_events (اسأل وكيلك "ماذا قام doorman بحظره مؤخرًا؟").

ملاحظة لويندوز: إذا كان إدخال الخادم يستخدم npx مباشرة، قم بتشغيله عبر cmd: "command": "cmd", "args": ["/c", "npx", "-y", "..."].

شاهدها تعمل

git clone https://github.com/Sushank05/mcp-doorman && cd mcp-doorman
npm install
npm run demo

يقوم العرض التوضيحي بتوصيل البوابة بخادم يتعمد سوء التصرف (examples/demo-server.mjs) الذي يسرب بيانات اعتماد مزيفة، ويقدم حمولة حقن أوامر، ويوفر أداة مدمرة — ويظهر كل حارس وهو يكتشفها.

كيف تعمل

flowchart LR
    A["MCP client\n(Claude Desktop, Cursor, ...)"] -- stdio --> D
    subgraph D [mcp-doorman]
        direction TB
        P[policy] --> R[rate limit] --> AP[approval] --> RD[redaction] --> I[injection scan] --> AU[(audit log)]
    end
    D -- stdio --> S1[github server]
    D -- stdio --> S2[filesystem server]
    D -- streamable HTTP --> S3[remote server]

البوابة هي خادم MCP تجاه عميلك وعميل MCP تجاه كل خادم أعلى (عمليات stdio تابعة أو نقاط نهاية HTTP قابلة للبث)، وتجمعها خلف اتصال واحد. إنها مبنية على TypeScript SDK الرسمي.

الإعدادات

كل شيء موجود في ملف JSON واحد. مثال كامل مع كل خيار:

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }   // ${VAR} = read from gateway env
    },
    "remote": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${MCP_TOKEN}" } }
  },

  "policy": {
    "defaultAction": "allow",                    // "allow" | "deny" | "approve"
    "rules": [                                   // first match wins, evaluated top-down
      { "match": "*__delete*",  "action": "deny",    "reason": "no destructive tools" },
      { "match": ["github__create_*", "*__send_*"], "action": "approve" },
      { "match": "filesystem__*", "action": "allow" }
    ]
  },

  "redaction": {
    "enabled": true,
    "disable": [],                               // built-in rule names to turn off
    "enableOptIn": ["email"],                    // opt-ins: "email", "us-ssn", "ipv4"
    "custom": [{ "name": "acme-id", "pattern": "ACME-[0-9]{6}" }],
    "redactArguments": false                     // also scrub model-supplied arguments
  },

  "injection": {
    "action": "flag",                            // "flag" (warn the model) | "block" | "off"
    "scanToolDescriptions": true,                // tool-poisoning check on tools/list
    "custom": []
  },

  "pinning": {
    "enabled": true,
    "onNewTool": "pin",                          // "pin" (TOFU) | "block" (until `mcp-doorman pin`)
    "onChangedTool": "block"                     // "block" | "warn"
  },

  "rateLimit": { "perMinute": 120, "perTool": { "*__send_*": 5 } },

  "approval": { "fallback": "deny", "timeoutMs": 120000 },  // fallback when client lacks elicitation

  "audit": { "enabled": true, "includeArguments": true, "includeResults": false },

  "logLevel": "info"
}

حالة التثبيت وسجل التدقيق افتراضيًا يكونان <config-name>.pins.json / <config-name>.audit.jsonl بجانب ملف الإعدادات.

واجهة سطر الأوامر

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

أدوات الأمان التي تبالغ في وعودها أسوأ من عدم وجود أي أداة. اقرأ هذا الجزء.

• الطرق الاستدلالية قابلة للالتفاف. أنماط الحقن تكتشف أشكال الهجوم الموثقة والشائعة. يمكن للمهاجم المتحمس صياغة هجوم حول أي تعبير عادي. استخدم سياسات deny/approve كحدود صلبة؛ الفحص هو دفاع في العمق.
• الإخفاء هو بذل أقصى جهد. يتم اكتشاف تنسيقات الرموز المعروفة بشكل موثوق؛ السر العشوائي السداسي العشري بدون سياق لا يتم اكتشافه. لا توجه الوكلاء إلى مخازن بيانات الاعتماد.
• هذا ليس صندوق رمل. الخوادم العلوية لا تزال تعمل كعمليات فرعية بصلاحيات مستخدمك. يحرس Doorman البروتوكول؛ قم بإقرانه مع حاويات (على غرار ToolHive) لحراسة العملية.
• TOFU يثق في أول رؤية. التثبيت يكتشف التغييرات، وليس الأدوات التي كانت ضارة من اليوم الأول — لهذا يوجد ماسح الوصف ومراجعتك الخاصة.
• بوابات الموافقة تحتاج إلى elicitation. العملاء الذين لا يدعمون elicitation يتراجعون إلى approval.fallback (الرفض افتراضيًا).

خريطة الطريق — مساعدة مطلوبة 🙌

• تفعيل resources/* و prompts/* (حاليًا الأدوات فقط)
• تمرير لأخذ العينات والجذور
• حزم قواعد المجتمع (doorman-rules-finance، doorman-rules-healthcare…)
• وضع التعلم: المراقبة لمدة أسبوع، اقتراح سياسة الحد الأدنى من الصلاحيات
• دعم خلفية سياسات OPA / Cedar
• الأمر الفرعي mcp-doorman audit: طباعة جميلة والاستعلام عن سجل JSONL
• لوحة تحكم ويب لتصور التدقيق
• كشف الأسرار العام القائم على الإنتروبيا

اختر أيًا مما سبق، أو ابدأ بـ [مشكلة أولى جيدة](https://github.com/YOUR_GITHUB_USERNAME/mcp-doorman/labels/good%20first%20issue). قواعد الكشف الجديدة هي أسهل مساهمة: تعبير عادي واحد + اختباران. انظر CONTRIBUTING.md و docs/detection-rules.md.

التطوير

npm install
npm test          # 69 اختبار: وحدة + نهاية إلى نهاية stdio كامل
npm run build
npm run demo      # شاهد الحراس وهم يعملون مباشرة

الترخيص

Apache-2.0 — مجاني لأي استخدام، مع منح براءة اختراع صريح.