@everystack/mcp 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server that makes Claude an everystack expert",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/prompts/deploy.ts

@@ -58,12 +58,7 @@ export function registerDeployPrompt(server: McpServer): void {
                 ].join('\n') : '',
                 '## Deploy Steps',
                 '',
-                '### 1. Build',
-                '```bash',
-                'pnpm export  # Expo export (builds dist/)',
-                '```',
-                '',
-                '### 2. Deploy Infrastructure',
+                '### 1. Deploy Infrastructure',
                 '```bash',
                 `pnpm sst deploy --stage ${stage}`,
                 '```',

package/src/resources/aws-setup.md

@@ -46,69 +46,152 @@ Your AWS account has a "root user" (the email you signed up with). The root user
 
 ### Create the permissions policy
 
-This policy gives the user exactly the permissions SST needs to deploy your app.
+This policy gives the user the permissions SST needs to deploy your app, scoped to your app's resources. Every statement targets your app name prefix so this user can't touch other apps in the same account.
 
 7. Select **Attach policies directly**
 8. Click **Create policy** (this opens a new tab)
 9. Click the **JSON** tab
-10. Delete anything in the editor and paste this:
+10. Delete anything in the editor and paste this (replacing the placeholders — see table below):
 
 ```json
 {
   "Version": "2012-10-17",
   "Statement": [
     {
-      "Sid": "EverystackDeploy",
+      "Sid": "SSM",
+      "Effect": "Allow",
+      "Action": "ssm:*",
+      "Resource": [
+        "arn:aws:ssm:{REGION}:{ACCOUNT_ID}:parameter/sst/*",
+        "arn:aws:ssm:{REGION}:{ACCOUNT_ID}:parameter/{APP_NAME}/*"
+      ]
+    },
+    {
+      "Sid": "S3",
+      "Effect": "Allow",
+      "Action": "s3:*",
+      "Resource": [
+        "arn:aws:s3:::{APP_NAME}-*-*",
+        "arn:aws:s3:::{APP_NAME}-*-*/*",
+        "arn:aws:s3:::sst-asset-*",
+        "arn:aws:s3:::sst-asset-*/*",
+        "arn:aws:s3:::sst-state-*",
+        "arn:aws:s3:::sst-state-*/*"
+      ]
+    },
+    {
+      "Sid": "S3Protect",
+      "Effect": "Deny",
+      "Action": [
+        "s3:DeleteBucket",
+        "s3:PutBucketAcl",
+        "s3:PutBucketVersioning",
+        "s3:PutBucketEncryption",
+        "s3:PutBucketLogging"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Sid": "CF",
       "Effect": "Allow",
       "Action": [
-        "cloudformation:*",
-        "s3:*",
-        "lambda:*",
         "cloudfront:*",
-        "iam:CreateRole",
-        "iam:DeleteRole",
-        "iam:GetRole",
-        "iam:GetRolePolicy",
-        "iam:PassRole",
-        "iam:AttachRolePolicy",
-        "iam:DetachRolePolicy",
-        "iam:PutRolePolicy",
-        "iam:DeleteRolePolicy",
-        "iam:ListRolePolicies",
-        "iam:ListAttachedRolePolicies",
-        "iam:TagRole",
-        "iam:UntagRole",
-        "iam:CreateServiceLinkedRole",
-        "rds:*",
-        "ec2:DescribeVpcs",
-        "ec2:DescribeSubnets",
-        "ec2:DescribeSecurityGroups",
-        "ec2:DescribeRouteTables",
-        "ec2:DescribeAvailabilityZones",
-        "ec2:DescribeVpcEndpoints",
-        "ec2:CreateSecurityGroup",
-        "ec2:DeleteSecurityGroup",
-        "ec2:AuthorizeSecurityGroupIngress",
-        "ec2:RevokeSecurityGroupIngress",
-        "ec2:AuthorizeSecurityGroupEgress",
-        "ec2:RevokeSecurityGroupEgress",
-        "ec2:CreateVpcEndpoint",
-        "ec2:DeleteVpcEndpoint",
-        "ec2:CreateTags",
-        "ec2:DeleteTags",
-        "route53:*",
-        "sqs:*",
-        "ssm:*",
-        "logs:*",
-        "sts:GetCallerIdentity",
-        "sts:AssumeRole"
+        "cloudfront-keyvaluestore:*"
       ],
       "Resource": "*"
+    },
+    {
+      "Sid": "Lambda",
+      "Effect": "Allow",
+      "Action": "lambda:*",
+      "Resource": "arn:aws:lambda:{REGION}:{ACCOUNT_ID}:function:{APP_NAME}-*"
+    },
+    {
+      "Sid": "LambdaGlobal",
+      "Effect": "Allow",
+      "Action": [
+        "lambda:CreateEventSourceMapping",
+        "lambda:DeleteEventSourceMapping",
+        "lambda:GetEventSourceMapping",
+        "lambda:ListEventSourceMappings",
+        "lambda:UpdateEventSourceMapping",
+        "lambda:ListFunctions",
+        "lambda:GetFunctionConfiguration",
+        "lambda:TagResource",
+        "lambda:UntagResource",
+        "lambda:ListTags"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Sid": "SQS",
+      "Effect": "Allow",
+      "Action": "sqs:*",
+      "Resource": "arn:aws:sqs:{REGION}:{ACCOUNT_ID}:{APP_NAME}-*"
+    },
+    {
+      "Sid": "IAM",
+      "Effect": "Allow",
+      "Action": "iam:*Role*",
+      "Resource": [
+        "arn:aws:iam::{ACCOUNT_ID}:role/{APP_NAME}-*",
+        "arn:aws:iam::{ACCOUNT_ID}:role/SchedulerRole-*"
+      ]
+    },
+    {
+      "Sid": "Scheduler",
+      "Effect": "Allow",
+      "Action": [
+        "scheduler:CreateScheduleGroup",
+        "scheduler:DeleteScheduleGroup",
+        "scheduler:GetScheduleGroup",
+        "scheduler:ListTagsForResource",
+        "scheduler:TagResource",
+        "scheduler:UntagResource"
+      ],
+      "Resource": "arn:aws:scheduler:{REGION}:{ACCOUNT_ID}:schedule-group/{APP_NAME}-*"
+    },
+    {
+      "Sid": "Logs",
+      "Effect": "Allow",
+      "Action": "logs:*",
+      "Resource": [
+        "arn:aws:logs:{REGION}:{ACCOUNT_ID}:log-group:/aws/lambda/{APP_NAME}-*",
+        "arn:aws:logs:{REGION}:{ACCOUNT_ID}:log-group:/aws/lambda/{APP_NAME}-*:*"
+      ]
+    },
+    {
+      "Sid": "LogsList",
+      "Effect": "Allow",
+      "Action": "logs:DescribeLogGroups",
+      "Resource": "arn:aws:logs:{REGION}:{ACCOUNT_ID}:log-group:*"
+    },
+    {
+      "Sid": "Discovery",
+      "Effect": "Allow",
+      "Action": "s3:ListAllMyBuckets",
+      "Resource": "*"
+    },
+    {
+      "Sid": "STS",
+      "Effect": "Allow",
+      "Action": "sts:GetCallerIdentity",
+      "Resource": "*"
     }
   ]
 }
 ```
 
+Replace the placeholders with your values:
+
+| Placeholder | Example | Where to find it |
+|-------------|---------|-------------------|
+| `{ACCOUNT_ID}` | `123456789012` | `aws sts get-caller-identity` |
+| `{REGION}` | `us-east-1` | Your default AWS region |
+| `{APP_NAME}` | `myapp` | The `name` in your `sst.config.ts` |
+
+If your app creates additional S3 buckets outside the `{APP_NAME}-*` pattern, add them to the S3 statement.
+
 11. Click **Next**
 12. Name the policy: `everystack-dev-policy`
 13. Optionally add a description: "Permissions for everystack SST deploys"
@@ -168,6 +251,26 @@ You should see something like:
 
 If you see your account number and `everystack-dev`, your credentials are working. You are ready to deploy.
 
+### What each statement does
+
+| Statement | Actions | Scope | Purpose |
+|-----------|---------|-------|---------|
+| **SSM** | `ssm:*` | `sst/*` + `{APP_NAME}/*` params | SST state management + app secrets |
+| **S3** | `s3:*` | App buckets + SST state/asset buckets | Media, client bundles, OTA updates, SST state |
+| **S3Protect** | Deny destructive bucket ops | `*` | Prevents `DeleteBucket`, ACL/versioning/encryption/logging changes |
+| **CF** | `cloudfront:*`, `cloudfront-keyvaluestore:*` | `*` | Router distribution + KVS cache versioning |
+| **Lambda** | `lambda:*` | `{APP_NAME}-*` functions | API, Image, Worker Lambdas |
+| **LambdaGlobal** | Event source mappings, list, tags | `*` | SQS-to-Lambda subscriptions, resource discovery |
+| **SQS** | `sqs:*` | `{APP_NAME}-*` queues | Background jobs + dead-letter queues (V3) |
+| **IAM** | `iam:*Role*` | `{APP_NAME}-*` + `SchedulerRole-*` | Lambda execution roles + EventBridge Scheduler role |
+| **Scheduler** | Schedule group CRUD + tags | `{APP_NAME}-*` groups | EventBridge Scheduler for delayed tasks |
+| **Logs** | `logs:*` | `/aws/lambda/{APP_NAME}-*` | CloudWatch log groups for Lambda functions |
+| **LogsList** | `logs:DescribeLogGroups` | `*` | Log group enumeration |
+| **Discovery** | `s3:ListAllMyBuckets` | `*` | CLI resource discovery |
+| **STS** | `sts:GetCallerIdentity` | `*` | Identity verification |
+
+**V2-only apps** can omit `SQS` and `Scheduler`. **V1-only apps** can omit `SQS`, `Scheduler`, `IAM`, and `Logs`.
+
 ## Production hardening
 
-The `everystack-dev` user above has broad permissions suitable for getting started. When you are ready to harden your setup for production, read `everystack://security` for a three-profile model that separates infrastructure creation, day-to-day operations, and CI/CD into distinct IAM users with minimal permissions.
+For production, read `everystack://security` for a three-profile model that separates infrastructure creation, day-to-day operations, and CI/CD into distinct IAM users with minimal permissions.

package/src/resources/deployment.md

@@ -92,12 +92,12 @@ Each stage gets isolated resources (separate database, buckets, Lambda functions
 ## Deploy Flow
 
 ```bash
-# 1. Export Expo app
-pnpm export
-
-# 2. Deploy infrastructure + code
+# 1. Deploy infrastructure + code
 pnpm sst deploy --stage dev
 
+# 2. Export + publish app bundles
+everystack update --stage dev
+
 # 3. Run migrations
 everystack db:migrate
 

package/src/resources/images.md

@@ -65,9 +65,29 @@ import { imagesSchema } from '@everystack/images/schema';
 // Adds: image_variants table tracking generated variants
 ```
 
+## S3 Origin Cache
+
+CloudFront caches are per-region. Enable `s3Cache` to persist rendered images to S3 so the first Sharp render is the last, globally:
+
+```typescript
+export const handler = createImageHandler({
+  bucket: Resource.Media.name,
+  s3Cache: { enabled: true },
+});
+```
+
+Cache keys are deterministic from parsed params. Add a 30-day lifecycle rule on the `cache/` prefix to auto-expire stale renders. To clean up immediately when an original is deleted:
+
+```typescript
+import { deleteImageCache } from '@everystack/server/image';
+await deleteImageCache(bucket, 'uploads/photo.jpg');
+```
+
+See `docs/caching.md` for full setup.
+
 ## Gotchas
 
 - Sharp runs on Lambda ARM64 (uses Lambda layer or bundled binary)
-- First request for a variant is slow (processing), subsequent are cached
-- CloudFront caches processed images (set appropriate Cache-Control)
+- First request for a variant is slow (processing), subsequent are cached by CloudFront and S3
+- With `s3Cache` enabled, Sharp runs once per variant globally (not once per CloudFront region)
 - AVIF encoding is slower than WebP but produces smaller files