port-doctor-mcp

FastMCP 기반의 로컬 stdio MCP 서버로, 개발 포트 점유 상태를 확인하고 포트별로 해당 프로세스를 종료합니다.

기능

• 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의 Settings -> Project -> Python Interpreter에서 이 프로젝트의 .venv/bin/python을 선택하고, 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 서버는 클라이언트가 stdin/stdout을 통해 JSON-RPC 메시지를 보낼 때까지 대기합니다. '프로세스가 종료되지 않음'을 시작 실패로 간주하지 마세요.

수동 테스트 목록

프로젝트 루트에서 다음을 실행하세요:

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)를 호출하고 Python 프로세스의 PID, 이름, 메모리를 확인할 수 있는지 확인합니다.

5. kill_process_by_port(8765, force=false)를 호출하고 success: true가 반환되는지 확인한 다음 테스트 터미널을 닫습니다.

데이터베이스, IDE, 시스템 서비스 등 중요한 프로세스에서 kill_process_by_port를 직접 테스트하지 마세요. 이 도구는 기본값이 force=true이며 강제 종료 신호를 보냅니다.

FastMCP CLI로 schema 확인

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를 참조하세요.