@revealui/mcp 0.0.1-pre.0 → 0.1.0

package/.env.example

@@ -0,0 +1,9 @@
+MCP_PERSISTENCE_DRIVER=pglite
+ELECTRIC_DATABASE_URL=postgres://dev:dev@localhost:5432/revealui_mcp
+ELECTRIC_API_KEY=replace-me
+MCP_METRICS_MODE=logs
+PGVECTOR_ENABLED=false
+
+# Notes:
+# - Do NOT commit real credentials. Store real secrets in CI/Vault.
+# - Set `PGVECTOR_ENABLED=true` when using local Postgres with pgvector for vector testing.

package/MCP_MAINTENANCE.md

@@ -0,0 +1,265 @@
+# MCP Maintenance Guide
+
+This document consolidates all MCP-related maintenance information including CRDT audit strategy, key decisions, migration procedures, and metrics/observability approach.
+
+---
+
+## Table of Contents
+
+1. [Decision Log](#decision-log)
+2. [CRDT Audit](#crdt-audit)
+3. [Migration Checklist](#migration-checklist)
+4. [Metrics & Observability](#metrics--observability)
+
+---
+
+## Decision Log
+
+### MCP Decision — pglite (ElectricSQL) + Logs‑First Metrics
+
+**TL;DR** — Default to ElectricSQL (`pglite`) for local development to get Postgres parity, CRDT sync, and smooth production migration. Start observability with a logs‑first approach (`MCP_METRICS_MODE=logs`). Provide a documented migration path to managed Postgres + `pgvector` for production, and TODOs to add Prometheus + Grafana later.
+
+#### Why `pglite` (ElectricSQL)
+
+- Local Postgres parity: preserves SQL semantics developers expect while providing Electric sync.
+- CRDT & sync primitives: built-in conflict resolution and metadata for replicated state.
+- Smooth prod path: same logical model maps to managed Postgres (Neon / Supabase) with minimal code changes.
+
+#### Default configuration
+
+- `MCP_PERSISTENCE_DRIVER=pglite` (dev default)
+- `ELECTRIC_DATABASE_URL=` (placeholder for local pglite path/URL)
+- `MCP_METRICS_MODE=logs`
+
+#### Local vector testing
+
+- Use a compose variant with local Postgres + `pgvector` when testing vector queries or index behavior. `pglite` remains the default for state and CRDT behavior.
+
+#### Security stance
+
+- Never commit credentials. Use `packages/mcp/.env.example` with placeholders only.
+- Store `ELECTRIC_DATABASE_URL`, `ELECTRIC_API_KEY`, `PROD_DATABASE_URL` in CI secrets or Vault for staging/prod.
+
+#### Migration path (dev → prod)
+
+- Dev: `pglite` (local ElectricSQL)
+- Stage: Local Postgres with `pgvector` + Electric sync metadata
+- Prod: Managed Postgres (enable `pgvector`), Electric sync metadata preserved
+
+(See [Migration Checklist](#migration-checklist) section for a detailed plan.)
+
+#### Observability
+
+- Start with logs-first metrics (Option C). Emit structured log events for conflicts, merges, and error rates.
+- TODO: add Prometheus + Grafana manifests under `packages/mcp/k8s/` when operational budget permits.
+
+#### TODOs (short)
+
+- Add `packages/mcp/docker-compose.yml` with `pglite` dev service and `postgres+pgvector` variant.
+- Add `packages/mcp/src/adapters/db.ts` with `connectPglite()` / `connectPostgres()`.
+- Add CRDT migrations & backfill scripts.
+- Add integration tests that spin up compose and validate CRDT merges.
+- Add `packages/mcp/metrics.md` (logs-first) and TODOs for Option A (Prometheus + Grafana).
+
+---
+
+## CRDT Audit
+
+### CRDT Audit — Candidate Entities & Strategy
+
+**Goal** — ensure all replicated, collaborative, or concurrent state uses CRDT semantics to avoid manual conflict resolution.
+
+#### Scope
+
+- Applies to MCP persistence: local `pglite` (dev) and managed Postgres (prod).
+- Targets entity categories that are concurrently updated or replicated.
+
+#### Candidate entities and recommended CRDT types
+
+- `documents` / `shared_documents`
+  - Use: collaborative edits
+  - CRDT: delta CRDT (RGA / JSON CRDT / operation-based)
+  - Policy: preserve operations and causal order
+- `subscription_state` / `cursors`
+  - Use: client offsets, cursors
+  - CRDT: LWW register or monotonic counter
+  - Policy: LWW with server-side monotonic enforcement where possible
+- `presence` / `ephemeral_status`
+  - Use: frequent transient updates
+  - CRDT: OR-Set with TTL or presence map
+  - Policy: TTL-based garbage collection
+- `message_ack` / `delivered_acks`
+  - Use: dedup across replicas
+  - CRDT: OR-Set or G-Set with tombstones
+  - Policy: idempotent ack addition, compact tombstones periodically
+- `user_settings` / `shared_settings`
+  - Use: small multi-client updates
+  - CRDT: observed-remove map / JSON CRDT
+  - Policy: field-level merge, operator override protected
+
+#### Implementation notes
+
+- Adapter responsibilities:
+  - `connectPglite()` should declare CRDT columns via Electric APIs (where available).
+  - `connectPostgres()` must keep Electric metadata columns and map CRDT metadata to Postgres-compatible storage.
+- Schema:
+  - Add `_electric_meta` or `_crdt_meta` columns near payloads.
+  - Store operation deltas if possible for efficient merges.
+- Rollout:
+  - Feature-flag per-entity CRDT enablement for staged rollout.
+  - Small-sample backfills prior to full backfill.
+- Storage & compaction:
+  - Implement delta compaction for large-delta CRDTs.
+  - Schedule periodic compaction jobs to remove tombstones and shrink op logs.
+
+#### Testing
+
+- Unit tests: CRDT op merges for each primitive (OR-Set, PNCounter, LWW register).
+- Integration tests: concurrent writers with `pglite` stack asserting deterministic merged state.
+- Migration tests: backfill scripts run on sample data and validate checksum diffs.
+
+#### Risk & mitigation
+
+- Existing payload types incompatible with CRDT fields — use non-destructive migrations and backfill.
+- Vector index (pgvector) mapping must be preserved during schema changes — treat embedding columns as orthogonal.
+
+#### Suggested tests to add
+
+- `packages/mcp/__tests__/crdt.unit.test.ts` — unit semantics.
+- `packages/mcp/__tests__/crdt.integration.test.ts` — compose-based concurrent writes.
+
+---
+
+## Migration Checklist
+
+### MCP Migration Checklist — pglite → Managed Postgres + pgvector
+
+**Goal** — safely cut over from `pglite` dev workflows to managed Postgres in production while preserving CRDT semantics and vector index integrity.
+
+#### Pre‑reqs
+
+- Staging Postgres provisioned with `pgvector` enabled.
+- Backups and CI/Vault secrets available: `ELECTRIC_DATABASE_URL`, `ELECTRIC_API_KEY`, `PROD_DATABASE_URL`.
+- Smoke test harness and CRDT integration tests present.
+
+#### Ordered checklist
+
+1. **Backup source DB**
+```bash
+pg_dump -Fc -f backup.before.mcp.dump "$CURRENT_DB_URL"
+```
+
+2. **Provision staging DB with `pgvector`**
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+3. **Apply schema migrations to staging (include CRDT metadata columns)**
+- Add migration files: `packages/mcp/migrations/0001_add_crdt_columns.sql` and rollback script.
+
+4. **Small backfill (sample subset)**
+- Run `packages/mcp/migrations/backfill_crdt_meta.js` for representative rows; validate merges.
+
+5. **Run integration smoke tests**
+- Execute CRDT integration test suite against staging.
+
+6. **Export/import full snapshot (if migrating data)**
+```bash
+pg_restore -d "$STAGING_DB_URL" backup.before.mcp.dump
+```
+
+7. **Create `pgvector` indexes (maintenance window suggested)**
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE INDEX IF NOT EXISTS documents_embedding_idx ON documents USING ivfflat (embedding vector_l2_ops) WITH (lists = 100);
+```
+
+8. **Full backfill & compaction**
+- Run full backfill; compact delta-CRDT ops as needed.
+
+9. **Switch app config (canary first)**
+- Set `MCP_PERSISTENCE_DRIVER=postgres`
+- Update `ELECTRIC_DATABASE_URL` to prod managed DB via secrets
+
+10. **Canary / canary tests**
+- Route small traffic, monitor conflict events and query correctness.
+
+11. **Full cutover**
+- Promote config change to all instances.
+
+12. **Post-migration validation**
+- Run full test suite, verify vector results, verify merge/conflict telemetry.
+
+13. **Rollback readiness**
+```bash
+pg_restore -d "$PROD_DB_URL" backup.before.mcp.dump
+```
+
+#### Operational notes
+
+- Prefer online migration with feature flags and small maintenance windows for index builds.
+- Validate checksums and sample-row diffs after every major migration step.
+- Keep rollback scripts next to each migration file.
+
+---
+
+## Metrics & Observability
+
+### MCP Metrics & Observability — Logs‑First (Option C)
+
+#### Decision
+
+- Start with logs-first metrics to avoid hosted monitoring costs and reduce infra.
+- Emit structured logs for conflicts, merges, errors, and key latencies.
+- Provide clear TODOs and skeletons to add Prometheus + Grafana later.
+
+#### Env & modes
+
+- `MCP_METRICS_MODE=logs` (default)
+- Other modes: `otel` (collector), `prometheus` (future Option A)
+
+#### Structured log schema (recommended JSON fields)
+
+- `timestamp`
+- `service = "mcp"`
+- `event` = `conflict|merge|error|operation`
+- `entity` = `documents|cursors|presence|...`
+- `entity_id`
+- `op_type` = `write|merge|backfill|index`
+- `details` = short summary
+- `duration_ms`
+- `trace_id` (optional)
+
+#### Conflict/merge logging example (concept)
+
+- Log a `conflict` event when CRDT merge produces non-trivial resolution; include `before`, `ops_count`, `merged_summary`.
+
+#### Log collection options (free)
+
+- Use file logs + `loki` (self-hosted) and Grafana Loki datasource for queries (both OSS).
+- Or aggregate logs to a central file/CI artifact and analyze with `rg`/`jq` for small teams.
+
+#### Quick local setup (suggested)
+
+- Start compose with `loki` (optional) to collect logs, or rely on local file logs.
+```bash
+docker-compose -f packages/mcp/docker-compose.yml up -d loki
+```
+
+#### TODOs for Option A (Prometheus + Grafana)
+
+- Add `packages/mcp/k8s/` manifests and Helm chart scaffolding for Prometheus exporters and Grafana dashboards.
+- Instrument code with Prometheus client metrics (conflict counters, merge latencies).
+- Add dashboards and alert rules for high conflict rates.
+
+#### Implementation guidance
+
+- Implement `packages/mcp/src/telemetry.ts` that:
+  - Emits structured logs for every conflict/merge.
+  - In `MCP_METRICS_MODE=logs`, write JSON lines to stdout and rotate to file if needed.
+- Provide quick grep/jq scripts in `packages/mcp/` to extract conflict rates.
+
+#### Security & privacy
+
+- Avoid logging sensitive payloads (mask user PII).
+- Keep telemetry ingestion endpoints protected; local logs are preferred during dev.

package/README.md

@@ -0,0 +1,260 @@
+# @revealui/mcp
+
+**Model Context Protocol (MCP) - Complete Integration Package**
+
+Centralized MCP server infrastructure, configuration, and documentation for RevealUI.
+
+## Overview
+
+This package contains everything MCP-related:
+
+- **7 MCP Servers** - Code validator, Vercel, Stripe, Neon, Supabase, Playwright, Next.js DevTools
+- **Configuration Templates** - For Claude Code / Claude Desktop
+- **Utilities** - Config management, database adapters
+- **Documentation** - Complete guides and per-server docs
+- **Database Migrations** - MCP-related schema
+
+> **Pro Package** — `@revealui/mcp` is available to RevealUI Pro subscribers via GitHub Packages.
+> Install: `pnpm add @revealui/mcp --registry https://npm.pkg.github.com`
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+# In the monorepo:
+pnpm install
+
+# As an external Pro subscriber:
+pnpm add @revealui/mcp --registry https://npm.pkg.github.com
+```
+
+### 2. Configure MCP Client
+
+```bash
+# Use template for your IDE
+cp packages/mcp/configs/claude-template.json ~/.claude/config.json
+
+# Replace <REPO_PATH> with actual path
+sed -i "s|<REPO_PATH>|$(pwd)|g" ~/.claude/config.json
+```
+
+### 3. Test Server
+
+```bash
+# Test code validator
+tsx packages/mcp/src/servers/code-validator.ts
+# Should start (Ctrl+C to exit)
+```
+
+## Structure
+
+```
+packages/mcp/
+├── src/
+│   ├── servers/          # 7 MCP server implementations
+│   │   ├── code-validator.ts   ← AI code standards enforcer
+│   │   ├── vercel.ts
+│   │   ├── stripe.ts
+│   │   ├── neon.ts
+│   │   ├── supabase.ts
+│   │   ├── playwright.ts
+│   │   └── next-devtools.ts
+│   ├── config/           # Configuration utilities
+│   │   ├── index.ts
+│   │   ├── config.json
+│   │   └── README.md
+│   └── adapters/         # Database adapters
+│       └── db.ts
+├── configs/              # Template configurations
+│   ├── claude-template.json
+│   └── README.md
+├── docs/                 # Complete documentation
+│   ├── INDEX.md          ← Start here
+│   ├── README.md         # Main MCP guide
+│   ├── SETUP.md          # Setup instructions
+│   └── servers/          # Per-server documentation
+│       └── code-validator.md
+├── migrations/           # Database migrations
+│   ├── 0001_add_crdt_columns.sql
+│   └── ...
+└── package.json
+```
+
+## Available MCP Servers
+
+### 1. Code Validator ⭐
+**Status:** ✅ Active and configured
+
+Prevents AI-generated technical debt by validating code before it's written.
+
+- **Rules:** console.log, any types, TODO refs, debugger, skip tests
+- **Integration:** Pre-commit hook + MCP server
+- **Docs:** [docs/servers/code-validator.md](./docs/servers/code-validator.md)
+
+```bash
+tsx packages/mcp/src/servers/code-validator.ts
+```
+
+### 2. Vercel
+**Status:** Available (requires API key)
+
+Deploy and manage Vercel projects.
+
+```bash
+pnpm mcp:vercel
+```
+
+### 3. Stripe
+**Status:** Available (requires API key)
+
+Payment processing and billing operations.
+
+```bash
+pnpm mcp:stripe
+```
+
+### 4. Neon
+**Status:** Available (requires API key)
+
+Database operations and SQL queries.
+
+```bash
+pnpm mcp:neon
+```
+
+### 5. Supabase
+**Status:** Available (requires API key)
+
+Supabase project management and CRUD operations.
+
+```bash
+pnpm mcp:supabase
+```
+
+### 6. Playwright
+**Status:** Available
+
+Browser automation and web scraping.
+
+```bash
+pnpm mcp:playwright
+```
+
+### 7. Next.js DevTools
+**Status:** Available
+
+Next.js 16+ runtime diagnostics and automation.
+
+```bash
+pnpm mcp:next-devtools
+```
+
+## Configuration
+
+All configuration templates are in `configs/`:
+
+- **`claude-template.json`** - Claude Code / Claude Desktop
+
+See [configs/README.md](./configs/README.md) for details.
+
+## Environment Variables
+
+```env
+# Code Validator (no env vars needed)
+
+# Vercel MCP
+VERCEL_API_KEY=vercel_...
+
+# Stripe MCP
+STRIPE_SECRET_KEY=sk_test_...
+
+# Neon MCP
+NEON_API_KEY=neon_...
+
+# Supabase MCP
+SUPABASE_URL=https://....supabase.co
+SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=...
+```
+
+## Documentation
+
+📚 **[Complete Documentation Index](./docs/INDEX.md)**
+
+- **[Main Guide](./docs/README.md)** - MCP overview
+- **[Setup Guide](./docs/SETUP.md)** - Configuration steps
+- **[Code Validator](./docs/servers/code-validator.md)** - Validator guide
+
+## Development
+
+```bash
+# Build package
+pnpm build
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm typecheck
+
+# Lint
+pnpm lint
+```
+
+## Package Scripts (Root)
+
+```bash
+# Start individual MCP servers
+pnpm mcp:vercel
+pnpm mcp:stripe
+pnpm mcp:neon
+pnpm mcp:supabase
+pnpm mcp:playwright
+pnpm mcp:next-devtools
+
+# Setup MCP configuration
+pnpm setup:mcp
+```
+
+## Exports
+
+```typescript
+// Config utilities
+import { getMCPConfig } from '@revealui/mcp/config'
+```
+
+## Migration from Old Structure
+
+This package consolidates MCP code from multiple locations:
+
+**Before:**
+- `scripts/mcp/` → Now `src/servers/`
+- `packages/config/src/mcp/` → Now `src/config/`
+- Multiple config files → Now `configs/` templates
+- Scattered docs → Now `docs/`
+
+**After:**
+- Everything in `packages/mcp/` ✅
+
+## Related Documentation
+
+- [Root MCP Guide](../../docs/MCP.md)
+- [Automation Guide](../../docs/AUTOMATION.md) - AI agent integration
+- [Project Overview](../../docs/OVERVIEW.md) - Framework overview
+
+## References
+
+- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
+- [Anthropic MCP Servers](https://github.com/anthropics/mcp-servers)
+- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)
+
+## License
+
+Commercial — see [LICENSE.commercial](../../LICENSE.commercial)
+
+---
+
+**Status:** ✅ Consolidated and Active
+**Servers:** 7 available (1 active, 6 optional)
+**Last Updated:** 2026-03-04

package/__tests__/crdt.integration.test.ts

@@ -0,0 +1,156 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import adapters, { connectPglite, type McpDbClient } from '../src/adapters/db.js'
+
+describe('CRDT integration (smoke)', () => {
+  it('adapter functions exist', () => {
+    expect(typeof adapters.connectPglite).toBe('function')
+    expect(typeof adapters.connectPostgres).toBe('function')
+    expect(typeof adapters.createMcpDbClient).toBe('function')
+  })
+})
+
+// Skip integration tests in unit test mode
+// Integration tests need TEST_DATABASE_URL explicitly set or PGlite in test environment
+// Don't run by default as PGlite initialization can be slow
+const testDatabaseUrl = process.env.TEST_DATABASE_URL
+const isTestMode = process.env.NODE_ENV === 'test'
+
+describe.skipIf(!testDatabaseUrl || isTestMode)('CRDT integration with PGlite', () => {
+  let client: McpDbClient
+
+  beforeAll(async () => {
+    // Use in-memory PGlite for testing
+    client = await connectPglite({ dataDir: ':memory:' })
+  })
+
+  afterAll(async () => {
+    if (client) {
+      await client.close()
+    }
+  })
+
+  it('should create crdt_operations table', async () => {
+    // Verify table exists by querying it
+    const result = await client.query(
+      `SELECT column_name FROM information_schema.columns WHERE table_name = 'crdt_operations'`,
+    )
+
+    const columns = result.rows.map((r) => r.column_name)
+    expect(columns).toContain('id')
+    expect(columns).toContain('document_id')
+    expect(columns).toContain('operation_type')
+    expect(columns).toContain('payload')
+    expect(columns).toContain('vector_clock')
+    expect(columns).toContain('node_id')
+  })
+
+  it('should insert and query CRDT operations', async () => {
+    const opId = `op-${Date.now()}`
+    const docId = 'doc-test-1'
+    const nodeId = 'node-a'
+
+    // Insert a CRDT operation
+    await client.query(
+      `INSERT INTO crdt_operations (id, document_id, operation_type, payload, vector_clock, node_id)
+       VALUES ($1, $2, $3, $4, $5, $6)`,
+      [
+        opId,
+        docId,
+        'insert',
+        JSON.stringify({ field: 'title', value: 'Test' }),
+        JSON.stringify({ [nodeId]: 1 }),
+        nodeId,
+      ],
+    )
+
+    // Query it back
+    const result = await client.query(`SELECT * FROM crdt_operations WHERE id = $1`, [opId])
+
+    expect(result.rows).toHaveLength(1)
+    expect(result.rows[0]?.document_id).toBe(docId)
+    expect(result.rows[0]?.operation_type).toBe('insert')
+    expect(result.rows[0]?.node_id).toBe(nodeId)
+  })
+
+  it('should support concurrent operations from multiple nodes', async () => {
+    const docId = `doc-concurrent-${Date.now()}`
+    const nodeA = 'node-a'
+    const nodeB = 'node-b'
+
+    // Simulate concurrent writes from two nodes
+    await Promise.all([
+      client.query(
+        `INSERT INTO crdt_operations (id, document_id, operation_type, payload, vector_clock, node_id)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [
+          `op-a-${Date.now()}`,
+          docId,
+          'update',
+          JSON.stringify({ field: 'content', value: 'From A' }),
+          JSON.stringify({ [nodeA]: 1 }),
+          nodeA,
+        ],
+      ),
+      client.query(
+        `INSERT INTO crdt_operations (id, document_id, operation_type, payload, vector_clock, node_id)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [
+          `op-b-${Date.now()}`,
+          docId,
+          'update',
+          JSON.stringify({ field: 'content', value: 'From B' }),
+          JSON.stringify({ [nodeB]: 1 }),
+          nodeB,
+        ],
+      ),
+    ])
+
+    // Query all operations for this document
+    const result = await client.query(
+      `SELECT * FROM crdt_operations WHERE document_id = $1 ORDER BY created_at`,
+      [docId],
+    )
+
+    // Both operations should be preserved (CRDT property)
+    expect(result.rows).toHaveLength(2)
+
+    const nodes = result.rows.map((r) => r.node_id)
+    expect(nodes).toContain(nodeA)
+    expect(nodes).toContain(nodeB)
+  })
+
+  it('should handle vector clock ordering', async () => {
+    const docId = `doc-clock-${Date.now()}`
+    const nodeId = 'node-clock'
+
+    // Insert operations with incrementing vector clock
+    for (let i = 1; i <= 3; i++) {
+      await client.query(
+        `INSERT INTO crdt_operations (id, document_id, operation_type, payload, vector_clock, node_id)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [
+          `op-${docId}-${i}`,
+          docId,
+          'update',
+          JSON.stringify({ field: 'counter', value: i }),
+          JSON.stringify({ [nodeId]: i }),
+          nodeId,
+        ],
+      )
+    }
+
+    const result = await client.query(
+      `SELECT * FROM crdt_operations WHERE document_id = $1 ORDER BY created_at`,
+      [docId],
+    )
+
+    expect(result.rows).toHaveLength(3)
+
+    // Verify vector clocks are preserved and can be used for ordering
+    const clocks = result.rows.map((r) => {
+      const vc = r.vector_clock as Record<string, number>
+      return vc[nodeId]
+    })
+    expect(clocks).toEqual([1, 2, 3])
+  })
+})