Skip to content

Commit df1d8a0

Browse files
richiemcilroyrichiemcilroy
committed
docs(mcp): rewrite tools reference with sandbox_run_project as entry point
1 parent 7ea2d9d commit df1d8a0

1 file changed

Lines changed: 102 additions & 88 deletions

File tree

‎apps/docs/content/docs/mcp/tools.mdx‎

Lines changed: 102 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,153 +1,167 @@
11
---
22
title: Tools Reference
3-
description: Complete reference for all 14 MCP tools.
3+
description: Reference for the Sandchest MCP tools, with sandbox_run_project as the default entry point.
44
---
55

6-
## Sandbox lifecycle
6+
Sandchest exposes low-level sandbox primitives and one high-level workflow tool.
77

8-
### `sandbox_create`
8+
## Start here
9+
10+
### `sandbox_run_project`
11+
12+
The default tool for requests like:
13+
14+
- "run `bun run lint` in a new sandbox"
15+
- "test this repo in Sandchest"
16+
- "build this project in isolation"
917

10-
Create a new isolated Linux sandbox (Firecracker microVM).
18+
It creates a sandbox, loads the project, prepares the runtime, installs dependencies, runs the command, and returns the result plus replay URL.
19+
20+
In `source: "auto"` mode, it preserves local changes with upload, but prefers shallow clone when the local repo is clean and has a public HTTPS origin.
1121

1222
| Parameter | Type | Required | Description |
1323
|-----------|------|----------|-------------|
14-
| `image` | `string` | No | Image URI. Default: `sandchest://ubuntu-22.04/base` |
15-
| `profile` | `small \| medium \| large` | No | Resource profile. Default: `small` |
16-
| `env` | `Record<string, string>` | No | Environment variables |
24+
| `command` | `string` | Yes | Command to run inside the project |
25+
| `local_path` | `string` | No | Local project directory to upload |
26+
| `repo_url` | `string` | No | Public git repo URL to clone |
27+
| `source` | `auto \| upload \| git_clone` | No | How to load code. Default: `auto` |
28+
| `remote_path` | `string` | No | Workspace path in the sandbox. Default: `/tmp/work` |
29+
| `profile` | `small \| medium \| large` | No | Sandbox size |
30+
| `env` | `Record<string, string>` | No | Environment variables for sandbox creation |
31+
| `runtime` | `auto \| bun \| npm \| yarn \| pnpm \| python \| go \| none` | No | Runtime/toolchain to prepare |
32+
| `install` | `boolean` | No | Install dependencies before running. Default: `true` |
33+
| `install_command` | `string` | No | Override the dependency install command |
34+
| `exclude` | `string[]` | No | Extra exclude globs for local uploads |
35+
| `baseline` | `boolean` | No | Initialize a baseline git repo after upload |
36+
| `keep_sandbox` | `boolean` | No | Keep the sandbox after the command. Default: `true` |
37+
| `timeout` | `number` | No | Final command timeout in seconds. Default: `300` |
38+
39+
Returns:
40+
41+
- `sandbox_id`
42+
- `replay_url`
43+
- `source` summary
44+
- detected project/runtime details
45+
- final command result (`exit_code`, `stdout`, `stderr`, `duration_ms`)
46+
- any warnings
47+
48+
## Lifecycle
49+
50+
### `sandbox_create`
1751

18-
Returns: `sandbox_id`, `replay_url`
52+
Create a new isolated Linux sandbox.
1953

2054
### `sandbox_list`
2155

2256
List active sandboxes.
2357

24-
| Parameter | Type | Required | Description |
25-
|-----------|------|----------|-------------|
26-
| `status` | `running \| stopped \| failed` | No | Filter by status |
58+
### `sandbox_stop`
2759

28-
Returns: Array of `{ sandbox_id, status, replay_url }`
60+
Gracefully stop a sandbox and preserve the replay URL.
2961

30-
### `sandbox_stop`
62+
### `sandbox_destroy`
3163

32-
Gracefully stop a sandbox. Collects artifacts and flushes logs.
64+
Hard-delete a sandbox immediately.
3365

34-
| Parameter | Type | Required | Description |
35-
|-----------|------|----------|-------------|
36-
| `sandbox_id` | `string` | Yes | The sandbox to stop |
66+
### `sandbox_fork`
3767

38-
### `sandbox_destroy`
68+
Fork a running sandbox to create a fast checkpointed copy.
3969

40-
Permanently destroy a sandbox and all its data.
70+
### `sandbox_replay`
4171

42-
| Parameter | Type | Required | Description |
43-
|-----------|------|----------|-------------|
44-
| `sandbox_id` | `string` | Yes | The sandbox to destroy |
72+
Return the replay URL for a sandbox.
4573

4674
## Command execution
4775

4876
### `sandbox_exec`
4977

50-
Execute a command in a sandbox. Returns exit code, stdout, and stderr.
78+
Run a one-off command in a sandbox.
5179

52-
| Parameter | Type | Required | Description |
53-
|-----------|------|----------|-------------|
54-
| `sandbox_id` | `string` | Yes | The sandbox to execute in |
55-
| `cmd` | `string` | Yes | Command to run (interpreted by `/bin/sh`) |
56-
| `cwd` | `string` | No | Working directory. Default: `/root` |
57-
| `timeout` | `number` | No | Timeout in seconds. Default: 300 |
80+
Use this when you already have a prepared sandbox and do not need shell state to persist.
5881

5982
### `sandbox_session_create`
6083

61-
Create a persistent shell session where commands share state.
84+
Create a persistent shell session.
6285

63-
| Parameter | Type | Required | Description |
64-
|-----------|------|----------|-------------|
65-
| `sandbox_id` | `string` | Yes | The sandbox |
86+
Optional inputs:
6687

67-
Returns: `session_id`
88+
- `shell` with default `/bin/bash`
89+
- `env` for session-scoped environment variables
6890

6991
### `sandbox_session_exec`
7092

71-
Run a command in a persistent session. Inherits all prior state.
72-
73-
| Parameter | Type | Required | Description |
74-
|-----------|------|----------|-------------|
75-
| `sandbox_id` | `string` | Yes | The sandbox |
76-
| `session_id` | `string` | Yes | The session |
77-
| `cmd` | `string` | Yes | Command to run |
78-
| `timeout` | `number` | No | Timeout in seconds. Default: 300 |
93+
Run a command inside a persistent session.
7994

8095
### `sandbox_session_destroy`
8196

82-
Destroy a persistent shell session.
97+
Destroy a persistent session.
8398

84-
| Parameter | Type | Required | Description |
85-
|-----------|------|----------|-------------|
86-
| `sandbox_id` | `string` | Yes | The sandbox |
87-
| `session_id` | `string` | Yes | The session to destroy |
99+
## Source loading and files
100+
101+
### `sandbox_git_clone`
88102

89-
## Files
103+
Clone a public git repository into a sandbox.
104+
105+
Best when:
106+
107+
- the repo is public
108+
- you want the fastest source-loading path
109+
- you do not need local uncommitted changes
110+
111+
Defaults to `/tmp/work` when no destination path is provided.
90112

91113
### `sandbox_upload`
92114

93-
Upload a file to a sandbox.
115+
Upload one file into a sandbox.
94116

95-
| Parameter | Type | Required | Description |
96-
|-----------|------|----------|-------------|
97-
| `sandbox_id` | `string` | Yes | The sandbox |
98-
| `path` | `string` | Yes | Destination path (e.g., `/work/config.json`) |
99-
| `content` | `string` | Yes | File content |
100-
| `encoding` | `utf-8 \| base64` | No | Content encoding. Default: `utf-8` |
117+
### `sandbox_upload_dir`
101118

102-
### `sandbox_download`
119+
Upload a local directory into a sandbox.
103120

104-
Download a file from a sandbox.
121+
Best when:
105122

106-
| Parameter | Type | Required | Description |
107-
|-----------|------|----------|-------------|
108-
| `sandbox_id` | `string` | Yes | The sandbox |
109-
| `path` | `string` | Yes | File path in the sandbox |
123+
- the repo is private
124+
- the code only exists locally
125+
- local uncommitted changes must be included
110126

111-
### `sandbox_file_list`
127+
Requires `SANDCHEST_MCP_ALLOWED_PATHS`.
112128

113-
List files and directories at a path.
129+
### `sandbox_download`
114130

115-
| Parameter | Type | Required | Description |
116-
|-----------|------|----------|-------------|
117-
| `sandbox_id` | `string` | Yes | The sandbox |
118-
| `path` | `string` | Yes | Directory path to list |
131+
Download one file from a sandbox.
119132

120-
## Artifacts
133+
### `sandbox_download_dir`
121134

122-
### `sandbox_artifacts_list`
135+
Download a sandbox directory to a new local path.
123136

124-
List registered artifacts for a sandbox.
137+
Requires `SANDCHEST_MCP_ALLOWED_PATHS`.
125138

126-
| Parameter | Type | Required | Description |
127-
|-----------|------|----------|-------------|
128-
| `sandbox_id` | `string` | Yes | The sandbox |
139+
### `sandbox_file_list`
129140

130-
## Forking
141+
List files in a sandbox directory.
131142

132-
### `sandbox_fork`
143+
## Review and patch workflows
133144

134-
Create an instant copy of a running sandbox (memory + filesystem + all state).
145+
### `sandbox_diff`
135146

136-
| Parameter | Type | Required | Description |
137-
|-----------|------|----------|-------------|
138-
| `sandbox_id` | `string` | Yes | The sandbox to fork |
139-
| `env` | `Record<string, string>` | No | Additional env vars for the fork |
147+
Inspect changes in a git repo inside the sandbox.
140148

141-
Fork is sub-second. The original sandbox is unaffected.
149+
Use `mode: "review"` for inspection and `mode: "patch"` for a patch-safe export.
142150

143-
## Replay
151+
### `sandbox_apply_patch`
144152

145-
### `sandbox_replay`
153+
Apply a unified diff inside a sandbox git repo.
146154

147-
Get the replay URL for a sandbox.
155+
## Artifacts
148156

149-
| Parameter | Type | Required | Description |
150-
|-----------|------|----------|-------------|
151-
| `sandbox_id` | `string` | Yes | The sandbox |
157+
### `sandbox_artifacts_list`
158+
159+
List artifacts registered for a sandbox.
160+
161+
## Recommended defaults
162+
163+
Use these in order:
152164

153-
Returns: `sandbox_id`, `replay_url`
165+
1. `sandbox_run_project` for one-shot "new sandbox + run command" requests.
166+
2. `sandbox_list` and `sandbox_fork` for reuse.
167+
3. Primitive tools when you need exact control over setup, sessions, file transfer, or patch workflows.

0 commit comments

Comments
 (0)