{"_id":"@blue-hope/tui-mcp","_rev":"8-6bbc6497762a60a95416f735a8616b01","name":"@blue-hope/tui-mcp","dist-tags":{"latest":"0.0.8"},"versions":{"0.0.1":{"name":"@blue-hope/tui-mcp","version":"0.0.1","keywords":["mcp","tui","pty","terminal"],"license":"MIT","_id":"@blue-hope/tui-mcp@0.0.1","maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"bin":{"tui-mcp":"dist/index.js"},"dist":{"shasum":"b36313ecd9501202e1df27ffb20ce8569ab19347","tarball":"https://registry.npmjs.org/@blue-hope/tui-mcp/-/tui-mcp-0.0.1.tgz","fileCount":43,"integrity":"sha512-orbJ0uA8YF1HIvAMZtDDPn5cInoUaVc1RavsxW/orR8lbKZDma94qe7vsIauzMpjytKa6dQwPWCnZYF/nUTs+w==","signatures":[{"sig":"MEUCIQDh9s1lZkg5XX9Di9xftjgVyc2ztlB5VkCplQDsRtNsVQIgOdOuyS8U/HNQqRXyYAjg49qEVd4fmtnIYmECs//VXq4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":103860},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"e83cb00000b3dfa55a9e70dcad05d01eec3a2920","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","prepare":"npm run build","test:watch":"vitest"},"_npmUser":{"name":"blue-hope","email":"ms7045436@gmail.com"},"_npmVersion":"10.9.2","description":"MCP server for controlling TUI applications in sandboxed PTY sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","nanoid":"^5.0.9","node-pty":"^1.0.0","@xterm/headless":"^5.5.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tui-mcp_0.0.1_1775806788646_0.7277420029311987","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@blue-hope/tui-mcp","version":"0.0.2","keywords":["mcp","tui","pty","terminal"],"license":"MIT","_id":"@blue-hope/tui-mcp@0.0.2","maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"bin":{"tui-mcp":"dist/index.js"},"dist":{"shasum":"c4c2604502f612d727492f4e8c0701cb37b92c86","tarball":"https://registry.npmjs.org/@blue-hope/tui-mcp/-/tui-mcp-0.0.2.tgz","fileCount":44,"integrity":"sha512-EHzWqZ0aP7dKitG4xnAWjfLttIQMuBcGylOmNMfskpN703vfBkDRNKWxdJLXRahJQ6/OjsnTPF01tNkqc4BvpQ==","signatures":[{"sig":"MEUCIHtxSz+xOZIznRETn3HxGhARY4AdTw2GZEMi9qVYeTUAAiEAm3fD3Wg4UstUvLMGvWaKnnIEkXZ8CrZ7xaaPXWeLY/o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":108027},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"d78a2b68c7f8ed6447f69ab8cb4861eea14c8969","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","prepare":"npm run build","test:watch":"vitest"},"_npmUser":{"name":"blue-hope","email":"ms7045436@gmail.com"},"_npmVersion":"10.9.2","description":"MCP server for controlling TUI applications in sandboxed PTY sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","nanoid":"^5.0.9","node-pty":"^1.0.0","@xterm/headless":"^5.5.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tui-mcp_0.0.2_1775808146899_0.9391489756277243","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@blue-hope/tui-mcp","version":"0.0.3","keywords":["mcp","tui","pty","terminal"],"license":"MIT","_id":"@blue-hope/tui-mcp@0.0.3","maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"bin":{"tui-mcp":"dist/index.js"},"dist":{"shasum":"8b7cb3b92ebe1e552ee6f48497cfcc4e59a11110","tarball":"https://registry.npmjs.org/@blue-hope/tui-mcp/-/tui-mcp-0.0.3.tgz","fileCount":44,"integrity":"sha512-pechDTWWZIZXoBBSfBFTM0XJOuDf4Az90hoPeo3HkEDHpZ180/HyMWba0hzH/UMyRlgaKJba8aIie9xMK2gnNA==","signatures":[{"sig":"MEYCIQDaykWyCRBs5vVBJF5ChiQp52Nm34GogWxOrKBrqu9QIgIhAKsSo0eDzEOMP86bSPqeWeTnoe8CTw37gGmDzfHi12bt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":108296},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"c14af8128af37207e0b56e1d6327b4531b8aecb5","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","prepare":"npm run build","test:watch":"vitest","postinstall":"node -e \"const fs=require('fs'),p=require('path'),d=p.join(__dirname,'node_modules','node-pty','prebuilds');if(fs.existsSync(d))for(const dir of fs.readdirSync(d)){const h=p.join(d,dir,'spawn-helper');if(fs.existsSync(h))fs.chmodSync(h,0o755)}\""},"_npmUser":{"name":"blue-hope","email":"ms7045436@gmail.com"},"_npmVersion":"10.9.2","description":"MCP server for controlling TUI applications in sandboxed PTY sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","nanoid":"^5.0.9","node-pty":"^1.0.0","@xterm/headless":"^5.5.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tui-mcp_0.0.3_1775808528032_0.22731914603417747","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@blue-hope/tui-mcp","version":"0.0.4","keywords":["mcp","tui","pty","terminal"],"license":"MIT","_id":"@blue-hope/tui-mcp@0.0.4","maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"bin":{"tui-mcp":"dist/index.js"},"dist":{"shasum":"37fb37f176b5f9e0f2591b2bcb59be349d67afc6","tarball":"https://registry.npmjs.org/@blue-hope/tui-mcp/-/tui-mcp-0.0.4.tgz","fileCount":44,"integrity":"sha512-VrYSpMeqVamLmfnHaSaOPpTxat1vhFEA3U3g36D2+8vJOVwcs36J23YTFapPrPoPiwjBWJ4G/COZO3esLVP/TQ==","signatures":[{"sig":"MEYCIQDSXNe5P7KNCjV7ZPpy2Vy1ppvemGK5n545AZTwUkQsdwIhAODaRW6MSbOKRwhPLEqo0T/zbLQlt6xBVUZthILy9nBg","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":110193},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"93823af864254debb7c4e6c5dcb02d482172ac16","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","prepare":"npm run build","test:watch":"vitest","postinstall":"node -e \"const fs=require('fs'),p=require('path'),d=p.join(__dirname,'node_modules','node-pty','prebuilds');if(fs.existsSync(d))for(const dir of fs.readdirSync(d)){const h=p.join(d,dir,'spawn-helper');if(fs.existsSync(h))fs.chmodSync(h,0o755)}\""},"_npmUser":{"name":"blue-hope","email":"ms7045436@gmail.com"},"_npmVersion":"10.9.2","description":"MCP server for controlling TUI applications in sandboxed PTY sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","nanoid":"^5.0.9","node-pty":"^1.0.0","@xterm/headless":"^5.5.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tui-mcp_0.0.4_1775828143630_0.8023322025438271","host":"s3://npm-registry-packages-npm-production"}},"0.0.5":{"name":"@blue-hope/tui-mcp","version":"0.0.5","keywords":["mcp","tui","pty","terminal"],"license":"MIT","_id":"@blue-hope/tui-mcp@0.0.5","maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"bin":{"tui-mcp":"dist/index.js"},"dist":{"shasum":"3f5252f00ec6d70685df89720da93dd04a171603","tarball":"https://registry.npmjs.org/@blue-hope/tui-mcp/-/tui-mcp-0.0.5.tgz","fileCount":44,"integrity":"sha512-IMkEAQGx83YGzR5uAvBNc8zSBEGJp21vJlbz7f2tZVSmhj1u3xqPC1gmhoVyGkLxuPYFmFvOKGSTA+dZR+coVg==","signatures":[{"sig":"MEYCIQDhkXac5nEgU4/IKIQDMZx2NQpdvFOrEMmgJruIbP6vGQIhALwYTCLtWoVezkpaGBZS1fSHwGE56dHcTm+i83lWe8sH","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":109814},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"d1041ef45cfd23bce2c6510c7ee52656bfca8467","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","prepare":"npm run build","test:watch":"vitest"},"_npmUser":{"name":"blue-hope","email":"ms7045436@gmail.com"},"_npmVersion":"10.9.2","description":"MCP server for controlling TUI applications in sandboxed PTY sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","nanoid":"^5.0.9","node-pty":"^1.0.0","@xterm/headless":"^5.5.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tui-mcp_0.0.5_1775828260541_0.14854037137704812","host":"s3://npm-registry-packages-npm-production"}},"0.0.6":{"name":"@blue-hope/tui-mcp","version":"0.0.6","keywords":["mcp","tui","pty","terminal","model-context-protocol","ai","agent"],"license":"MIT","_id":"@blue-hope/tui-mcp@0.0.6","maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"homepage":"https://github.com/blue-hope/tui-mcp","bugs":{"url":"https://github.com/blue-hope/tui-mcp/issues"},"bin":{"tui-mcp":"dist/index.js"},"dist":{"shasum":"73c4dde8816d9ce7daf5b6b0ab2d8b3b06931070","tarball":"https://registry.npmjs.org/@blue-hope/tui-mcp/-/tui-mcp-0.0.6.tgz","fileCount":45,"integrity":"sha512-B9/WBMURlLXpk2FqrdB6nnaVXLEQrZbXrHmZDbiYEMlxxWVXy/uXFNuPGugCRgGOTtRCTpFtYjYEUhLwSRvJkw==","signatures":[{"sig":"MEUCIGeRL8vJQg6G+VPUAqnH7XZA9ZRe59qkJd5ZqnwtTs6cAiEAuS7BchrOFCkD8K1301TvM4uOHRD4sCLEbwvOJrO9XPI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":123824},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"0b51b531da9b64a8c21300429be60342ad8a09c1","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","prepare":"npm run build","test:watch":"vitest"},"_npmUser":{"name":"blue-hope","email":"ms7045436@gmail.com"},"repository":{"url":"git+https://github.com/blue-hope/tui-mcp.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for controlling TUI applications in sandboxed PTY sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","nanoid":"^5.0.9","node-pty":"^1.0.0","@xterm/headless":"^5.5.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tui-mcp_0.0.6_1775987058040_0.2034068896452852","host":"s3://npm-registry-packages-npm-production"}},"0.0.7":{"name":"@blue-hope/tui-mcp","version":"0.0.7","keywords":["mcp","tui","pty","terminal","model-context-protocol","ai","agent"],"license":"MIT","_id":"@blue-hope/tui-mcp@0.0.7","maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"homepage":"https://github.com/blue-hope/tui-mcp","bugs":{"url":"https://github.com/blue-hope/tui-mcp/issues"},"bin":{"tui-mcp":"dist/index.js"},"dist":{"shasum":"90deff1c9605ff8b7012b336d370afab78797160","tarball":"https://registry.npmjs.org/@blue-hope/tui-mcp/-/tui-mcp-0.0.7.tgz","fileCount":45,"integrity":"sha512-KtLvZoF5SHFMSAVmAg7ywoljt3fHARIIM3g9MisFOHeC1HpkMfM1ITxf/THmcwhOrv15AeU58eEVgAJD3yTkgQ==","signatures":[{"sig":"MEUCIQCW6PNd+xhbaX0s7FJPfXKxgd+Ufq9v3uvvrSJp5FxiJAIgILAUeKyDpmJTRouFYOiVmAeSTG9z2JezpZbSQQyV80s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":125064},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"b60da2f6a132c58bc9b95b182821c7e5b699b99a","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","prepare":"npm run build","test:watch":"vitest"},"_npmUser":{"name":"blue-hope","email":"ms7045436@gmail.com"},"repository":{"url":"git+https://github.com/blue-hope/tui-mcp.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for controlling TUI applications in sandboxed PTY sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","nanoid":"^5.0.9","node-pty":"^1.0.0","@xterm/headless":"^5.5.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tui-mcp_0.0.7_1775989608775_0.30390975871676895","host":"s3://npm-registry-packages-npm-production"}},"0.0.8":{"name":"@blue-hope/tui-mcp","version":"0.0.8","description":"MCP server for controlling TUI applications in sandboxed PTY sessions","type":"module","main":"dist/index.js","bin":{"tui-mcp":"dist/index.js"},"scripts":{"build":"tsc","prepare":"npm run build","dev":"tsx src/index.ts","test":"vitest run","test:watch":"vitest"},"keywords":["mcp","tui","pty","terminal","model-context-protocol","ai","agent"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/blue-hope/tui-mcp.git"},"homepage":"https://github.com/blue-hope/tui-mcp","bugs":{"url":"https://github.com/blue-hope/tui-mcp/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","@xterm/headless":"^5.5.0","node-pty":"^1.0.0","nanoid":"^5.0.9","zod":"^3.24.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0","tsx":"^4.19.0","vitest":"^3.0.0"},"engines":{"node":">=18.0.0"},"_id":"@blue-hope/tui-mcp@0.0.8","gitHead":"bc56ca68b100678da0d174d8d9d774b4777d35d3","types":"./dist/index.d.ts","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-VjB5453bLz4hWrliI9LG+wO4nWbkVbglQB9DHNupwKbOb+n+pvOAq5tHeptl+wnJWd7smnd2yRGxU/TqWq8nug==","shasum":"316fd7c05be44ecb16eb756a12b05650ea11c460","tarball":"https://registry.npmjs.org/@blue-hope/tui-mcp/-/tui-mcp-0.0.8.tgz","fileCount":45,"unpackedSize":138472,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDMLE2nNrupRhIHpXhn4WcIWsQP92MV7I2m4iMXnmKsvAiAWT7ge/kjvBsiyff2o5t1Vi2Ukzxsd9gv2mndFbQ6mLw=="}]},"_npmUser":{"name":"blue-hope","email":"ms7045436@gmail.com"},"directories":{},"maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tui-mcp_0.0.8_1776008679351_0.3823176361621323"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-10T07:39:48.525Z","modified":"2026-04-12T15:44:39.633Z","0.0.1":"2026-04-10T07:39:48.779Z","0.0.2":"2026-04-10T08:02:27.042Z","0.0.3":"2026-04-10T08:08:48.190Z","0.0.4":"2026-04-10T13:35:43.774Z","0.0.5":"2026-04-10T13:37:40.660Z","0.0.6":"2026-04-12T09:44:18.198Z","0.0.7":"2026-04-12T10:26:48.926Z","0.0.8":"2026-04-12T15:44:39.513Z"},"bugs":{"url":"https://github.com/blue-hope/tui-mcp/issues"},"license":"MIT","homepage":"https://github.com/blue-hope/tui-mcp","keywords":["mcp","tui","pty","terminal","model-context-protocol","ai","agent"],"repository":{"type":"git","url":"git+https://github.com/blue-hope/tui-mcp.git"},"description":"MCP server for controlling TUI applications in sandboxed PTY sessions","maintainers":[{"name":"blue-hope","email":"ms7045436@gmail.com"}],"readme":"<p align=\"center\">\n  <h1 align=\"center\">tui-mcp</h1>\n  <p align=\"center\">\n    MCP server for controlling TUI applications through AI agents\n    <br />\n    <a href=\"https://www.npmjs.com/package/@blue-hope/tui-mcp\"><strong>npm</strong></a>\n    &nbsp;&middot;&nbsp;\n    <a href=\"https://github.com/blue-hope/tui-mcp/issues\"><strong>Issues</strong></a>\n  </p>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@blue-hope/tui-mcp\"><img src=\"https://img.shields.io/npm/v/@blue-hope/tui-mcp.svg\" alt=\"npm version\" /></a>\n  <a href=\"https://www.npmjs.com/package/@blue-hope/tui-mcp\"><img src=\"https://img.shields.io/npm/dm/@blue-hope/tui-mcp.svg\" alt=\"npm downloads\" /></a>\n  <a href=\"https://github.com/blue-hope/tui-mcp/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/blue-hope/tui-mcp.svg\" alt=\"license\" /></a>\n  <a href=\"https://github.com/blue-hope/tui-mcp\"><img src=\"https://img.shields.io/github/stars/blue-hope/tui-mcp.svg?style=social\" alt=\"GitHub stars\" /></a>\n</p>\n\n---\n\nLaunch TUI applications (vim, htop, lazygit, etc.) in sandboxed PTY sessions and let AI agents observe and interact with them.\n\nLike [chrome-devtools MCP](https://github.com/anthropics/chrome-devtools-mcp) for browsers and [mobile-mcp](https://github.com/mobile-next/mobile-mcp) for mobile devices — but for terminal UIs.\n\n```\nAgent: launch({ command: \"vim\", args: [\"main.py\"] })\nAgent: type_text({ sessionId: \"a3f8k2x1\", text: \"iprint('hello')\" })\nAgent: press_key({ sessionId: \"a3f8k2x1\", key: \"Escape\" })\nAgent: type_text({ sessionId: \"a3f8k2x1\", text: \":wq\" })\nAgent: press_key({ sessionId: \"a3f8k2x1\", key: \"Enter\" })\n```\n\n## Quick Start\n\nAdd to your MCP client config:\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@blue-hope/tui-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\nAdd to `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"tui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@blue-hope/tui-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Other MCP clients</strong></summary>\n\nAny MCP client that supports stdio transport:\n\n```json\n{\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@blue-hope/tui-mcp\"]\n}\n```\n\n</details>\n\n## Tools\n\n### Session Management\n\n| Tool | Description |\n|------|-------------|\n| `launch` | Launch a TUI app in a new PTY session |\n| `list_sessions` | List all active sessions |\n| `kill_session` | Terminate a session |\n| `send_signal` | Send a POSIX signal (SIGINT, SIGTSTP, SIGCONT, etc.) |\n| `wait_for_exit` | Wait for process to exit, returns exit code |\n\n### Observation\n\n| Tool | Description |\n|------|-------------|\n| `take_snapshot` | Capture screen content, cursor position, and dimensions |\n| `get_cursor_position` | Get current cursor X/Y |\n| `get_screen_size` | Get terminal cols/rows |\n| `find_text` | Find text position on screen (row, col) |\n\n### Input\n\n| Tool | Description |\n|------|-------------|\n| `type_text` | Send text input to the TUI |\n| `press_key` | Send key press (`Enter`, `Ctrl+C`, `Alt+X`, `F5`, etc.) |\n\n### Control\n\n| Tool | Description |\n|------|-------------|\n| `resize` | Resize the terminal |\n| `wait_for_text` | Wait until specific text appears on screen |\n| `wait_for_stable` | Wait until screen stops changing |\n\n## Examples\n\n### Edit a file with vim\n\n```\nlaunch({ command: \"vim\", args: [\"file.txt\"] })\n→ { sessionId: \"a3f8k2x1\", pid: 12345, cols: 80, rows: 24 }\n\ntype_text({ sessionId: \"a3f8k2x1\", text: \"ihello world\" })\npress_key({ sessionId: \"a3f8k2x1\", key: \"Escape\" })\ntype_text({ sessionId: \"a3f8k2x1\", text: \":wq\" })\npress_key({ sessionId: \"a3f8k2x1\", key: \"Enter\" })\n```\n\n### Use lazygit in a repo\n\n```\nlaunch({ command: \"lazygit\", args: [], cwd: \"/path/to/repo\" })\ntake_snapshot({ sessionId: \"...\" })\n→ { lines: [...], cursor: { x: 0, y: 0 }, rows: 24, cols: 80 }\n```\n\n### Run a command and wait for output\n\n```\nlaunch({ command: \"npm test\" })\nwait_for_text({ sessionId: \"...\", text: \"Tests passed\", timeout: 30000 })\n```\n\n### Custom environment and dimensions\n\n```\nlaunch({\n  command: \"htop\",\n  args: [],\n  cols: 120,\n  rows: 40,\n  env: { \"HTOPRC\": \"/path/to/config\" }\n})\n```\n\n## `launch` Modes\n\n| Mode | When | Example |\n|------|------|---------|\n| **Direct** | `args` is provided | `launch({ command: \"vim\", args: [\"file.txt\"] })` |\n| **Shell** | `args` is omitted | `launch({ command: \"ls -la \\| head -20\" })` |\n\nDirect mode calls the binary directly. Shell mode runs through `$SHELL -c \"...\"`, supporting pipes, globs, and environment variable expansion.\n\n## Key Support\n\nSupports arbitrary key combinations:\n\n| Category | Examples |\n|----------|---------|\n| Named keys | `Enter`, `Tab`, `Escape`, `Backspace`, `Space`, `Delete`, `Home`, `End`, `PageUp`, `PageDown` |\n| Arrow keys | `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight` (or `Up`, `Down`, `Left`, `Right`) |\n| Function keys | `F1` through `F12` |\n| Ctrl combos | `Ctrl+C`, `Ctrl+Z`, `Ctrl+A`, `Ctrl+D`, ... |\n| Alt combos | `Alt+X`, `Alt+Enter`, ... |\n| Single chars | `a`, `1`, `/`, ... |\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `TUI_MCP_IDLE_TIMEOUT` | `1800000` (30 min) | Idle session timeout in ms |\n\n## How It Works\n\n```\nAI Agent (Claude, Cursor, etc.)\n    │  stdio (JSON-RPC 2.0)\n    ▼\n┌──────────────────────────────────┐\n│  tui-mcp server                  │\n│                                  │\n│  ┌────────────┐  ┌────────────┐  │\n│  │ Session A  │  │ Session B  │  │\n│  │ ┌────────┐ │  │ ┌────────┐ │  │\n│  │ │node-pty│ │  │ │node-pty│ │  │\n│  │ └───┬────┘ │  │ └───┬────┘ │  │\n│  │     │ PTY  │  │     │ PTY  │  │\n│  │ ┌───▼────┐ │  │ ┌───▼────┐ │  │\n│  │ │ xterm  │ │  │ │ xterm  │ │  │\n│  │ │headless│ │  │ │headless│ │  │\n│  │ └────────┘ │  │ └────────┘ │  │\n│  └────────────┘  └────────────┘  │\n└──────────────────────────────────┘\n    │                    │\n    ▼                    ▼\n  vim                  htop\n```\n\nEach session pairs a [node-pty](https://github.com/microsoft/node-pty) process with an [@xterm/headless](https://www.npmjs.com/package/@xterm/headless) terminal emulator. The PTY spawns the TUI app; xterm parses its ANSI output into a readable screen buffer. Tool calls within a session are serialized via a per-session mutex.\n\n## Development\n\n```bash\ngit clone https://github.com/blue-hope/tui-mcp.git\ncd tui-mcp\nnpm install\nnpm run dev      # Run with tsx (hot reload)\nnpm run build    # Compile TypeScript\nnpm test         # Run tests\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # Entry point, MCP server bootstrap\n├── session.ts            # Session: PTY + Terminal pair\n├── session-manager.ts    # Session lifecycle, idle timeout\n├── tools.ts              # 11 MCP tool registrations\n├── keys.ts               # Key name → ANSI sequence mapper\n├── mutex.ts              # Promise-based FIFO mutex\n├── tool-wrapper.ts       # Handler wrapper (logging, errors)\n└── __tests__/            # vitest test suite\n```\n\n## Requirements\n\n- Node.js >= 18\n- macOS or Linux (node-pty requires POSIX)\n- C++ build tools for node-pty native module (`node-gyp`)\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}