@everystack/mcp 0.3.2 → 0.3.3

package/dist/prompts/debug.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+export function registerDebugPrompt(server) {
+    server.prompt('debug', 'Systematic debugging for common everystack issues. Provides diagnostic steps based on the symptom.', {
+        symptom: z.string().describe('Description of the problem (e.g., "401 on all API requests", "RLS blocking reads", "Lambda timeout")'),
+        projectPath: z.string().optional().describe('Absolute path to project root'),
+    }, async ({ symptom, projectPath }) => {
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: [
+                            `Debug this issue: ${symptom}`,
+                            '',
+                            '## Instructions',
+                            '',
+                            '1. Read everystack://core for architecture context.',
+                            projectPath ? `2. Run project_status with projectPath="${projectPath}" to understand the project.` : '',
+                            projectPath ? `3. Run project_validate with projectPath="${projectPath}" to find configuration issues.` : '',
+                            projectPath ? `4. Run schema_analyze with projectPath="${projectPath}" to check schema/handler alignment.` : '',
+                            '',
+                            '## Diagnostic Framework',
+                            '',
+                            'Work through these categories systematically:',
+                            '',
+                            '### 1. Authentication Issues (401/403)',
+                            '',
+                            'If the symptom involves authentication or authorization:',
+                            '',
+                            '- **Check token flow:**',
+                            '  - Is the JWT being sent in the Authorization header?',
+                            '  - Is the token expired? Decode at jwt.io and check `exp`',
+                            '  - Does `auth.verifyToken` return a valid payload?',
+                            '',
+                            '- **Check publicRoutes:**',
+                            '  - Is the route supposed to be public? Check `auth.publicRoutes` in handler config',
+                            '  - Is the RPC in `auth.publicRpc`?',
+                            '',
+                            '- **Check pgSettings:**',
+                            '  - Is `pgSettings` configured in the handler?',
+                            '  - Does it set `role` and `request.jwt.claims`?',
+                            '  - Test with: `SELECT current_setting(\'request.jwt.claims\', true);`',
+                            '',
+                            '### 2. RLS Issues (empty results, permission denied)',
+                            '',
+                            'Read everystack://security for RLS debugging.',
+                            '',
+                            '- **Check RLS is enabled:**',
+                            '  ```sql',
+                            '  SELECT tablename, rowsecurity FROM pg_tables WHERE schemaname = \'public\';',
+                            '  ```',
+                            '',
+                            '- **Check policies exist:**',
+                            '  ```sql',
+                            '  SELECT * FROM pg_policies WHERE schemaname = \'public\';',
+                            '  ```',
+                            '',
+                            '- **Test as specific role:**',
+                            '  ```sql',
+                            '  SET LOCAL ROLE authenticated;',
+                            '  SELECT set_config(\'request.jwt.claims\', \'{"sub":"user-id","role":"authenticated"}\', true);',
+                            '  SELECT * FROM your_table;',
+                            '  ```',
+                            '',
+                            '- **Common RLS mistakes:**',
+                            '  - Policy references wrong claim path (sub vs user_id)',
+                            '  - USING clause doesn\'t match the data (e.g., UUID vs text comparison)',
+                            '  - Missing policy for the operation (SELECT exists but not INSERT)',
+                            '  - Forgot `WITH CHECK` on INSERT/UPDATE policies',
+                            '',
+                            '### 3. Query Issues (wrong data, missing relations)',
+                            '',
+                            'Read everystack://query-protocol for filter syntax.',
+                            '',
+                            '- **Check relations config:**',
+                            '  - Does the handler `relations` config match the Drizzle schema relations?',
+                            '  - Is the relation direction correct (from/to)?',
+                            '',
+                            '- **Check column names:**',
+                            '  - Handler uses camelCase by default. Database uses snake_case.',
+                            '  - Check `naming` option in handler config.',
+                            '',
+                            '### 4. Deployment Issues',
+                            '',
+                            'Read everystack://deployment and everystack://cli.',
+                            '',
+                            '- **Lambda errors:**',
+                            '  ```bash',
+                            '  everystack logs:errors --stage dev',
+                            '  everystack logs:tail --stage dev',
+                            '  ```',
+                            '',
+                            '- **Database connection:**',
+                            '  ```bash',
+                            '  everystack db:psql --stage dev',
+                            '  everystack diag --stage dev',
+                            '  ```',
+                            '',
+                            '- **Common deployment issues:**',
+                            '  - Missing secrets: `pnpm sst secret list --stage dev`',
+                            '  - VPC configuration: Lambda can\'t reach RDS without proper VPC setup',
+                            '  - Bundle size: Check if unnecessary packages are bundled',
+                            '',
+                            '### 5. Performance Issues',
+                            '',
+                            '- **Slow queries:**',
+                            '  - Check for missing indexes on filtered/joined columns',
+                            '  - Check `maxLimit` and `maxEmbedDepth` in handler config',
+                            '  - Use `EXPLAIN ANALYZE` on slow queries',
+                            '',
+                            '- **Cold starts:**',
+                            '  - Minimize Lambda bundle size',
+                            '  - Use provisioned concurrency for production',
+                            '',
+                            '## Resolution',
+                            '',
+                            'After diagnosing:',
+                            '1. Identify the root cause',
+                            '2. Propose a fix with the specific code change',
+                            '3. Verify the fix resolves the issue',
+                            '4. Run project_validate to ensure no new issues were introduced',
+                        ].filter(Boolean).join('\n'),
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/prompts/deploy.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDeployPrompt(server: McpServer): void;
+//# sourceMappingURL=deploy.d.ts.map

package/dist/prompts/deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/prompts/deploy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0H5D"}

package/dist/prompts/deploy.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+export function registerDeployPrompt(server) {
+    server.prompt('deploy', 'Step-by-step deployment walkthrough for a specific stage. Covers AWS credentials, SST deploy, migrations, and verification.', {
+        stage: z.enum(['dev', 'staging', 'production']).describe('Deployment stage'),
+        projectPath: z.string().optional().describe('Absolute path to project root'),
+    }, async ({ stage, projectPath }) => {
+        const isProduction = stage === 'production';
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: [
+                            `Deploy to ${stage}.`,
+                            '',
+                            '## Instructions',
+                            '',
+                            '1. Read everystack://deployment for infrastructure setup.',
+                            '2. Read everystack://security for AWS credential setup and deployment checklist.',
+                            projectPath ? `3. Run project_validate with projectPath="${projectPath}" to check for issues before deploying.` : '',
+                            projectPath ? `4. Run project_status with projectPath="${projectPath}" to see current deployment state.` : '',
+                            '',
+                            '## Pre-Deploy Checklist',
+                            '',
+                            '### AWS Credentials',
+                            '',
+                            '1. Verify the correct AWS profile is configured:',
+                            `   - ${stage === 'dev' ? '`everystack-manage` — for development deploys and CLI operations' : ''}`,
+                            `   - ${isProduction ? '`everystack-deploy` — for CI/CD production deploys (limited permissions)' : ''}`,
+                            '2. Run `aws sts get-caller-identity` to verify the active profile',
+                            '3. Ensure `everystack-create` profile is DISABLED unless first deploy',
+                            '',
+                            '### Secrets',
+                            '',
+                            'Set required secrets for this stage:',
+                            '```bash',
+                            `pnpm sst secret set JwtSecret "$(openssl rand -base64 32)" --stage ${stage}`,
+                            '```',
+                            '',
+                            isProduction ? [
+                                '### Production Safety',
+                                '',
+                                '- [ ] All tests pass: `pnpm test`',
+                                '- [ ] No security warnings: run project_validate',
+                                '- [ ] RLS policies are in place for all tables',
+                                '- [ ] pgSettings is configured in handler',
+                                '- [ ] No hardcoded secrets in source',
+                                '- [ ] .env files are not committed',
+                                '',
+                            ].join('\n') : '',
+                            '## Deploy Steps',
+                            '',
+                            '### 1. Deploy Infrastructure',
+                            '```bash',
+                            `pnpm sst deploy --stage ${stage}`,
+                            '```',
+                            '',
+                            'This creates/updates:',
+                            '- S3 bucket for static assets',
+                            '- CloudFront distribution',
+                            '- Lambda functions',
+                            '- RDS Aurora Serverless (V2+)',
+                            '- SQS queues (V3)',
+                            '- IAM roles and policies',
+                            '',
+                            '### 3. Database Setup (V2+)',
+                            '```bash',
+                            `everystack db:migrate --stage ${stage}`,
+                            stage === 'dev' ? `everystack db:seed --stage ${stage}  # dev only` : '',
+                            '```',
+                            '',
+                            '### 4. Verify',
+                            '```bash',
+                            '# Check Lambda logs',
+                            `everystack logs:tail --stage ${stage}`,
+                            '',
+                            '# Test the API',
+                            `curl https://your-domain/api/health`,
+                            '',
+                            `# Connect to database (${stage})`,
+                            `everystack db:psql --stage ${stage}`,
+                            '```',
+                            '',
+                            '## Post-Deploy',
+                            '',
+                            '### OTA Updates (no redeploy needed)',
+                            '```bash',
+                            `everystack update --channel ${stage === 'production' ? 'production' : stage} --message "Description"`,
+                            '```',
+                            '',
+                            isProduction ? [
+                                '### Production Monitoring',
+                                '',
+                                '- Check CloudWatch for Lambda errors',
+                                '- Monitor RDS connection count',
+                                '- Verify CDN cache hit rates',
+                                '- Set up CloudWatch alarms for error rates',
+                            ].join('\n') : '',
+                            '',
+                            '## Rollback',
+                            '',
+                            'If something goes wrong:',
+                            '```bash',
+                            '# Revert to previous OTA update',
+                            `everystack update --channel ${stage === 'production' ? 'production' : stage} --rollback`,
+                            '',
+                            '# For infrastructure changes, redeploy from a known good commit',
+                            'git checkout <good-commit>',
+                            `pnpm sst deploy --stage ${stage}`,
+                            '```',
+                        ].filter(Boolean).join('\n'),
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/prompts/design-schema.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDesignSchemaPrompt(server: McpServer): void;
+//# sourceMappingURL=design-schema.d.ts.map

package/dist/prompts/design-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-schema.d.ts","sourceRoot":"","sources":["../../src/prompts/design-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAoGlE"}

package/dist/prompts/design-schema.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+export function registerDesignSchemaPrompt(server) {
+    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',
+                    content: {
+                        type: 'text',
+                        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/dist/prompts/governance-setup.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * `governance_setup` — guide the agent to wire the everystack governance hooks
+ * into the project's `.claude/settings.json`. The server instructions tell the
+ * agent that enforcement runs via hooks; this prompt produces the exact block and
+ * the confirm-first procedure.
+ */
+export declare function registerGovernanceSetupPrompt(server: McpServer): void;
+//# sourceMappingURL=governance-setup.d.ts.map

package/dist/prompts/governance-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance-setup.d.ts","sourceRoot":"","sources":["../../src/prompts/governance-setup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2ErE"}

package/dist/prompts/governance-setup.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+/**
+ * `governance_setup` — guide the agent to wire the everystack governance hooks
+ * into the project's `.claude/settings.json`. The server instructions tell the
+ * agent that enforcement runs via hooks; this prompt produces the exact block and
+ * the confirm-first procedure.
+ */
+export function registerGovernanceSetupPrompt(server) {
+    server.prompt('governance_setup', 'Install the everystack governance hooks (grounding gate + cheat gates) into .claude/settings.json. The MCP server alone does not enforce — the hooks are the teeth.', {
+        projectPath: z.string().optional().describe('Absolute path to the project root'),
+        mode: z
+            .enum(['workspace', 'installed'])
+            .optional()
+            .describe('"workspace" (run from this monorepo via tsx) or "installed" (the published @everystack/mcp bin). Default: detect.'),
+    }, async ({ projectPath, mode }) => {
+        const cmd = mode === 'workspace'
+            ? 'npx tsx packages/mcp/src/index.ts'
+            : mode === 'installed'
+                ? 'everystack-mcp'
+                : 'everystack-mcp';
+        const hooks = {
+            hooks: {
+                SessionStart: [{ hooks: [{ type: 'command', command: `${cmd} context` }] }],
+                PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: `${cmd} gate` }] }],
+                PostToolUse: [
+                    { matcher: 'Read', hooks: [{ type: 'command', command: `${cmd} mark` }] },
+                    { matcher: 'Write|Edit', hooks: [{ type: 'command', command: `${cmd} validate` }] },
+                ],
+            },
+        };
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: [
+                            `Install the everystack governance hooks for ${projectPath ? 'the project at ' + projectPath : 'this project'}.`,
+                            '',
+                            '## Why',
+                            '',
+                            'The everystack MCP server provides knowledge, but ENFORCEMENT (the grounding gate and',
+                            'cheat gates) runs only when these Claude Code hooks are installed. Without them, nothing',
+                            'catches off-script work (hand-written migrations, data bundled into the app, secrets behind',
+                            'EXPO_PUBLIC_*).',
+                            '',
+                            '## Procedure (confirm-first — never silent)',
+                            '',
+                            '1. Read `docs/governance-setup.md` and `hooks.example.json` from the @everystack/mcp package.',
+                            `2. Check whether ${projectPath ? projectPath + '/.claude/settings.json' : '.claude/settings.json'} already has these hooks (commands calling \`${cmd} gate\`).`,
+                            '3. If absent, show the human the exact block below and confirm the command form before writing:',
+                            '   - **Workspace (this monorepo):** `npx tsx packages/mcp/src/index.ts <sub>`',
+                            '   - **Installed package:** `everystack-mcp <sub>` (install `@everystack/mcp`; in a hook prefer',
+                            '     `pnpm exec everystack-mcp <sub>` over bare `npx`, which re-resolves on every tool call).',
+                            '4. Merge the `hooks` block into `.claude/settings.json` (preserve any existing `hooks`/`permissions`).',
+                            '5. Remind the human: hooks run a shell command on every tool call. This is a deliberate,',
+                            '   security-relevant change — it is their call, not yours to make silently.',
+                            '',
+                            '## The block to merge',
+                            '',
+                            '```json',
+                            JSON.stringify(hooks, null, 2),
+                            '```',
+                            '',
+                            '## After install',
+                            '',
+                            '- A fresh session denies every non-Read tool until the project contract (CLAUDE.md + its',
+                            '  REQUIRED-READS) is read. That is the grounding gate working.',
+                            '- `everystack-mcp report` summarizes what the agent tried (the telemetry sensor).',
+                        ].join('\n'),
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/prompts/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPrompts(server: McpServer): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAUvD"}

package/dist/prompts/index.js

@@ -0,0 +1,20 @@
+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';
+import { registerGovernanceSetupPrompt } from './governance-setup.js';
+import { registerClaudeMdPrompt } from './claude-md.js';
+import { registerRunbookPrompt } from './runbook.js';
+export function registerPrompts(server) {
+    registerNewAppPrompt(server);
+    registerAddFeaturePrompt(server);
+    registerDesignSchemaPrompt(server);
+    registerDeployPrompt(server);
+    registerDebugPrompt(server);
+    registerSecurePrompt(server);
+    registerGovernanceSetupPrompt(server);
+    registerClaudeMdPrompt(server);
+    registerRunbookPrompt(server);
+}

package/dist/prompts/new-app.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerNewAppPrompt(server: McpServer): void;
+//# sourceMappingURL=new-app.d.ts.map

package/dist/prompts/new-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-app.d.ts","sourceRoot":"","sources":["../../src/prompts/new-app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAkN5D"}