{"id":29140892,"url":"https://github.com/takafu/repl-mcp","last_synced_at":"2025-06-30T18:02:15.261Z","repository":{"id":301731177,"uuid":"1002475375","full_name":"takafu/repl-mcp","owner":"takafu","description":"A simple MCP server for managing REPL sessions.","archived":false,"fork":false,"pushed_at":"2025-06-28T13:41:15.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-28T13:48:13.383Z","etag":null,"topics":["automation","bash","cli","cross-platform","irb","mcp-server","nodejs","pry","python","repl","ruby","session-management","shell","terminal","typescript","zsh"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/takafu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-15T14:58:33.000Z","updated_at":"2025-06-28T13:47:24.000Z","dependencies_parsed_at":"2025-06-28T13:48:16.908Z","dependency_job_id":"45a369c0-58f4-48be-a4d6-13374f9eb6f7","html_url":"https://github.com/takafu/repl-mcp","commit_stats":null,"previous_names":["takafu/repl-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/takafu/repl-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takafu%2Frepl-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takafu%2Frepl-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takafu%2Frepl-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takafu%2Frepl-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/takafu","download_url":"https://codeload.github.com/takafu/repl-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takafu%2Frepl-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262807330,"owners_count":23367425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","bash","cli","cross-platform","irb","mcp-server","nodejs","pry","python","repl","ruby","session-management","shell","terminal","typescript","zsh"],"created_at":"2025-06-30T18:01:16.468Z","updated_at":"2025-06-30T18:02:15.234Z","avatar_url":"https://github.com/takafu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# repl-mcp\n\nA simple MCP server for managing REPL sessions. Provides basic tools to create and execute commands in various REPLs and shells.\n\n## Motivation\n\nWorking 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.\n\n## Features\n\n### Core Features\n\n- **Multiple REPL Support**: Python, IPython, Node.js, Ruby (pry, irb), bash, zsh\n- **Session Management**: Create, execute commands, and destroy REPL sessions\n- **Customizable Setup**: Configure setup commands and environment variables\n- **Cross-Platform**: Works on Windows, macOS, and Linux\n\n### Additional Features\n\n- **Timeout Recovery**: LLM assistance when commands timeout\n- **Session Learning**: Remembers prompt patterns within sessions\n\n## Installation\n\n[![npm version](https://img.shields.io/npm/v/repl-mcp)](https://www.npmjs.com/package/repl-mcp)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=repl-mcp\u0026config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22repl-mcp%40latest%22%5D%7D)\n\n### VS Code\n\nClick the button above or add to your `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"repl-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"repl-mcp@latest\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add repl-mcp npx repl-mcp@latest\n```\n\n### Manual MCP Configuration\n\nAdd to your MCP settings file:\n\n```json\n{\n  \"mcpServers\": {\n    \"repl-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"repl-mcp@latest\"]\n    }\n  }\n}\n```\n\n### From Source\n\n1. Clone this repository\n2. Install dependencies: `npm install`\n3. Build the project: `npm run build`\n4. Add to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"repl-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/repl-mcp/build/index.js\"]\n    }\n  }\n}\n```\n\n## Available Tools\n\n### `create_repl_session`\n\nCreate a new REPL session with predefined or custom configuration.\n\n**Parameters:**\n\n- `configName` (optional): Name of predefined configuration\n- `customConfig` (optional): Custom configuration object\n\n**Example:**\n\n```json\n{\n  \"configName\": \"pry\"\n}\n```\n\nOr with custom config:\n\n```json\n{\n  \"customConfig\": {\n    \"name\": \"Custom Ruby Session\",\n    \"type\": \"pry\",\n    \"shell\": \"bash\",\n    \"setupCommands\": [\"cd /path/to/project\", \"bundle install\"],\n    \"replCommand\": \"bundle exec pry\"\n  }\n}\n```\n\n### `execute_repl_command`\n\nExecute a command in an existing REPL session.\n\n**Parameters:**\n\n- `sessionId`: The session ID\n- `command`: Command to execute\n- `timeout` (optional): Timeout in milliseconds (default: 30000)\n\n**Example:**\n\n```json\n{\n  \"sessionId\": \"session_1234567890_abc123\",\n  \"command\": \"puts 'Hello, World!'\"\n}\n```\n\n**Response with LLM Question:**\n\nWhen timeout occurs, the response may include an LLM question:\n\n```json\n{\n  \"success\": false,\n  \"question\": \"Session timed out. Raw output: '❯ '. What should I do?\",\n  \"questionType\": \"timeout_analysis\",\n  \"canContinue\": true\n}\n```\n\n**How to respond:** Use `answer_session_question` with one of these formats:\n- `READY:❯` - The prompt \"❯\" is ready for commands\n- `SEND:\\n` - Send Enter key (use `\\x03` for Ctrl+C)\n- `WAIT:5` - Wait 5 more seconds for completion\n- `FAILED:reason` - Mark the session as failed\n\n### `list_repl_sessions`\n\nList all active REPL sessions.\n\n### `get_session_details`\n\nGet detailed information about a specific session.\n\n**Parameters:**\n\n- `sessionId`: The session ID\n\n### `destroy_repl_session`\n\nDestroy an existing REPL session.\n\n**Parameters:**\n\n- `sessionId`: The session ID\n\n### `list_repl_configurations`\n\nList all available predefined REPL configurations.\n\n### `answer_session_question`\n\nAnswer a question from session creation or command execution during LLM-assisted recovery.\n\n**Parameters:**\n\n- `sessionId`: The session ID\n- `answer`: LLM guidance response in one of these formats:\n  - `READY:pattern` - Specify the detected prompt pattern (e.g., `READY:❯` means \"❯\" is the prompt)\n  - `SEND:command` - Send specific input (e.g., `SEND:\\n` for Enter, `SEND:\\x03` for Ctrl+C)\n  - `WAIT:seconds` - Wait longer for completion (e.g., `WAIT:10`)\n  - `FAILED:reason` - Mark session as failed with explanation\n\n**Example:**\n\n```json\n{\n  \"sessionId\": \"session_1234567890_abc123\",\n  \"answer\": \"READY:∙\"\n}\n```\n\n## Predefined Configurations\n\n*Note: Each REPL tool must be installed and available in your PATH.*\n\n### REPL Configurations\n\n- **pry**: Ruby Pry REPL with advanced debugging features\n- **irb**: Ruby IRB REPL with standard functionality\n- **ipython**: Enhanced Python REPL with rich features\n- **node**: Node.js JavaScript REPL\n- **python**: Standard Python REPL\n\n### Shell Configurations\n\n- **bash**: Bash shell environment\n- **zsh**: Zsh shell environment (with Oh My Zsh support)\n\n### Advanced Configurations\n\n- **rails_console**: Rails console with bundle exec\n- **rails_console_production**: Production Rails console\n\n## LLM-Assisted Recovery\n\n### How It Works\n\nWhen command execution times out, the server can request LLM assistance:\n\n1. **Captures Raw Output**: Collects terminal output for analysis\n2. **LLM Analysis**: LLM examines the output and provides guidance\n3. **Response Types**: Four response patterns for different situations:\n   - `READY:pattern` - Prompt detected, specify the pattern\n   - `SEND:command` - Send a specific command (e.g., `\\n` for Enter)\n   - `WAIT:seconds` - Wait longer for command completion\n   - `FAILED:reason` - Mark as failure with explanation\n\n### Session Learning\n\nPatterns identified by LLM are remembered for the session duration to improve subsequent command performance.\n\n## Usage Examples\n\n### Basic REPL Usage\n\n#### Create a Python Session\n\n```json\n{\n  \"tool\": \"create_repl_session\",\n  \"arguments\": {\n    \"configName\": \"python\"\n  }\n}\n```\n\n#### Execute Ruby Code\n\n```json\n{\n  \"tool\": \"execute_repl_command\",\n  \"arguments\": {\n    \"sessionId\": \"session_1234567890_abc123\",\n    \"command\": \"User.count\"\n  }\n}\n```\n\n### LLM-Assisted Recovery Example\n\nWhen a command times out, you can use LLM assistance:\n\n```json\n{\n  \"tool\": \"answer_session_question\",\n  \"arguments\": {\n    \"sessionId\": \"session_1234567890_abc123\",\n    \"answer\": \"READY:❯\"\n  }\n}\n```\n\nThe session will remember this pattern for future commands.\n\n## Session Management\n\nEach session maintains:\n\n- **Unique session ID**: For session identification and management\n- **Configuration details**: REPL type, shell, setup commands, etc.\n- **Current status**: initializing, ready, executing, error, terminated\n- **Command history**: Record of executed commands\n- **Last output and errors**: Most recent execution results\n- **Creation and activity timestamps**: Session lifecycle tracking\n- **Learned prompt patterns**: Custom patterns discovered through LLM assistance\n\n### Session Lifecycle\n\n1. **Initialization**: Session created with specified configuration\n2. **Ready**: Session prepared for command execution\n3. **Executing**: Command being processed\n4. **Learning**: LLM assistance for prompt detection (when needed)\n5. **Optimized**: Learned patterns enable fast execution\n\n## Error Handling\n\nThe server provides comprehensive error handling with intelligent recovery:\n\n### Traditional Error Handling\n\n- **Session creation failures**: Clear error messages with diagnostic information\n- **Command execution timeouts**: Graceful timeout handling with retry options\n- **REPL crashes and recovery**: Automatic detection and session state management\n- **Invalid command detection**: Input validation and error reporting\n\n### LLM-Enhanced Recovery\n\n- **Prompt detection failures**: Automatic LLM consultation for unknown prompts\n- **Adaptive timeout handling**: Smart waiting based on command complexity\n- **Custom environment support**: Dynamic learning for non-standard shells\n- **Contextual error analysis**: Rich error information for troubleshooting\n\n### Error Response Format\n\n**Standard Error:**\n\n```json\n{\n  \"success\": false,\n  \"error\": \"Session not found\",\n  \"executionTime\": 0\n}\n```\n\n**LLM-Assisted Error:**\n\n```json\n{\n  \"success\": false,\n  \"error\": \"Timeout - LLM guidance needed\",\n  \"question\": \"Session timed out. What should I do?\",\n  \"questionType\": \"timeout_analysis\",\n  \"canContinue\": true,\n  \"context\": { \"sessionId\": \"...\", \"rawOutput\": \"...\" }\n}\n```\n\n## Development\n\n### Building\n\n```bash\nnpm run build\n```\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\nThis will start TypeScript in watch mode for development.\n\n## Platform-Specific Notes\n\n### Windows\n\n- Uses `cmd` or `powershell` as default shell\n- Some REPL features may behave differently\n\n### macOS/Linux\n\n- Uses `bash` or `zsh` as default shell\n- Full feature support\n\n## Troubleshooting\n\n### Common Issues\n\n#### Traditional Issues\n\n1. **Session creation fails**: Check that the required REPL command is installed and accessible\n2. **Commands timeout consistently**: Increase timeout value or check REPL responsiveness\n3. **REPL not found**: Ensure the REPL executable is in your PATH\n\n#### LLM-Assisted Issues\n\n1. **LLM guidance not working**: Ensure you're using the `answer_session_question` tool with proper response format\n2. **Pattern not learned**: Check that the LLM response follows the `READY:pattern` format exactly\n3. **Timeout questions ignored**: Use `answer_session_question` tool to provide LLM guidance\n\n### Best Practices\n\n#### For Complex Shells\n\n- **Custom prompts**: Use `READY:pattern` to teach the system your prompt when timeouts occur\n- **Nested environments**: Use `WAIT:seconds` for environments that need time to settle\n\n#### Performance Tips\n\n- **Session learning**: Patterns learned during LLM assistance improve subsequent commands\n- **Multiple sessions**: Each session learns independently\n\n### Debug Information\n\nEnable detailed debugging by checking the `debugLogs` field in responses:\n\n```json\n{\n  \"success\": true,\n  \"output\": \"...\",\n  \"debugLogs\": [\n    \"2025-06-22T15:31:15.504Z: [DEBUG session_xxx] Prompt detected: true\",\n    \"2025-06-22T15:31:15.505Z: [DEBUG session_xxx] Learned new prompt pattern: '∙'\"\n  ]\n}\n```\n\n## Contributing\n\nContributions are welcome! The LLM-assisted features make it easy to add support for new shell environments and REPL types. When contributing:\n\n1. **Test with different shells**: Ensure compatibility across bash, zsh, and other environments\n2. **Consider prompt variations**: Test with custom prompts and themes\n3. **Update configurations**: Add new predefined configs for common setups\n4. **Document LLM patterns**: Share successful prompt patterns for others\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftakafu%2Frepl-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftakafu%2Frepl-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftakafu%2Frepl-mcp/lists"}