@digitalocean/mcp 1.0.13 → 1.0.14

package/apps/docs/vercel-migration-guide.md

@@ -0,0 +1,651 @@
+# Vercel to App Platform Migration Instructions
+
+You are assisting with migrating applications from Vercel to DigitalOcean App Platform using MCP servers. Follow these instructions carefully to ensure a smooth migration.
+
+## Initial Setup
+
+First, ask the user for the name of the Vercel app they want to migrate.
+
+**Note:** You can repeat this migration process for each additional app they want to move over.
+
+Then verify:
+- You have access to **Vercel MCP server** and **DigitalOcean MCP server**
+- **Vercel CLI is installed** (`vercel` command available) - **Required for retrieving environment variables**
+- Check if the current directory is a github repository and it is the same as the project that needs to be migrated
+- Clone the repository to local disk if code change is needed
+- User has confirmed they want to proceed with migration
+
+**Important:** The Vercel CLI is required because the Vercel MCP server does not provide environment variables. Make sure the user has:
+1. Installed Vercel CLI: `npm i -g vercel`
+2. Authenticated: `vercel login`
+
+**Note:** These instructions use a hybrid approach:
+- **Vercel CLI:** Required for environment variables and app inspection
+- **Vercel MCP server:** For project information (where available)
+- **DigitalOcean MCP server:** Primary method for App Platform operations
+- **Fallback options:** `doctl` CLI or [DigitalOcean REST API](https://docs.digitalocean.com/reference/api/digitalocean/)
+
+## Relevant App Platform Documentations
+
+- [llms.txt](https://docs.digitalocean.com/products/app-platform/llms.txt)
+- [nodejs specific buildpack instructions](https://docs.digitalocean.com/products/app-platform/reference/buildpacks/nodejs/)
+- [App Spec reference](https://docs.digitalocean.com/products/app-platform/reference/app-spec/)
+
+## Migration Process
+
+### Step 1: Get App Information
+
+#### 1.1 Prepare Local Environment and Pull Environment Variables
+
+1. **Create a local migration folder:**
+   - Pattern: `./vercel-migration/<vercel-app-name>-migration/`
+   - Example: `mkdir -p ./vercel-migration/my-app-migration`
+   - Navigate to it: `cd ./vercel-migration/<vercel-app-name>-migration/`
+
+2. **Link to Vercel project (if not already linked):**
+   - Check if already linked: look for `.vercel` directory
+   - If NOT linked, run: `vercel link --project <your-project-name> -y`
+   - If already linked, skip this step to avoid double linking
+
+3. **Pull environment variables from Vercel:**
+   - Ask the user which environment to pull from: production, development, preview, or other
+   - Run: `vercel env pull .env.<environment> --environment=<environment>`
+   - Examples:
+     - Production: `vercel env pull .env.production --environment=production`
+     - Development: `vercel env pull .env.development --environment=development`
+     - Preview: `vercel env pull .env.preview --environment=preview`
+   - Verify the file was created: `ls -la .env.<environment>`
+   - If unable to pull environment variables, leave them blank or empty when creating the App Platform app
+
+#### 1.2 Get App Details Using Vercel CLI
+
+1. **Get app information:**
+   - Use `vercel inspect <app-name>` or `vercel ls` to find the app
+
+2. **For this app, collect:**
+   - App name and ID
+   - GitHub/GitLab/BitBucket repository URL. This can also be obtained via Vercel MCP.
+   - Current deployment branch
+   - Build command
+   - Output directory (only for static sites)
+   - Root directory / source_dir for monorepos
+   - Node.js version or runtime
+   - **Custom domains** (list all domains attached to this app, including apex and subdomains)
+   - Any serverless function routes (paths under `/api/*`)
+   - Cron job configurations
+
+3. **Verify environment variables:**
+   - Check that `.env.<environment>` file exists in your migration folder
+   - All environment variables should be transferred as it is. Do not change the names.
+
+3. **Show the user** what you found and confirm they want to proceed
+   - Include the list of domains that will need DNS updates
+   - **Note:** Build and run commands will be validated in the next step by checking the repository
+
+4. If the app fails to deploy, fetch logs
+   - [Retrieve Deployment Logs](https://docs.digitalocean.com/reference/api/digitalocean/#tag/Apps/operation/apps_get_logs)
+   - Or ask the user to provide build or deploy logs for analysing the error and fix it.
+
+### Step 2: App Migration
+
+Follow these steps to migrate the app:
+
+#### 2.1 Project settings and Build Configuration
+
+**Inspect the repository to understand project structure and let App Platform buildpack auto-detect build/run commands**
+
+1. **Fetch and inspect package.json from the repository:**
+   - If monorepo or source_dir is specified: look at `[source_dir]/package.json`. Deploy them as separate components per app.
+   - If root level app: look at root `package.json`
+   - Identify the framework from dependencies (Next.js, React, Vue, Express, etc.)
+   - Note if there's a "build" script and "start" script in the scripts section
+   - Check the "engines" field for Node.js version requirements
+
+2. **Check Vercel configuration for custom settings:**
+   - Look in `vercel.json` for `buildCommand`, `outputDirectory`, or `framework` settings
+   - Check Vercel project settings for any custom build/install commands
+   - Note the framework detected by Vercel
+   - If Vercel uses custom commands, consider using them; otherwise leave empty for buildpack auto-detection
+
+3. **Validation before migration:**
+
+   **Project Structure:**
+   - Verify package.json exists at the correct location (root or source_dir)
+   - Check for package-lock.json or yarn.lock (for dependency consistency)
+   - For monorepos: verify source_dir path is correct relative to repository root
+   - Supported Node.js version in "engines" field in App Platform, (from https://docs.digitalocean.com/products/app-platform/reference/buildpacks/nodejs/#current-buildpack-version-and-supported-runtimes)
+
+   **Build/Run Commands - Prefer buildpack auto-detection:**
+   - **Default approach:** Leave build and run commands empty to let App Platform buildpack auto-detect based on framework
+   - **Only specify custom commands if:**
+     - Vercel uses non-standard build commands (check vercel.json)
+     - The project has custom scripts that differ from framework defaults
+     - You need to override buildpack defaults for specific reasons
+   - **Reference:** [App Platform Node.js buildpack documentation](https://docs.digitalocean.com/products/app-platform/reference/buildpacks/nodejs/) for auto-detection behavior
+
+   **For Static Sites:**
+   - Buildpack will auto-detect framework and build command
+   - Specify `output_dir` only if different from framework default (e.g., Next.js uses `out` for static export, not `.next`)
+   - Common output directories: `build`, `dist`, `out`, `public`, `_site`
+
+   **For Web Services:**
+   - Buildpack will auto-detect framework and start command
+   - Ensure app listens on `process.env.PORT` (App Platform injects this variable)
+   - Leave run command empty unless using a custom start script
+
+   **Install Command:**
+   - Buildpack auto-detects npm, yarn, or pnpm based on lockfile
+   - Only specify custom install command if needed (e.g., monorepo workspaces)
+
+   **If you need to specify commands:**
+   - Verify the script exists in package.json "scripts" section
+   - Or verify the framework package is in dependencies/devDependencies
+   - Ask the user to confirm if uncertain
+
+#### 2.2 Environment Variables
+
+1. **Use the environment variables pulled from Vercel in Step 1.1:**
+   - Read the `.env.<environment>` file from the migration folder
+   - Parse all variables from this file
+   - If no environment variables were pulled, leave blank or empty
+
+2. **Transform system variables:**
+   - Note: `VERCEL_URL`, `VERCEL_ENV`, any `VERCEL_GIT_*` and Vercel-specific system variables will NOT be available in App Platform
+   - Warn the user if the app depends on these variables
+
+3. **Prepare environment variables for App Platform:**
+   - Keep the same variable names (except for Vercel-specific ones)
+   - Mark sensitive variables (API keys, secrets, database passwords) as encrypted
+   - If unable to retrieve values, leave blank or empty
+
+#### 2.3 Component Type Detection
+
+Determine the appropriate App Platform component type based on the app's characteristics:
+
+**Static Sites:**
+- Pure static HTML/CSS/JS with no server-side logic
+- Static site generators (Gatsby, Hugo, Jekyll, etc.) that build to an output directory
+- React/Vue/Angular SPAs that are fully client-side rendered
+- **Create as Static Site component**
+- **Configuration needed:**
+  - `build_command`: Leave empty for buildpack auto-detection (or specify if custom)
+  - `output_dir`: Only if different from framework default (e.g., `build`, `dist`, `out`, `public`)
+
+**Web Services (Dynamic Sites):**
+- Next.js apps with API routes (files in `/pages/api/*` or `/app/api/*`)
+- Next.js apps using server-side rendering (SSR) or server components
+- Node.js/Express backend applications
+- Any app that needs a running server process
+- Apps with serverless functions in `/api/*` directory
+- **Create as Web Service component**
+- **Configuration needed:**
+  - `build_command`: Leave empty for buildpack auto-detection (or specify if custom)
+  - `run_command`: Leave empty for buildpack auto-detection (or specify if custom)
+  - No `output_dir` - the service runs continuously
+
+**How to determine:**
+1. Check if app has `/api/*` routes or serverless functions → **Web Service**
+2. Check if Next.js uses `getServerSideProps`, `getInitialProps`, or server components → **Web Service**
+3. Check if there's a server file (like `server.js`, `index.js` with Express) → **Web Service**
+4. If purely static output with no server logic → **Static Site**
+5. When in doubt, check the Vercel deployment type or framework detection
+
+**Multiple Components (Advanced):**
+- If the app has both static content AND API routes, you could separate into:
+  - Option A: Single web service (simplest - handles both static and API)
+  - Option B: Separate static site + web service components (more complex setup)
+- **Recommend Option A** unless user specifically wants separation
+
+#### 2.4 Feature Translation
+
+**Serverless Functions → Web Services or Functions:**
+- Vercel serverless functions in `/api/*` directory
+- Migrate to App Platform web service with API endpoints
+- OR guide user to use App Platform Functions
+- Note: Edge Functions are NOT directly supported - must refactor to web services
+
+**Cron Jobs:**
+- If Vercel has cron jobs invoking API endpoints
+- Create native App Platform cron jobs
+- Map cron expressions directly
+- Update to use App Platform internal URLs instead of `/api/*` HTTP endpoints
+
+**Middleware:**
+- Vercel `middleware.ts` is NOT supported in App Platform
+- Inform user they need to implement application-level middleware
+- This requires code changes in the application itself
+
+**ISR (Incremental Static Regeneration):**
+- NOT directly supported in App Platform
+- Inform user they have these options:
+  - Rebuild static site periodically using cron jobs
+  - Convert to server-side rendering (SSR)
+  - Use Spaces with cache persistence for future NFS support
+
+**Image Optimization:**
+- NOT natively supported in App Platform
+- Recommend these alternatives:
+  1. Cloudflare Images API (fully managed, paid after 5000 transformations)
+  2. Next.js `next/image` with Sharp in the same container
+  3. Dedicated worker or cron job with Sharp/libvips processing to Spaces
+  4. External image CDN service
+
+**Headers and Redirects:**
+- Vercel `headers` in `vercel.json` → Configure CORS in app spec or application middleware
+- Vercel `redirects` in `vercel.json` → App Platform routing rules in app spec
+- Vercel `rewrites` in `vercel.json` → Internal routing configuration in app spec
+
+**Edge Caching:**
+- Vercel has configurable multi-tier caching
+- App Platform has standard CDN caching (cannot disable or configure extensively)
+- Guide user to adjust cache headers in their application
+
+#### 2.5 Create App Platform App
+
+**Using DigitalOcean MCP (Primary Method):**
+
+1. **Use DigitalOcean MCP to create the app with configuration based on component type:**
+
+   **IMPORTANT: Only proceed with app creation after completing validation in step 2.1**
+
+   **For Static Sites:**
+   ```
+   - Repository: [GitHub/GitLab URL]
+   - Branch: [same as Vercel]
+   - Region: Choose closest to user's audience
+   - Build Command: [Leave empty for buildpack auto-detection, or use custom command from vercel.json if present]
+   - Output Directory: [Only specify if non-standard, e.g., "out" for Next.js static export]
+   - Source Directory: [if monorepo, the path to the app, e.g., "apps/frontend"]
+   - Environment Variables: [from .env.<environment> file pulled in Step 1.1]
+   - Component Type: Static Site
+   - Node Version: [from package.json engines field, if specified]
+   ```
+
+   **For Web Services (Dynamic Sites):**
+   ```
+   - Repository: [GitHub/GitLab URL]
+   - Branch: [same as Vercel]
+   - Region: Choose closest to user's audience
+   - Build Command: [Leave empty for buildpack auto-detection, or use custom command from vercel.json if present]
+   - Run Command: [Leave empty for buildpack auto-detection, or use custom command from vercel.json if present]
+   - Source Directory: [if monorepo, the path to the app, e.g., "apps/api"]
+   - Environment Variables: [from .env.<environment> file pulled in Step 1.1]
+   - Component Type: Web Service
+   - HTTP Port: [Leave as default, buildpack will detect. App must listen on process.env.PORT]
+   - Node Version: [from package.json engines field, if specified]
+   ```
+
+2. **Include the git commit hash** to ensure deployment matches Vercel's current state
+
+3. **Save the app spec to local filesystem:**
+   - Save the generated app spec as `./vercel-migration/<app-name>-migration/app-spec.yaml`
+   - This allows the user to manually create the app if automatic deployment fails
+
+**Alternative using CLI:** Use `doctl apps create` with an app spec YAML/JSON file
+
+4. **Set up any required databases:**
+   - If app uses Vercel Postgres → Create Managed PostgreSQL
+   - If app uses Vercel KV → Create Managed ValKey (Redis fork)
+   - Update connection strings in environment variables
+
+#### 2.6 Configure Domains
+
+**Using DigitalOcean MCP (Primary Method):**
+
+1. **Add custom domains to the App Platform app:**
+   - For each domain that was in Vercel, add it to the App Platform app
+   - App Platform will provide DNS configuration details
+   - Both apex domains (example.com) and subdomains (www.example.com) are supported
+   - App Platform will automatically provision SSL certificates
+
+2. **Provide DNS update instructions to the user:**
+   - Display these instructions as post deployment instruction.
+   - List each domain that needs to be updated
+   - Ask if the user wants to manage domains through DigitalOcean or keep it self managed (outside of DigitalOcean)
+   - If the user wants to Manage domains through DigitalOcean, then display the following message
+
+   ```md
+   ## Move DNS records to DigitalOcean
+
+   Update your DNS provider with our nameservers.
+
+   DigitalOcean Nameservers
+   - ns1.digitalocean.com
+   - ns2.digitalocean.com
+   - ns3.digitalocean.com
+   ```
+   - If the user wants to keep it self managed
+      - Get the default_ingress using `get_app` and replace the value in the following section, then display the following message
+   ```md
+   Add a new CNAME record using the provided alias to point your domain to your DigitalOcean app.
+
+   ## CNAME alias
+   $default_ingress
+
+   Check if CNAME flattening is supported for root domains. If your provider doesn't support this method, you can create an A record that points to your root domain.
+
+   ## A Records
+   - 162.159.140.98
+   - 172.66.0.96
+   ```
+   - Note: default ingress is only available after a successful deployment.
+
+3. **Important notes for the user:**
+   - DNS propagation can take up to 48 hours
+   - Wildcard domains (*.example.com) are also supported if needed
+
+**Alternative using CLI:** Use `doctl apps update <app-id>` to add domains
+
+#### 2.8 Automatic Deployment Troubleshooting
+
+**If deployment fails, follow this automatic recovery process:**
+
+1. **Check deployment status:**
+   - Use DigitalOcean MCP to get the deployment status
+   - Status will be either: ACTIVE, DEPLOYED (success) or FAILED, ERROR (failure)
+
+2. **Fetch deployment logs immediately:**
+   - Use DigitalOcean MCP to get build logs for the failed deployment
+   - Use DigitalOcean MCP to get runtime logs if available
+   - Use DigitalOcean REST API to get logs if MCP doesn't support retriving logs
+   - Ask the user to copy and paste the build and deploy error logs if REST api is not available for use
+   - Parse the error messages to identify the failure type
+
+3. **Analyze the error and attempt automatic fix:**
+
+   **For "command not found" or "script not found" errors:**
+   - **Automatic fix - prefer buildpack auto-detection:**
+     - **First attempt:** Leave build/run commands empty to let buildpack auto-detect
+     - This works for most standard frameworks (Next.js, React, Vue, etc.)
+     - If this fails, then try checking package.json for custom scripts:
+       - Read package.json from the migration folder at `./vercel-migration/<app-name>-migration/package.json`
+       - If Vercel used a custom script (check vercel.json), use that specific script
+       - If project has custom scripts that differ from framework defaults, specify those
+   - Update the app with corrected configuration and redeploy
+
+   **For "no start command" or run command errors:**
+   - **Automatic fix - prefer buildpack auto-detection:**
+     - **First attempt:** Leave run command empty to let buildpack auto-detect
+     - Buildpack will use framework defaults or package.json "start" script
+     - Only specify custom run command if buildpack auto-detection fails
+   - Update run command and redeploy
+
+   **For "output directory not found" errors:**
+   - **Automatic fix:**
+     - Check common output directories: `build`, `dist`, `out`, `public`, `.next`
+     - **Check .gitignore in migration folder** for build output patterns
+     - Look in build logs for "writing output to..." messages
+     - Update output_dir and redeploy
+
+   **For "module not found" or dependency errors:**
+   - **Check migration folder for lockfile** (package-lock.json or yarn.lock)
+   - **Automatic fix options:**
+     - If lockfile is in a subdirectory, update source_dir
+     - If using private packages, check if registry auth env vars are needed
+     - Add NODE_ENV=production if missing
+
+   **For port/health check failures (service starts but fails health check):**
+   - Fetch runtime logs to see what port the app is listening on
+   - **Automatic fix:**
+     - Check if app is hardcoded to wrong port
+     - Ensure PORT environment variable is set
+     - Update HTTP port configuration if needed
+
+   **For monorepo/source directory errors:**
+   - **Automatic fix:**
+     - Check Vercel config for rootDirectory
+     - **Search migration folder** for package.json in subdirectories
+     - Look for workspace configuration files (lerna.json, nx.json, etc.)
+     - Update source_dir to correct path and redeploy
+     - Deploy the mono repo under 1 app, where each repository service is a `service component` or `static site component` depending on the repository service. Ask the user for confirmation.
+
+4. **Apply the fix and redeploy:**
+   - Use DigitalOcean MCP to update the app configuration
+   - Trigger a new deployment
+   - Wait for deployment to complete and check status again
+
+5. **Retry logic:**
+   - If first automatic fix fails, fetch logs again and try alternative fix
+   - Maximum 3 automatic retry attempts per app
+   - After 3 failed attempts, report to user with detailed error and ask for manual intervention
+
+6. **Report fix applied:**
+   - Tell the user what error was found
+   - Tell the user what fix was applied
+   - Show the updated configuration
+
+### Step 3: Validation and Automatic Recovery
+
+After migrating the app:
+
+1. **Verify deployment succeeded** in App Platform (use DigitalOcean MCP to check status)
+   - Wait for the deployment to complete (this may take several minutes)
+   - Check deployment status: should be "ACTIVE" or "DEPLOYED"
+
+2. **If deployment FAILED, trigger automatic troubleshooting:**
+   - Follow the process in section 2.8 "Automatic Deployment Troubleshooting"
+   - Fetch logs, analyze errors, apply fixes automatically
+   - Retry up to 3 times with different fixes
+   - **Continue with validation after:**
+     - The app is successfully deployed, OR
+     - 3 automatic fix attempts have failed and user intervention is needed
+
+3. **If automatic fixes fail after 3 attempts:**
+   - Present detailed error information to the user
+   - Show what fixes were attempted
+   - Ask user for manual configuration input:
+     - Correct build command
+     - Correct output directory
+     - Missing environment variables
+     - Source directory path
+   - Apply user's corrections and redeploy
+
+4. **Test the deployed application:**
+   - Visit the App Platform URL
+   - Test critical functionality
+   - Test API endpoints if present
+   - Check that environment variables are working
+
+5. **Report status to the user:**
+   - Indicate the migration result: Success, Auto-Fixed, or Failed
+   - If auto-fixed, show what was corrected
+   - If failed, show the errors and fixes that were attempted
+
+### Step 4: Migration Summary
+
+After completing the migration, provide:
+
+1. **Summary table** with:
+   - Original Vercel app name
+   - New App Platform app name
+   - Status (Success/Auto-Fixed/Failed)
+   - If Auto-Fixed: what error was found and what fix was applied
+   - App Platform URL
+   - Domains that need DNS updates (with status: pending/completed)
+   - Any manual steps required
+
+2. **Auto-fix summary** (if automatic fixes were applied):
+   - Detail the errors encountered
+   - Show the fixes that were successfully applied
+   - Highlight any configuration changes made
+
+3. **Domain migration checklist:**
+   - List all domains that need DNS updates
+   - Provide the specific DNS changes for each domain
+   - Remind user to test first, then update DNS
+   - Warn about DNS propagation time (up to 48 hours)
+
+3. **Feature gaps to address:**
+   - List any Vercel features that couldn't be directly migrated
+   - Provide workarounds or alternative solutions
+
+4. **Next steps:**
+   - DNS update instructions (with specific records for each domain)
+   - Testing recommendations
+   - Optimization suggestions
+   - Timeline: Remind user to keep Vercel running until DNS fully propagates
+
+## Special Considerations
+
+### Preview Deployments
+- Vercel automatic PR previews are NOT currently available in App Platform
+- **Workaround:** Create a separate dev app with dev environment
+- Recommend using GitHub Actions for preview deployments
+
+### MCP vs CLI Usage
+This migration uses a **hybrid approach** combining both MCP servers and CLI tools:
+
+**Vercel:**
+- **Vercel CLI (Required):** Environment variables retrieval, app inspection
+- **Vercel MCP server (Optional):** Project metadata where available
+- **Note:** The Vercel MCP server does NOT provide environment variables
+
+**DigitalOcean:**
+- **DigitalOcean MCP server (Primary):** App creation, deployment management, domain configuration
+- **Fallback:** `doctl` CLI or REST API if MCP is unavailable
+
+### Database Migration
+- Creating new databases is straightforward
+- **Data migration** is complex and requires separate tooling
+- Inform user they need to handle data migration separately
+
+### Webhooks
+- Vercel deployment webhooks exist
+- App Platform webhooks are available but may be limited
+- Check if webhooks are needed and configure accordingly
+
+## Error Handling
+
+If migration fails for an app:
+
+1. **Capture the error details** from App Platform (via DigitalOcean MCP or dashboard)
+2. **Analyze common issues:**
+
+### Build Command Errors
+**Symptom:** Build fails with "command not found" or "script not found"
+**Cause:** Custom build command doesn't exist or buildpack couldn't auto-detect
+**Fix:**
+- **Prefer buildpack auto-detection:** Leave build command empty and let buildpack detect framework
+- **If auto-detection fails:**
+  - Check vercel.json for custom buildCommand
+  - Read package.json from migration folder at `./vercel-migration/<app-name>-migration/package.json`
+  - Verify the framework is in dependencies (e.g., "next", "react", "vue")
+  - For monorepos: ensure source_dir is correct
+- **Reference:** [App Platform Node.js buildpack docs](https://docs.digitalocean.com/products/app-platform/reference/buildpacks/nodejs/) for auto-detection behavior
+
+### Output Directory Errors (Static Sites)
+**Symptom:** "Output directory not found" or "No files to deploy"
+**Cause:** The output_dir doesn't match what the build produces
+**Fix:**
+- Check framework documentation to find correct output directory
+- **Look in .gitignore in the migration folder** - often lists build output directories
+- Run the build command locally or check framework docs
+- Common output directories:
+  - `build` (Create React App, Vite)
+  - `dist` (Vue CLI, Vite, Angular)
+  - `out` (Next.js static export)
+  - `public` (Gatsby, Hugo)
+  - `_site` (Jekyll)
+- **Inspect the migration folder** after build to see where files are output
+
+### Run Command Errors (Web Services)
+**Symptom:** Service crashes immediately or "command not found"
+**Cause:** Custom run command is invalid or buildpack couldn't auto-detect
+**Fix:**
+- **Prefer buildpack auto-detection:** Leave run command empty and let buildpack detect framework
+- **Buildpack will automatically use:**
+  - Framework-specific start commands (e.g., `next start` for Next.js)
+  - The "start" script from package.json if it exists
+  - The "main" field from package.json for plain Node.js apps
+- **If auto-detection fails:**
+  - Check vercel.json for custom start command
+  - Verify app is built before starting (some frameworks need build step)
+  - Ensure app listens on `process.env.PORT`
+- **Reference:** [App Platform Node.js buildpack docs](https://docs.digitalocean.com/products/app-platform/reference/buildpacks/nodejs/) for default run behavior
+
+### Port Configuration Errors
+**Symptom:** Service is "unhealthy" or "failed health check"
+**Cause:** App is not listening on the PORT environment variable
+**Fix:**
+- Ensure the app code listens on `process.env.PORT`
+- Update app code if it's hardcoded to a specific port
+- Default ports to check: 3000, 8080, 5000, 4000
+
+### Monorepo/Source Directory Errors
+**Symptom:** "package.json not found" or "Cannot find module"
+**Cause:** The source_dir is incorrect or not set
+**Fix:**
+- Check Vercel's `rootDirectory` setting
+- **Inspect the migration folder** at `./vercel-migration/<app-name>-migration/`
+- Look for workspace configuration in the repo (lerna.json, nx.json, pnpm-workspace.yaml)
+- Find where package.json exists in the repo structure
+- Set source_dir to the path of the specific app (e.g., `apps/web`, `packages/api`)
+- Ensure package.json exists at that path in the migration folder
+
+### Missing Environment Variables
+**Symptom:** Build succeeds but app crashes at runtime, or shows errors about missing config
+**Cause:** Required environment variables weren't migrated
+**Fix:**
+- **Check .env.example or .env.sample in the migration folder** at `./vercel-migration/<app-name>-migration/`
+- Check the app's documentation (README.md in cloned repo)
+- Look for required variables in the code
+- Add missing variables to App Platform
+- Common missing vars: DATABASE_URL, API_KEY, NEXT_PUBLIC_*, etc.
+
+### Dependency Installation Errors
+**Symptom:** "Cannot find module" or "npm install failed"
+**Cause:** Missing dependencies, lockfile issues, or version conflicts
+**Fix:**
+- **Check migration folder** at `./vercel-migration/<app-name>-migration/` for package-lock.json or yarn.lock
+- Ensure lockfile is in the correct directory (root or source_dir)
+- Check package.json for "engines" requirements
+- Verify Node.js version compatibility (reference App Platform buildpack docs)
+- May need to add environment variables for private npm registries
+- If using workspaces (monorepo), ensure workspace configuration is correct
+
+3. **Suggest fixes** based on error type
+4. **Ask user** if they want to retry with corrections
+5. **Update the app configuration** and redeploy
+
+## User Communication
+
+Throughout the migration:
+- **Be transparent** about what features can and cannot be migrated
+- **Warn early** about features requiring code changes (middleware, edge functions)
+- **Provide alternatives** for unsupported features
+- **Estimate timeframes** - typical migration should complete in under 30 minutes per app
+- **Explain the process:**
+  - Migration folders will be created at `./vercel-migration/<app-name>-migration/` for each app
+  - App specs will be saved for each app as backup
+  - App Platform buildpack documentation will be referenced for best practices
+- **Explain automatic recovery** - let users know that if deployments fail, you will automatically analyze logs and attempt fixes
+- **Show your work** - when automatic fixes are applied, explain what error was found and how it was fixed
+- **Confirm** before making changes that could affect production
+- **Keep user informed** during automatic retry attempts (e.g., "Deployment failed, analyzing logs and attempting fix 1 of 3...")
+
+## Final Checklist
+
+Before marking migration complete:
+
+- [ ] The app has been created in App Platform
+- [ ] Deployment is successful (either on first try or after automatic fixes)
+- [ ] Automatic troubleshooting was attempted if deployment failed
+- [ ] User has been informed of any automatic fixes that were applied
+- [ ] Environment variables have been transferred from the .env file pulled in Step 1.1
+- [ ] Build configurations match validated settings from repository inspection
+- [ ] App spec has been saved to `./vercel-migration/<app-name>-migration/app-spec.yaml`
+- [ ] Custom domains have been added to the App Platform app
+- [ ] User has received DNS update instructions for each domain
+- [ ] User understands to test before updating DNS
+- [ ] User has been informed about unsupported features
+- [ ] User has testing instructions
+- [ ] User knows how to rollback if needed
+- [ ] User knows to keep Vercel running until DNS propagates
+- [ ] Summary includes the app's status (Success/Auto-Fixed/Failed) with details
+- [ ] If successful: provide app name, URL (default ingress), and dashboard URL (`https://cloud.digitalocean.com/apps/$app_id`)
+- [ ] If failed: tell the user to create a support ticket and link to DigitalOcean's documentation
+- [ ] Remind user they can repeat this process for additional apps they want to migrate
+---
+
+**Remember:** This is a migration assistant role. Always prioritize user confirmation for critical decisions and be clear about what can and cannot be automatically migrated.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalocean/mcp",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "DigitalOcean MCP Implementation,",
   "author": "DigitalOcean",
   "homepage": "https://github.com/digitalocean-labs/mcp-digitalocean?tab=readme-ov-file#mcp-digitalocean-integration",
@@ -11,6 +11,12 @@
     "model-context-protocol"
   ],
   "bin": "./index.js",
+  "files": [
+    "index.js",
+    "dist/",
+    "apps/",
+    "README.md"
+  ],
   "scripts": {
     "mcp-golang": "node ./index.js"
   },