feat: add neon authV2 support (#151)

## PR Description

### Title: Add Neon Auth v2 Support with Prompts and Client Detection

### Summary

This PR updates the Neon MCP server to support Neon Auth v2 (Better
Auth-based) and introduces a new prompts system with client-specific
instructions.

### Changes

#### Neon Auth v2 Migration
- **Migrated from Stack Auth to Better Auth**: Updated the
`provision_neon_auth` tool to use the new `createNeonAuth` API with
`BetterAuth` provider instead of the legacy `createNeonAuthIntegration`
with `Stack` provider
- **Branch-level provisioning**: Added optional `branchId` parameter,
allowing Neon Auth to be provisioned on specific branches (not just the
project's default branch)
- **Updated response format**: Returns the Better Auth-compatible base
URL instead of Stack-specific environment variables

#### New Prompts System
- **Added `setup-neon-auth` prompt**: Interactive guide for setting up
Neon Auth in Vite+React projects, with steps for provisioning, package
installation, client setup, and UI components
- **Client-specific instructions**: The prompt adapts its guidance based
on the detected MCP client (Cursor, Claude, or other)
- **Just-in-Time Context Protocol**: Embedded documentation fetching
protocol that guides AI agents to fetch external docs only when needed

#### Client Application Detection
- **New utility**: Added `detectClientApplication()` to identify the MCP
client from the initialization handshake
- **Client type injection**: The detected client type is now passed to
tool handlers via `extra.clientApplication`

#### Dependency Updates
- Upgraded `@neondatabase/api-client` from 2.0.0 to 2.5.0
- Upgraded `axios` from 1.11.0 to 1.13.2 (with resolution override)

#### Other
- Minor UI fix: Updated color classes in landing page to use theme
tokens (`text-muted-foreground`, `bg-muted`)
- Added `Prettify` type helper

### Breaking Changes
- The `provision_neon_auth` tool parameter `database` has been renamed
to `databaseName` for consistency with other tools

---

Author: pffigueiredo

.github/workflows/claude-code-review.yml

@@ -22,13 +22,8 @@ concurrency:
 
 jobs:
   claude-review:
-    # For automatic runs: only allow members/collaborators/owners
-    # For manual runs: always allow (since only repo members can trigger workflows)
-    if: |
-      github.event_name == 'workflow_dispatch' ||
-      github.event.pull_request.author_association == 'OWNER' ||
-      github.event.pull_request.author_association == 'MEMBER' ||
-      github.event.pull_request.author_association == 'COLLABORATOR'
+    # Disabled: set to false to prevent workflow execution
+    if: ${{ false }}
 
     runs-on:
       group: neondatabase-protected-runner-group

bun.lock

@@ -6,13 +6,13 @@
       "dependencies": {
         "@keyv/postgres": "2.1.2",
         "@modelcontextprotocol/sdk": "1.11.2",
-        "@neondatabase/api-client": "2.0.0",
+        "@neondatabase/api-client": "2.5.0",
         "@neondatabase/serverless": "1.0.0",
         "@radix-ui/react-accordion": "1.2.11",
         "@segment/analytics-node": "2.2.1",
         "@sentry/node": "9.19.0",
         "@tailwindcss/postcss": "4.1.10",
-        "axios": "1.11.0",
+        "axios": "1.13.2",
         "body-parser": "2.2.0",
         "chalk": "5.3.0",
         "class-variance-authority": "0.7.1",
@@ -55,6 +55,9 @@
       },
     },
   },
+  "overrides": {
+    "axios": "1.13.2",
+  },
   "packages": {
     "@ai-sdk/provider": ["@ai-sdk/provider@1.1.3", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-qZMxYJ0qqX/RfnuIaab+zp8UAeJn/ygXXAffR5I4N0n1IrvA6qBsjc8hXLmBiMV2zoXlifkacF7sEFnYnjBcqg=="],
 
@@ -232,7 +235,7 @@
 
     "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.11.2", "", { "dependencies": { "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.3", "eventsource": "^3.0.2", "express": "^5.0.1", "express-rate-limit": "^7.5.0", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.23.8", "zod-to-json-schema": "^3.24.1" } }, "sha512-H9vwztj5OAqHg9GockCQC06k1natgcxWQSRpQcPJf6i5+MWBzfKkRtxGbjQf0X2ihii0ffLZCRGbYV2f2bjNCQ=="],
 
-    "@neondatabase/api-client": ["@neondatabase/api-client@2.0.0", "", { "dependencies": { "axios": "^1.7.9" } }, "sha512-UwjRRy8gyShNDfbbP1N+rA235FzqVWP/WPi4cgLnkGgConqpiR+U9Dsegaxu+HxAgK678kQ/5wc4/EPexvE7tw=="],
+    "@neondatabase/api-client": ["@neondatabase/api-client@2.5.0", "", { "dependencies": { "axios": "^1.9.0" } }, "sha512-Tg5/Aq8zg1kxT8OuaRULpl0NcxTLpOBpcbdeC8RO3U6Ubftu+YSjKUqB5NRZWITMwDy8GSJtPQYF/xHHlsqauQ=="],
 
     "@neondatabase/serverless": ["@neondatabase/serverless@1.0.0", "", { "dependencies": { "@types/node": "^22.10.2", "@types/pg": "^8.8.0" } }, "sha512-XWmEeWpBXIoksZSDN74kftfTnXFEGZ3iX8jbANWBc+ag6dsiQuvuR4LgB0WdCOKMb5AQgjqgufc0TgAsZubUYw=="],
 
@@ -550,7 +553,7 @@
 
     "autoevals": ["autoevals@0.0.111", "", { "dependencies": { "@braintrust/core": "0.0.71", "ajv": "^8.13.0", "compute-cosine-similarity": "^1.1.0", "js-levenshtein": "^1.1.6", "js-yaml": "^4.1.0", "linear-sum-assignment": "^1.0.7", "mustache": "^4.2.0", "openai": "4.47.1", "zod": "^3.22.4", "zod-to-json-schema": "^3.22.5" } }, "sha512-H38avDrcWU6w7aP0CwCansc/Um/3Bm8yvjMX6g8TR4FIJeyY84poimdNK3GDRk+hhoiY1DovdZoEJILWC6OmgQ=="],
 
-    "axios": ["axios@1.11.0", "", { "dependencies": { "follow-redirects": "^1.15.6", "form-data": "^4.0.4", "proxy-from-env": "^1.1.0" } }, "sha512-1Lx3WLFQWm3ooKDYZD1eXmoGO9fxYQjrycfHFC8P0sCfQVXyROp0p9PFWBehewBOdCwHc+f/b8I0fMto5eSfwA=="],
+    "axios": ["axios@1.13.2", "", { "dependencies": { "follow-redirects": "^1.15.6", "form-data": "^4.0.4", "proxy-from-env": "^1.1.0" } }, "sha512-VPk9ebNqPcy5lRGuSlKx752IlDatOjT9paPlm8A7yOuW2Fbvp4X3JznJtT4f0GzGLLiWE9W8onz51SqLYwzGaA=="],
 
     "axobject-query": ["axobject-query@4.1.0", "", {}, "sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ=="],
 
@@ -1368,8 +1371,6 @@
 
     "@humanfs/node/@humanwhocodes/retry": ["@humanwhocodes/retry@0.3.1", "", {}, "sha512-JBxkERygn7Bv/GbN5Rv8Ul6LVknS+5Bp6RgDC/O8gEBU/yeH5Ui5C/OlWrTb6qct7LjjfT6Re2NxB0ln0yYybA=="],
 
-    "@neondatabase/api-client/axios": ["axios@1.9.0", "", { "dependencies": { "follow-redirects": "^1.15.6", "form-data": "^4.0.0", "proxy-from-env": "^1.1.0" } }, "sha512-re4CqKTJaURpzbLHtIi6XpDv20/CnpXOtjRY5/CU32L8gU8ek9UIivcfvSWvmKEngmVbrUtPpdDwWDWL7DNHvg=="],
-
     "@neondatabase/serverless/@types/node": ["@types/node@22.15.18", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-v1DKRfUdyW+jJhZNEI1PYy29S2YRxMV5AOO/x/SjKmW0acCIOqmbj6Haf9eHAhsPmrhlHSxEhv/1WszcLWV4cg=="],
 
     "@opentelemetry/core/@opentelemetry/semantic-conventions": ["@opentelemetry/semantic-conventions@1.28.0", "", {}, "sha512-lp4qAiMTD4sNWW4DbKLBkfiMZ4jbAboJIGOQr5DvciMRI494OapieI9qiODpOt0XBr1LjIDy1xAGAnVs5supTA=="],

landing/components/Introduction.tsx

@@ -45,9 +45,9 @@ export const Introduction = ({ className }: { className?: string }) => (
             Safe for cloud environments. All transactions are read-only -
             perfect for querying and analyzing data without modification risks.
           </p>
-          <p className="text-xs text-gray-600">
+          <p className="text-xs text-muted-foreground">
             Enable read-only mode by adding the{' '}
-            <code className="bg-gray-100 px-1 py-0.5 rounded text-xs">
+            <code className="bg-muted px-1 py-0.5 rounded text-xs">
               x-read-only: true
             </code>{' '}
             header in your MCP configuration.

package-lock.json

@@ -35,13 +35,13 @@
   "dependencies": {
     "@keyv/postgres": "2.1.2",
     "@modelcontextprotocol/sdk": "1.11.2",
-    "@neondatabase/api-client": "2.0.0",
+    "@neondatabase/api-client": "2.5.0",
     "@neondatabase/serverless": "1.0.0",
     "@radix-ui/react-accordion": "1.2.11",
     "@segment/analytics-node": "2.2.1",
     "@sentry/node": "9.19.0",
     "@tailwindcss/postcss": "4.1.10",
-    "axios": "1.11.0",
+    "axios": "1.13.2",
     "body-parser": "2.2.0",
     "chalk": "5.3.0",
     "class-variance-authority": "0.7.1",
@@ -84,5 +84,8 @@
   },
   "engines": {
     "node": ">=22.0.0"
+  },
+  "resolutions": {
+    "axios": "1.13.2"
   }
 }

package.json

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { fetchRawGithubContent } from './resources.js';
+import { ToolHandlerExtraParams } from './tools/types.js';
+import { ClientApplication } from './utils/client-application.js';
+
+export const setupNeonAuthViteReactArgsSchema = {
+  projectId: z
+    .string()
+    .optional()
+    .describe(
+      'Optional Neon project ID. If not provided, the guide will help discover available projects.',
+    ),
+  branchId: z
+    .string()
+    .optional()
+    .describe(
+      'Optional branch ID. If not provided, the default branch will be used.',
+    ),
+  databaseName: z
+    .string()
+    .optional()
+    .describe(
+      'Optional database name. If not provided, the default database (neondb) will be used.',
+    ),
+} as const;
+
+export const NEON_PROMPTS = [
+  {
+    name: 'setup-neon-auth',
+    description:
+      'Interactive guide for setting up Neon Auth in a Vite+React project. Walks through provisioning, package installation, client setup, and UI components.',
+    argsSchema: setupNeonAuthViteReactArgsSchema,
+  },
+] as const;
+
+const CLIENT_SPECIFIC_INSTRUCTIONS: Record<ClientApplication, string> = {
+  cursor: `
+  - **For URLs:** Use the \`@Web\` tool (or \`web_search\`) to fetch the page.
+  - **For Files:** Use \`grep\` or \`cat\` to read local files.
+  `,
+  claude: `
+   - **For URLs:** Use your \`web_fetch\` tool (or \`web_search\`) to read content.
+   - **For Files:** Use \`grep\` or \`cat\` to read local files.
+  `,
+  other: `
+   - **For URLs:** Use your web fetch tool to read content, or curl if you need to.
+   - **For Files:** Use \`grep\` or \`cat\` to read local files.
+  `,
+};
+
+const COMMON_FOLLOW_INSTRUCTIONS = (clientApplication: ClientApplication) => `
+
+# Just-in-Time Context Protocol
+
+## 1. ASSESSMENT & TRIGGER
+- **Analyze Gaps:** Before generating code, ask: "Do I have the *exact* API signatures and patterns for this specific task in my context?"
+- **Lazy Loading:** Do NOT read external links or docs if the current context is sufficient.
+- **Trigger:** IF you lack specific details AND a reference link/path exists in the rules (e.g., \`[Full Setup](url)\`), you MUST fetch that resource immediately.
+
+## 2. STRICT LINK OBEDIENCE
+- **No Guessing:** If a task relates to a linked topic (e.g., "Styling"), you are PROHIBITED from inferring patterns. You must read the linked reference.
+- **Method:**
+   ${CLIENT_SPECIFIC_INSTRUCTIONS[clientApplication]}
+
+## 3. EXECUTION
+- **State Intent:** Briefly confirm: "Fetching [Topic] details from [Source]..."
+- **Apply & Discard:** Extract only what is needed for the current task.
+
+## ENFORCEMENT
+⚠️ You MUST follow these rules. If you skip documentation lookup, you are breaking protocol.
+`;
+
+export const getPromptTemplate = async (
+  promptName: string,
+  extra: ToolHandlerExtraParams,
+  args?: Record<string, string>,
+): Promise<string> => {
+  if (promptName === 'setup-neon-auth') {
+    // Variables are available for future template interpolation
+    void args?.projectId;
+    void args?.branchId;
+    void args?.databaseName;
+
+    const content = await fetchRawGithubContent(
+      '/neondatabase-labs/ai-rules/main/mcp-prompts/neon-auth-setup.md',
+    );
+
+    return `
+    ${COMMON_FOLLOW_INSTRUCTIONS(extra.clientApplication)}
+
+    ---
+    
+    ${content}`;
+  }
+
+  throw new Error(`Unknown prompt: ${promptName}`);
+};

src/prompts.ts

@@ -2,6 +2,7 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { NEON_RESOURCES } from '../resources.js';
+import { NEON_PROMPTS, getPromptTemplate } from '../prompts.js';
 import {
   NEON_HANDLERS,
   NEON_TOOLS,
@@ -15,6 +16,7 @@ import { ServerContext } from '../types/context.js';
 import { setSentryTags } from '../sentry/utils.js';
 import { ToolHandlerExtraParams } from '../tools/types.js';
 import { handleToolError } from './errors.js';
+import { detectClientApplication } from '../utils/client-application.js';
 
 export const createMcpServer = (context: ServerContext) => {
   const server = new McpServer(
@@ -26,6 +28,9 @@ export const createMcpServer = (context: ServerContext) => {
       capabilities: {
         tools: {},
         resources: {},
+        prompts: {
+          listChanged: true,
+        },
       },
     },
   );
@@ -59,22 +64,34 @@ export const createMcpServer = (context: ServerContext) => {
             },
           },
           async (span) => {
+            // Get client info from MCP protocol
+            const clientInfo = server.server.getClientVersion();
+
             const properties = {
               tool_name: tool.name,
               readOnly: String(context.readOnly ?? false),
+              clientName: clientInfo?.name ?? 'unknown',
             };
             logger.info('tool call:', properties);
+            logger.info('MCP Client Info:', clientInfo);
             setSentryTags(context);
             track({
               userId: context.account.id,
               event: 'tool_call',
               properties,
-              context: { client: context.client, app: context.app },
+              context: {
+                client: context.client,
+                app: context.app,
+                clientInfo,
+              },
             });
+
+            const clientApplication = detectClientApplication(clientInfo?.name);
             const extraArgs: ToolHandlerExtraParams = {
               ...extra,
               account: context.account,
               readOnly: context.readOnly,
+              clientApplication,
             };
             try {
               return await toolHandler(args, neonClient, extraArgs);
@@ -121,6 +138,59 @@ export const createMcpServer = (context: ServerContext) => {
     );
   });
 
+  // Register prompts
+  NEON_PROMPTS.forEach((prompt) => {
+    server.prompt(
+      prompt.name,
+      prompt.description,
+      prompt.argsSchema,
+      async (args, extra) => {
+        // Get client info from MCP protocol
+        const clientInfo = server.server.getClientVersion();
+        const clientApplication = detectClientApplication(clientInfo?.name);
+
+        const properties = { prompt_name: prompt.name };
+        logger.info('prompt call:', properties);
+        setSentryTags(context);
+        track({
+          userId: context.account.id,
+          event: 'prompt_call',
+          properties,
+          context: { client: context.client, app: context.app },
+        });
+        try {
+          const extraArgs: ToolHandlerExtraParams = {
+            ...extra,
+            account: context.account,
+            readOnly: context.readOnly,
+            clientApplication,
+          };
+          const template = await getPromptTemplate(
+            prompt.name,
+            extraArgs,
+            args,
+          );
+          return {
+            messages: [
+              {
+                role: 'user',
+                content: {
+                  type: 'text',
+                  text: template,
+                },
+              },
+            ],
+          };
+        } catch (error) {
+          captureException(error, {
+            extra: properties,
+          });
+          throw error;
+        }
+      },
+    );
+  });
+
   server.server.onerror = (error: unknown) => {
     const message = error instanceof Error ? error.message : 'Unknown error';
     logger.error('Server error:', {