A
licenseNot graded
qualityB
maintenanceEnables LLM agents to safely reclaim disk space by deleting build artifact directories like node_modules, .venv, and target, with strong guardrails to prevent accidental or malicious deletion.
MIT
mcp-local-sandbox-cleaner
by 571242
It's an MCP server for finding and cleaning up the leftover junk coding agents create in a workspace — scratch files, test caches — and for checking whether dev ports are still occupied.
Scan for artifacts (
scan_sandbox_artifacts): lists known junk names (.scratch,.agent-tmp,tmp_test_output,.pytest_cache,.coverage,coverage,.turbo,.tsbuildinfo) directly under a workspace root, non-recursively, with each path's last-modified age; optionally skip anything newer thanminAgeMinutes.Delete artifacts (
clean_sandbox_artifacts): removes exactly what the scan would list, with adryRunflag to preview andminAgeMinutesas a guard against wiping directories an agent is still writing to. Note it ignores git, so tracked files inside matched directories are deleted too.Check dev ports (
inspect_dangling_dev_ports): reports which of the given ports (default 3000, 3001, 5173, 5174, 8000, 8080, 8888) are occupied. It does not identify the owning process and does not kill anything — a live dev server and a zombie look identical.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-local-sandbox-cleanerscan my workspace for leftover AI scratch files and show what a dry run would delete"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-local-sandbox-cleaner
An MCP server that finds the junk coding agents leave behind in a workspace: scratch directories, test caches, and dev ports that may no longer be serving anything. It can delete the files; it only reports the ports.
Not published to npm — build it from source.
Install
pnpm install
pnpm buildPoint your MCP client at dist/index.js:
{
"mcpServers": {
"sandbox-cleaner": {
"command": "node",
"args": ["/absolute/path/to/mcp-local-sandbox-cleaner/dist/index.js"]
}
}
}Related MCP server: DevTwin MCP
Tools
scan_sandbox_artifacts
Lists matching paths and how long ago each was modified.
Argument | Type | Meaning |
| string | Workspace root. |
| number | Skip anything modified more recently than this. Defaults to 0. |
Looks for these names directly under the workspace root, no recursion:
.scratch, .agent-tmp, tmp_test_output, .pytest_cache, .coverage,
coverage, .turbo, .tsbuildinfo.
.tsbuildinfo is matched as that exact filename, so it will not catch the
tsconfig.tsbuildinfo files the TypeScript compiler actually writes. The list
is a plain array at the top of src/index.ts; edit it to suit your workspace.
clean_sandbox_artifacts
Deletes what scan_sandbox_artifacts would list.
Argument | Type | Meaning |
| string | Workspace root. |
| boolean | Report without deleting. Defaults to false. |
| number | Skip recently modified paths. Defaults to 0. |
Two things to know before running this without dryRun:
It does not consult git. A tracked file inside
.scratch/is deleted like anything else. Run withdryRun: truefirst if that matters.coverageis matched by name at the workspace root. If you keep real source in a directory calledcoverage, it goes.
minAgeMinutes is the guard against deleting a directory an agent is still
writing to. Set it to something like 15 to leave in-flight work alone.
inspect_dangling_dev_ports
Reports which of the given ports are in use. Defaults to
3000, 3001, 5173, 5174, 8000, 8080, 8888.
It does not identify the owning process and does not kill anything. Despite the name, the check is just "is this port occupied" — a healthy dev server and a zombie one look the same.
On Windows the match goes through findstr, which is a substring test: probing
3000 also reports listeners on 13000 and 30000. On Linux it uses
lsof -i, which matches the port exactly.
License
MIT. See LICENSE.
Available Tools
3 toolsclean_sandbox_artifactsC
Safely sweep verified transient files and directories to recover disk space and maintain repository cleanliness.
| Name | Required | Description | Default |
|---|---|---|---|
| dryRun | No | If true, only report what would be deleted without actually deleting. | |
| minAgeMinutes | No | Minimum age in minutes. Files modified more recently will be skipped to avoid disrupting active agent sessions. | |
| workspacePath | Yes | Target workspace path. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies deletion via 'sweep' and 'recover disk space', but does not state that files are irreversibly removed, what 'verified' means, whether dry-run is the default, or what permissions are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler or repetition. It is appropriately sized, though the space saved by conciseness could have been used to disclose critical deletion behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive cleanup tool with no annotations and no output schema, the description is too thin. It should explain what gets deleted, how safety is ensured, and how dry-run interacts with real deletion, especially since the schema already defines these parameters but the description does not tie them together.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented with useful detail, including dryRun behavior and minAgeMinutes semantics. The description does not add meaning beyond the schema, which is the expected baseline when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb/resource combination: 'sweep verified transient files and directories' with the goal of recovering disk space. It is clear that this performs cleanup, but it does not explicitly distinguish itself from the sibling scan_sandbox_artifacts tool or state that it deletes rather than reports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus the sibling scan_sandbox_artifacts, nor any conditions for when not to use it. The phrase 'maintain repository cleanliness' implies usage but does not give the agent actionable selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
inspect_dangling_dev_portsA
Detect orphaned local development ports (e.g. 3000, 5173, 8000, 8080) left behind by stopped agent runs.
| Name | Required | Description | Default |
|---|---|---|---|
| ports | No | Optional list of port numbers to check. Defaults to standard dev ports [3000, 3001, 5173, 5174, 8000, 8080, 8888]. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Detect' implies a read-oriented inspection rather than cleanup, and the cause 'stopped agent runs' adds useful context, but it does not explicitly confirm non-destructiveness, permissions, or what the detection returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. The examples and causal context all support the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with zero required parameters and full schema coverage, the description is largely complete. The main minor gap is that it does not state what the detection returns, and no output schema exists to cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single optional 'ports' parameter is fully documented with defaults. The description mentions example ports but adds no syntax or filtering semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Detect') and resource ('orphaned local development ports') and gives examples and a cause ('stopped agent runs'). It is clear what the tool does, but it does not explicitly distinguish itself from the sibling scan/clean sandbox artifact tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'left behind by stopped agent runs' implies the usage context, but the description does not say when to prefer this tool over alternatives such as scan_sandbox_artifacts or clean_sandbox_artifacts, nor does it state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
scan_sandbox_artifactsC
Scan a target workspace for dangling temporary test outputs, agent scratches, and bloated caches, with optional file age threshold.
| Name | Required | Description | Default |
|---|---|---|---|
| minAgeMinutes | No | Optional minimum age in minutes since last modification (default: 0). Set e.g. 15 to avoid touching files currently in use by an ongoing turn. | |
| workspacePath | Yes | Absolute or relative path to the workspace root. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it never says the scan is read-only, non-destructive, or that it only reports results without deleting. 'Scan' implies detection, but that is an inference rather than a disclosed trait; nothing about side effects, scope limits, or result shape is stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the verb and target, with no filler. It is efficient but so terse that it omits useful context rather than wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description should say what the scan returns (a report/list of candidates?) and confirm it makes no changes. It covers the object of the scan well but leaves the outcome and safety profile implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including a good explanation of minAgeMinutes and the rationale for avoiding in-use files. The description's 'optional file age threshold' merely restates the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (scan) plus the resource (target workspace) and enumerates what it looks for: dangling test outputs, agent scratches, bloated caches. It is clear it's a detection tool, implicitly distinct from clean_sandbox_artifacts, though the description never names that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not guidance, and no routing to clean_sandbox_artifacts or inspect_dangling_dev_ports. The scan-then-clean workflow is only inferable from the sibling names, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.0- First observed
clean_sandbox_artifacts - First observed
inspect_dangling_dev_ports - First observed
scan_sandbox_artifacts
TDQS
A3.5/5.0
Scored across 3 tools
Disambiguation5/5
Each tool has a clearly distinct role: scan detects artifacts, clean removes them, and inspect targets orphaned development ports. There is no meaningful overlap between artifact detection, artifact cleanup, and port inspection.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern: scan_sandbox_artifacts, clean_sandbox_artifacts, and inspect_dangling_dev_ports. The convention is predictable and readable.
Tool Count5/5
Three tools are well-scoped for a focused sandbox cleaner, with each operation earning its place. The surface covers detection, cleanup, and a related diagnostics check without bloat.
Completeness4/5
The core artifact lifecycle is covered by scan and clean, and port inspection adds useful diagnostics. However, dangling ports can only be detected, not terminated or reclaimed, leaving a minor operational gap.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Lets coding agents check their own code for leaked secrets, risky dependencies and AI-code mistakes
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides AI coding agents with structured, evidence-based diagnostics about the local development environment, detecting tech stack, runtime mismatches, dependency state, services, ports, and Git status without exposing secrets or using network calls.10Apache 2.0
- AlicenseAqualityAmaintenanceEnables AI assistants to audit and clean development workspaces safely by detecting reclaimable artifacts, exposed .env files, and potential secret leaks.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables autonomous coding agents to check memory, CPU, and disk headroom before heavy work, emitting cgroup-aware NEAR_OOM_THRESHOLD alerts that let them back off before an OOM kill or context blowup. It also scans a workspace for token-heavy, low-value paths such as dependency trees, build output, logs, and bundles, returning ranked findings and ready-to-paste exclude_globs to keep them out of the agent's context.MIT