Setup Agent - Dev Environment Setup

Give me a repo link—I’ll set up the environment.

SetupAgent analyzes a GitHub repository, generates a reproducible setup plan, optionally installs system/tooling dependencies, and verifies the project can build or start.
It works standalone from the CLI and can also be driven by an AI assistant via MCP.

---

Table of Contents

• What It Solves
• Key Features
• Supported Stacks & OS
• Requirements
• Install
• Quick Start (CLI)
• Artifacts
• MCP Integration (Optional)
• How It Works
• Security Model
• Roadmap
• FAQ

---

What It Solves

• Unknown or mismatched toolchains (JDK/Maven/Gradle, Python/pip, Node/npm/yarn/pnpm)
• Version drift and missing system packages
• Manual IDE tweaks (e.g., Lombok / annotation processing)
• Container vs. local environment confusion

---

Key Features

• Auto-detection: Java, Python, Node.js; build tools; container files (Dockerfile, docker-compose.yml, .devcontainer/)
• Reproducible plan: Emits plan.yaml (machine) + SetupPlan.md (human)
• Dry-run by default: Preview exactly what would run; real execution only with --assume-yes
• Safe execution: Strict command allowlist, timeouts, and output truncation
• Verification: Runs language-appropriate tests/build (./mvnw test, pytest, npm test)
• Reports: Summarizes results and next steps in SetupReport.md
• MCP integration: Exposes safe tools so an AI can orchestrate setup

---

Supported Stacks & OS

Languages / Build

• Java (Maven/Gradle; Lombok guidance)
• Python (pip/uv)
• Node.js (npm/yarn/pnpm)

Operating Systems

• Ubuntu/Debian (apt) — fully supported for execution
• macOS (Homebrew) and Windows (winget/choco) — interfaces stubbed and ready to extend

Containers

• If container files are present, a container plan is suggested alongside a local plan

---

Requirements

• Python 3.10+
• Git
• Ubuntu/Debian for real execution (apt). macOS/Windows execution paths can be added later.

---

Install

git clone https://github.com/yourusername/setup_agent.git
cd setup_agent
python3 -m venv .venv
source .venv/bin/activate
pip install -r setup_agent/requirements.txt

Tip: It is safe to start in dry-run mode. No system changes are made unless you pass --assume-yes.

---

Quick Start (CLI)

# Show help
python -m setup_agent.cli --help
python -m setup_agent.cli setup --help

# Preview (dry-run): plan + report, no system changes
python -m setup_agent.cli setup https://github.com/spring-projects/spring-petclinic --dry-run

# More examples (preview)
python -m setup_agent.cli setup https://github.com/pallets/flask --dry-run
python -m setup_agent.cli setup https://github.com/vercel/next.js --dry-run

# Execute on Ubuntu/WSL (installs apt packages, builds, verifies)
sudo -v  # warm up sudo to avoid prompts
python -m setup_agent.cli setup https://github.com/spring-projects/spring-petclinic --assume-yes

---

Artifacts

• plan.yaml — machine-readable plan
• SetupPlan.md — human-readable steps (auto vs. manual)
• SetupReport.md — execution & verification summary
• logs/setup-*.log — detailed logs

---

MCP Integration (Optional)

Expose SetupAgent’s safe local tools to an AI assistant.

Start the local MCP server

# Run the stdio MCP server
python -m setup_agent.mcp_server

Register with Claude Desktop (user scope)

# From a terminal on the same machine as Claude Desktop
claude mcp add --scope user setup-agent python -m setup_agent.mcp_server

Check status in Claude chat with /mcp.

Exposed tools

• git.clone
• fs.find / fs.read
• shell.run (allowlisted commands only)
• pkg.install (apt; others stubbed)
• ide.todo
• artifacts.save

Prefer HTTP instead of stdio? Adapt the server entry point and register the HTTP endpoint with your client.

---

How It Works

1. Scan — Clone and inspect the repository for language/build/container signals
2. Infer — Determine required tools/versions (e.g., openjdk-17-jdk, pip/uv, npm/yarn/pnpm)
3. Plan — Emit plan.yaml and SetupPlan.md (container and local paths when available)
4. Execute — Run allowlisted commands only. Default is dry-run; real execution with --assume-yes
5. Verify — Run project tests/build targets
6. Report — Summarize actions, results, and remediation tips

---

Security Model

• Default dry-run — no changes without --assume-yes
• Allowlist — only safe prefixes are executed:
  git, mvn/./mvnw, gradle/./gradlew, npm/yarn/pnpm, python/pip/uv, apt/sudo apt, docker/docker compose, dotnet
• Timeouts & truncation — prevents runaway processes and oversized logs
• Least privilege — sudo only when installing system packages

---

Roadmap

• macOS (brew) and Windows (winget/choco) execution paths
• Additional stacks: Go, Rust, .NET
• Container health checks and port probes
• IDE automation helpers (IntelliJ / VS Code)

---

FAQ

Do I have to use MCP/AI?
No. The CLI works independently. MCP simply lets an AI drive the same safe tools.

Will it modify my system?
Not unless you pass --assume-yes. Dry-run reads and plans only.

Can I use this for production?
This project targets developer environments. For production, prefer containerized or IaC approaches.