ローカルファイル操作用のゼロ依存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 | 標準入力とタイムアウトをサポートしたストリーミングコマンド実行 | destructiveHint |
diff | 2つのファイルまたはテキスト文字列の差分（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のログ: 3秒 → 5ミリ秒、メモリ: 500MB → 数KB |
| B | lsでの遅延stat | sort=sizeのときだけstatSyncを呼び出し。1000ファイルのディレクトリ: 50ミリ秒 → 2ミリ秒 |
| 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差分 | O(ND)アルゴリズム。edit、block、diffで使用 |
| 検索スコアリング | まず名前一致（I/Oなし）、その後は上位50候補のみstat |
| 出力形式 | grep: file:line:content、ls: コンパクトな列、read: 行番号＋切り詰めヒント |
| プロトコル | O(1)のMapディスパッチ、同期ハンドラーのショートサーキット |
# 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