port-sentry

🎯 Why?

AI coding agents constantly try to start dev servers on ports that are already in use, leading to cascading failures and wasted tokens. While tools like lsof and netstat exist for humans, there is no MCP server that gives agents structured, actionable port intelligence — forcing them to parse raw shell output or guess random port numbers.

Target audience: Developers using AI coding agents (Claude Code, Cursor, Codex, Copilot) who frequently run dev servers, databases, and microservices locally and are tired of 'port already in use' errors derailing their agent workflows.

✨ Features

• ✨ List all ports currently in use with owning process name, PID, and command line
• ✨ Find the next N available ports within a specified range
• ✨ Check if a specific port is available or occupied
• ✨ Kill the process occupying a specific port (with safety confirmations)
• ✨ Wait/poll for a port to become free with configurable timeout

🚀 Quick Start

# Install
pip install port-sentry

# Run
port-sentry --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/port-sentry.git
cd port-sentry

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
port-sentry --help

# Common usage examples
port-sentry --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT © 2026 — See LICENSE for details.