# devbox-mcp

`devbox-mcp` is a minimal stdio MCP server for a personal development machine. It gives an MCP client terminal, process, and filesystem access with exactly the operating-system permissions of the user that runs it.

## Threat model

This is intentionally a full-access personal devbox tool. It has no command allowlist, path restriction, read-only mode, approval layer, or sandbox. Running it as `gurol` allows MCP callers to do anything that `gurol` can do, but it does not bypass normal OS permissions or grant additional privileges.

The server does not provide authentication or a network listener. External access and authentication are the responsibility of the OpenAI Secure MCP Tunnel. systemd and Ansible deployment are managed in a separate repository.

## Usage

Node.js 24 or newer is required.

```sh
npm ci
npm run build
npm start
```

The server reads MCP JSON-RPC from stdin and writes only MCP protocol messages to stdout. Diagnostics, if any, go to stderr. It inherits the launching process environment and uses `HOME` as the default working directory.

## Tools

- `exec`: run `/bin/bash -c`, returning stdout, stderr, exit status, timeout, and truncation details.
- `process_start`: start a long-running shell command and return an opaque process ID.
- `process_status`: inspect a managed process.
- `process_output`: page through bounded captured stdout/stderr with byte offsets.
- `process_kill`: terminate a managed process group.
- `read_file`: perform a bounded read, returning UTF-8 text or base64 binary data.
- `write_file`: write UTF-8 text, using atomic replacement for regular files when possible.
- `list_directory`: list one directory level with basic metadata.
- `stat`: inspect file, directory, or symlink metadata.

## v0.1 limits

The process registry is in memory and is lost on server restart. Captured process output retains only the newest 2 MiB, `exec` retains at most 1 MiB per output stream, and individual file/process-output reads are limited to 1 MiB. Filesystem listing is deliberately non-recursive.