local-mcp
Serveur MCP zéro dépendance pour les opérations sur fichiers locaux. 13 outils de système de fichiers + 3 méta-outils pour la découverte progressive — pas de SDK, pas de framework, pas de npm install nécessaire.
Protocole MCP : 2024-11-05 · Transport : stdio + HTTP streamable · Runtime : Node.js ≥ 22.0.0
Architecture
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
Total : ~855 lignes, zéro dépendance d'exécution.
Outils
Outils de système de fichiers (13)
| Outil | Description |
|---|
search_tools | Recherche des outils disponibles par mot-clé — économise ~90 % de jetons par rapport à la liste complète |
describe_tool | Obtient le schéma d'entrée complet d'un outil spécifique (chargé à la demande) |
call_tool | Exécute n'importe quel outil par nom avec des arguments |
Au lieu d'envoyer les 13 schémas d'outils (~3 000 jetons) dans chaque requête, la découverte progressive avec ces 3 méta-outils la réduit à ~50 jetons — ~90 % d'économies de jetons.
Optimisations supplémentaires
Pour commencer
# Zero install — no dependencies
node local-mcp.mjs
# With configuration
MCP_WORKSPACE=D:/projects node local-mcp.mjs
Mode stdio (par défaut)
{
"mcpServers": {
"local-mcp": {
"command": "node",
"args": ["D:/path/to/local-mcp.mjs"],
"env": {
"MCP_WORKSPACE": "D:/projects"
}
}
}
}
Mode HTTP
node local-mcp.mjs --http
node local-mcp.mjs --http --port 3456
Prend en charge JSON-RPC 2.0 POST, streaming SSE (Accept: text/event-stream), CORS et GET /tools.
Options 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
Configuration
Sécurité
- Toutes les opérations sur fichiers sont restreintes à
MCP_WORKSPACE et ses sous-répertoires
- Clés de signets sûres vis-à-vis du prototype (bloque l'injection
__proto__/constructor/prototype)
- Les écritures atomiques (temp + rename) empêchent les écritures partielles de fichiers
- La détection des fichiers binaires empêche la lecture de fichiers non textuels
.gitignore et les répertoires d'exclusion courants (node_modules, .git, etc.) sont respectés
Dépendances
Zéro dépendance d'exécution. Utilise uniquement les modules intégrés de Node.js :
Journal des modifications
- A. Lecture head/tail en streaming : journaux de 500 Mo de 3 s à 5 ms
- B. Stat paresseux dans ls : répertoire de 1000 fichiers de 50 ms à 2 ms
- C. Concurrence adaptative de grep avec
availableParallelism()
- D. Éviction de cache LRU via l'ordre d'insertion de la Map
- E. Protection en octets de grep (100 Mo / 1000 fichiers)
- F. Transmission de la notification de progression pour la spec MCP 2025
- Correctif : bug de portée de
streamHead — done défini à l'extérieur du callback de la Promise
v1.1.0
- 13 outils de système de fichiers + 3 méta-outils pour la découverte progressive
- transport stdio + HTTP streamable
- moteur de diff Myers, cache de lecture, exec en streaming
- configuration basée sur l'environnement avec validation
Développement
# 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
Contribution
- Maintenir la contrainte zéro dépendance
- Ajouter des tests pour les nouvelles fonctionnalités
- Mettre à jour le tableau des Optimisations pour les changements de performances
Licence
MIT
