dev-env-mcp

A local MCP (Model Context Protocol) server that gives coding agents a safe, structured way to manage Python environments inside a project workspace.

Instead of letting an agent run arbitrary shell commands, dev-env-mcp exposes a small, well-defined API for:

• selecting a project workspace
• creating/using a virtual environment inside that workspace
• running restricted pip operations in that venv
• freezing pinned dependencies to requirements.txt

---

Why this exists

Agents often struggle to reliably manage Python envs because:

• environment details are implicit (which interpreter? which venv?)
• shell command execution is powerful but risky
• installs can be slow/hang on Windows and cause inconsistent state

dev-env-mcp makes env management explicit and verifiable:

• all actions are scoped to a chosen workspace root
• the active venv is persisted per workspace

---

Key concepts

Workspace

A workspace is the project directory that the server is allowed to modify.
All file paths are sandboxed to the active workspace root.

Select it with:

• workspace_use(path)

The active workspace is persisted globally so the server can remember it across restarts.

Active venv

Inside each workspace, the server tracks which venv is currently active.
The active venv is persisted in:

<workspace>/.dev-env-mcp/state.json

---

Features

Workspace management

• workspace_use(path)
  • Selects the active workspace root (typically where pyproject.toml / .git lives)
  • All subsequent operations are restricted to this workspace

Virtual environment management

• env_create(path=".venv")
  • Creates a venv inside the active workspace and marks it as active
• env_use(path=".venv")
  • Selects an existing venv inside the active workspace and marks it as active

Restricted pip operations

• pip(action, packages=None, options=None, confirm=False)
  • Actions: install | uninstall | list | show | check
  • Runs python -m pip ... using the active venv python
  • Pip options are allowlisted
  • Uninstall requires confirm=true

Freezing dependencies

• freeze(path="requirements.txt")
  • Writes pinned requirements from the active venv to a file in the workspace

---

Reliability and stability

• Bounded execution: per-action timeouts + capped stdout/stderr.
• Post-condition verification: if pip/venv hangs after the desired state is reached, the server verifies the state, stops the process, and returns success with an audit trail.
• Process-tree termination: stops the full subprocess tree to avoid orphaned children.

---

Security model

This MCP is intentionally restrictive:

• ✅ No arbitrary command execution (no shell=True)
• ✅ Workspace sandboxing: all file paths must resolve inside the active workspace
• ✅ pip runs only via the active venv python (<venv>/python -m pip)
• ✅ pip options are allowlisted (unknown flags are rejected)
• ✅ destructive actions require explicit confirmation (confirm=true for uninstall)
• ✅ outputs are truncated to prevent log flooding
• ✅ audit log per workspace

Audit log:

<workspace>/.dev-env-mcp/audit.log

---

Requirements

• Python 3.10+ (tested on Windows)
• uv recommended (fast runner + reproducible installs)
• Runtime dependencies (from pyproject.toml):
  • mcp[cli]
  • psutil

---

Run the server (stdio transport)

This server is intended to be started by an MCP client (Codex / Cursor / Inspector) using stdio.

From the repo root:

uv run server.py

If you run it manually, it will wait for MCP client messages on stdin.

---

Example client workflow (tool-call sequence)

Typical agent flow:

1. Select the project workspace
2. Create a venv
3. Install dependencies
4. Freeze requirements

Example calls:

• workspace_use("C:\\path\\to\\project")
• env_create(".venv")
• pip(action="install", packages=["requests", "python-dotenv"])
• freeze("requirements.txt")

---

Project structure

dev-env-mcp/
  dev_env_mcp/
    server.py        # MCP tool definitions and orchestration
    workspace.py     # workspace root detection + sandbox path resolver
    state.py         # per-workspace + global persistent state
    audit.py         # JSONL audit logging
    runner.py        # safe subprocess runner (timeouts, caps, process-tree kill)
    venv_ops.py      # venv create/use helpers (+ optional soft verify)
    pip_ops.py       # allowlisted pip actions + verification-based early exit
    freeze.py        # requirements.txt generation
    config.py        # timeouts, caps, allowlists
  server.py          # entrypoint
  pyproject.toml
  README.md

---

Notes / limitations

• This server intentionally supports a narrow set of operations.
• It does not modify global Python installations.
• It does not support conda/poetry by design.
• For very large packages, installs may still take time — the goal is to be safe, predictable, and verifiable.

---

License

MIT