NEURA

An English-first, internationalized AI news platform built with Next.js, Supabase, and the Model Context Protocol (MCP). NEURA includes a zero-configuration editorial preview; every operational write, notification, campaign and social publication uses real persisted adapters and fails closed when its provider is not configured.

What ships

• English-first routes with Italian content parity: /en and /it.

• Editorial home, infinite latest/category/search feeds, article pages, localized RSS, native social sharing, bookmarks and deferred comments.

• Persisted comment threads with signed guest identity, own-edit/delete windows, reports, moderation audit, rate limits and real email notifications.

• Double-opt-in newsletter, Markdown campaigns, recipient snapshots, scheduling, Resend delivery, signed webhooks, suppression, unsubscribe and erasure.

• Real LinkedIn, X and WhatsApp publishing through leased, idempotent Supabase outboxes with retry/read-back.

• Supabase Postgres and Storage with full-text search, row-level security, editorial roles, translations, consent registries and immutable media.

• Public, stateless, read-only MCP server at /api/mcp; approved comments are included without exposing private moderation data.

• API-key-protected admin MCP at /api/mcp/admin with editorial CRUD, comment moderation, campaigns, media and social outbox tools.

• Portable agent plugin manifests for Codex/OpenAI, Claude Code, and GitHub Copilot CLI.

• Hexagonal boundaries: domain and application code do not depend on Next.js or Supabase.

• Server Components, immediate write invalidation, optimized images, self-hosted fonts, native view transitions/loading states, and an enforced token-driven design system.

• Vercel configuration and GitHub Actions quality gate.

Related MCP server: News API MCP Server

Stack

• Next.js 16.3 and React 19.2

• TypeScript 5

• Supabase Postgres, Auth, and SSR client

• MCP TypeScript SDK

• Vitest and ESLint

• @google/design.md CLI 0.4

Run locally

Node.js 24 is used in CI and on Vercel. No environment variables are required for the read-only editorial demo or ephemeral demo Studio during local development.

npm ci
npm run dev

Open http://localhost:3000. The root redirects permanently to /en; use /it for Italian. Demo editorial data lives in memory and resets when the process restarts. Comments, newsletter delivery and social publishing remain visibly unavailable until Supabase and their real providers are configured.

To make local settings explicit:

cp .env.example .env.local

Use NEURA_CONTENT_MODE=demo locally and NEURA_CONTENT_MODE=supabase in every Preview/Production environment. Local development also enables the ephemeral demo Studio. Production Studio fails closed without Supabase unless NEURA_ENABLE_DEMO_STUDIO=true is set explicitly for an intentional, disposable review deployment. Demo production never confirms a non-persistent newsletter write.

Quality gate

npm run check

The gate runs design-system validation, plugin validation, lint, TypeScript, tests, the production build, and Brotli bundle/image budgets. GitHub Actions runs the same checks from a clean npm ci install.

MCP quick check

Discovery metadata:

curl http://localhost:3000/api/mcp/info

Read the latest English articles:

curl --request POST http://localhost:3000/api/mcp \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'MCP-Method: tools/call' \
  --header 'MCP-Name: list_articles' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_articles","arguments":{"locale":"en","limit":3},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

See MCP.md for public and admin tools, modern discovery, pagination, authentication, legacy compatibility, CORS, and production client configuration.

Production setup

1. Reproduce the database locally with the committed Supabase configuration, migration, and seed.

2. Create separate Supabase projects for Preview/Staging and Production.

3. Dry-run and apply the migration; do not automatically seed production.

4. Bootstrap the first Auth editor through the Supabase Dashboard and a bounded SQL grant.

5. Configure Resend, LinkedIn, X and WhatsApp credentials/webhooks, plus the Vercel cron secret.

6. Import this repository into Vercel, set the documented environment variables, and deploy.

7. Run the HTTP, localization, Supabase, comments, newsletter, social-outbox and MCP smoke checks.

Full instructions: DEPLOYMENT.md.

Documentation

• Architecture and boundaries

• Deployment and environment setup

• Internationalization and content model

• MCP server and client usage

• Cross-client agent plugin

• Operations, performance budgets, troubleshooting, and rollback

• Independent optimization report

• Design system source

Security model

• Public pages and Studio use the public Supabase URL and anon/publishable key. Workers and the admin MCP use the service-role key only after cron/API-key authentication; it must never use a NEXT_PUBLIC_* variable.

• Supabase RLS is the authorization boundary. Proxy and UI checks are convenience layers, not authorization.

• Anonymous users can read only published content and approved comments. Comment/newsletter mutations pass constrained RPCs, signed guest capabilities, same-origin checks and database rate limits; direct table writes are denied.

• Only authenticated users mapped to an editor or admin profile can mutate editorial data.

• The public MCP surface is intentionally read-only and exposes only published content plus approved comments. The admin endpoint requires a high-entropy Bearer key before resolving any server-only persistence/provider adapter; external actions additionally require confirm: true.

Repository map

src/app/                              Next.js delivery adapter
src/components/                       UI components
src/i18n/                             locale contract and message catalogs
src/modules/editorial/domain/         entities, invariants, and ports
src/modules/editorial/application/    use cases and cached queries
src/modules/editorial/infrastructure/ memory and Supabase adapters
src/modules/comments/                 threaded comments, moderation and notifications
src/modules/newsletter-delivery/      campaigns, Resend and consent lifecycle
src/modules/social-publishing/        provider adapters and social outbox
src/modules/mcp/                       public and authenticated MCP adapters
plugins/neura-ai-news/                 portable agent plugin bundle
supabase/migrations/                  versioned database schema and RLS
supabase/seed.sql                     deterministic development content

The canonical architecture description is ARCHITECTURE.md.