{"_id":"@ahmedshaikh/shell-session-mcp","name":"@ahmedshaikh/shell-session-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ahmedshaikh/shell-session-mcp","version":"0.1.0","type":"module","description":"Persistent stateful shell as an MCP server — env vars, cwd, and shell state survive across tool calls (unlike one-shot bash).","bin":{"shell-session":"dist/server.js"},"engines":{"node":">=18"},"scripts":{"serve":"tsx src/server.ts","build":"tsc","test":"node --import tsx --test --test-force-exit test/*.test.ts","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.23.8"},"devDependencies":{"@types/node":"^20.11.0","tsx":"^4.7.0","typescript":"^5.4.0"},"license":"MIT","author":{"name":"ahmedshaikh"},"keywords":["mcp","model-context-protocol","claude","agent","ai","shell","bash","persistent-shell","repl"],"repository":{"type":"git","url":"git+https://github.com/RaziStuff/shell-session-mcp.git"},"homepage":"https://github.com/RaziStuff/shell-session-mcp#readme","bugs":{"url":"https://github.com/RaziStuff/shell-session-mcp/issues"},"publishConfig":{"access":"public"},"gitHead":"00fb5c0c5304434096ed9b39825eebb892397a21","_id":"@ahmedshaikh/shell-session-mcp@0.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-YOnG+X+5I429ncnU4uOcxTf8x8zpl6iRBmuzM2c0EIiI/FKKmdILDNyrcId/1VGUm89M5/JhKe6sAKlJ/XF+2w==","shasum":"acc5f78c657913b99fb34cfdc1a72ef4fbb8e69c","tarball":"https://registry.npmjs.org/@ahmedshaikh/shell-session-mcp/-/shell-session-mcp-0.1.0.tgz","fileCount":5,"unpackedSize":11387,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDeI5OpuZyvCq/4OrEMijmIsxwU6zEkLjHy9QI8ONbTbAIhAOty1jBdHV7WdJiJB2NIiVeryejZPM+WF80uvuG7ciVM"}]},"_npmUser":{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"},"directories":{},"maintainers":[{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/shell-session-mcp_0.1.0_1782701022899_0.2485422363517822"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T02:43:42.733Z","0.1.0":"2026-06-29T02:43:43.001Z","modified":"2026-06-29T02:43:43.254Z"},"maintainers":[{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"}],"description":"Persistent stateful shell as an MCP server — env vars, cwd, and shell state survive across tool calls (unlike one-shot bash).","homepage":"https://github.com/RaziStuff/shell-session-mcp#readme","keywords":["mcp","model-context-protocol","claude","agent","ai","shell","bash","persistent-shell","repl"],"repository":{"type":"git","url":"git+https://github.com/RaziStuff/shell-session-mcp.git"},"author":{"name":"ahmedshaikh"},"bugs":{"url":"https://github.com/RaziStuff/shell-session-mcp/issues"},"license":"MIT","readme":"# shell-session\n\nA **persistent, stateful shell** as an MCP server. Unlike a one-shot `bash` tool —\nwhere env vars, `cd`, `source`, and shell functions vanish after every call — this\nkeeps a single long-lived shell alive, so state set once is reused across calls.\n\n```\nshell(\"export PATH=/opt/node/bin:$PATH\")   # set it once\nshell(\"cd /my/project\")\nshell(\"node --version\")                     # PATH + cwd still apply\n```\n\nNo more re-`export`ing the same vars or re-`cd`ing on every command.\n\n## Tools\n\n- **`shell(command, timeout_ms?)`** — run a command in the persistent shell;\n  returns the exit code + combined stdout/stderr.\n- **`shell_reset()`** — kill the shell and start fresh (clears all state).\n- **`shell_status()`** — alive?, pid, current working directory.\n\n## How it works\n\nA plain `child_process` shell (no pty, **no native dependencies**) reads commands\nfrom its stdin pipe. Completion is detected with a unique end-marker that also\nprints the command's exit code. Since a non-interactive shell doesn't echo stdin,\nonly command *output* is captured.\n\n## Limitations (honest)\n\n- **No TTY:** interactive programs (vim, `less`, prompts) and commands that read\n  stdin won't work — this is for batch commands.\n- **A timed-out command keeps running** in the session; call `shell_reset` to\n  recover (without a pty there's no way to signal just the foreground command).\n- One command at a time (calls are serialized).\n\n## Setup\n\n```bash\nnpm install\nnpm test          # proves persistence: env/cwd/functions survive across calls\n```\n\nRegister with an MCP client, e.g.:\n\n```bash\nclaude mcp add shell-session -- node /abs/path/shell-session/dist/server.js\n```\n\nNode 18+.\n","readmeFilename":"README.md","_rev":"1-3ad290d224e8d4d864a64d9e543f6ca4"}