workbench-mcp

workbench-mcp is a Python FastMCP server for controlled local workspace inspection, bounded file reads/searches, guarded text patching, allowlisted test execution, read-only Git status, approved artifact collection, and workspace diagnostics.

It is intended for developer workbenches where an MCP client needs useful repository context without receiving unrestricted filesystem or shell access.

Problem Statement

AI-assisted development tools often need to inspect files, run tests, and collect reports. Giving those tools raw shell access or broad host filesystem access is risky. This project wraps common development actions in typed MCP tools backed by explicit workspace, artifact, command, timeout, output, and redaction controls.

Related MCP server: BridgeDesk

Project Status

Status: v0.1.0 release preparation on branch codex/workbench-mcp-v1.

Implemented and locally verified:

• stdio FastMCP server startup.

• In-memory and stdio MCP client/server smoke tests.

• Docker image build, direct container smoke test, Compose config, and Compose smoke workflow.

• Reproducible public demo that creates a temporary Git workspace and writes a JSON report.

• GitHub Actions CI is green for the latest pushed Phase 7 commit 34fc81ae32e4404f01f3f460b43e6508e108421d in run 29778875177.

• Local final-audit fixes after that pushed commit require a new CI run after push.

Not implemented:

• HTTP or Streamable HTTP transport for this project.

• Complete arbitrary-code execution sandboxing.

• Package publishing, Docker image publishing, Git tags, or GitHub releases.

Feature Overview

• Workspace metadata through workspace_info.

• Directory listing and UTF-8 text reads bounded to WORKSPACE_ROOT.

• Text search with glob, case-sensitivity, result, and output limits.

• One guarded expected-content text replacement through apply_patch when READ_ONLY_MODE=false.

• Allowlisted command execution using argument arrays and shell=False.

• Named predefined test commands with JSON reports under the artifact root.

• Read-only Git status using non-mutating Git commands.

• Approved artifact collection from category-specific artifact directories.

• Diagnostic findings for workspace, artifact, executable, Git, and transport state.

• Secret-pattern and host-root redaction before MCP-facing responses.

Architecture

flowchart TD
    Client["MCP client"] --> Transport["FastMCP stdio transport"]
    Transport --> Server["workbench_mcp.server.create_server"]
    Server --> ToolLayer["Typed MCP tool/resource layer"]
    ToolLayer --> Services["Service layer"]
    Services --> Config["Validated WorkbenchConfig"]
    Services --> Security["Security helpers"]
    Security --> Workspace["WORKSPACE_ROOT boundary"]
    Security --> Artifacts["ARTIFACT_DIRECTORY boundary"]
    Services --> Process["subprocess with shell=False"]
    Services --> Git["read-only git status"]
    ToolLayer --> Errors["safe ToolError conversion and redaction"]

More detail: docs/architecture.md.

Registered MCP Tools

These are the exact tool names registered by src/workbench_mcp/tools/common.py and verified by tests/unit/test_mcp_server.py.

No destructive Git tools, delete-file tools, shell tools, or unrestricted command tools are registered.

Server-Information Resource

Exact resource registration:

Payload keys returned by server_information_payload:

{
  "package_version": "0.1.0",
  "server_capabilities": {
    "workspace_inspection": true,
    "filesystem_read": true,
    "text_search": true,
    "controlled_text_patch": false,
    "allowlisted_commands": [],
    "predefined_tests": [],
    "git_status": true,
    "artifact_collection": true,
    "diagnostics": true
  },
  "registered_tool_names": [
    "workspace_info",
    "list_files",
    "read_file",
    "search_text",
    "apply_patch",
    "run_command",
    "run_tests",
    "git_status",
    "collect_artifact",
    "diagnose_workspace"
  ],
  "active_safety_limits": {
    "max_file_size_bytes": 1048576,
    "max_command_seconds": 30,
    "max_output_bytes": 1048576
  },
  "read_only_status": true,
  "sanitized_workspace_metadata": {
    "name": "workbench-mcp",
    "exists": true,
    "is_directory": true
  },
  "supported_transports": ["stdio"]
}

Values reflect the active configuration. The tool list and supported transports are fixed for this release.

Installation With uv

Install uv, then install the locked project environment:

uv sync --frozen --all-groups
uv run python --version
uv run workbench-mcp --version

On this Windows verification shell, bare uv is not on PATH; the equivalent verified command prefix is:

& $env:APPDATA\Python\Python313\Scripts\uv.exe run python --version

Configuration Reference

Configuration loads from defaults, optional TOML via WORKBENCH_MCP_CONFIG, and environment variables. Environment variables override TOML values.

Example TOML:

[workbench_mcp]
workspace_root = "."
read_only_mode = true
max_file_size_bytes = 1048576
max_command_seconds = 30
max_output_bytes = 1048576
allowed_commands = [{ name = "python", executable = "python" }]
test_commands = [{ name = "smoke", command = ["python", "-c", "print('ok')"] }]
artifact_directory = "artifacts"
secret_patterns = ["(?i)(api[_-]?key|token|secret|password)\\s*[:=]\\s*[^\\s]+"]
log_level = "INFO"

Verified Stdio Quick Start

For an MCP client, configure stdio with:

{
  "command": "uv",
  "args": ["run", "workbench-mcp", "--transport", "stdio"],
  "env": {
    "WORKSPACE_ROOT": "/path/to/workspace",
    "ARTIFACT_DIRECTORY": "/path/to/workspace/artifacts",
    "READ_ONLY_MODE": "true"
  }
}

Local stdio verification command:

uv run pytest tests/e2e/test_mcp_stdio.py

Do not configure HTTP ports for this project; HTTP is not implemented or tested here.

Verified Docker Quick Start

Build and smoke-test the local image:

docker build -t workbench-mcp:local .
uv run python scripts/run-container-smoke.py --image workbench-mcp:local

Compose smoke workflow:

mkdir -p .workbench-demo/workspace .workbench-demo/artifacts
printf 'hello compose\n' > .workbench-demo/workspace/smoke.txt
docker compose config
docker compose run --rm --build workbench-mcp-smoke

PowerShell equivalent for the mount preparation:

New-Item -ItemType Directory -Force .workbench-demo\workspace, .workbench-demo\artifacts | Out-Null
Set-Content -LiteralPath .workbench-demo\workspace\smoke.txt -Value "hello compose"

The container defaults to stdio, non-root UID/GID 10001:10001, no published ports, no host networking, no Docker socket mount, dropped Linux capabilities in Compose, and no-new-privileges:true in smoke workflows.

Demo

Run the public reproducible demo:

uv run python scripts/run-demo.py

The demo creates a temporary Git workspace, writes deterministic files, configures the real server, invokes the MCP tools through a FastMCP client, runs an approved test, applies one controlled patch, demonstrates a blocked traversal attempt, writes artifacts/demo/workbench-demo-report.json, prints a short summary, and cleans up the temporary workspace.

Testing Commands

uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -rs
uv run pytest --cov=workbench_mcp --cov-report=term-missing
uv build
uv run pytest tests/e2e/test_mcp_stdio.py
uv run python scripts/run-demo.py

Docker checks:

docker build -t workbench-mcp:local .
uv run python scripts/run-container-smoke.py --image workbench-mcp:local
docker compose config
docker compose run --rm --build workbench-mcp-smoke

Security Model

• Deny by default for commands and writes.

• Workspace paths are resolved with pathlib and must remain inside WORKSPACE_ROOT.

• Artifact paths are resolved inside category directories under ARTIFACT_DIRECTORY.

• Symlink escapes, parent traversal, absolute-path escapes, oversized files, binary text reads, shell operators, executable paths, command timeouts, bounded output capture, and truncation are covered by source checks and tests.

• Expected service errors are converted to sanitized MCP ToolError messages.

• Git behavior is read-only, bounded by the configured command timeout/output limit, and disables external diff execution for diff-stat inspection.

• Docker smoke workflows use a non-root runtime user and avoid privileged mounts.

This is not a complete arbitrary-code execution sandbox. Allowlisting a powerful executable such as python, pytest, or git still grants that executable whatever behavior it can perform inside the configured workspace and OS permissions.

More detail: docs/threat-model.md and SECURITY.md.

Known Limitations

• Only stdio transport is implemented and verified.

• HTTP and Streamable HTTP are not configured, exposed, or tested by this project.

• The server relies on host OS permissions; it is not a VM, kernel sandbox, or container escape prevention system.

• Windows symlink security tests skip when the OS denies symlink creation with WinError 1314; Linux CI runs those tests explicitly.

• Command safety depends on narrow allowlists. Do not allowlist broad interpreters for untrusted workspaces unless the surrounding environment is disposable.

• Artifact collection supports approved text suffixes only.

• Docker and Compose smoke workflows are finite verification commands, not a long-running hosted service.

Troubleshooting

• uv not found: install uv or use the full uv.exe path on Windows as shown above.

• workspace_root does not exist: set WORKSPACE_ROOT to an existing directory.

• artifact_directory does not exist: create the directory or set ARTIFACT_DIRECTORY.

• writes are blocked because READ_ONLY_MODE is enabled: set READ_ONLY_MODE=false only for workspaces where controlled patching is acceptable.

• executable is not allowlisted: add a bare executable name to ALLOWED_COMMANDS.

• Docker bind-mount permission failures on Linux: run smoke workflows with a host-compatible UID/GID, as documented in docs/runbook.md.

• HTTP port questions: there is no project HTTP listener in this release.

Evidence And Docs

• PROJECT_EVIDENCE.md

• docs/architecture.md

• docs/threat-model.md

• docs/runbook.md

• docs/debugging.md

• docs/failure-catalog.md

• docs/release-checklist-v0.1.0.md

• SECURITY.md

• CONTRIBUTING.md