fan-67/local-mcp
स्थानीय फ़ाइल सिस्टम संचालन के लिए एक हल्का stdio-आधारित MCP सर्वर — AI सहायकों के लिए read, write, edit, search, exec। विशेष रूप से Chatbox के लिए अनुकूलित: exec के लिए bat-bypass (CVE-2026-6130), एस्केपिंग समस्याओं को समाप्त करने के लिए b64 एन्कोडिंग, और सटीक कोड ब्लॉक लक्ष्यीकरण के लिए multi-pattern regex।
स्थानीय फ़ाइल संचालन के लिए शून्य-निर्भरता MCP सर्वर। 13 फ़ाइलसिस्टम उपकरण + प्रगतिशील खोज के लिए 3 मेटा-उपकरण — कोई SDK, कोई फ्रेमवर्क, 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 env कॉन्फ़िगरेशन सत्यापन के साथ
**कुल: ~855 पंक्तियाँ, शून्य रनटाइम निर्भरताएँ।**
| उपकरण | विवरण | एनोटेशन |
|---|---|---|
read | पंक्ति संख्याओं के साथ फ़ाइल पढ़ें, वैकल्पिक head/tail ट्रंकेशन | readOnlyHint |
search | नाम से फ़ाइल खोजें (ग्लोब) फिर सामग्री से (ग्रेप) | readOnlyHint |
ls | आलसी स्टैट के साथ कॉम्पैक्ट निर्देशिका सूची | readOnlyHint |
exec | stdin समर्थन और टाइमआउट के साथ स्ट्रीमिंग कमांड निष्पादन | destructiveHint |
diff | दो फ़ाइलों या टेक्स्ट स्ट्रिंग्स में अंतर (Myers O(ND)) | readOnlyHint |
copy | फ़ाइल या निर्देशिका की प्रतिलिपि बनाएँ | destructiveHint |
move | फ़ाइल/निर्देशिका स्थानांतरित या नाम बदलें | destructiveHint |
batch | कई ऑपरेशन क्रमिक रूप से चलाएँ; परमाणु रोलबैक, $prev संदर्भ | destructiveHint |
file | एकीकृत: पढ़ें, लिखें, संपादित करें, जोड़ें, हटाएँ, जानकारी, mkdir, स्थानांतरित करें | — |
block | रेंज या फ़ंक्शन नाम द्वारा कोड ब्लॉक पढ़ें/बदलें/सम्मिलित करें/हटाएँ | — |
bookmark | स्थायी पथ उपनाम (जोड़ें/प्राप्त करें/सूचीबद्ध करें/हटाएँ) | — |
grep | file:line:content कॉम्पैक्ट प्रारूप, अनुकूली समवर्तीता के साथ | readOnlyHint |
watch | परिवर्तनों के लिए फ़ाइल/निर्देशिका देखें; अधिकतम 20 समवर्ती वॉचर | — |
| उपकरण | विवरण |
|---|---|
search_tools | कीवर्ड द्वारा उपलब्ध उपकरण खोजें — सभी को सूचीबद्ध करने की तुलना में ~90% टोकन बचाता है |
describe_tool | किसी विशिष्ट उपकरण के लिए पूर्ण इनपुट स्कीमा प्राप्त करें (मांग पर लोड किया गया) |
call_tool | तर्कों के साथ किसी भी उपकरण को नाम से निष्पादित करें |
हर अनुरोध में सभी 13 उपकरण स्कीमा (~3,000 टोकन) भेजने के बजाय, इन 3 मेटा-उपकरणों के साथ प्रगतिशील खोज इसे ~50 टोकन तक कम कर देती है — ~90% टोकन बचत।
| # | अनुकूलन | प्रभाव |
|---|---|---|
| A | स्ट्रीम head/tail पढ़ना | streamHead() पूरी फ़ाइलों को पढ़ने से बचाता है। 500MB लॉग: 3s → 5ms, मेमोरी: 500MB → कुछ KB |
| B | ls में आलसी स्टैट | केवल sort=size होने पर statSync कॉल करता है। 1000-फ़ाइल निर्देशिका: 50ms → 2ms |
| C | अनुकूली grep समवर्तीता | हार्डकोडेड 16 कर्मियों के बजाय os.availableParallelism() (अधिकतम 16, न्यूनतम 4) |
| D | LRU कैश निष्कासन | मैप इंसर्शन-ऑर्डर LRU — गर्म छोटी फ़ाइलें अब ठंडी बड़ी फ़ाइलों द्वारा निकाली नहीं जातीं |
| E | Grep बाइट सुरक्षा | MAX_GREP_TOTAL_MB=100 + MAX_GREP_FILES=1000 गार्ड OOM को रोकते हैं |
| F | प्रगति सूचना | MCP 2025 स्पेक के लिए _meta.progressToken पासथ्रू (TODO: लंबे निष्पादन के लिए ईवेंट) |
| क्षेत्र | विवरण |
|---|---|
| पढ़ने का कैश | आकार-जागरूक निष्कासन (अधिकतम 50 आइटम, 10 MB) + 5s TTL |
| Myers डिफ | O(ND) एल्गोरिदम, edit, block, और diff द्वारा उपयोग किया जाता है |
| खोज स्कोरिंग | पहले नाम-मिलान (कोई I/O नहीं), फिर केवल शीर्ष 50 उम्मीदवारों का स्टैट |
| आउटपुट प्रारूप | grep: file:line:content, ls: कॉम्पैक्ट कॉलम, read: पंक्ति संख्याएँ + ट्रंकेशन संकेत |
| प्रोटोकॉल | O(1) मैप डिस्पैच, सिंक हैंडलर शॉर्ट-सर्किट |
# शून्य इंस्टॉल — कोई निर्भरता नहीं
node local-mcp.mjs
# कॉन्फ़िगरेशन के साथ
MCP_WORKSPACE=D:/projects node local-mcp.mjs
{
"mcpServers": {
"local-mcp": {
"command": "node",
"args": ["D:/path/to/local-mcp.mjs"],
"env": {
"MCP_WORKSPACE": "D:/projects"
}
}
}
}
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 # उपयोग + env वेरिएबल दिखाएँ
node local-mcp.mjs --list-tools # उपलब्ध उपकरण प्रिंट करें और बाहर निकलें
node local-mcp.mjs --http # HTTP मोड शुरू करें
node local-mcp.mjs --http --port 3456
| चर | डिफ़ॉल्ट | विवरण |
|---|---|---|
MCP_WORKSPACE | process.cwd() | कार्य निर्देशिका रूट (सुरक्षा सीमा) |
MCP_DATA | {WORKSPACE}/.mcp-data | डेटा निर्देशिका (बुकमार्क, अस्थायी फ़ाइलें) |
MCP_DIR | {WORKSPACE} | tree/ls कमांड के लिए डिफ़ॉल्ट निर्देशिका |
MCP_PORT | 3100 | HTTP सर्वर पोर्ट (--http का उपयोग करते समय) |
MCP_READONLY | false | सभी लेखन संचालन को अवरुद्ध करने के लिए true सेट करें |
MCP_EXCLUDE | — | खोज से बाहर करने के लिए अल्पविराम-पृथक अतिरिक्त निर्देशिकाएँ |
MCP_WORKSPACE और उपनिर्देशिकाओं तक सीमित__proto__/constructor/prototype इंजेक्शन को रोकती हैं).gitignore और सामान्य बहिष्कृत निर्देशिकाएँ (node_modules, .git, आदि) का सम्मान किया जाता हैशून्य रनटाइम निर्भरताएँ। केवल Node.js अंतर्निहित का उपयोग करता है:
| मॉड्यूल | उद्देश्य |
|---|---|
fs | फ़ाइल सिस्टम + glob (Node 22) |
child_process | स्ट्रीमिंग शेल निष्पादन |
http | HTTP परिवहन (Express की आवश्यकता नहीं) |
path | पथ समाधान |
os | अनुकूली समवर्तीता के लिए availableParallelism() |
readline | पंक्ति-दर-पंक्ति स्ट्रीमिंग प्रसंस्करण |
availableParallelism() के साथ अनुकूली grep समवर्तीताstreamHead स्कोप बग — done को Promise कॉलबैक के बाहर परिभाषित किया गया# परीक्षण चलाएँ
node --test test/*.test.mjs
# उपकरण जोड़ना
# 1. local-mcp.mjs में स्कीमा + हैंडलर परिभाषित करें
# 2. server.tool() के साथ पंजीकृत करें
# 3. परीक्षण जोड़ें
MIT