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% 的 token |
describe_tool | 获取特定工具的完整输入模式（按需加载） |
call_tool | 按名称和参数执行任意工具 |
与其在每个请求中发送全部 13 个工具模式（约 3,000 token），这 3 个元工具实现的渐进式发现将其减少到约 50 token — 节省约 90% 的 token。
性能优化（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. 流式头部/尾部读取：500MB 日志 3s → 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 引擎、读取缓存、流式执行
- 基于环境的配置与验证
开发
# 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
