port-doctor-mcp

Локальный stdio MCP-сервер на основе FastMCP для проверки занятости портов разработки и завершения соответствующих процессов по номеру порта.

Функции

• check_port_status(port: int): проверяет, занят ли порт, и возвращает PID, имя, объём памяти RSS, протокол и состояние соединения процесса, занимающего порт.

• kill_process_by_port(port: int, force: bool = True): завершает процесс, занимающий порт. По умолчанию используется принудительное завершение; при передаче force=false применяется более мягкий terminate. Сервер не завершает сам себя.

• scan_common_dev_ports(): сканирует распространённые порты разработки: 3000, 3001, 4173, 5000, 5173, 8000, 8001, 8080, 8081, 8888, 9000.

Related MCP server: localhost-mcp

Установка

Требуется Python 3.10 или новее.

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

Проверьте, что зависимости действительно установлены в текущем интерпретаторе:

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

Если здесь по-прежнему появляется ModuleNotFoundError, значит, установка зависимостей и запуск сервера выполняются не в одном и том же Python. Не ограничивайтесь только выполнением Invalidate Caches; в PyCharm выберите .venv/bin/python этого проекта в Settings -> Project -> Python Interpreter и используйте тот же интерпретатор в Run Configuration.

Например, путь к интерпретатору проекта должен выглядеть примерно так:

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

Пример для Windows:

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

Запуск

Это stdio-сервер: после запуска он ожидает обмена данными с MCP-клиентом через stdin/stdout и не предоставляет HTTP-порт.

python server.py

Также можно использовать FastMCP CLI:

fastmcp run server.py

Для разработки и отладки можно использовать MCP Inspector (если это поддерживает установленная версия FastMCP CLI):

fastmcp dev inspector server.py

Отсутствие обычного вывода и постоянное ожидание ввода в терминале после запуска python server.py — это нормальное явление: stdio MCP-сервер ожидает, пока клиент отправит сообщения JSON-RPC через stdin/stdout. Не воспринимайте «процесс не завершается» как сбой запуска.

Чек-лист ручного тестирования

Выполните в корневом каталоге проекта:

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 должен отображать следующие три инструмента:

• check_port_status: обязательный параметр port, целое число.

• kill_process_by_port: обязательный параметр port, необязательный force, по умолчанию true.

• scan_common_dev_ports: без параметров.

Тестирование с помощью Inspector

Выполните:

fastmcp dev inspector server.py

В открывшемся Inspector последовательно проверьте:

1. Вызовите check_port_status, передав 5000 или 8000.

2. Вызовите scan_common_dev_ports и убедитесь, что возвращаются scanned_ports и occupied_ports.

3. Запустите отдельный тестовый сервис:

   python -m http.server 8765 --bind 127.0.0.1

4. Вызовите check_port_status(8765) и убедитесь, что видны PID, имя и объём памяти процесса Python.

5. Вызовите kill_process_by_port(8765, force=false) и убедитесь, что возвращается success: true, затем закройте тестовый терминал.

Не тестируйте kill_process_by_port напрямую на важных процессах, таких как базы данных, IDE и системные службы. Этот инструмент по умолчанию использует force=true и отправляет сигнал принудительного завершения.

Проверка схемы с помощью FastMCP CLI

fastmcp inspect server.py --format mcp

Проверьте, что в выводе корректны имена инструментов, описания, типы параметров и значения по умолчанию.

Конфигурация MCP-клиента

Замените путь ниже на абсолютный путь к этому проекту и добавьте его в конфигурацию клиента, поддерживающего MCP:

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

Пример для Windows:

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

В MCP.so передаётся информация о каталоге GitHub-репозитория; это не исправит за вас локальный интерпретатор Python. Другим пользователям после установки по-прежнему нужно сначала создать виртуальное окружение и выполнить pip install -r requirements.txt.

Публикация на MCP.so

MCP.so — это каталог MCP-серверов; он не превращает локальный stdio-процесс в публичный HTTP-сервис. Перед публикацией сначала отправьте этот проект в публичный GitHub-репозиторий, затем откройте:

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

Заполните:

• Repository URL: адрес вашего GitHub-репозитория.

• Name: port-doctor-mcp.

На странице отправки может быть доступна платная опция ускоренной публикации; покупка не влияет на работу кода этого проекта. После того как пользователи найдут проект в каталоге, им всё равно потребуется настроить локальное окружение Python в соответствии с приведёнными выше шагами установки.

Пример возвращаемого значения

check_port_status(8000) возвращает структуру примерно следующего вида:

{
  "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"
        }
      ]
    }
  ]
}

Предупреждение о безопасности

kill_process_by_port — инструмент с побочными эффектами. По умолчанию (force=true) отправляется сигнал принудительного завершения, что может привести к потере несохранённых данных; рекомендуется сначала вызвать check_port_status, чтобы подтвердить PID, и только потом решать, завершать ли процесс. При чтении информации о процессах других пользователей или завершении защищённых процессов операционная система может вернуть ошибку прав доступа.

Лицензия

См. LICENSE.