port-doctor-mcp

Ein lokaler stdio-MCP-Server auf Basis von FastMCP, der prüft, ob Entwicklungsports belegt sind, und den entsprechenden Prozess über den Port beendet.

Funktionen

• check_port_status(port: int): Prüft, ob ein Port belegt ist, und gibt PID, Name, RSS-Speicherverbrauch, Protokoll und Verbindungsstatus des belegenden Prozesses zurück.

• kill_process_by_port(port: int, force: bool = True): Beendet den Prozess, der den Port belegt. Standardmäßig wird eine erzwungene Beendigung durchgeführt; mit force=false wird das sanftere terminate verwendet. Der Server beendet sich nicht selbst.

• scan_common_dev_ports(): Scannt gängige Entwicklungsports: 3000, 3001, 4173, 5000, 5173, 8000, 8001, 8080, 8081, 8888, 9000.

Related MCP server: localhost-mcp

Installation

Erforderlich ist Python 3.10 oder höher.

python -m venv .venv
source .venv/bin/activate       # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Prüfe, ob der aktuelle Interpreter die Abhängigkeiten tatsächlich installiert hat:

python -c "import sys, psutil, fastmcp; print(sys.executable); print('psutil', psutil.__version__); print('fastmcp', fastmcp.__version__)"

Wenn hier weiterhin ModuleNotFoundError angezeigt wird, bedeutet das, dass für die Installation der Abhängigkeiten und den Start des Servers nicht dasselbe Python verwendet wird. Führe nicht nur Invalidate Caches aus; wähle in PyCharm unter Settings -> Project -> Python Interpreter das .venv/bin/python dieses Projekts aus und verwende in der Run Configuration denselben Interpreter.

Der Interpreterpfad des Projekts sollte beispielsweise so aussehen:

/path/to/port-doctor-mcp/.venv/bin/python

Windows-Beispiel:

C:\path\to\port-doctor-mcp\.venv\Scripts\python.exe

Ausführen

Dies ist ein stdio-Server. Nach dem Start wartet er darauf, dass MCP-Clients über stdin/stdout kommunizieren; es wird kein HTTP-Port bereitgestellt.

python server.py

Alternativ kann die FastMCP-CLI verwendet werden:

fastmcp run server.py

Für Entwicklung und Debugging kann MCP Inspector verwendet werden (abhängig von der Unterstützung durch die aktuell installierte FastMCP-CLI):

fastmcp dev inspector server.py

Es ist normal, dass das Terminal nach dem direkten Ausführen von python server.py keine normale Ausgabe zeigt und weiterhin auf Eingaben wartet: Der stdio-MCP-Server wartet darauf, dass Clients JSON-RPC-Nachrichten über stdin/stdout senden. Betrachte es nicht als Startfehler, wenn der Prozess nicht beendet wird.

Manuelle Testliste

Im Projektstammverzeichnis ausführen:

source .venv/bin/activate
python -m pip check
python -m py_compile server.py
git diff --check
fastmcp list server.py --input-schema --output-schema --json

fastmcp list sollte die folgenden drei Tools anzeigen:

• check_port_status: Erforderlich: port, ganze Zahl.

• kill_process_by_port: Erforderlich: port, optional: force, Standardwert true.

• scan_common_dev_ports: Keine Parameter.

Testen mit Inspector

Ausführen:

fastmcp dev inspector server.py

Teste im geöffneten Inspector der Reihe nach:

1. Rufe check_port_status auf und übergib 5000 oder 8000.

2. Rufe scan_common_dev_ports auf und bestätige, dass scanned_ports und occupied_ports zurückgegeben werden.

3. Starte einen dedizierten Testdienst:

   python -m http.server 8765 --bind 127.0.0.1

4. Rufe check_port_status(8765) auf und bestätige, dass PID, Name und Speicher des Python-Prozesses angezeigt werden.

5. Rufe kill_process_by_port(8765, force=false) auf, bestätige, dass success: true zurückgegeben wird, und schließe dann das Testterminal.

Teste kill_process_by_port nicht direkt an wichtigen Prozessen wie Datenbanken, IDEs oder Systemdiensten. Mit der Standardeinstellung force=true sendet dieses Tool ein erzwungenes Beendigungssignal.

Schema mit der FastMCP-CLI prüfen

fastmcp inspect server.py --format mcp

Prüfe, ob die Toolnamen, Beschreibungen, Parametertypen und Standardwerte in der Ausgabe korrekt sind.

MCP-Client-Konfiguration

Ersetze den folgenden Pfad durch den absoluten Pfad dieses Projekts und füge ihn in die Konfiguration eines MCP-fähigen Clients ein:

{
  "mcpServers": {
    "port-doctor-mcp": {
      "command": "/absolute/path/to/port-doctor-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/port-doctor-mcp/server.py"]
    }
  }
}

Windows-Beispiel:

{
  "mcpServers": {
    "port-doctor-mcp": {
      "command": "C:\\path\\to\\port-doctor-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\port-doctor-mcp\\server.py"]
    }
  }
}

Bei MCP.so werden die Verzeichnisinformationen des GitHub-Repositorys eingereicht; dein lokaler Python-Interpreter wird dadurch nicht repariert. Andere Benutzer müssen nach der Installation weiterhin zuerst eine virtuelle Umgebung erstellen und pip install -r requirements.txt ausführen.

Veröffentlichen auf MCP.so

MCP.so ist ein Verzeichnis für MCP-Server und verwandelt keinen lokalen stdio-Prozess in einen öffentlich erreichbaren HTTP-Dienst. Committe dieses Projekt vor der Veröffentlichung in ein öffentliches GitHub-Repository und öffne dann:

https://mcp.so/submit?type=server

Ausfüllen:

• Repository URL: Die Adresse deines GitHub-Repositorys.

• Name: port-doctor-mcp.

Die Einreichungsseite bietet möglicherweise eine kostenpflichtige Express-Veröffentlichung an; ob du diese kaufst, hat keinen Einfluss auf die Ausführung des Codes dieses Projekts. Nachdem Benutzer das Projekt im Verzeichnis entdeckt haben, müssen sie weiterhin die lokale Python-Umgebung gemäß den obigen Installationsschritten konfigurieren.

Beispiel für Rückgabewerte

check_port_status(8000) gibt eine ähnliche Struktur wie die folgende zurück:

{
  "port": 8000,
  "in_use": true,
  "process_count": 1,
  "processes": [
    {
      "pid": 12345,
      "name": "python",
      "memory_rss_bytes": 52428800,
      "memory_rss_mb": 50.0,
      "connections": [
        {
          "protocol": "tcp",
          "local_address": "127.0.0.1:8000",
          "status": "LISTEN"
        }
      ]
    }
  ]
}

Sicherheitshinweise

kill_process_by_port ist ein Tool mit Nebenwirkungen. Standardmäßig sendet force=true ein erzwungenes Beendigungssignal, was zum Verlust nicht gespeicherter Daten führen kann; es wird empfohlen, zuerst check_port_status aufzurufen, um die PID zu bestätigen, bevor du entscheidest, ob der Prozess beendet werden soll. Beim Lesen von Prozessinformationen anderer Benutzer oder beim Beenden geschützter Prozesse kann das Betriebssystem einen Berechtigungsfehler zurückgeben.

Lizenz

Siehe LICENSE.