paper-mcp

Shared paper for users and agents. Built with Next.js, Clerk, Convex, Neon, and sketchbook-ui.

Stack

• Next.js app router
• Clerk auth
• Convex realtime backend
• Neon + Drizzle
• sketchbook-ui for the paper UI

Local Setup

npm install
cp env.example .env.local

Fill in .env.local, then run:

npx convex dev
npx drizzle-kit push
npm run doctor
npm run dev:stack

Required Local Env

# Clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
CLERK_ISSUER_URL=https://your-clerk-subdomain.clerk.accounts.dev
CLERK_WEBHOOK_SIGNING_SECRET=whsec_...

# Neon
DATABASE_URL=postgresql://...

# Convex
CONVEX_DEPLOYMENT=dev:...
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site

# AI
OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

Production Deploy

Vercel env

Use deploy/vercel.production.env as the import template.

Important values:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: production Clerk key for the same Clerk instance
• CLERK_SECRET_KEY: matching production Clerk secret
• NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
• NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/dashboard
• NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/dashboard
• CONVEX_DEPLOYMENT=prod:intent-mole-436
• CONVEX_DEPLOY_KEY=...
• NEXT_PUBLIC_CONVEX_URL=https://intent-mole-436.convex.cloud
• NEXT_PUBLIC_CONVEX_SITE_URL=https://intent-mole-436.convex.site
• CONVEX_TMPDIR=.convex-tmp

Convex prod env

Use deploy/convex.production.env for the Convex dashboard values.

Important value:

• CLERK_ISSUER_URL=https://clerk.paper.ruixen.app

This value is the Clerk Frontend API URL that Convex trusts in auth.config.ts. It should match the Clerk production instance and the publishable key used by the frontend.

Build behavior

npm run build now does a real production Convex deploy before the Next.js build:

npx convex deploy --cmd 'npm run build:app'

That matters because production needs both:

• the frontend bundle built by Next.js
• the current Convex functions pushed to intent-mole-436

If you only want a local app build without deploying Convex, use:

npm run build:app

Clerk + Convex Notes

• The Clerk production instance currently uses the custom domain family under paper.ruixen.app
• Clerk Frontend API: https://clerk.paper.ruixen.app
• Clerk account portal: https://accounts.paper.ruixen.app
• Convex auth expects audience convex
• The Clerk JWT template named convex must exist

In this repo, the browser always requests the explicit convex JWT template before talking to Convex.

Custom Domain Notes

To keep the current production auth setup working:

• app domain should be paper.ruixen.app
• Clerk DNS records in Cloudflare should stay DNS only, not proxied
• Convex production should trust https://clerk.paper.ruixen.app

If you later change the Clerk production domain again, you must recheck:

• Clerk publishable key in Vercel
• CLERK_ISSUER_URL in Convex
• Clerk DNS verification / SSL

Verification

Before shipping:

npm run lint
npm run test:unit
npx tsc --noEmit
npm run build

npm run doctor is also useful when auth/env wiring changes.

Useful Commands

npm run doctor
npm run dev:stack
npm run bootstrap
npm run clean
npx convex run health:stack '{}'

Relevant Files

• package.json
• convex/auth.config.ts
• src/providers/ConvexClientProvider.tsx
• scripts/doctor.mjs
• deploy/vercel.production.env
• deploy/convex.production.env