@everystack/mcp 0.2.0

package/src/prompts/design-schema.ts

@@ -0,0 +1,104 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+export function registerDesignSchemaPrompt(server: McpServer): void {
+  server.prompt(
+    'design-schema',
+    'Interactive schema design: plain English description → Drizzle schema + migrations + RLS policies + handler config + testing checklist.',
+    {
+      description: z.string().describe('Plain English description of the data model (e.g., "blog with posts, comments, and tags")'),
+      projectPath: z.string().optional().describe('Absolute path to project root (to analyze existing schema)'),
+    },
+    async ({ description, projectPath }) => {
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: [
+                `Design a database schema for: ${description}`,
+                '',
+                '## Instructions',
+                '',
+                '1. Read everystack://schema-patterns for Drizzle schema conventions.',
+                '2. Read everystack://security for RLS policy patterns.',
+                '3. Read everystack://handler-options for handler configuration.',
+                projectPath ? `4. Run schema_analyze with projectPath="${projectPath}" to understand the existing schema.` : '',
+                '',
+                '## Deliverables',
+                '',
+                'Generate ALL of the following:',
+                '',
+                '### 1. Drizzle Schema (db/schema.ts)',
+                '',
+                'Follow these conventions:',
+                '- UUID primary keys: `uuid(\'id\').primaryKey().defaultRandom()`',
+                '- Timestamps: `timestamp(\'created_at\', { withTimezone: true }).defaultNow().notNull()`',
+                '- Soft delete columns: `deletedAt` + `deletedBy` on user-facing tables',
+                '- Foreign keys with `.references(() => table.column)`',
+                '- Export all tables as named exports',
+                '- Add Drizzle `relations()` for SSR query building and API embedding',
+                '',
+                '### 2. SQL Migration with RLS',
+                '',
+                'Generate a custom SQL migration that includes:',
+                '',
+                '```sql',
+                '-- For each table:',
+                'ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;',
+                '',
+                '-- Grant minimum required access per role:',
+                'GRANT SELECT ON table_name TO anon;',
+                'GRANT SELECT, INSERT, UPDATE, DELETE ON table_name TO authenticated;',
+                'GRANT ALL ON table_name TO admin;',
+                '',
+                '-- Policies per access pattern:',
+                '-- Public read:',
+                'CREATE POLICY "anon_select" ON table_name FOR SELECT TO anon USING (deleted_at IS NULL);',
+                '',
+                '-- Own rows only:',
+                'CREATE POLICY "own_rows" ON table_name FOR ALL TO authenticated',
+                '  USING (user_id = current_setting(\'request.jwt.claims\', true)::json->>\'sub\');',
+                '',
+                '-- Admin full access:',
+                'CREATE POLICY "admin_all" ON table_name FOR ALL TO admin USING (true);',
+                '```',
+                '',
+                'Adapt the policies to the specific access patterns for each table.',
+                '',
+                '### 3. Handler Configuration',
+                '',
+                'Generate the createHandler() config snippet:',
+                '- `exposedTables`: only tables that should be API-accessible',
+                '- `relations`: for embedding related data in API queries',
+                '- `rowOwnership`: for user-scoped tables',
+                '- `softDelete`: for tables with deletedAt columns',
+                '- `protectedFields`: fields users cannot set directly (role, deletedAt)',
+                '- `hiddenColumns`: sensitive columns not returned in API responses',
+                '',
+                '### 4. Testing Checklist',
+                '',
+                'Generate a testing checklist:',
+                '- [ ] Anonymous users can read public data',
+                '- [ ] Anonymous users cannot write any data',
+                '- [ ] Authenticated users can only read/write their own data',
+                '- [ ] Soft-deleted rows are hidden from normal queries',
+                '- [ ] Admin users can access all data',
+                '- [ ] Foreign key constraints prevent orphaned rows',
+                '- [ ] RLS policies work with pgSettings claim injection',
+                '',
+                'Test each RLS policy with:',
+                '```sql',
+                'SET LOCAL ROLE authenticated;',
+                "SELECT set_config('request.jwt.claims', '{\"sub\": \"user-uuid\", \"role\": \"authenticated\"}', true);",
+                'SELECT * FROM table_name; -- should only return own rows',
+                '```',
+              ].filter(Boolean).join('\n'),
+            },
+          },
+        ],
+      };
+    },
+  );
+}

package/src/prompts/index.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerNewAppPrompt } from './new-app.js';
+import { registerAddFeaturePrompt } from './add-feature.js';
+import { registerDesignSchemaPrompt } from './design-schema.js';
+import { registerDeployPrompt } from './deploy.js';
+import { registerDebugPrompt } from './debug.js';
+import { registerSecurePrompt } from './secure.js';
+
+export function registerPrompts(server: McpServer): void {
+  registerNewAppPrompt(server);
+  registerAddFeaturePrompt(server);
+  registerDesignSchemaPrompt(server);
+  registerDeployPrompt(server);
+  registerDebugPrompt(server);
+  registerSecurePrompt(server);
+}

package/src/prompts/new-app.ts

@@ -0,0 +1,211 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+export function registerNewAppPrompt(server: McpServer): void {
+  server.prompt(
+    'new-app',
+    'Scaffold a new everystack app. Describe what you want to build and Claude will recommend the right tier, check prerequisites, and walk you through setup.',
+    {
+      description: z.string().describe('Describe what you want to build (e.g., "a recipe sharing app where people can post and save recipes")'),
+      tier: z.enum(['V1', 'V2', 'V3']).optional().describe('Target tier: V1 (static), V2 (dynamic with DB), V3 (full platform). If omitted, recommended based on description.'),
+      name: z.string().optional().describe('App name (e.g., my-app). If omitted, suggested from description.'),
+    },
+    async ({ description, tier, name }) => {
+      const hasTier = tier !== undefined;
+      const hasName = name !== undefined;
+
+      const tierPackages: Record<string, string[]> = {
+        V1: ['@everystack/server', '@everystack/cli', '@everystack/ui'],
+        V2: [
+          '@everystack/server', '@everystack/cli', '@everystack/ui',
+          '@everystack/api', '@everystack/auth', '@everystack/admin',
+          '@everystack/logging', '@everystack/security', '@everystack/query',
+        ],
+        V3: [
+          '@everystack/server', '@everystack/cli', '@everystack/ui',
+          '@everystack/api', '@everystack/auth', '@everystack/admin',
+          '@everystack/logging', '@everystack/security', '@everystack/query',
+          '@everystack/jobs', '@everystack/storage', '@everystack/images',
+        ],
+      };
+
+      // When tier is omitted, build an intake phase for Claude to work through
+      const intakeSection = !hasTier ? [
+        '## Step 1: Understand the Idea',
+        '',
+        `The user wants to build: "${description}"`,
+        '',
+        'Read the everystack://getting-started resource for how to explain things to beginners.',
+        'Listen to what they want to build. Do NOT categorize into tiers or ask them to choose.',
+        'Every app starts the same way: a running Expo app. Build the UI first, add complexity when features demand it.',
+        '',
+        '## Step 2: Choose a Name',
+        '',
+        hasName
+          ? `Use the name: "${name}"`
+          : 'Suggest a short, lowercase, hyphenated name based on the description (e.g., "recipe-share", "my-recipes"). Ask the user if they like it or want something different.',
+        '',
+        '## Step 3: Check Prerequisites',
+        '',
+        'Run the check_environment tool with phase "local".',
+        'Read everystack://getting-started for how to explain each prerequisite to a beginner.',
+        'Walk through installing missing tools ONE AT A TIME. Confirm each works before moving to the next.',
+        'Only V1 prerequisites are needed now — Node.js, git, pnpm. PostgreSQL is NOT needed yet.',
+        'AWS tools (AWS CLI, credentials, SST) are NOT needed now. The user will build and run locally first.',
+        '',
+        '## Step 4: Scaffold the Project',
+        '',
+        'Once prerequisites are ready and the user has confirmed the name, proceed with the scaffolding steps below.',
+        'The app starts as a static Expo app. Database, auth, and other features are added later when needed.',
+        'Explain each step in plain language alongside the technical commands.',
+        '',
+      ].join('\n') : '';
+
+      const effectiveTier = tier || 'V1';
+      const effectiveName = name || 'my-app';
+      const packages = tierPackages[effectiveTier];
+
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: [
+                intakeSection,
+                hasTier
+                  ? `Create a new everystack ${effectiveTier} app called "${effectiveName}".`
+                  : '## Scaffolding Instructions',
+                `Description: ${description}`,
+                '',
+                hasTier ? [
+                  '## Prerequisites',
+                  '',
+                  'Run the check_environment tool with phase "local" to verify local development prerequisites.',
+                  'If any required tools are missing, help the user install them before proceeding.',
+                  'AWS tools are not needed yet — the user will build and run locally first.',
+                ].join('\n') : '',
+                '',
+                '## Instructions',
+                '',
+                '1. Read the everystack://core resource for architecture and conventions.',
+                effectiveTier !== 'V1' ? '2. Read everystack://security for the security model.' : '',
+                effectiveTier !== 'V1' ? '3. Read everystack://schema-patterns for Drizzle schema design.' : '',
+                effectiveTier !== 'V1' ? '4. Read everystack://auth for authentication setup.' : '',
+                '',
+                '## Steps to Execute',
+                '',
+                '### 1. Project Setup',
+                `- Create the project directory: ${effectiveName}/`,
+                '- Initialize with: `npx create-expo-app@latest`',
+                `- Install packages: \`pnpm add ${packages.join(' ')}\``,
+                effectiveTier !== 'V1' ? '- Install peer deps: `pnpm add drizzle-orm && pnpm add -D drizzle-kit`' : '',
+                '- Install SST: `pnpm add -D sst`',
+                '',
+                '### 2. Project Structure',
+                '```',
+                `${effectiveName}/`,
+                '├── app/              # Expo Router pages',
+                effectiveTier !== 'V1' ? '├── db/               # Schema, migrations, seed' : '',
+                '├── server/           # Lambda handlers',
+                effectiveTier !== 'V1' ? '│   └── api.ts        # PostgREST handler' : '',
+                effectiveTier === 'V3' ? '│   ├── worker.ts     # SQS worker handler' : '',
+                effectiveTier === 'V3' ? '│   └── image.ts      # Image processing handler' : '',
+                '├── lib/              # Shared code (auth context, API client)',
+                '├── sst.config.ts     # Infrastructure',
+                '└── package.json',
+                '```',
+                '',
+                effectiveTier !== 'V1' ? [
+                  '### 3. Database Schema',
+                  `Create db/schema.ts with tables for the ${description}.`,
+                  'Follow the patterns from everystack://schema-patterns:',
+                  '- UUID primary keys with defaultRandom()',
+                  '- created_at timestamps on all tables',
+                  '- Foreign key references with proper cascading',
+                  '- Relations for both SSR and API query embedding',
+                  '',
+                  '### 4. Migrations',
+                  '- Generate: `npx drizzle-kit generate`',
+                  '- Add RLS policies in a custom SQL migration',
+                  '- Reference the RLS templates from everystack://security',
+                  '',
+                  '### 5. Handler Configuration',
+                  'Create server/api.ts using createPluginLambdaHandler or createLambdaHandler.',
+                  'Include:',
+                  '- auth.verifyToken for JWT verification',
+                  '- pgSettings for RLS context injection',
+                  '- exposedTables to limit API surface',
+                  '- rowOwnership for user-scoped mutation control',
+                  '- softDelete for reversible deletes',
+                  '',
+                  '### 6. Auth Setup',
+                  'Read everystack://auth for the full auth flow.',
+                  '- Set up createAuthHandlers with the JWT secret',
+                  '- Create lib/auth-context.tsx with AuthProvider',
+                  '- Add signup/signin screens',
+                  '',
+                ].join('\n') : '',
+                '## Validation',
+                '',
+                'After scaffolding, run the project_validate tool to check for common mistakes.',
+                '',
+                '## Run Locally',
+                '',
+                'Read everystack://first-run for a walkthrough of what to expect.',
+                '- Run `npx expo start` (or `pnpm dev`)',
+                '- Press `w` to open in a browser',
+                '- Verify the app loads and displays correctly',
+                '- Try changing text in app/index.tsx to confirm hot reload works',
+                '',
+                'This is the milestone: the user sees their app running on their own computer.',
+                'Celebrate this. Then continue building features.',
+                '',
+                !hasTier ? [
+                  '## Growing Your App',
+                  '',
+                  'Build the UI together first — screens, navigation, components, styling. Everything is static and visual.',
+                  '',
+                  'When a feature needs user accounts, login, or saved data:',
+                  '- Read everystack://adding-database for the step-by-step guide',
+                  '- Run check_environment("local") again — PostgreSQL will be needed',
+                  '',
+                  'When a feature needs file uploads or background processing:',
+                  '- Read everystack://storage for file uploads',
+                  '- Read everystack://jobs for background tasks',
+                  '- Read everystack://images for image processing',
+                ].join('\n') : '',
+                '',
+                '## Project Documentation',
+                'Read the everystack://project-claude-md resource and write a CLAUDE.md file to the project root.',
+                `Replace {PROJECT_NAME} with "${effectiveName}", {ONE_LINE_DESCRIPTION} with "${description}",`,
+                'and {ANNOTATED_DIRECTORY_TREE} with the actual project structure created above.',
+                '',
+                '## Deployment (Later)',
+                '',
+                'When the user is ready to put the app on the internet:',
+                '1. Run check_environment with phase "deploy" to verify AWS prerequisites',
+                '2. Set up AWS credentials (read everystack://aws-setup for beginners, everystack://security for IAM profiles)',
+                '### SST Configuration',
+                'Create sst.config.ts with:',
+                '- S3 bucket for static assets',
+                '- CloudFront distribution',
+                '- Lambda for SSR',
+                effectiveTier !== 'V1' ? '- RDS Aurora Serverless PostgreSQL' : '',
+                effectiveTier !== 'V1' ? '- VPC configuration' : '',
+                effectiveTier === 'V3' ? '- SQS queue for background jobs' : '',
+                effectiveTier === 'V3' ? '- S3 bucket for file uploads' : '',
+                '',
+                '### Deploy',
+                'Read everystack://deployment for the full walkthrough.',
+                '1. `pnpm sst deploy --stage dev`',
+                effectiveTier !== 'V1' ? '2. `everystack db:migrate`' : '',
+                effectiveTier !== 'V1' ? '3. `everystack db:seed` (dev only)' : '',
+              ].filter(Boolean).join('\n'),
+            },
+          },
+        ],
+      };
+    },
+  );
+}

package/src/prompts/secure.ts

@@ -0,0 +1,231 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+export function registerSecurePrompt(server: McpServer): void {
+  server.prompt(
+    'secure',
+    'Set up security for an everystack project: AWS IAM profiles, JWT auth, RLS policies, and edge verification.',
+    {
+      features: z.string().optional().describe('Comma-separated security features to set up (e.g., "aws,rls,auth"). Defaults to all.'),
+      projectPath: z.string().optional().describe('Absolute path to project root'),
+    },
+    async ({ features, projectPath }) => {
+      const allFeatures = ['aws', 'rls', 'auth', 'edge'];
+      const requested = features
+        ? features.split(',').map((f) => f.trim().toLowerCase())
+        : allFeatures;
+
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: [
+                `Set up security for ${projectPath ? 'the project at ' + projectPath : 'my everystack project'}.`,
+                `Features: ${requested.join(', ')}`,
+                '',
+                '## Instructions',
+                '',
+                '1. Read everystack://security for the complete security model.',
+                '2. Read everystack://auth for JWT authentication details.',
+                projectPath ? `3. Run project_validate with projectPath="${projectPath}" to find existing security gaps.` : '',
+                projectPath ? `4. Run schema_analyze with projectPath="${projectPath}" to check schema security.` : '',
+                '',
+                requested.includes('aws') ? [
+                  '## AWS IAM Profiles',
+                  '',
+                  'Set up three named AWS profiles with least-privilege permissions:',
+                  '',
+                  '### 1. everystack-create (Infrastructure Creation)',
+                  '',
+                  '**When:** First deploy only. Disable after infrastructure exists.',
+                  '',
+                  '```ini',
+                  '# ~/.aws/credentials',
+                  '[everystack-create]',
+                  'aws_access_key_id = ...',
+                  'aws_secret_access_key = ...',
+                  '```',
+                  '',
+                  'Permissions needed:',
+                  '- CloudFormation (create stacks)',
+                  '- S3 (create buckets)',
+                  '- CloudFront (create distributions)',
+                  '- Lambda (create functions)',
+                  '- RDS (create clusters)',
+                  '- IAM (create roles — scoped to everystack-* prefix)',
+                  '- VPC (create VPC, subnets, security groups)',
+                  '- SQS (create queues)',
+                  '',
+                  '**After first deploy:** Delete or deactivate these access keys.',
+                  '',
+                  '### 2. everystack-manage (Day-to-Day CLI)',
+                  '',
+                  '**When:** Development, running CLI commands, migrations.',
+                  '',
+                  'Permissions needed:',
+                  '- Lambda:InvokeFunction (for CLI → Lambda operations)',
+                  '- S3:PutObject/GetObject (for OTA updates)',
+                  '- CloudWatch:GetLogEvents (for log tailing)',
+                  '- SSM:GetParameter (for secret access)',
+                  '',
+                  '**Cannot:** Create or delete infrastructure, modify IAM, access RDS directly.',
+                  '',
+                  '### 3. everystack-deploy (CI/CD)',
+                  '',
+                  '**When:** Automated deployments from CI/CD pipelines.',
+                  '',
+                  'Permissions needed:',
+                  '- CloudFormation:UpdateStack (update existing, not create new)',
+                  '- Lambda:UpdateFunctionCode',
+                  '- S3:PutObject (deploy assets)',
+                  '- CloudFront:CreateInvalidation',
+                  '',
+                  '**Cannot:** Create new infrastructure, modify IAM, access secrets.',
+                  '',
+                ].join('\n') : '',
+
+                requested.includes('auth') ? [
+                  '## JWT Authentication',
+                  '',
+                  'Read everystack://auth for full details.',
+                  '',
+                  '### Setup',
+                  '',
+                  '1. Generate a strong JWT secret:',
+                  '```bash',
+                  'pnpm sst secret set JwtSecret "$(openssl rand -base64 32)" --stage dev',
+                  '```',
+                  '',
+                  '2. Create auth handlers:',
+                  '```typescript',
+                  "import { createAuthHandlers } from '@everystack/auth';",
+                  '',
+                  'const auth = createAuthHandlers(db, schema, jwtSecret, {',
+                  "  mode: 'postgres',",
+                  '  sql,',
+                  '  cookies: true, // HttpOnly cookies for web',
+                  '});',
+                  '```',
+                  '',
+                  '3. Wire into Lambda handler with auth routes.',
+                  '',
+                  '4. Create AuthProvider in lib/auth-context.tsx.',
+                  '',
+                  '### Token Lifecycle',
+                  '',
+                  '- Access tokens: short-lived (15 min default)',
+                  '- Refresh tokens: long-lived (7 days default)',
+                  '- Auto-refresh on 401 via client interceptor',
+                  '',
+                ].join('\n') : '',
+
+                requested.includes('rls') ? [
+                  '## Row-Level Security (RLS)',
+                  '',
+                  'Read everystack://security for the mental model and templates.',
+                  '',
+                  '### How RLS Works in everystack',
+                  '',
+                  '1. Client sends JWT in Authorization header',
+                  '2. Handler verifies JWT, extracts claims',
+                  '3. `pgSettings` sets PostgreSQL session variables:',
+                  '   - `SET LOCAL ROLE authenticated`',
+                  '   - `set_config(\'request.jwt.claims\', \'{"sub":"...","role":"..."}\', true)`',
+                  '4. Query runs inside a transaction with those settings',
+                  '5. RLS policies read the claims and filter rows',
+                  '',
+                  '### Step-by-Step',
+                  '',
+                  '1. **Create roles** (one-time migration):',
+                  '```sql',
+                  'CREATE ROLE anon NOLOGIN;',
+                  'CREATE ROLE authenticated NOLOGIN;',
+                  'CREATE ROLE admin NOLOGIN;',
+                  'GRANT anon, authenticated, admin TO authenticator;',
+                  '```',
+                  '',
+                  '2. **Enable RLS on every table:**',
+                  '```sql',
+                  'ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;',
+                  '```',
+                  '',
+                  '3. **Grant minimum permissions:**',
+                  '```sql',
+                  'GRANT SELECT ON table_name TO anon;',
+                  'GRANT SELECT, INSERT, UPDATE, DELETE ON table_name TO authenticated;',
+                  'GRANT ALL ON table_name TO admin;',
+                  '```',
+                  '',
+                  '4. **Create policies per access pattern:**',
+                  '',
+                  '**Public read (soft-delete aware):**',
+                  '```sql',
+                  "CREATE POLICY \"anon_select\" ON table_name FOR SELECT TO anon",
+                  '  USING (deleted_at IS NULL);',
+                  '```',
+                  '',
+                  '**Own rows only:**',
+                  '```sql',
+                  "CREATE POLICY \"own_rows_select\" ON table_name FOR SELECT TO authenticated",
+                  "  USING (user_id = (current_setting('request.jwt.claims', true)::json->>'sub')::uuid);",
+                  '```',
+                  '',
+                  '**Admin full access:**',
+                  '```sql',
+                  "CREATE POLICY \"admin_all\" ON table_name FOR ALL TO admin USING (true);",
+                  '```',
+                  '',
+                  '5. **Configure pgSettings in handler:**',
+                  '```typescript',
+                  'pgSettings: (user) => ({',
+                  "  role: user?.role === 'admin' ? 'admin' : user ? 'authenticated' : 'anon',",
+                  "  'request.jwt.claims': JSON.stringify(user || { role: 'anon' }),",
+                  '}),',
+                  '```',
+                  '',
+                  '### Testing RLS',
+                  '',
+                  '```sql',
+                  '-- Test as authenticated user',
+                  'BEGIN;',
+                  'SET LOCAL ROLE authenticated;',
+                  "SELECT set_config('request.jwt.claims',",
+                  "  '{\"sub\": \"user-uuid\", \"role\": \"authenticated\"}', true);",
+                  'SELECT * FROM posts; -- should only return own posts',
+                  'ROLLBACK;',
+                  '```',
+                  '',
+                ].join('\n') : '',
+
+                requested.includes('edge') ? [
+                  '## Edge JWT Verification',
+                  '',
+                  'Verify JWTs at the CDN edge before requests reach Lambda:',
+                  '',
+                  '- CloudFront function validates JWT signature (HS256)',
+                  '- Rejects expired or malformed tokens at the edge',
+                  '- Reduces Lambda invocations for unauthorized requests',
+                  '- See everystack://deployment for CloudFront function setup',
+                  '',
+                ].join('\n') : '',
+
+                '## Verification',
+                '',
+                'After setup, verify security:',
+                '',
+                '1. Run project_validate to check for gaps',
+                '2. Test unauthenticated access returns 401',
+                '3. Test cross-user data isolation with RLS',
+                '4. Verify JWT claims propagate through pgSettings',
+                '5. Check `.env` files are not committed',
+                '6. Confirm `everystack-create` profile is disabled',
+              ].filter(Boolean).join('\n'),
+            },
+          },
+        ],
+      };
+    },
+  );
+}