Setup Agent MCP

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

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

Quick Start (CLI)

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

Register with Claude Desktop (user scope)

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.