# mcp-socket

Stateful **outbound TCP/UDP MCP server** for LLMs.

Sockets stay open across tool calls until you close them or they hit the idle timeout. That makes multi-step protocols practical: HTTP/1.x, SMTP, Redis, DNS (UDP), custom text/binary protocols, and more.

See [DESIGN.md](DESIGN.md) for the full design.

## Install

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Run

```bash
# stdio (default) — typical for MCP clients
mcp-socket

# or
python -m mcp_socket

# HTTP transport
mcp-socket --transport streamable-http --host 127.0.0.1 --port 8000
```

### CLI options

| Option | Default | Description |
|--------|---------|-------------|
| `--transport` | `stdio` | `stdio`, `streamable-http`, or `sse` |
| `--host` | `127.0.0.1` | HTTP bind address |
| `--port` | `8000` | HTTP bind port |
| `--socket-idle-timeout` | `300` | Idle seconds before auto-close |
| `--cleanup-interval` | `5` | Cleanup scan interval |
| `--allow-private-network` | off | Allow RFC1918/loopback/ULA/etc. |
| `--max-sockets` | `128` | Max concurrent sockets |
| `--max-send-bytes` | `1048576` | Max send payload |
| `--max-recv-bytes` | `1048576` | Max recv payload |
| `--log-level` | `INFO` | Logging level |

## Tools

| Tool | Purpose |
|------|---------|
| `resolve_dns` | Hostname → A/AAAA |
| `tcp_connect` | Connect TCP to IP:port |
| `udp_open` | Create UDP socket |
| `tcp_send` / `udp_send` | Send (`utf8` or `base64`) |
| `tcp_recv` / `udp_recv` | Receive (base64 + optional text) |
| `socket_poll` | Check readability |
| `list_sockets` | Inspect open sockets |
| `close_socket` | Close (optional TCP RST) |

`tcp_connect` / `udp_send` require **IP literals**. Call `resolve_dns` first for hostnames.

Private and local destinations are blocked by default (`ADDRESS_BLOCKED`). Use `--allow-private-network` for local testing.

## Example (TCP HTTP/1.0)

```text
resolve_dns(hostname="example.com")
→ { "ipv4": ["93.184.216.34"], ... }

tcp_connect(address="93.184.216.34", port=80)
→ { "socket_id": "...", "state": "connected" }

tcp_send(socket_id="...", encoding="utf8",
         data="GET / HTTP/1.0\r\nHost: example.com\r\n\r\n")

tcp_recv(socket_id="...", max_bytes=65536, timeout_seconds=5)
→ { "bytes_received": N, "data_base64": "...", "text": "HTTP/1.0 200 ..." }

close_socket(socket_id="...")
```

## Security

Before every `connect()` / `sendto()`:

- Destination must be a valid IP literal
- Private/local ranges are denied unless `--allow-private-network`
- Multicast / unspecified / reserved ranges are always denied

No TLS, no listening sockets, no proxy support — higher-level servers can layer those on top.

## Develop

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT