alchemax-plugin 0.1.0__tar.gz

alchemax_plugin-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Terraform
+*.tfstate*
+.terraform
+.terraform.lock.hcl
+terraform.tfvars.json
+*.pem
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+build
+develop-eggs
+dist
+downloads
+eggs
+.eggs
+lib
+lib64
+parts
+sdist
+var
+wheels
+*.egg-info
+.installed.cfg
+*.egg
+.pytest_cache
+.venv
+venv
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# OS
+.DS_Store
+.env
+.env.local
+*.tar.gz

alchemax_plugin-0.1.0/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy project files
+COPY . .
+
+# Install dependencies
+RUN pip install --no-cache-dir -e .
+
+# Install FastAPI and uvicorn
+RUN pip install --no-cache-dir fastapi uvicorn[standard]
+
+# Expose port
+EXPOSE 8000
+
+# Run API server
+CMD ["python", "api.py"]

alchemax_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: alchemax-plugin
+Version: 0.1.0
+Summary: Standalone MCP plugin for deploying Docker apps to AWS EC2
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.34
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: uvicorn[standard]>=0.30

alchemax_plugin-0.1.0/README.md

@@ -0,0 +1,544 @@
+# Alchemax Plugin
+
+**Standalone Python MCP toolkit for deploying Docker applications to AWS EC2.**
+
+A lightweight, infrastructure-as-code plugin that provisions a single EC2 instance per workspace and manages multi-app deployments via docker-compose + Terraform. Zero SaaS, zero dashboard—infrastructure lives in your AWS account.
+
+**Use cases:**
+- Deploy multiple Docker services (API, worker, scheduler) to one EC2
+- One-command deploys with dependency ordering
+- Infrastructure as code (Terraform) with optional app manifests (alchemax.json)
+- Local state, no remote backend required
+- API logging & health checks via SSM (no SSH needed)
+
+## Installation
+
+### Claude Code
+
+```bash
+# No install needed — uvx runs it on demand
+claude mcp add alchemax-plugin -- uvx alchemax-plugin
+```
+
+Or install permanently first:
+
+```bash
+uv tool install alchemax-plugin
+claude mcp add alchemax-plugin -- alchemax-plugin
+```
+
+### Opencode
+
+No install needed — use `uvx` directly in your `opencode.json`:
+
+```json
+{
+  "mcpServers": {
+    "alchemax-plugin": {
+      "command": "uvx",
+      "args": ["alchemax-plugin"]
+    }
+  }
+}
+```
+
+Or install permanently:
+
+```bash
+uv tool install alchemax-plugin
+```
+
+Then add to your project's `opencode.json`:
+
+```json
+{
+  "mcpServers": {
+    "alchemax-plugin": {
+      "command": "alchemax-plugin"
+    }
+  }
+}
+```
+
+Or run directly without installing:
+
+```json
+{
+  "mcpServers": {
+    "alchemax-plugin": {
+      "command": "uvx",
+      "args": ["alchemax-plugin"]
+    }
+  }
+}
+```
+
+### Manual (any MCP client)
+
+```bash
+pip install alchemax-plugin
+# then point your MCP client at: alchemax-plugin
+```
+
+## Setup
+
+### 1. AWS Credentials
+
+```bash
+aws configure
+# or use AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars
+```
+
+### 2. Docker Hub (for building images)
+
+```bash
+export DOCKER_HUB_USERNAME=your-username
+docker login
+```
+
+### 3. Initialize Workspace
+
+```bash
+alchemax-plugin setup prod us-east-1
+# Creates ~/.alp/prod/terraform/ with all infrastructure code
+```
+
+## Quick Start Examples
+
+**Single app from Docker image:**
+```bash
+alchemax-plugin deploy_app prod myapp docker.io/user/myapp:v1.0.0 8000
+```
+
+**Single app from source (auto-build):**
+```bash
+alchemax-plugin deploy_from_source prod myapp /path/to/source 8000
+```
+
+**Multi-app project with manifest:**
+```bash
+# In your project root, create alchemax.json (see below)
+alchemax-plugin deploy_all prod /path/to/project
+```
+
+**List all workspaces:**
+```bash
+alchemax-plugin list_workspaces
+```
+
+**View instance status & logs:**
+```bash
+alchemax-plugin get_status prod
+alchemax-plugin get_logs prod backend 50
+```
+
+**Tear down:**
+```bash
+alchemax-plugin destroy prod
+# EBS volume has prevent_destroy; see gotchas below for removal
+```
+
+## Project Manifest (alchemax.json)
+
+Multi-app projects define an optional `alchemax.json` in the project root. Without it, use `deploy_app()` / `deploy_from_source()` for single apps.
+
+```json
+{
+  "name": "cloud-suite",
+  "workspace": {
+    "region": "us-east-1",
+    "instance_type": "t3.micro",
+    "ebs_volume_size": 10,
+    "env": {
+      "LOG_LEVEL": "info",
+      "DB_HOST": "localhost"
+    }
+  },
+  "apps": [
+    {
+      "id": "backend",
+      "port": 8000,
+      "path": "./api",
+      "dockerfile": "Dockerfile",
+      "tag": "v1.0.0",
+      "health_check": "/api/health",
+      "env": {
+        "DB_PATH": "/data"
+      },
+      "secrets": ["DATABASE_URL", "API_KEY", "JWT_SECRET"],
+      "depends_on": []
+    },
+    {
+      "id": "worker",
+      "port": 8001,
+      "path": "./worker",
+      "tag": "v1.0.0",
+      "health_check": "/health",
+      "depends_on": ["backend"]
+    }
+  ]
+}
+```
+
+### Schema
+
+- **`workspace.env`** — committed env vars (LOG_LEVEL, DB_HOST, etc.). Safe to commit.
+- **`apps[].env`** — per-app committed vars. Merged with workspace.env at deploy.
+- **`apps[].secrets`** — list of secret names. Values pulled from:
+  1. Process environment (`export DATABASE_URL=...`)
+  2. `.env.local` file in project root (git-ignored)
+  3. AWS SSM Parameter Store (future)
+  
+  **Never commit secret values to alchemax.json.**
+
+- **`apps[].tag`** — Docker image tag. Not `:latest` (enables rollback + version tracking).
+- **`apps[].depends_on`** — array of app IDs. Deployment order enforced + passed to docker-compose.
+- **`apps[].health_check`** — optional HTTP endpoint for readiness checks (e.g., `/api/health`).
+
+### Secrets Workflow
+
+```bash
+# 1. Define secret names in manifest
+# "secrets": ["DATABASE_URL", "API_KEY"]
+
+# 2. Set values locally
+export DATABASE_URL="postgres://localhost/db"
+export API_KEY="secret-value"
+
+# 3. Or write .env.local (git-ignored)
+echo "DATABASE_URL=postgres://localhost/db" > .env.local
+echo "API_KEY=secret-value" >> .env.local
+
+# 4. Deploy — secrets injected into containers
+alchemax-plugin deploy_all prod /path/to/project
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Your Project (git repo)                                         │
+│  ├── api/                  (FastAPI, Express, Django, etc.)     │
+│  ├── worker/               (Python, Node, Go worker)           │
+│  ├── alchemax.json         (optional multi-app manifest)       │
+│  └── .env.local            (git-ignored, secrets)              │
+└──────────┬──────────────────────────────────────────────────────┘
+           │ alchemax-plugin CLI or MCP
+           ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ ~/.alp/<workspace>/                                             │
+│  ├── terraform/             (Terraform state + .tf files)      │
+│  ├── terraform.tfvars.json  (generated from apps.json)         │
+│  └── apps.json              (deployed app list + metadata)     │
+└──────────┬──────────────────────────────────────────────────────┘
+           │ Terraform Apply
+           ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ AWS Account                                                     │
+│ ├── EC2 Instance (t3.micro, Ubuntu 22.04)                     │
+│ │   ├── Docker Daemon                                          │
+│ │   │   ├── Container: backend (port 8000)                    │
+│ │   │   ├── Container: worker (port 8001)                     │
+│ │   │   └── ...                                                │
+│ │   ├── nginx reverse proxy (:80, :443)                        │
+│ │   └── /data/ (EBS volume, prevent_destroy)                  │
+│ ├── VPC + Security Group (allow 22, 80, 443, app ports)       │
+│ ├── EIP (elastic IP for stable public IP)                     │
+│ ├── IAM Role (SSM access for get_logs)                        │
+│ └── Route53 (optional custom domain + TLS)                    │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+One EC2 per workspace. All apps on the same instance via docker-compose.
+
+## Tools Reference
+
+### Discovery
+
+**`list_workspaces()`**
+List all workspaces with live AWS EC2 data (state, public IP, app count).
+```bash
+alchemax-plugin list_workspaces
+```
+
+**`get_project_info(project_path)`**
+Read alchemax.json and return app metadata + deployment order.
+```bash
+alchemax-plugin get_project_info /path/to/project
+```
+
+### Setup
+
+**`setup(workspace, region?)`**
+Initialize workspace. Creates ~/.alp/<workspace>/terraform/, copies .tf files, runs `terraform init`.
+```bash
+alchemax-plugin setup prod us-east-1
+alchemax-plugin setup staging eu-west-1
+```
+
+### Deployment
+
+**`deploy_app(workspace, name, image, port, env?)`**
+Deploy a Docker image to the workspace.
+```bash
+alchemax-plugin deploy_app prod api docker.io/user/myapi:v1.0.0 8000 \
+  '{"LOG_LEVEL": "info"}'
+```
+
+**`deploy_from_source(workspace, name, source_path, port?, env?)`**
+Build Docker image from source (auto-detects language), push to Docker Hub, deploy.
+```bash
+alchemax-plugin deploy_from_source prod backend /path/to/api 8000 \
+  '{"DEBUG": "false"}'
+```
+
+**`deploy_all(workspace, project_path, docker_hub_user?)`**
+Deploy all apps from alchemax.json in dependency order. Stops on first failure.
+```bash
+alchemax-plugin deploy_all prod /path/to/project
+```
+
+### Status & Logs
+
+**`get_status(workspace)`**
+Check EC2 instance state (running/stopped/not-found), public IP, uptime, app count.
+```bash
+alchemax-plugin get_status prod
+```
+
+**`get_logs(workspace, app_name, lines?)`**
+Fetch container logs via AWS SSM SendCommand (no SSH required).
+```bash
+alchemax-plugin get_logs prod backend 100
+alchemax-plugin get_logs prod worker 50
+```
+
+**`list_apps(workspace)`**
+List deployed apps in a workspace.
+```bash
+alchemax-plugin list_apps prod
+```
+
+### Management
+
+**`remove_app(workspace, name)`**
+Remove an app from the workspace and re-apply Terraform.
+```bash
+alchemax-plugin remove_app prod worker
+```
+
+**`configure_domain(workspace, domain)`**
+Point custom domain at the workspace EC2 instance (Route 53 + certbot TLS).
+```bash
+alchemax-plugin configure_domain prod myapp.example.com
+```
+
+**`destroy(workspace)`**
+Tear down all infrastructure (EC2, VPC, EBS, IAM). **EBS volume has `prevent_destroy` to guard against data loss.**
+```bash
+alchemax-plugin destroy prod
+# If destroy fails due to prevent_destroy:
+# terraform state rm aws_ebs_volume.data
+# alchemax-plugin destroy prod
+```
+
+## IAM Policy
+
+Attach this policy to your AWS user. Minimal permissions for alchemax-plugin:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ec2:*",
+        "iam:CreateRole",
+        "iam:CreateInstanceProfile",
+        "iam:AttachRolePolicy",
+        "iam:AddRoleToInstanceProfile",
+        "iam:GetRole",
+        "iam:GetInstanceProfile",
+        "iam:DeleteRole",
+        "iam:DeleteInstanceProfile",
+        "iam:RemoveRoleFromInstanceProfile",
+        "iam:DetachRolePolicy",
+        "iam:ListInstanceProfiles"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+## MCP Integration
+
+Use as an MCP server in Claude Desktop or other MCP clients:
+
+```json
+// ~/.claude/mcp_servers.json
+{
+  "alchemax-plugin": {
+    "command": "python",
+    "args": ["-m", "alchemax_plugin.server"]
+  }
+}
+```
+
+Then call tools via MCP:
+```
+Claude: deploy_all workspace=prod project_path=/path/to/project
+```
+
+## State & Data Persistence
+
+**State:**
+- `~/.alp/<workspace>/terraform/` — Terraform state (local, not remote)
+- `~/.alp/<workspace>/apps.json` — deployed app list + metadata
+- `~/.alp/<workspace>/terraform.tfvars.json` — generated from apps.json
+
+**Data:**
+- `/data/<app-name>/` — EBS volume mounted in each container
+- Persists across container restarts and even workspace teardown (prevent_destroy)
+- To delete data: manually delete EBS volume in AWS console or via CLI
+
+## Troubleshooting
+
+### "Docker buildx: permission denied"
+```bash
+docker logout
+docker login
+# Re-run deploy
+```
+
+### "Terraform state is locked"
+```bash
+# Find the lock table name in ~/.alp/<workspace>/terraform/
+aws dynamodb delete-item \
+  --table-name alchemax-tflock-xxxxx \
+  --key '{"LockID": {"S": "..."}}'
+```
+
+### "EBS volume has prevent_destroy"
+```bash
+cd ~/.alp/<workspace>/terraform/
+terraform state rm aws_ebs_volume.data
+terraform destroy  # or use CLI: alchemax-plugin destroy <workspace>
+```
+
+### Instance not responding / containers failing
+```bash
+alchemax-plugin get_logs prod backend 100
+alchemax-plugin get_status prod  # check EC2 state
+# SSH if needed:
+ssh -i ~/.alp/<workspace>/terraform/alp-key.pem ubuntu@<public-ip>
+```
+
+### App not reachable at public IP
+1. Check instance is running: `get_status`
+2. Check nginx routing: `get_logs prod` (look for 404 errors)
+3. Verify port mapping in `list_apps`
+4. Check docker-compose: SSH to instance, run `docker ps`
+
+### Env vars not set in container
+```bash
+# Verify in deployed apps.json
+cat ~/.alp/<workspace>/apps.json
+# If missing, re-deploy:
+alchemax-plugin deploy_app <workspace> <app> <image> <port> '<env-json>'
+```
+
+## Known Limitations
+
+- **Docker-only** — no Lambda, Cloud Run, or other runtimes. Cross-provider orchestration belongs in your orchestrator repo.
+- **Single EC2 per workspace** — all apps share the same instance (cost-efficient for small teams, not multi-tenant).
+- **No built-in monitoring** — hook it up to your own CloudWatch / Prometheus.
+- **`:latest` images** — tag images explicitly in manifests for rollback safety.
+- **No auto-scaling** — static instance. For variable load, manually scale up instance type.
+
+## Development
+
+### Running Tests
+
+```bash
+source .venv/bin/activate
+pytest tests/ -v
+```
+
+### Project Structure
+
+```
+alchemax_plugin/
+├── server.py        # MCP server + tool definitions (12 tools)
+├── metadata.py      # alchemax.json parsing + validation
+├── builder.py       # docker buildx + registry push
+├── runner.py        # Terraform CLI wrapper
+├── workspace.py     # ~/.alp/<workspace> state management
+├── tfstate.py       # apps.json ↔ terraform.tfvars conversion
+├── analyzer.py      # language/framework detection
+└── terraform/       # Terraform modules (6 .tf files + 2 templates)
+    ├── main.tf      # Providers + locals
+    ├── variables.tf # All configurable vars
+    ├── network.tf   # VPC, subnet, security group
+    ├── ec2.tf       # EC2 instance + IAM role
+    ├── ebs.tf       # EBS volume + SSH key
+    ├── outputs.tf   # Terraform outputs
+    ├── docker-compose.yml.tpl
+    ├── nginx.conf.tpl
+    └── init.sh      # EC2 user-data script
+
+tests/
+├── test_metadata.py    # 11 tests: parsing, validation, ordering
+├── test_workspace.py   # 4 tests: state management
+├── test_builder.py     # 4 tests: Docker image analysis
+└── test_analyzer.py    # 4 tests: language detection
+```
+
+### Adding a New Tool
+
+1. Add `@register_tool()` decorator with schema
+2. Implement function in `server.py`
+3. Add test in `tests/test_*.py`
+4. Update README
+
+Example:
+```python
+@register_tool(
+    "my_tool",
+    "Description of what it does.",
+    {
+        "type": "object",
+        "properties": {
+            "workspace": {"type": "string"},
+        },
+        "required": ["workspace"],
+    },
+)
+def my_tool(workspace: str) -> dict[str, Any]:
+    """Implementation."""
+    return {"success": True, "result": "..."}
+```
+
+### Modifying Terraform
+
+Terraform files are ported as-is from alchemax. Key constraints:
+- Local state only (no S3 backend)
+- alp- prefix for all IAM roles (avoid collisions)
+- docker-compose on t3.micro (adjust variables.tf for larger instances)
+- EBS prevent_destroy (data safety)
+- nginx reverse proxy on ports 80/443
+
+Changes to `.tf` files are picked up on next `deploy_all()` or `setup()`.
+
+## Contributing
+
+Contributions welcome. Maintain the "primitive, not platform" philosophy:
+- Keep it Docker-only
+- No cross-provider types
+- One EC2 per workspace
+- Keep state local (no remote backend)
+
+## License
+
+MIT

alchemax_plugin-0.1.0/alchemax_plugin/__init__.py

@@ -0,0 +1,3 @@
+"""Alchemax plugin: standalone MCP toolkit for Docker app deployment to AWS EC2."""
+
+__version__ = "0.1.0"

alchemax_plugin-0.1.0/alchemax_plugin/analyzer.py

@@ -0,0 +1,83 @@
+"""Source code language and framework detection."""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+class SourceAnalyzer:
+    """Analyzes source code for language, framework, and Dockerfile presence."""
+
+    @staticmethod
+    def analyze(source_path: Path) -> dict:
+        """Analyze source directory. Return lang, framework, has_dockerfile."""
+        if not source_path.exists():
+            return {"language": None, "framework": None, "has_dockerfile": False}
+
+        has_dockerfile = (source_path / "Dockerfile").exists()
+        if has_dockerfile:
+            return {"language": None, "framework": None, "has_dockerfile": True}
+
+        language, framework = None, None
+
+        # Check Node.js
+        pkg_json = source_path / "package.json"
+        if pkg_json.exists():
+            try:
+                with open(pkg_json) as f:
+                    data = json.load(f)
+                    deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+                    if "next" in deps:
+                        language, framework = "node", "next"
+                    elif "express" in deps:
+                        language, framework = "node", "express"
+                    elif "react" in deps:
+                        language, framework = "node", "react"
+                    else:
+                        language = "node"
+            except (json.JSONDecodeError, OSError):
+                language = "node"
+
+        # Check Python
+        if not language:
+            if (source_path / "requirements.txt").exists():
+                language = "python"
+                try:
+                    with open(source_path / "requirements.txt") as f:
+                        content = f.read()
+                        if "fastapi" in content:
+                            framework = "fastapi"
+                        elif "flask" in content:
+                            framework = "flask"
+                        elif "django" in content:
+                            framework = "django"
+                except OSError:
+                    pass
+
+            elif (source_path / "pyproject.toml").exists():
+                language = "python"
+                try:
+                    with open(source_path / "pyproject.toml") as f:
+                        content = f.read()
+                        if "fastapi" in content:
+                            framework = "fastapi"
+                        elif "flask" in content:
+                            framework = "flask"
+                        elif "django" in content:
+                            framework = "django"
+                except OSError:
+                    pass
+
+        # Check Go
+        if not language and (source_path / "go.mod").exists():
+            language = "go"
+
+        # Check Rust
+        if not language and (source_path / "Cargo.toml").exists():
+            language = "rust"
+
+        return {
+            "language": language,
+            "framework": framework,
+            "has_dockerfile": has_dockerfile,
+        }