Labsco
takafu logo

REPL MCP Server

★ 3

from takafu

A universal REPL session manager supporting Python, Node.js, Ruby, and more, with session management and LLM-assisted recovery.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#scraping#monitoring#translation

repl-mcp

REPL MCP

A simple MCP server for managing REPL sessions. Provides basic tools to create and execute commands in various REPLs and shells, with an integrated Web UI for browser-based session monitoring.

Motivation

Working with remote REPLs (like Rails console on production servers) often forces you to cram complex operations into single commands since losing connection means losing your session state. This tool enables persistent REPL sessions that survive individual command executions, allowing you to work naturally with interactive environments through AI agents. The integrated Web UI provides browser-based monitoring for session observation.

Features

Core Features

  • Multiple REPL Support: Python, IPython, Node.js, Ruby (pry, irb), bash, zsh
  • Session Management: Create, execute commands, and destroy REPL sessions
  • Web UI Integration: Browser-based terminal monitoring for session observation
  • Customizable Setup: Configure setup commands and environment variables
  • Cross-Platform: Works on Windows, macOS, and Linux

Additional Features

  • Timeout Recovery: LLM assistance when commands timeout
  • Session Learning: Remembers prompt patterns within sessions

Browser-Based Session Monitoring

  • Session URLs: http://localhost:8023/session/SESSION_ID - Monitor sessions in browser
  • Dynamic Ports: Auto-selects available ports starting from 8023
  • Cross-Platform: Works on any device with modern browser
  • Real-time: Live terminal output via WebSocket connection

Available Tools

create_session

Create a new REPL session with preset or custom configuration. Use displayName to set a custom name that appears in the browser tab title. Returns a webUrl that can be opened in a browser to monitor the session via Web UI.

Parameters:

  • presetConfig (optional): Name of predefined configuration
  • displayName (optional): Custom display name for the session (shown in browser tab)
  • customConfig (optional): Custom configuration object

Example with preset:

{
  "presetConfig": "pry",
  "displayName": "My Ruby Session"
}

Example with custom configuration:

{
  "displayName": "Custom Python Session",
  "customConfig": {
    "type": "python",
    "shell": "bash",
    "commands": ["python3"],
    "timeout": 10000
  }
}

Response:

{
  "success": true,
  "sessionId": "abc123",
  "config": "Ruby Pry REPL",
  "webUrl": "http://localhost:8023/session/abc123"
}

Response includes:

  • sessionId: Unique session identifier (6-character format)
  • webUrl: Browser URL for session monitoring
  • config: Configuration name used

send_input_to_session

Send input to a REPL session.

Parameters:

  • sessionId: The session ID
  • input: Input text to send to the session
  • options (optional): Input options object
    • wait_for_prompt (default: false): Wait for prompt to return
    • timeout (default: 30000): Timeout in milliseconds
    • add_newline (default: true): Add newline to input

Example:

{
  "sessionId": "abc123",
  "input": "puts 'Hello, World!'",
  "options": {
    "wait_for_prompt": true
  }
}

list_repl_sessions

List all active REPL sessions. Each session includes a webUrl for browser access.

Response includes:

  • sessions: Array of session objects with webUrl for each
  • Each session includes: id, name, type, status, webUrl, etc.

get_session_details

Get detailed information about a specific session. Includes webUrl for browser access.

Parameters:

  • sessionId: The session ID

Response includes:

  • session: Detailed session information
  • webUrl: Browser URL for session monitoring

destroy_repl_session

Destroy an existing REPL session.

Parameters:

  • sessionId: The session ID

list_repl_configurations

List all available predefined REPL configurations.

send_signal_to_session

Send a signal (like Ctrl+C, Ctrl+Z) to interrupt or control a REPL session process.

Parameters:

  • sessionId: The session ID
  • signal: Signal to send (SIGINT, SIGTSTP, SIGQUIT)

Example:

{
  "sessionId": "abc123",
  "signal": "SIGINT"
}

Note on Windows: On Windows, only SIGINT is practically effective. It is sent as a Ctrl+C event and can be used to interrupt running commands or terminate compatible processes like Node.js REPLs. SIGTSTP and SIGQUIT have no effect.

set_session_ready

Mark a session as ready with a specific prompt pattern. Used during session recovery.

Parameters:

  • sessionId: The session ID
  • pattern: Prompt pattern (regex or literal string)

Example:

{
  "sessionId": "abc123",
  "pattern": "❯ "
}

wait_for_session

Wait additional time for a session to become ready.

Parameters:

  • sessionId: The session ID
  • seconds: Number of seconds to wait

Example:

{
  "sessionId": "abc123",
  "seconds": 5
}

mark_session_failed

Mark a session as failed with a reason.

Parameters:

  • sessionId: The session ID
  • reason: Reason for failure

Example:

{
  "sessionId": "abc123",
  "reason": "Process crashed"
}

Session Recovery

When sessions timeout or become unresponsive, you can use recovery tools:

  • send_signal_to_session - Send Ctrl+C, Ctrl+Z, or other signals to interrupt processes
  • set_session_ready - Mark session ready when you detect a working prompt
  • wait_for_session - Wait longer for slow commands to complete
  • mark_session_failed - Mark session as failed when recovery isn't possible

Prompt patterns learned during recovery are remembered for the session duration.

Session Management

Each session maintains:

  • Unique session ID: 6-character format for easy identification and management
  • Configuration details: REPL type, shell, setup commands, etc.
  • Current status: initializing, ready, executing, error, terminated
  • Command history: Record of executed commands
  • Last output and errors: Most recent execution results
  • Creation and activity timestamps: Session lifecycle tracking
  • Learned prompt patterns: Custom patterns discovered through LLM assistance
  • Web UI access: Browser URL for session monitoring

Session Lifecycle

  1. Initialization: Session created with specified configuration
  2. Ready: Session prepared for command execution
  3. Executing: Command being processed
  4. Learning: LLM assistance for prompt detection (when needed)
  5. Optimized: Learned patterns enable fast execution

Error Handling

The server provides comprehensive error handling with intelligent recovery:

Traditional Error Handling

  • Session creation failures: Clear error messages with diagnostic information
  • Command execution timeouts: Graceful timeout handling with retry options
  • REPL crashes and recovery: Automatic detection and session state management
  • Invalid command detection: Input validation and error reporting

LLM-Enhanced Recovery

  • Prompt detection failures: Automatic LLM consultation for unknown prompts
  • Adaptive timeout handling: Smart waiting based on command complexity
  • Custom environment support: Dynamic learning for non-standard shells
  • Contextual error analysis: Rich error information for troubleshooting

Error Response Format

Standard Error:

{
  "success": false,
  "error": "Session not found",
  "executionTime": 0
}

LLM-Assisted Error:

{
  "success": false,
  "error": "Timeout - LLM guidance needed",
  "question": "Session timed out. What should I do?",
  "questionType": "timeout_analysis",
  "canContinue": true,
  "context": { "sessionId": "...", "rawOutput": "..." }
}

Development

Building

npm run build

Development Mode

npm run dev

This will start TypeScript in watch mode for development.

Platform-Specific Notes

Windows

  • Uses cmd or powershell as default shell
  • Some REPL features may behave differently
  • Signal Handling: Only SIGINT is effectively supported. It is translated to a Ctrl+C event, which can stop most command-line tools and exit REPLs like Node.js. SIGTSTP (Ctrl+Z) and SIGQUIT (Ctrl+\) are not supported by the Windows console and will have no effect.

macOS/Linux

  • Uses bash or zsh as default shell
  • Full feature support