local-mcp
로컬 파일 작업을 위한 제로 의존성 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줄, 제로 런타임 의존성.
도구
파일시스템 도구 (13개)
메타 도구 (3개) — 점진적 탐색
| 도구 | 설명 |
|---|
search_tools | 키워드로 사용 가능한 도구 검색 — 전체 나열 대비 약 90% 토큰 절약 |
describe_tool | 특정 도구의 전체 입력 스키마 가져오기 (요청 시 로드) |
call_tool | 인수와 함께 이름으로 모든 도구 실행 |
모든 요청마다 13개 도구 스키마(약 3,000토큰)를 보내는 대신, 이 3개 메타 도구를 사용한 점진적 탐색은 약 50토큰으로 줄여줍니다 — 약 90% 토큰 절약.
성능 최적화 (v1.1.1)
추가 최적화
시작하기
# Zero install — no dependencies
node local-mcp.mjs
# With configuration
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를 지원합니다.
CLI 플래그
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 및 하위 디렉터리로 제한됨
- 프로토타입 안전 북마크 키 (
__proto__/constructor/prototype 주입 차단)
- 원자적 쓰기(임시 파일 + 이름 변경)로 부분 파일 쓰기 방지
- 바이너리 파일 감지로 텍스트가 아닌 파일 읽기 방지
.gitignore 및 일반적인 제외 디렉터리(node_modules, .git 등) 준수
의존성
제로 런타임 의존성. Node.js 내장 모듈만 사용:
변경 로그
v1.1.1 — 성능 최적화
- A. 스트리밍 head/tail 읽기: 500MB 로그 3초 → 5ms
- B. ls의 지연 stat: 파일 1000개 디렉터리 50ms → 2ms
- C.
availableParallelism()을 사용한 적응형 grep 동시성
- D. Map 삽입 순서를 통한 LRU 캐시 축출
- E. grep 바이트 보호 (100MB / 파일 1000개)
- F. MCP 2025 사양을 위한 진행 알림 패스스루
- 수정:
streamHead 스코프 버그 — done이 Promise 콜백 외부에 정의됨
v1.1.0
- 13개 파일시스템 도구 + 점진적 탐색을 위한 3개 메타 도구
- stdio + Streamable HTTP 전송
- Myers diff 엔진, 읽기 캐시, 스트리밍 exec
- 검증이 포함된 환경 기반 구성
개발
# 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
기여
- 제로 의존성 제약 유지
- 새 기능에 대한 테스트 추가
- 성능 변경 시 Optimizations 표 업데이트
라이선스
MIT
fan-67/local-mcp
