fan-67/local-mcpAI 어시스턴트를 위한 로컬 파일 시스템 작업(읽기, 쓰기, 편집, 검색, 실행)을 지원하는 경량 stdio 기반 MCP 서버입니다. Chatbox에 특별히 최적화됨: exec용 bat-bypass(CVE-2026-6130), 이스케이프 문제를 제거하는 b64 인코딩, 정밀한 코드 블록 타게팅을 위한 다중 패턴 정규식.
로컬 파일 작업을 위한 제로 의존성 MCP 서버. 13개의 파일시스템 도구 + 점진적 탐색을 위한 3개의 메타 도구 — SDK, 프레임워크, npm install이 필요 없습니다.
MCP 프로토콜: 2024-11-05 · 전송: stdio + Streamable HTTP · 런타임: Node.js ≥ 22.0.0
local-mcp.mjs — 595 lines, 13 tools, entry point
lib/mcp-core.mjs — 229 lines, stdio + HTTP transport, 9 MCP methods
lib/config.mjs — 31 lines, MCP_WORKSPACE/DATA env config with validation
총 약 855줄, 제로 런타임 의존성.
| 도구 | 설명 | 어노테이션 |
|---|---|---|
read | 줄 번호와 함께 파일 읽기, 선택적 head/tail 잘라내기 | readOnlyHint |
search | 이름(glob)으로 파일을 검색한 후 내용(grep)을 검색 | readOnlyHint |
ls | 지연 stat을 사용한 간결한 디렉터리 목록 | readOnlyHint |
exec | stdin 지원 및 타임아웃이 포함된 스트리밍 명령 실행 | destructiveHint |
diff | 두 파일 또는 텍스트 문자열 비교 (Myers O(ND)) | readOnlyHint |
copy | 파일 또는 디렉터리 복사 | destructiveHint |
move | 파일/디렉터리 이동 또는 이름 변경 | destructiveHint |
batch | 여러 작업을 순차적으로 실행; 원자적 롤백, $prev 참조 | destructiveHint |
file | 통합: 읽기, 쓰기, 편집, 추가, 삭제, 정보, mkdir, 이동 | — |
block | 범위 또는 함수 이름으로 코드 블록 읽기/교체/삽입/삭제 | — |
bookmark | 영구 경로 별칭 (add/get/list/delete) | — |
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 로그: 3초 → 5ms, 메모리: 500MB → 수 KB |
| B | ls의 지연 stat | sort=size일 때만 statSync 호출. 파일 1000개 디렉터리: 50ms → 2ms |
| C | 적응형 grep 동시성 | 하드코딩된 16개 워커 대신 os.availableParallelism() (최대 16, 최소 4) 사용 |
| D | LRU 캐시 축출 | Map 삽입 순서 기반 LRU — 자주 접근하는 작은 파일이 드물게 접근하는 대용량 파일에 의해 더 이상 축출되지 않음 |
| E | grep 바이트 보호 | MAX_GREP_TOTAL_MB=100 + MAX_GREP_FILES=1000 가드가 OOM을 방지 |
| F | 진행 알림 | MCP 2025 사양을 위한 _meta.progressToken 패스스루 (TODO: 긴 실행에 대한 이벤트) |
| 영역 | 세부 사항 |
|---|---|
| 읽기 캐시 | 크기 인지 축출 (최대 50개 항목, 10MB) + 5초 TTL |
| Myers diff | O(ND) 알고리즘, edit, block, diff에서 사용 |
| 검색 점수화 | 먼저 이름 일치(I/O 없음), 그 다음 상위 50개 후보만 stat |
| 출력 형식 | grep: file:line:content, ls: 간결한 열, read: 줄 번호 + 잘라내기 힌트 |
| 프로토콜 | O(1) Map 디스패치, 동기 핸들러 단락(short-circuit) |
# Zero install — no dependencies
node local-mcp.mjs
# With configuration
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 # Show usage + env vars
node local-mcp.mjs --list-tools # Print available tools and exit
node local-mcp.mjs --http # Start HTTP mode
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 콜백 외부에 정의됨# Run tests
node --test test/*.test.mjs
# Adding a tool
# 1. Define schema + handler in local-mcp.mjs
# 2. Register with server.tool()
# 3. Add tests
MIT