@ellery/terminal-mcp 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +301 -9
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +2 -61
- package/dist/client.js.map +1 -1
- package/dist/index.js +286 -14
- package/dist/index.js.map +1 -1
- package/dist/prompts/index.d.ts.map +1 -1
- package/dist/prompts/index.js +8 -0
- package/dist/prompts/index.js.map +1 -1
- package/dist/recording/index.d.ts +4 -0
- package/dist/recording/index.d.ts.map +1 -0
- package/dist/recording/index.js +3 -0
- package/dist/recording/index.js.map +1 -0
- package/dist/recording/manager.d.ts +62 -0
- package/dist/recording/manager.d.ts.map +1 -0
- package/dist/recording/manager.js +123 -0
- package/dist/recording/manager.js.map +1 -0
- package/dist/recording/recorder.d.ts +95 -0
- package/dist/recording/recorder.d.ts.map +1 -0
- package/dist/recording/recorder.js +296 -0
- package/dist/recording/recorder.js.map +1 -0
- package/dist/recording/types.d.ts +65 -0
- package/dist/recording/types.d.ts.map +1 -0
- package/dist/recording/types.js +2 -0
- package/dist/recording/types.js.map +1 -0
- package/dist/sandbox/config.d.ts +46 -0
- package/dist/sandbox/config.d.ts.map +1 -0
- package/dist/sandbox/config.js +144 -0
- package/dist/sandbox/config.js.map +1 -0
- package/dist/sandbox/controller.d.ts +72 -0
- package/dist/sandbox/controller.d.ts.map +1 -0
- package/dist/sandbox/controller.js +208 -0
- package/dist/sandbox/controller.js.map +1 -0
- package/dist/sandbox/index.d.ts +6 -0
- package/dist/sandbox/index.d.ts.map +1 -0
- package/dist/sandbox/index.js +4 -0
- package/dist/sandbox/index.js.map +1 -0
- package/dist/sandbox/prompt.d.ts +10 -0
- package/dist/sandbox/prompt.d.ts.map +1 -0
- package/dist/sandbox/prompt.js +434 -0
- package/dist/sandbox/prompt.js.map +1 -0
- package/dist/server.d.ts +2 -3
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +21 -0
- package/dist/server.js.map +1 -1
- package/dist/terminal/index.d.ts +1 -0
- package/dist/terminal/index.d.ts.map +1 -1
- package/dist/terminal/manager.d.ts +89 -31
- package/dist/terminal/manager.d.ts.map +1 -1
- package/dist/terminal/manager.js +313 -44
- package/dist/terminal/manager.js.map +1 -1
- package/dist/terminal/session.d.ts +34 -1
- package/dist/terminal/session.d.ts.map +1 -1
- package/dist/terminal/session.js +160 -3
- package/dist/terminal/session.js.map +1 -1
- package/dist/tools/createSession.d.ts +44 -0
- package/dist/tools/createSession.d.ts.map +1 -0
- package/dist/tools/createSession.js +41 -0
- package/dist/tools/createSession.js.map +1 -0
- package/dist/tools/definitions.d.ts +18 -0
- package/dist/tools/definitions.d.ts.map +1 -0
- package/dist/tools/definitions.js +116 -0
- package/dist/tools/definitions.js.map +1 -0
- package/dist/tools/destroySession.d.ts +31 -0
- package/dist/tools/destroySession.d.ts.map +1 -0
- package/dist/tools/destroySession.js +32 -0
- package/dist/tools/destroySession.js.map +1 -0
- package/dist/tools/getContent.d.ts +7 -0
- package/dist/tools/getContent.d.ts.map +1 -1
- package/dist/tools/getContent.js +8 -3
- package/dist/tools/getContent.js.map +1 -1
- package/dist/tools/index.d.ts.map +1 -1
- package/dist/tools/index.js +26 -1
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/listSessions.d.ts +19 -0
- package/dist/tools/listSessions.d.ts.map +1 -0
- package/dist/tools/listSessions.js +23 -0
- package/dist/tools/listSessions.js.map +1 -0
- package/dist/tools/screenshot.d.ts +26 -3
- package/dist/tools/screenshot.d.ts.map +1 -1
- package/dist/tools/screenshot.js +55 -5
- package/dist/tools/screenshot.js.map +1 -1
- package/dist/tools/sendKey.d.ts +7 -0
- package/dist/tools/sendKey.d.ts.map +1 -1
- package/dist/tools/sendKey.js +7 -2
- package/dist/tools/sendKey.js.map +1 -1
- package/dist/tools/startRecording.d.ts +68 -0
- package/dist/tools/startRecording.d.ts.map +1 -0
- package/dist/tools/startRecording.js +111 -0
- package/dist/tools/startRecording.js.map +1 -0
- package/dist/tools/stopRecording.d.ts +31 -0
- package/dist/tools/stopRecording.d.ts.map +1 -0
- package/dist/tools/stopRecording.js +76 -0
- package/dist/tools/stopRecording.js.map +1 -0
- package/dist/tools/type.d.ts +7 -0
- package/dist/tools/type.d.ts.map +1 -1
- package/dist/tools/type.js +7 -2
- package/dist/tools/type.js.map +1 -1
- package/dist/transport/socket.d.ts.map +1 -1
- package/dist/transport/socket.js +10 -0
- package/dist/transport/socket.js.map +1 -1
- package/dist/ui/index.d.ts +1 -0
- package/dist/ui/index.d.ts.map +1 -1
- package/dist/ui/index.js +17 -1
- package/dist/ui/index.js.map +1 -1
- package/dist/utils/platform.d.ts +6 -0
- package/dist/utils/platform.d.ts.map +1 -1
- package/dist/utils/platform.js +15 -0
- package/dist/utils/platform.js.map +1 -1
- package/dist/utils/render.d.ts +21 -0
- package/dist/utils/render.d.ts.map +1 -0
- package/dist/utils/render.js +162 -0
- package/dist/utils/render.js.map +1 -0
- package/package.json +6 -2
- package/sandbox-permissions.png +0 -0
package/README.md
CHANGED
|
@@ -27,7 +27,11 @@ curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/ins
|
|
|
27
27
|
- **Full Terminal Emulation**: Uses xterm.js headless for accurate VT100/ANSI emulation
|
|
28
28
|
- **Cross-Platform PTY**: Native pseudo-terminal support via node-pty (macOS, Linux, Windows)
|
|
29
29
|
- **MCP Protocol**: Implements Model Context Protocol for AI assistant integration
|
|
30
|
-
- **
|
|
30
|
+
- **Session Recording**: Record terminal sessions to asciicast format for playback with asciinema
|
|
31
|
+
- **Simple API**: Nine tools covering input, observation, recording, and session lifecycle
|
|
32
|
+
- **Headless Mode**: Run as a standalone MCP server without a TTY — ideal for CI, containers, and non-interactive environments
|
|
33
|
+
- **Multi-Session**: Run multiple isolated terminal sessions in one process, addressed by `sessionId`
|
|
34
|
+
- **Sandbox Mode**: Optional security restrictions for filesystem and network access
|
|
31
35
|
|
|
32
36
|
## Building from Source
|
|
33
37
|
|
|
@@ -71,14 +75,77 @@ With custom options:
|
|
|
71
75
|
terminal-mcp [OPTIONS]
|
|
72
76
|
|
|
73
77
|
Options:
|
|
74
|
-
--cols <number>
|
|
75
|
-
--rows <number>
|
|
76
|
-
--shell <path>
|
|
77
|
-
--
|
|
78
|
+
--cols <number> Terminal width in columns (default: 120)
|
|
79
|
+
--rows <number> Terminal height in rows (default: 40)
|
|
80
|
+
--shell <path> Shell to use (default: $SHELL or bash)
|
|
81
|
+
--headless Run in headless mode (embedded PTY + MCP over stdio, no TTY needed)
|
|
82
|
+
--sandbox Enable sandbox mode (restricts filesystem/network)
|
|
83
|
+
--sandbox-config <path> Load sandbox config from JSON file
|
|
84
|
+
--version, -v Show version number
|
|
85
|
+
--help, -h Show help message
|
|
86
|
+
|
|
87
|
+
Recording Options:
|
|
88
|
+
--record [mode] Enable recording (default mode: always)
|
|
89
|
+
Modes: always, on-failure, off
|
|
90
|
+
--record-dir <dir> Recording output directory
|
|
91
|
+
(default: ~/.local/state/terminal-mcp/recordings)
|
|
92
|
+
--idle-time-limit <sec> Max idle time between events (default: 2s)
|
|
93
|
+
--max-duration <sec> Max recording duration (default: 3600s)
|
|
94
|
+
--inactivity-timeout <sec> Stop after no output (default: 600s)
|
|
95
|
+
|
|
96
|
+
Multi-Session Options:
|
|
97
|
+
--max-sessions <n> Max concurrent sessions (default: 5)
|
|
98
|
+
--session-idle-timeout <sec> Idle non-default sessions are auto-destroyed
|
|
99
|
+
after this period (default: 600s)
|
|
78
100
|
```
|
|
79
101
|
|
|
102
|
+
## Headless Mode
|
|
103
|
+
|
|
104
|
+
By default, Terminal MCP uses a **dual-process architecture**: you run `terminal-mcp` in an interactive terminal (which creates a Unix socket), then your MCP client spawns a second instance that connects to that socket. This requires a TTY.
|
|
105
|
+
|
|
106
|
+
**Headless mode** (`--headless`) eliminates this requirement by spawning an embedded PTY internally and serving MCP directly over stdio in a single process. No interactive terminal session, no socket — just a self-contained MCP server with a built-in terminal.
|
|
107
|
+
|
|
108
|
+
### When to use headless mode
|
|
109
|
+
|
|
110
|
+
- **CI/CD pipelines** — no TTY available
|
|
111
|
+
- **Docker containers** — no interactive shell to run alongside
|
|
112
|
+
- **Remote/cloud environments** — MCP servers spawned by automation
|
|
113
|
+
- **Simplified setup** — single process, no socket coordination needed
|
|
114
|
+
|
|
115
|
+
### Configuration
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"mcpServers": {
|
|
120
|
+
"terminal": {
|
|
121
|
+
"command": "terminal-mcp",
|
|
122
|
+
"args": ["--headless", "--cols", "120", "--rows", "40"]
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### How it works
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
MCP Client (Claude Code, etc.)
|
|
132
|
+
│ STDIO (JSON-RPC)
|
|
133
|
+
▼
|
|
134
|
+
terminal-mcp --headless
|
|
135
|
+
├── MCP Server (stdio transport)
|
|
136
|
+
├── Terminal Emulator (@xterm/headless)
|
|
137
|
+
└── Embedded PTY (node-pty)
|
|
138
|
+
│
|
|
139
|
+
▼
|
|
140
|
+
Shell Process (bash, zsh, etc.)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
In headless mode, the terminal session is initialized eagerly at startup, so all tools (`type`, `sendKey`, `getContent`, `takeScreenshot`, `startRecording`, `stopRecording`, `createSession`, `listSessions`, `destroySession`) are available immediately.
|
|
144
|
+
|
|
80
145
|
## MCP Tools
|
|
81
146
|
|
|
147
|
+
All input/output tools (`type`, `sendKey`, `getContent`, `takeScreenshot`) accept an optional `sessionId` argument. Omit it to target the default session; pass the ID returned by `createSession` to drive a specific session.
|
|
148
|
+
|
|
82
149
|
### `type`
|
|
83
150
|
Send text input to the terminal.
|
|
84
151
|
|
|
@@ -123,30 +190,253 @@ Get the terminal buffer as plain text.
|
|
|
123
190
|
```
|
|
124
191
|
|
|
125
192
|
### `takeScreenshot`
|
|
126
|
-
Capture the terminal state
|
|
193
|
+
Capture the terminal state. Supports three output formats:
|
|
194
|
+
|
|
195
|
+
| Format | Description |
|
|
196
|
+
|--------|-------------|
|
|
197
|
+
| `text` (default) | JSON with plain text content, cursor position, and dimensions |
|
|
198
|
+
| `ansi` | JSON with ANSI color escape codes preserved in the content field |
|
|
199
|
+
| `png` | Color screenshot as a PNG image (requires `@resvg/resvg-js`) |
|
|
127
200
|
|
|
128
201
|
```json
|
|
129
202
|
{
|
|
130
203
|
"name": "takeScreenshot",
|
|
131
|
-
"arguments": {}
|
|
204
|
+
"arguments": { "format": "text" }
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The `ansi` format reconstructs SGR escape sequences from the terminal's cell buffer, preserving 16-color, 256-color, and 24-bit truecolor attributes along with bold, dim, italic, and underline styles.
|
|
209
|
+
|
|
210
|
+
The `png` format returns an MCP `image` content block with base64-encoded PNG data, rendered with the One Dark color theme and macOS-style window chrome.
|
|
211
|
+
|
|
212
|
+
### `startRecording`
|
|
213
|
+
Start recording terminal output to an asciicast v2 file.
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"name": "startRecording",
|
|
218
|
+
"arguments": {
|
|
219
|
+
"mode": "always",
|
|
220
|
+
"idleTimeLimit": 2,
|
|
221
|
+
"maxDuration": 3600
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Options:
|
|
227
|
+
- `mode`: `always` (save all) or `on-failure` (save only on non-zero exit)
|
|
228
|
+
- `outputDir`: Custom output directory
|
|
229
|
+
- `idleTimeLimit`: Max seconds between events (caps pauses in playback)
|
|
230
|
+
- `maxDuration`: Auto-stop after N seconds
|
|
231
|
+
- `inactivityTimeout`: Auto-stop after N seconds of no output
|
|
232
|
+
|
|
233
|
+
### `stopRecording`
|
|
234
|
+
Stop a recording and finalize the asciicast file.
|
|
235
|
+
|
|
236
|
+
```json
|
|
237
|
+
{
|
|
238
|
+
"name": "stopRecording",
|
|
239
|
+
"arguments": {
|
|
240
|
+
"recordingId": "abc123"
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### `createSession`
|
|
246
|
+
Create a new terminal session and return its metadata. Use the returned `sessionId` to target this session in subsequent tool calls.
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"name": "createSession",
|
|
251
|
+
"arguments": {
|
|
252
|
+
"shell": "/bin/zsh",
|
|
253
|
+
"cols": 100,
|
|
254
|
+
"rows": 30
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
All arguments are optional. Returns:
|
|
260
|
+
|
|
261
|
+
```json
|
|
262
|
+
{
|
|
263
|
+
"sessionId": "3029d",
|
|
264
|
+
"shell": "/bin/zsh",
|
|
265
|
+
"cols": 100,
|
|
266
|
+
"rows": 30,
|
|
267
|
+
"createdAt": "2026-04-25T12:58:01.072Z",
|
|
268
|
+
"lastActivityAt": "2026-04-25T12:58:01.072Z",
|
|
269
|
+
"isDefault": false
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### `listSessions`
|
|
274
|
+
List all active sessions including the default. Reports configured limits.
|
|
275
|
+
|
|
276
|
+
```json
|
|
277
|
+
{ "name": "listSessions", "arguments": {} }
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### `destroySession`
|
|
281
|
+
Destroy a session by ID. The default session cannot be destroyed.
|
|
282
|
+
|
|
283
|
+
```json
|
|
284
|
+
{
|
|
285
|
+
"name": "destroySession",
|
|
286
|
+
"arguments": { "sessionId": "3029d" }
|
|
132
287
|
}
|
|
133
288
|
```
|
|
134
289
|
|
|
290
|
+
## Multi-Session
|
|
291
|
+
|
|
292
|
+
By default, every tool call without a `sessionId` targets a single auto-created **default session** — the same behavior the project has always had. Pass `sessionId` to drive multiple isolated PTYs from one process.
|
|
293
|
+
|
|
294
|
+
- The default session is created on first use and cannot be destroyed.
|
|
295
|
+
- Additional sessions are created by `createSession` and tracked until they're destroyed or idle-evicted (`--session-idle-timeout`, default 600s).
|
|
296
|
+
- Concurrent sessions are capped at `--max-sessions` (default 5).
|
|
297
|
+
- An active recording captures output from all sessions in the process.
|
|
298
|
+
|
|
299
|
+
Typical use case: an AI agent driving a long-running build in one session while running diagnostics in another, without command interleaving.
|
|
300
|
+
|
|
301
|
+
## Sandbox Mode
|
|
302
|
+
|
|
303
|
+
Run the terminal with restricted filesystem and network access:
|
|
304
|
+
|
|
305
|
+
```bash
|
|
306
|
+
# Interactive permission configuration
|
|
307
|
+
terminal-mcp --sandbox
|
|
308
|
+
|
|
309
|
+
# With a config file
|
|
310
|
+
terminal-mcp --sandbox --sandbox-config ~/.terminal-mcp-sandbox.json
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
The interactive mode shows a TUI dialog to configure permissions:
|
|
314
|
+
|
|
315
|
+
<p align="center">
|
|
316
|
+
<img src="sandbox-permissions.png" alt="Sandbox Permissions Dialog" width="400">
|
|
317
|
+
</p>
|
|
318
|
+
- **Read/Write**: Full access (current directory, /tmp, caches)
|
|
319
|
+
- **Read-Only**: Can read but not modify (home directory)
|
|
320
|
+
- **Blocked**: No access (SSH keys, cloud credentials, auth tokens)
|
|
321
|
+
|
|
322
|
+
Example config file:
|
|
323
|
+
|
|
324
|
+
```json
|
|
325
|
+
{
|
|
326
|
+
"filesystem": {
|
|
327
|
+
"readWrite": [".", "/tmp", "~/.cache"],
|
|
328
|
+
"readOnly": ["~"],
|
|
329
|
+
"blocked": ["~/.ssh", "~/.aws", "~/.gnupg"]
|
|
330
|
+
},
|
|
331
|
+
"network": {
|
|
332
|
+
"mode": "all"
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
Platform support:
|
|
338
|
+
- **macOS**: Full support via sandbox-exec (Seatbelt)
|
|
339
|
+
- **Linux**: Full support via bubblewrap (requires `bwrap` installed)
|
|
340
|
+
- **Windows**: Graceful fallback (runs without sandbox)
|
|
341
|
+
|
|
342
|
+
See [Sandbox Documentation](./docs/sandbox.md) for detailed configuration options.
|
|
343
|
+
|
|
344
|
+
## Recording
|
|
345
|
+
|
|
346
|
+
Terminal MCP can record sessions to [asciicast v2](https://docs.asciinema.org/manual/asciicast/v2/) format, compatible with [asciinema](https://asciinema.org/) for playback.
|
|
347
|
+
|
|
348
|
+
### Quick Start
|
|
349
|
+
|
|
350
|
+
```bash
|
|
351
|
+
# Start with recording enabled
|
|
352
|
+
terminal-mcp --record
|
|
353
|
+
|
|
354
|
+
# Run your commands, then exit
|
|
355
|
+
exit
|
|
356
|
+
|
|
357
|
+
# Output shows the saved file path:
|
|
358
|
+
# Recordings saved:
|
|
359
|
+
# ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
|
|
360
|
+
#
|
|
361
|
+
# Play with: asciinema play <file>
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
### Playback
|
|
365
|
+
|
|
366
|
+
Install asciinema to play back recordings:
|
|
367
|
+
|
|
368
|
+
```bash
|
|
369
|
+
# macOS
|
|
370
|
+
brew install asciinema
|
|
371
|
+
|
|
372
|
+
# Linux/pip
|
|
373
|
+
pip install asciinema
|
|
374
|
+
|
|
375
|
+
# Play a recording
|
|
376
|
+
asciinema play ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
|
|
377
|
+
|
|
378
|
+
# Play at 2x speed
|
|
379
|
+
asciinema play -s 2 recording.cast
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
### Recording Modes
|
|
383
|
+
|
|
384
|
+
- **`always`** (default): Save every recording
|
|
385
|
+
- **`on-failure`**: Only save if the session exits with a non-zero code (useful for debugging failed CI runs)
|
|
386
|
+
|
|
387
|
+
```bash
|
|
388
|
+
# Only save recordings when something fails
|
|
389
|
+
terminal-mcp --record=on-failure
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
### MCP Tool Recording
|
|
393
|
+
|
|
394
|
+
AI assistants can also control recording programmatically via MCP tools:
|
|
395
|
+
|
|
396
|
+
1. Call `startRecording` to begin capturing
|
|
397
|
+
2. Perform terminal operations
|
|
398
|
+
3. Call `stopRecording` to finalize and save
|
|
399
|
+
|
|
400
|
+
This enables AI-driven workflows like "record this debugging session" or "capture this demo".
|
|
401
|
+
|
|
135
402
|
## Architecture
|
|
136
403
|
|
|
404
|
+
Terminal MCP has three operating modes:
|
|
405
|
+
|
|
406
|
+
| Mode | Flag | Stdin | Description |
|
|
407
|
+
|------|------|-------|-------------|
|
|
408
|
+
| **Interactive** | *(default)* | TTY | User gets a shell; AI connects via Unix socket |
|
|
409
|
+
| **Client** | *(default)* | non-TTY | Connects to an interactive session's socket, serves MCP over stdio |
|
|
410
|
+
| **Headless** | `--headless` | any | Self-contained: embedded PTY + MCP server over stdio |
|
|
411
|
+
|
|
412
|
+
### Headless mode (recommended for MCP configs)
|
|
413
|
+
|
|
137
414
|
```
|
|
138
415
|
MCP Client (Claude Code, etc.)
|
|
139
416
|
│ STDIO (JSON-RPC)
|
|
140
417
|
▼
|
|
141
|
-
|
|
418
|
+
terminal-mcp --headless
|
|
142
419
|
├── MCP SDK (@modelcontextprotocol/sdk)
|
|
143
420
|
├── Terminal Emulator (@xterm/headless)
|
|
144
|
-
└── PTY
|
|
421
|
+
└── Embedded PTY (node-pty)
|
|
145
422
|
│
|
|
146
423
|
▼
|
|
147
424
|
Shell Process (bash, zsh, etc.)
|
|
148
425
|
```
|
|
149
426
|
|
|
427
|
+
### Interactive + Client mode (two-process)
|
|
428
|
+
|
|
429
|
+
```
|
|
430
|
+
terminal-mcp (interactive, in your terminal)
|
|
431
|
+
├── User shell (stdin/stdout)
|
|
432
|
+
└── Unix socket server (/tmp/terminal-mcp.sock)
|
|
433
|
+
▲
|
|
434
|
+
│ JSON-RPC over socket
|
|
435
|
+
▼
|
|
436
|
+
terminal-mcp (client, spawned by MCP client)
|
|
437
|
+
└── MCP server (stdio transport)
|
|
438
|
+
```
|
|
439
|
+
|
|
150
440
|
## Example Session
|
|
151
441
|
|
|
152
442
|
```bash
|
|
@@ -174,7 +464,9 @@ See the [docs](./docs/) folder for detailed documentation:
|
|
|
174
464
|
- [Overview](./docs/index.md)
|
|
175
465
|
- [Installation](./docs/installation.md)
|
|
176
466
|
- [Tools Reference](./docs/tools.md)
|
|
467
|
+
- [Recording](./docs/recording.md)
|
|
177
468
|
- [Configuration](./docs/configuration.md)
|
|
469
|
+
- [Sandbox Mode](./docs/sandbox.md)
|
|
178
470
|
- [Examples](./docs/examples.md)
|
|
179
471
|
- [Architecture](./docs/architecture.md)
|
|
180
472
|
|
package/dist/client.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAsBA;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoH1E"}
|
package/dist/client.js
CHANGED
|
@@ -3,6 +3,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
|
|
3
3
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
4
4
|
import { VERSION } from "./utils/version.js";
|
|
5
5
|
import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
|
|
6
|
+
import { toolDefinitions } from "./tools/definitions.js";
|
|
6
7
|
/**
|
|
7
8
|
* MCP Client Mode - connects to existing terminal socket and serves MCP over stdio
|
|
8
9
|
*/
|
|
@@ -72,69 +73,9 @@ export async function startMcpClientMode(socketPath) {
|
|
|
72
73
|
});
|
|
73
74
|
});
|
|
74
75
|
}
|
|
75
|
-
// Define tools that proxy to the interactive terminal
|
|
76
|
-
const tools = [
|
|
77
|
-
{
|
|
78
|
-
name: "type",
|
|
79
|
-
description: "Type text into the terminal",
|
|
80
|
-
inputSchema: {
|
|
81
|
-
type: "object",
|
|
82
|
-
properties: {
|
|
83
|
-
text: {
|
|
84
|
-
type: "string",
|
|
85
|
-
description: "The text to type",
|
|
86
|
-
},
|
|
87
|
-
},
|
|
88
|
-
required: ["text"],
|
|
89
|
-
},
|
|
90
|
-
},
|
|
91
|
-
{
|
|
92
|
-
name: "sendKey",
|
|
93
|
-
description: "Send a special key to the terminal (e.g., enter, tab, ctrl+c)",
|
|
94
|
-
inputSchema: {
|
|
95
|
-
type: "object",
|
|
96
|
-
properties: {
|
|
97
|
-
key: {
|
|
98
|
-
type: "string",
|
|
99
|
-
description: "The key to send (e.g., enter, tab, escape, up, down, left, right, ctrl+c, ctrl+d)",
|
|
100
|
-
},
|
|
101
|
-
},
|
|
102
|
-
required: ["key"],
|
|
103
|
-
},
|
|
104
|
-
},
|
|
105
|
-
{
|
|
106
|
-
name: "getContent",
|
|
107
|
-
description: "Get the current content of the terminal buffer",
|
|
108
|
-
inputSchema: {
|
|
109
|
-
type: "object",
|
|
110
|
-
properties: {
|
|
111
|
-
visibleOnly: {
|
|
112
|
-
type: "boolean",
|
|
113
|
-
description: "If true, only return visible content (default: false)",
|
|
114
|
-
},
|
|
115
|
-
},
|
|
116
|
-
},
|
|
117
|
-
},
|
|
118
|
-
{
|
|
119
|
-
name: "takeScreenshot",
|
|
120
|
-
description: "Take a screenshot of the terminal showing current screen and cursor position",
|
|
121
|
-
inputSchema: {
|
|
122
|
-
type: "object",
|
|
123
|
-
properties: {},
|
|
124
|
-
},
|
|
125
|
-
},
|
|
126
|
-
{
|
|
127
|
-
name: "clear",
|
|
128
|
-
description: "Clear the terminal screen",
|
|
129
|
-
inputSchema: {
|
|
130
|
-
type: "object",
|
|
131
|
-
properties: {},
|
|
132
|
-
},
|
|
133
|
-
},
|
|
134
|
-
];
|
|
135
76
|
// Register list tools handler
|
|
136
77
|
server.setRequestHandler(ListToolsRequestSchema, async () => ({
|
|
137
|
-
tools,
|
|
78
|
+
tools: toolDefinitions,
|
|
138
79
|
}));
|
|
139
80
|
// Register call tool handler - proxy to socket
|
|
140
81
|
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
package/dist/client.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
|