# 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。

## 安装

需要 Python 3.10 或更高版本。

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

验证当前解释器确实安装了依赖：

```bash
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 中使用相同解释器。

例如项目的解释器路径应类似：

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

Windows 示例：

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

## 运行

这是 stdio 服务器，启动后会等待 MCP 客户端通过 stdin/stdout 通信，不会提供 HTTP 端口。

```bash
python server.py
```

也可以使用 FastMCP CLI：

```bash
fastmcp run server.py
```

开发调试可使用 MCP Inspector（以当前安装的 FastMCP CLI 支持为准）：

```bash
fastmcp dev inspector server.py
```

直接运行 `python server.py` 后终端没有普通输出、一直等待输入是正常现象：stdio MCP 服务器会等待客户端通过 stdin/stdout 发送 JSON-RPC 消息。不要把“进程没有退出”当成启动失败。

## 手动测试清单

在项目根目录执行：

```bash
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 测试

执行：

```bash
fastmcp dev inspector server.py
```

在打开的 Inspector 中依次测试：

1. 调用 `check_port_status`，传入 `5000` 或 `8000`。
2. 调用 `scan_common_dev_ports`，确认返回 `scanned_ports` 和 `occupied_ports`。
3. 启动一个专用测试服务：

   ```bash
   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

```bash
fastmcp inspect server.py --format mcp
```

检查输出中的工具名称、描述、参数类型和默认值是否正确。

## MCP 客户端配置

将下面的路径替换为本项目的绝对路径，然后放入支持 MCP 的客户端配置中：

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

Windows 示例：

```json
{
  "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 仓库，然后打开：

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

填写：

- `Repository URL`：你的 GitHub 仓库地址。
- `Name`：`port-doctor-mcp`。

提交页面可能提供付费加急发布选项；是否购买不影响本项目代码运行。用户从目录发现项目后，仍需按上面的安装步骤配置本地 Python 环境。

## 返回值示例

`check_port_status(8000)` 返回结构类似：

```json
{
  "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](LICENSE)。