WorkspaceGuard MCP

WorkspaceGuard MCP is a local, cross-platform MCP server that lets ChatGPT or an MCP client operate on one designated workspace. The project was rebuilt after studying FileMCP, keeping the useful security principles and trimming parts not yet needed for the first release.

What is it for?

• List, read by file or by line, search by name and search by content.

• Write files atomically, with dry_run and expected_sha256 support to avoid overwriting newer changes.

• "Delete" by moving into .workspaceguard/trash, with manual restore possible.

• Read Git status, log, and diff without enabling a shell.

• Optionally run a terminal via program + args, without shell string concatenation, and only allow executables in an allowlist.

• Use over stdio or MCP Streamable HTTP on 127.0.0.1 with a token.

• Write audit JSONL without storing file contents or full command arguments.

Related MCP server: Kastor

Key improvements

The app has an Electron desktop UI to pick a workspace, pick a mode, pick a command allowlist, start/stop the server, run an MCP check right inside the app, and connect a Secure MCP Tunnel. Following FileMCP's approach, the app generates a new loopback token per session, keeps the server on 127.0.0.1, manages the tunnel-client lifecycle, and stores the Runtime API key using the OS encryption mechanism (Keychain on macOS when available). The tunnel-client binary is still downloaded by the user from OpenAI; the project does not bundle that binary. The local runtime and Tunnel do not call Codex or OpenAI models/APIs: you use the app with ChatGPT Web through a developer-mode app, so no Codex quota is used. The conversation still follows the limits of the ChatGPT plan you are using.

Requirements

• Node.js 20 or later (tested with Node.js 24).

• Git if using the git_* tools.

• For ChatGPT: a workspace that supports custom MCP apps, a Secure MCP Tunnel, and a runtime API key with the appropriate tunnel permission. See OpenAI Secure MCP Tunnel.

Step-by-step setup

Step 1 — install dependencies

cd "/Users/danhpham/Documents/ChatGPT/MCP"
npm install

Do not put API keys in .env or commit them to Git.

Step 2 — check the whole project

npm run verify

This command runs typecheck, unit/integration tests, a production build, and a semantic smoke test over MCP stdio.

Step 3 — run the desktop UI (easiest way)

npm run desktop

In the WorkspaceGuard window:

1. Click Choose folder… and pick a test workspace.

2. Keep Read-only for the first run.

3. Click Start MCP. When the status changes to Running, the HTTP server is ready on 127.0.0.1:<port>.

4. Click Stop when done. Closing the app also stops both the server and the Tunnel.

The UI does not display or store the HTTP token; a new token is generated in the main process on every start.

Run a full MCP check right inside the UI

After the server reports Running, click Run MCP check. This is a real MCP client in the Electron main process, not a fake check through the UI.

• With Read-only, the app checks the MCP HTTP handshake, tool discovery, workspace_info, and list_files.

• With Read and write, the app additionally checks write_file → read_file → trash_path. You must tick the confirmation because a test file with a random name will be moved into .workspaceguard/trash.

• With Run commands, keep node ticked in the allowlist so the app additionally checks run_command using node --version.

Pick a separate test folder for the last two modes. The result of each step appears right in the check section of the UI.

Step 4 — build the core from the terminal (optional)

npm run build

The production entry point is:

/Users/danhpham/Documents/ChatGPT/MCP/dist/index.js

Step 5 — pick a workspace and mode from the terminal (optional)

It is best to start with a small test folder:

mkdir -p /tmp/workspaceguard-demo
printf 'Xin chào MCP\n' > /tmp/workspaceguard-demo/hello.txt

Three modes:

• read-only: only file-read and Git-read tools. This is the default.

• workspace-write: adds write_file and trash_path.

• command: adds write permission and run_command.

Note: the server still writes internal audit to .workspaceguard/audit.jsonl in all three modes. "Read-only" describes the public tools, not the filesystem sandbox of the server process itself.

Step 6A — run over stdio (recommended)

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode read-only

The terminal will wait for the MCP client to send requests over stdin. This is correct behavior, not a hang.

Step 6B — enable write permission

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode workspace-write

trash_path defaults to dry_run=true. Only when the caller sends dry_run=false is the path moved to trash.

Step 6C — allow running terminal commands yourself

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode command \
  --allow-command git,node,npm,npx

Example tool input:

{
  "program": "npm",
  "args": ["test"],
  "cwd": "",
  "timeout_seconds": 120
}

run_command does not use a shell, but it is not an OS sandbox. node, npm, Python, or any allowed executable can still read/write outside the workspace, use the network, and run other processes with the current account's privileges. Only use command mode with a trusted workspace and workflow.

Step 7 — connect ChatGPT using the Secure MCP Tunnel UI

On OpenAI Platform, create a Secure MCP Tunnel and a runtime API key with permission to use the tunnel. Download the tunnel-client matching your OS. Do not give the Runtime API key to Codex and do not write it into .env, source, or Git.

In the app, after MCP reports Running:

1. Paste the Tunnel ID in the form tunnel_....

2. Paste the Runtime API key. Next time you can leave it blank to use the encrypted saved key.

3. Enter tunnel-client if the binary is already in PATH, or click Choose file… to select the downloaded binary.

4. Keep the default profile, click Connect Tunnel, and wait for the "ready for ChatGPT" message.

5. The green "ready for ChatGPT" line confirms the local side is connected. Click Open ChatGPT Web; this app does not open or call Codex.

6. Click Disconnect Tunnel if you only want to disconnect ChatGPT; click Stop to stop both the Tunnel and the MCP server.

The app performs the equivalent of the tunnel-client init --sample sample_mcp_remote_no_auth → doctor --explain → run sequence, with the MCP endpoint http://127.0.0.1:<port>/mcp, a local health endpoint, and the token header passed via an environment variable. Tunnel profiles live in the app's private data, not in the workspace.

In ChatGPT Web, enable Developer Mode/custom MCP app per your workspace policy, create a new app, choose the Tunnel connection, select the tunnel you just created, run Scan Tools, then try workspace_info, list_files, and read_file before enabling write tools. If you do not see the Tunnel option, check that your workspace has been granted read permission and Tunnel access.

Step 8 — HTTP loopback (optional)

export WORKSPACE_MCP_TOKEN="$(openssl rand -hex 32)"

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport http \
  --mode read-only \
  --port 7331

Health check:

curl --fail http://127.0.0.1:7331/healthz

MCP requests must send the header:

X-Workspace-MCP-Token: <WORKSPACE_MCP_TOKEN>

The HTTP server only binds 127.0.0.1, checks Host, Origin, token, basic framing, and body limits. Use stdio if you have no specific HTTP need.

Available tools

Always available

• workspace_info

• list_files

• read_file

• read_file_range

• search_filenames

• search_content

• git_status

• git_log

• git_diff

workspace-write or command mode

• write_file

• trash_path

command mode only

• run_command

Restoring trashed files

The tool returns trashPath. Restore with a local command, for example:

mv "/tmp/workspaceguard-demo/.workspaceguard/trash/<id>/remove-me.txt" \
  "/tmp/workspaceguard-demo/remove-me.txt"

WorkspaceGuard does not automatically clean the trash in this version to avoid deleting data unintentionally.

Structure

src/
├── config.ts                 # CLI/env và mode
├── security/path-policy.ts   # containment + sensitive-path policy
├── services/files.ts         # file/search/write/trash
├── services/git.ts           # Git read-only
├── services/process.ts       # process limits + tree cleanup
├── tools.ts                  # MCP schemas, annotations, audit
├── server.ts                 # stdio + HTTP loopback
├── desktop/                  # Electron main/preload + renderer an toàn
└── index.ts                  # CLI entry
tests/                        # unit, integration, MCP semantic smoke
docs/                         # phân tích source và lộ trình

Additional documentation

• Analysis of the original FileMCP project

• Build steps and roadmap

• Security model

License and references

The project uses the Apache License 2.0. FileMCP also uses Apache-2.0; see NOTICE for the reference design sources. The tunnel-client binary is not included; operators download the appropriate build from the official OpenAI source.