# mcp-infra

An MCP (Model Context Protocol) server for infrastructure introspection — lets AI assistants query which processes are listening on specific ports on your machine.

## What it does

Exposes a single tool to MCP clients (like Claude Desktop or Claude Code):

**`get_processes_by_ports`** — given a list of port numbers, returns the process name and PID for each listening socket.

```json
// Example response for ports [8000, 3000]
{
  "8000": [{ "name": "python", "pid": "12345" }],
  "3000": [{ "name": "node", "pid": "67890" }]
}
```

This is useful when you want your AI assistant to understand what's running on your machine — e.g. "what's listening on port 5432?" or "check if my dev server is up."

## Requirements

- Python 3.11+
- Linux (uses `ss` from `iproute2`)
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

```bash
git clone https://github.com/your-username/mcp-infra
cd mcp-infra
uv sync
```

Or with pip:

```bash
pip install -e .
```

## Usage

### Run directly

```bash
uv run server.py
# or
python server.py
```

### Add to Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "infra": {
      "command": "uv",
      "args": ["run", "/path/to/mcp-infra/server.py"]
    }
  }
}
```

### Add to Claude Code

```bash
claude mcp add infra -- uv run /path/to/mcp-infra/server.py
```

## Tool reference

### `get_processes_by_ports(ports: list[int]) -> str`

Returns a JSON string mapping each port to a list of processes.

| Field | Type | Description |
|-------|------|-------------|
| `ports` | `list[int]` | Port numbers to query |

**Response shape per port:**
- `name` — process name
- `pid` — process ID as string
- `raw` — unparsed line (fallback if parsing fails)
- `error` — error message if `ss` failed for that port

## How it works

Uses the `ss` command (`ss -tlnp sport = :<port>`) to list TCP sockets in LISTEN state, then parses the `users:((...))` field to extract process names and PIDs.

## Contributing

Pull requests are welcome. Keep it focused — this is intentionally a small, single-purpose server.

## License

MIT