@everystack/mcp

The governance layer that governs how any agent builds everystack. Beyond architecture knowledge and guided prompts, it keeps the build on-script: a grounding gate (read the project contract before editing) and cheat gates (block the training-consensus shortcuts — bundling data instead of using the DB, hand-writing migrations, leaking a secret into the client bundle), with telemetry that records what the agent tried. The teeth run as Claude Code hooks; the same logic is importable so the operator CLI can self-gate at deploy.

Governance setup (hooks + telemetry): docs/governance-setup.md.

Setup

Add to your project's .mcp.json:

{
  "mcpServers": {
    "everystack": {
      "command": "npx",
      "args": ["@everystack/mcp"]
    }
  }
}

Or for a monorepo workspace:

{
  "mcpServers": {
    "everystack": {
      "command": "npx",
      "args": ["tsx", "packages/mcp/src/index.ts"]
    }
  }
}

What It Provides

Resources (Knowledge)

Claude reads these to understand everystack architecture and conventions.

Core (loaded first):

• everystack://core — Architecture, package map, tiers, conventions, handler reference
• everystack://security — Three-layer security model, AWS IAM profiles, RLS policies

Detail (loaded on demand):

• everystack://handler-options — Complete createHandler() options reference
• everystack://query-protocol — PostgREST filter syntax, embedding, aggregates
• everystack://client-api — Typed client, query builder, mutations
• everystack://auth — JWT auth flows, OAuth, token lifecycle
• everystack://schema-patterns — Drizzle schema design, migrations, RLS
• everystack://deployment — SST config, secrets, stages, resource linking
• everystack://admin — Declarative admin dashboard
• everystack://jobs — SQS background workers
• everystack://storage — S3 file uploads, presigned URLs
• everystack://logging — Structured logging, crash reports, analytics
• everystack://security-device — Device attestation, biometric auth
• everystack://testing — Jest setup, TDD workflow, mocking patterns
• everystack://plugins — Plugin system for composing handlers
• everystack://ssr — Server-side rendering, loaders, SEO
• everystack://images — Sharp image processing, CDN delivery
• everystack://events — Real-time events via LISTEN/NOTIFY + WebSocket
• everystack://cli — CLI command reference

Governance (hooks)

The teeth. Run as Claude Code hooks via the everystack-mcp bin — see docs/governance-setup.md.

| Subcommand | Hook | Role | |------------|------|------| | context | SessionStart | inject the contract to read | | gate | PreToolUse | block until grounded; block cheat gates | | mark | PostToolUse(Read) | record a contract read | | validate | PostToolUse(Write|Edit) | surface a cheat the write landed | | report | — | summarize the per-session telemetry |

Tools (Project Introspection)

| Tool | Purpose | |------|---------| | check_environment | Verify dev/deploy prerequisites (Node, pnpm, git, Expo, SST, AWS CLI, PostgreSQL) |

The legacy regex tools (project_status, schema_analyze, project_validate) were removed: they predated the v3 Model/Module surface and returned wrong answers on Model-based apps. They are being rebuilt on @everystack/model (the pure compiler) so introspection matches reality.

Prompts (Guided Workflows)

Structured prompts that guide Claude through multi-step tasks.

| Prompt | Purpose | |--------|---------| | new-app | Scaffold a new everystack app (V1/V2/V3) | | add-feature | Add auth, jobs, storage, images, admin, logging, security, SSR, or events | | design-schema | Plain English → Drizzle schema + RLS policies + handler config | | deploy | Stage-specific deployment walkthrough | | debug | Systematic debugging based on symptoms | | secure | AWS IAM profiles + RLS + JWT auth setup |

Design

Framework-aware. Depends on @everystack/model and @everystack/cli (plus @modelcontextprotocol/sdk and zod). An enforcement layer must track the framework version — it cannot float free of it. The cheat detectors reuse the CLI's shipped scanners (e.g. the canonical secret-shape patterns from @everystack/cli/audit) rather than duplicating them, loaded lazily so the common tool call stays fast.

Local-only. No network, no AWS. The grounding gate and cheat gates observe tool-call metadata and the proposed file content; they never write files themselves. Telemetry is a local JSONL under ~/.everystack/governance.

Fail-open. A governance bug never bricks tool use — only the explicit "ungrounded" and "cheat detected" conditions fail closed.

Curated resources. The markdown files are optimized for Claude consumption — organized by task, not by package. Each follows a consistent structure: When to Use, Setup, API Reference, Common Patterns, Gotchas.

Development

pnpm --filter @everystack/mcp test     # Run tests (206 passing)
pnpm --filter @everystack/mcp lint     # Type check

License

AGPL-3.0-only © Scalable Technology, Inc.

A commercial license is available for organizations that cannot or do not wish to comply with the AGPL-3.0 terms. For commercial licensing, contact [email protected].