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秒 → 5ミリ秒
- B. lsでの遅延stat: 1000ファイルのディレクトリ 50ミリ秒 → 2ミリ秒
- 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差分エンジン、読み取りキャッシュ、ストリーミング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
コントリビューション
- ゼロ依存の制約を維持する
- 新機能にはテストを追加する
- パフォーマンスの変更時は最適化テーブルを更新する
ライセンス
MIT
