npm-mcp

npm-mcp ist ein kleiner, schreibgeschützter Model Context Protocol-Server für die öffentliche npm-Registry. Er ermöglicht MCP-kompatiblen KI-Clients, npm-Pakete zu entdecken und gezielte Paketmetadaten zu untersuchen, ohne Install-, Veröffentlichungs-, Anmelde-, Shell-, Dateisystem- oder beliebige Fetch-Fähigkeiten bereitzustellen.

Mit Docker starten

Siehe Docker-Schnellstart, um den Server und den MCP Inspector aus einem frischen Checkout zu starten. Der wesentliche Befehl lautet:

docker compose --profile inspector up --build -d

Um die modellgesteuerte MCP-Toolnutzung zu testen, ohne ein Modell lokal auszuführen, verwenden Sie LibreChat mit dem Free-Model-Router von OpenRouter:

docker compose -f compose.yaml -f compose.openrouter.yaml --profile openrouter up --build -d

Öffnen Sie anschließend http://127.0.0.1:3080. Ein OpenRouter-API-Schlüssel ist auch für kostenlose Modelle erforderlich. Siehe OPENROUTER_QUICKSTART.md für Einrichtung und Verwendung. Das lokale Ollama-Profil bleibt als optionale vollständig lokale Alternative verfügbar.

Related MCP server: @kongyo2/npm-info-mcp-server

Tools

Alle Tools geben JSON als Text zurück, um eine breite Client-Kompatibilität zu gewährleisten, und stellen denselben Wert als strukturierten MCP-Inhalt bereit. Paketantworten werden bewusst gefiltert, anstatt das vollständige Metadaten-Dokument der Registry zurückzugeben.

Anforderungen und Installation

• Node.js 20 oder neuer (für natives fetch und AbortSignal.timeout)

• npm

git clone <repository-url>
cd npm-mcp
npm install

Lokal ausführen

npm start

Der Prozess wartet auf stdin auf MCP-Nachrichten und schreibt Protokollantworten auf stdout. Geben Sie nicht interaktiv in ihn ein; ein MCP-Client sollte ihn starten. Ein Entwicklungs-Watch-Modus ist mit npm run dev verfügbar.

Bereitstellung

Für lokale Clients verwenden Sie den Stdio-Einstiegspunkt. Für Docker- und Cloud-Bereitstellung verwenden Sie den zustandslosen Streamable-HTTP-Einstiegspunkt unter /mcp; dieser erfordert standardmäßig ein Bearer-Token und stellt /healthz für Health-Checks bereit. Siehe den Leitfaden für Docker- und Cloud-Bereitstellung für Docker Compose und Bereitstellungsanweisungen für Google Cloud Run, Azure Container Apps, AWS App Runner/ECS Fargate und Kubernetes.

Die Compose-Datei enthält außerdem den offiziellen MCP Inspector als optionalen Client. Führen Sie docker compose --profile inspector up --build -d aus und öffnen Sie dann http://127.0.0.1:6274. Siehe Einen MCP-Client in Docker ausführen für die Token-Einrichtung und die CLI-Nutzung.

Test

npm test

Die Tests verwenden den integrierten Test-Runner von Node und simulierte fetch-Antworten, sodass sie keine Live-npm-Registry benötigen.

Um den Server interaktiv mit MCP Inspector zu untersuchen:

npx @modelcontextprotocol/inspector node src/index.js

Öffnen Sie die von Inspector ausgegebene URL, verbinden Sie sich, wählen Sie Tools, wählen Sie ein Tool aus, geben Sie dessen Argumente ein und führen Sie es aus.

MCP-Client-Konfiguration

Verwenden Sie einen absoluten Pfad, damit der Client den Server aus jedem Arbeitsverzeichnis starten kann:

{
  "mcpServers": {
    "npm": {
      "command": "node",
      "args": ["/absolute/path/to/npm-mcp/src/index.js"]
    }
  }
}

Der genaue äußere Konfigurationsschlüssel kann je nach MCP-Client variieren, aber der Befehl und die Argumente sind dieselben.

Beispielaufrufe

{"name":"npm_search_packages","arguments":{"query":"postgres orm","limit":10}}

{"name":"npm_get_package","arguments":{"packageName":"@nestjs/core"}}

{"name":"npm_get_latest_version","arguments":{"packageName":"react"}}

{"name":"npm_get_versions","arguments":{"packageName":"axios"}}

Architektur

• src/index.js ist ausschließlich für den Stdio-Start zuständig.

• src/http.js und src/http-server.js stellen den authentifizierten Streamable-HTTP-Einstiegspunkt bereit, der von Containern verwendet wird.

• src/server.js erstellt den MCP-Server und registriert die vier Tools.

• src/tools/ enthält Schemas, gezielte Antwortaufbereitung und Handler.

• src/services/npm-registry.js ist das einzige Modul, das mit npm kommuniziert. Es validiert Paketnamen, beschränkt URLs auf die offiziellen Registry-Endpunkte, wendet ein Timeout an und normalisiert Netzwerk-/HTTP-/Antwortfehler.

Scoped-Namen werden als einzelnes Registry-Pfadsegment kodiert. Der Server ist zustandslos und führt keine Schreibvorgänge durch.

Zukünftige Verbesserungen

Mögliche spätere Ergänzungen umfassen Download-Statistiken, Abhängigkeitsanalyse, Paketsicherheitsinformationen, Caching und OAuth-basierte Remote-Authentifizierung.