local-mcp

خوادم MCP بدون تبعيات لعمليات الملفات المحلية. 13 أداة لنظام الملفات + 3 أدوات تعريفية للاكتشاف التدريجي — بدون SDKs، بدون أطر عمل، بدون حاجة لـ npm install.

بروتوكول MCP: 2024-11-05 · النقل: stdio + Streamable HTTP · بيئة التشغيل: Node.js ≥ 22.0.0

الهندسة المعمارية

local-mcp.mjs       — 595 سطرًا، 13 أداة، نقطة الدخول
lib/mcp-core.mjs    — 229 سطرًا، نقل stdio + HTTP، 9 طرق MCP
lib/config.mjs      —  31 سطرًا، إعداد متغيرات البيئة MCP_WORKSPACE/DATA مع التحقق

الإجمالي: ~855 سطرًا، بدون أي تبعيات وقت التشغيل.

الأدوات

أدوات نظام الملفات (13)

الأدوات التعريفية (3) — الاكتشاف التدريجي

بدلاً من إرسال جميع مخططات الأدوات الـ 13 (~3,000 رمز مميز) في كل طلب، يقلل الاكتشاف التدريجي باستخدام هذه الأدوات التعريفية الثلاثة إلى ~50 رمزًا مميزًا — توفير ~90% من الرموز المميزة.

تحسينات الأداء (v1.1.1)

تحسينات إضافية

بدء الاستخدام

# تثبيت صفري — بدون تبعيات
node local-mcp.mjs

# مع التهيئة
MCP_WORKSPACE=D:/projects node local-mcp.mjs

وضع stdio (الافتراضي)

{
  "mcpServers": {
    "local-mcp": {
      "command": "node",
      "args": ["D:/path/to/local-mcp.mjs"],
      "env": {
        "MCP_WORKSPACE": "D:/projects"
      }
    }
  }
}

وضع HTTP

node local-mcp.mjs --http
node local-mcp.mjs --http --port 3456

يدعم طلبات JSON-RPC 2.0 POST، دفق SSE (Accept: text/event-stream)، CORS، و GET /tools.

وسائط سطر الأوامر

node local-mcp.mjs --help          # عرض الاستخدام + متغيرات البيئة
node local-mcp.mjs --list-tools    # طباعة الأدوات المتاحة والخروج
node local-mcp.mjs --http          # بدء وضع HTTP
node local-mcp.mjs --http --port 3456

التهيئة

الأمان

• جميع عمليات الملفات مقيدة بـ MCP_WORKSPACE والدلائل الفرعية
• مفاتيح المراجع آمنة من البروتوتايب (تمنع حقن __proto__/constructor/prototype)
• عمليات الكتابة الذرية (مؤقت + إعادة تسمية) تمنع الكتابة الجزئية للملفات
• اكتشاف الملفات الثنائية يمنع قراءة الملفات غير النصية
• احترام .gitignore والدلائل المستثناة الشائعة (node_modules، .git، إلخ.)

التبعيات

بدون أي تبعيات وقت التشغيل. يستخدم فقط الوحدات المدمجة في Node.js:

سجل التغييرات

v1.1.1 — تحسينات الأداء

• A. قراءة دفق head/tail: سجلات 500 ميجابايت من 3 ثوانٍ إلى 5 مللي ثانية
• B. إحصائيات كسولة في ls: دليل 1000 ملف من 50 مللي ثانية إلى 2 مللي ثانية
• C. توازي تكيفي في grep باستخدام availableParallelism()
• D. إزالة LRU من الذاكرة المؤقتة عبر ترتيب الإدراج في الخريطة
• E. حماية حجم grep (100 ميجابايت / 1000 ملف)
• F. تمرير إشعار التقدم لمواصفات MCP 2025
• إصلاح: خطأ نطاق streamHead — تم تعريف done خارج رد الاتصال الخاص بـ Promise

v1.1.0

• 13 أداة لنظام الملفات + 3 أدوات تعريفية للاكتشاف التدريجي
• نقل stdio + Streamable HTTP
• محرك Myers diff، ذاكرة تخزين مؤقت للقراءة، تنفيذ الأوامر المتدفق
• تهيئة قائمة على متغيرات البيئة مع التحقق

التطوير

# تشغيل الاختبارات
node --test test/*.test.mjs

# إضافة أداة
# 1. حدد المخطط + المعالج في local-mcp.mjs
# 2. سجل باستخدام server.tool()
# 3. أضف اختبارات

المساهمة

1. حافظ على قيد عدم وجود تبعيات
2. أضف اختبارات للوظائف الجديدة
3. قم بتحديث جدول التحسينات لتغييرات الأداء

الترخيص

MIT