<div align="center">

# `port-sentry`

### An MCP server that gives AI coding agents superpowers over network ports — find free ports, identify port hogs, and kill zombie processes without ever leaving the chat.

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Language](https://img.shields.io/badge/language-python-green.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) ![PyPI](https://img.shields.io/pypi/v/port-sentry?style=flat-square&color=blue) ![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square) ![License](https://img.shields.io/badge/license-MIT-green?style=flat-square) ![MCP](https://img.shields.io/badge/MCP-Compatible-purple?style=flat-square) ![Tests](https://img.shields.io/badge/tests-passing-brightgreen?style=flat-square)

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

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

```bash
# Install
pip install port-sentry

# Run
port-sentry --help
```

## 📦 Installation

### From Source

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

```bash
# 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](https://github.com/charmbracelet/vhs):

```bash
vhs < demo.tape
```

## 📖 Usage

```bash
# Show help
port-sentry --help

# Common usage examples
port-sentry --example
```

## 🏗️ Architecture

```mermaid
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](LICENSE) for details.

---

<div align="center">

**If this project helped you, please ⭐ star it!**

[Made with ❤️ and AI](https://github.com)

</div>