Update README with full feature set
- Server mode documentation - Terminal escape sequences (send_key) - ANSI stripping, regex, keepalive - Connection stats and transcripts - Security section
This commit is contained in:
parent
a8fbd71e0c
commit
5595f1aef1
164
README.md
164
README.md
@ -1,87 +1,129 @@
|
||||
# mctelnet
|
||||
|
||||
MCP server providing telnet client capabilities for LLMs. Connect to BBSes, MUDs, network devices, and any telnet-accessible system.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
uvx mctelnet
|
||||
```
|
||||
|
||||
Or add to Claude Code:
|
||||
**Telnet for LLMs.** Connect to BBSes, MUDs, network devices, or host your own telnet services.
|
||||
|
||||
```bash
|
||||
claude mcp add mctelnet "uvx mctelnet"
|
||||
```
|
||||
|
||||
## Why?
|
||||
|
||||
LLMs can now interact with the vast world of telnet-accessible systems:
|
||||
- **Retro computing** - BBSes, ASCII art servers, text adventures
|
||||
- **Network ops** - Routers, switches, legacy infrastructure
|
||||
- **Automation** - Expect-style scripting for any interactive prompt
|
||||
- **Hosting** - Run telnet services that LLMs can manage
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
# Watch Star Wars in ASCII (really!)
|
||||
connect("towel.blinkenlights.nl", 23, strip_ansi=True)
|
||||
|
||||
# Login to a server
|
||||
expect_send(conn_id, "login:", "admin")
|
||||
expect_send(conn_id, "Password:", "secret", hide_send=True)
|
||||
expect_send(conn_id, "$ ", "uptime")
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- **Multi-connection management** - Handle multiple simultaneous telnet sessions
|
||||
- **Expect-style automation** - Pattern matching for interactive prompts
|
||||
- **Script execution** - Run complete login/automation sequences
|
||||
- **Password hiding** - Redact sensitive data from outputs
|
||||
### Client Mode - Connect Anywhere
|
||||
|
||||
## Tools
|
||||
|
||||
| Tool | Description |
|
||||
| Tool | What it does |
|
||||
|------|-------------|
|
||||
| `connect` | Establish telnet connection, returns connection ID |
|
||||
| `send` | Send text to connection (auto-reads response) |
|
||||
| `read` | Read available data from connection |
|
||||
| `expect` | Wait for one of multiple patterns |
|
||||
| `expect_send` | Wait for pattern, then send text |
|
||||
| `run_script` | Execute expect-style automation script |
|
||||
| `list_connections` | Show all active connections |
|
||||
| `disconnect` | Close a connection |
|
||||
| `disconnect_all` | Close all connections |
|
||||
| `connect` | Connect with optional ANSI stripping, keepalive |
|
||||
| `send` | Send text, auto-read response |
|
||||
| `send_key` | Send escape sequences (ctrl-c, arrows, F-keys) |
|
||||
| `expect` | Wait for patterns (supports regex) |
|
||||
| `expect_send` | Wait then send - perfect for prompts |
|
||||
| `run_script` | Full automation sequences |
|
||||
| `connection_info` | Stats: bytes sent/received, uptime |
|
||||
| `get_transcript` | Complete session history |
|
||||
|
||||
## Usage Examples
|
||||
### Server Mode - Host Services
|
||||
|
||||
### Basic Interaction
|
||||
| Tool | What it does |
|
||||
|------|-------------|
|
||||
| `start_server` | Listen on a port (localhost by default) |
|
||||
| `list_clients` | See who's connected |
|
||||
| `send_client` | Send to specific client |
|
||||
| `broadcast` | Send to all clients |
|
||||
| `read_client` | Get buffered client input |
|
||||
|
||||
## Examples
|
||||
|
||||
### Expect-Style Automation
|
||||
|
||||
```python
|
||||
# Connect to a server
|
||||
conn = await connect("bbs.example.com", 23)
|
||||
# conn returns {"id": "abc123", ...}
|
||||
|
||||
# Send a command
|
||||
await send("abc123", "help")
|
||||
|
||||
# Disconnect
|
||||
await disconnect("abc123")
|
||||
```
|
||||
|
||||
### Expect-Style Login
|
||||
|
||||
```python
|
||||
# Connect and wait for login prompt
|
||||
conn = await connect("server.example.com", 23)
|
||||
|
||||
# Handle login sequence
|
||||
await expect_send(conn_id, "login:", "myuser")
|
||||
await expect_send(conn_id, "Password:", "mypass", hide_send=True)
|
||||
await expect_send(conn_id, "$ ", "ls -la")
|
||||
```
|
||||
|
||||
### Scripted Automation
|
||||
|
||||
```python
|
||||
await run_script(conn_id, [
|
||||
# Scripted login + commands
|
||||
run_script(conn_id, [
|
||||
{"expect": "login:", "send": "admin"},
|
||||
{"expect": "Password:", "send": "secret", "hide": True},
|
||||
{"expect": "$ ", "send": "show version"},
|
||||
{"expect": "$ ", "send": "show interfaces"},
|
||||
{"expect": "$ ", "send": "exit"}
|
||||
])
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
### Terminal Keys
|
||||
|
||||
- Connecting to retro BBSes and MUDs
|
||||
- Network device configuration (routers, switches)
|
||||
- Legacy system automation
|
||||
- Interactive service testing
|
||||
- Terminal-based game playing
|
||||
```python
|
||||
# Send escape sequences
|
||||
send_key(conn_id, "ctrl-c") # Interrupt
|
||||
send_key(conn_id, "up") # Arrow key
|
||||
send_key(conn_id, "f1") # Function key
|
||||
send_key(conn_id, "break") # Telnet break
|
||||
|
||||
# See all available keys
|
||||
list_keys()
|
||||
```
|
||||
|
||||
### Regex Pattern Matching
|
||||
|
||||
```python
|
||||
# Flexible matching
|
||||
expect(conn_id, [r"user(name)?:", r"login:"], regex=True)
|
||||
expect_send(conn_id, "password", "secret", ignore_case=True)
|
||||
```
|
||||
|
||||
### Host a Service
|
||||
|
||||
```python
|
||||
# Start server (binds localhost:2323)
|
||||
start_server(2323)
|
||||
|
||||
# Send welcome to new connections
|
||||
send_client(server_id, client_id, "Welcome to my LLM-powered service!")
|
||||
|
||||
# Broadcast to everyone
|
||||
broadcast(server_id, "Server shutting down in 5 minutes")
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
**With Claude Code:**
|
||||
```bash
|
||||
claude mcp add mctelnet "uvx mctelnet"
|
||||
```
|
||||
|
||||
**Standalone:**
|
||||
```bash
|
||||
uvx mctelnet
|
||||
```
|
||||
|
||||
**From source:**
|
||||
```bash
|
||||
git clone https://git.supported.systems/MCP/mctelnet
|
||||
cd mctelnet
|
||||
uv run mctelnet
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
- Server mode binds to `127.0.0.1` by default (localhost only)
|
||||
- Port validation (1-65535)
|
||||
- Connection limits prevent resource exhaustion
|
||||
- Graceful shutdown cleans up all connections
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user