Team Ai
Apppublic

victor/just-bash-mcp

sourceHugging Faceupdated 5mo agoView on Hugging Face
0likes
App README

just-bash MCP

A remote MCP server that exposes `just-bash` as a safe, bounded, agent-friendly virtual shell workspace. Built per the PRD in PRD.md.

  • —Transport: Streamable HTTP at POST /mcp, stateless, direct JSON responses.
  • —Health: GET /healthz (unauthenticated).
  • —Metrics: GET /metrics (bearer-protected, Prometheus exposition format).
  • —Isolation: every session runs in a dedicated Node worker thread with cooperative AbortSignal cancellation and a parent-process hard watchdog.
  • —Default capabilities: in-memory filesystem only; network, Python, and JavaScript are disabled.

Tools

ToolPurpose
session_createCreate an isolated workspace.
session_resetReset a session (mode: empty or initial_files).
session_deleteIdempotently destroy a session.
bash_execRun a bash script inside a session.
files_writeBatch-write files (utf8/base64) with quotas.
files_readPaginated file read with utf8-safe slicing.
files_listBounded recursive list with glob + cursor.

bash_exec returns truncated, timed_out, hard_killed, session_valid, and (when stdout/stderr exceed the embed cap) resource_links to a justbash://session/{sid}/exec/{eid}/{stream} URI that the client can fetch via resources/read.

Environment

Required in production (NODE_ENV=production):

  • —MCP_AUTH_TOKEN — at least 32 bytes
  • —ALLOWED_HOSTS — comma-separated, e.g. myspace-owner-mcp.hf.space,localhost
  • —ALLOWED_ORIGINS — comma-separated, e.g. https://myspace-owner-mcp.hf.space,https://huggingface.co

Optional (see src/config.ts for the full list and defaults):

PORT=7860
METRICS_TOKEN=
MAX_SESSIONS=10
MAX_SESSION_FS_BYTES=10485760
MAX_SINGLE_FILE_BYTES=5242880
MAX_WRITE_BATCH_BYTES=2097152
MAX_READ_BYTES_PER_CALL=65536
MAX_EMBEDDED_STDOUT_BYTES=16384
MAX_EMBEDDED_STDERR_BYTES=8192
MAX_CAPTURED_OUTPUT_BYTES_EXEC=524288
MAX_RESOURCE_BYTES_SESSION=2097152
MAX_RESOURCE_BYTES_GLOBAL=33554432
MAX_EXECS_RETAINED_SESSION=20
SESSION_IDLE_TTL_SECONDS=1800
SESSION_SWEEP_INTERVAL_SECONDS=60
WORKER_MAX_OLD_GEN_MB=64
DEFAULT_TIMEOUT_MS=5000
MAX_TIMEOUT_MS=30000
WATCHDOG_GRACE_MS=1000
SHUTDOWN_GRACE_MS=5000
ENABLE_NETWORK=false
ENABLE_PYTHON=false
ENABLE_JAVASCRIPT=false
MAX_SESSIONS_PER_TOKEN=10
MAX_ACTIVE_EXECS_PER_TOKEN=2
MAX_TOOL_CALLS_PER_MINUTE=60
MAX_AUTH_FAILURES_PER_MINUTE=10

The server refuses to start in production if MCP_AUTH_TOKEN, ALLOWED_HOSTS, or ALLOWED_ORIGINS are missing, or if any of ENABLE_NETWORK, ENABLE_PYTHON, ENABLE_JAVASCRIPT, or DANGEROUSLY_ALLOW_FULL_INTERNET_ACCESS are enabled.

Local development

bash
npm install
npm test          # unit + integration tests via node --test + tsx
npm run dev       # run the server via tsx
npm run build && npm start  # run compiled JS

Hugging Face Space

Add MCP_AUTH_TOKEN, ALLOWED_HOSTS, and ALLOWED_ORIGINS as Space secrets, push this repo, and the Docker build will produce a service exposed on /mcp of your Space URL.

Sessions are ephemeral; Space restarts lose all session state by design (see PRD §22, §32).