new

Author: agairola

CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an MCP (Model Context Protocol) OAuth 2.1 server implementation built with Next.js 15, providing secure authentication for MCP clients. The application serves as an OAuth authorization server that enables MCP clients to authenticate users and access protected MCP resources.
+
+## Core Architecture
+
+### Authentication Flow
+- **NextAuth.js**: Handles user authentication via Google OAuth provider
+- **OAuth 2.1 Server**: Custom implementation with PKCE support for MCP client authorization
+- **Database**: PostgreSQL with Prisma ORM storing OAuth clients, tokens, and user sessions
+- **MCP Integration**: Uses `@vercel/mcp-adapter` for MCP protocol handling
+
+### Key Components
+- `app/auth.ts`: NextAuth configuration with Google provider and Prisma adapter
+- `app/api/oauth/`: OAuth 2.1 server endpoints (register, token, authorize)
+- `app/mcp/[transport]/route.ts`: MCP server with authentication middleware
+- `prisma/schema.prisma`: Database schema for OAuth entities and NextAuth models
+
+### Database Schema
+The Prisma schema includes:
+- NextAuth models (User, Account, Session, VerificationToken)
+- OAuth 2.1 models (Client, AccessToken, AuthCode) with PKCE support
+- Proper foreign key relationships and cascading deletes
+
+## Development Commands
+
+```bash
+# Start development server
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Start production server
+pnpm start
+
+# Lint code
+pnpm lint
+
+# Database operations
+pnpm prisma generate      # Generate Prisma client
+pnpm prisma db push       # Push schema changes to database
+pnpm prisma migrate dev   # Create and apply migrations
+pnpm prisma studio        # Open database admin interface
+```
+
+## Environment Setup
+
+Required environment variables:
+- `DATABASE_URL`: PostgreSQL connection string
+- `AUTH_SECRET`: NextAuth secret key
+- `GOOGLE_CLIENT_ID`: Google OAuth client ID
+- `GOOGLE_CLIENT_SECRET`: Google OAuth client secret
+- `REDIS_URL`: Optional Redis URL for SSE transport support
+
+## Database Management
+
+PostgreSQL must be running locally for development:
+```bash
+# Start PostgreSQL (macOS with Homebrew)
+brew services start postgresql@14
+
+# Stop PostgreSQL
+brew services stop postgresql@14
+```
+
+## MCP Integration
+
+The MCP server (`app/mcp/[transport]/route.ts`) implements:
+- Bearer token authentication using OAuth access tokens
+- Token audience validation for security
+- CORS headers for cross-origin requests
+- Sample tool implementation (`add_numbers`)
+
+## Security Considerations
+
+- PKCE (Proof Key for Code Exchange) is implemented for public clients
+- Access tokens are validated against database and checked for expiration
+- Token audience validation prevents token misuse across different resources
+- Proper CORS configuration for MCP client access
+
+## Testing MCP Integration
+
+MCP clients can connect using:
+- SSE transport: `https://your-domain.com/mcp/sse`
+- HTTP transport: `https://your-domain.com/mcp/mcp`
+
+Clients must include OAuth access token in Authorization header as Bearer token.
+
+## Prisma Client Location
+
+The Prisma client is generated to `generated/prisma/` directory (not the default location) as specified in the schema generator configuration.

MCP_IMPLEMENTATION_ANALYSIS.md

@@ -117,6 +117,19 @@ ALTER TABLE "AuthCode" ADD COLUMN "resource" TEXT;
 
 -- AccessToken table  
 ALTER TABLE "AccessToken" ADD COLUMN "resource" TEXT;
+
+-- RefreshToken table (NEW - for refresh token support)
+CREATE TABLE "RefreshToken" (
+  "id" TEXT NOT NULL PRIMARY KEY DEFAULT gen_random_uuid(),
+  "token" TEXT NOT NULL UNIQUE,
+  "expiresAt" TIMESTAMP(3) NOT NULL,
+  "clientId" TEXT NOT NULL,
+  "userId" TEXT NOT NULL,
+  "resource" TEXT,
+  "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "RefreshToken_clientId_fkey" FOREIGN KEY ("clientId") REFERENCES "Client" ("id") ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT "RefreshToken_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User" ("id") ON DELETE CASCADE ON UPDATE CASCADE
+);
 ```
 
 ## MCP Authorization Flow (Now Compliant)
@@ -174,8 +187,100 @@ After deploying these changes, verify:
 ## Next Steps
 
 1. **Deploy changes** to your Vercel instance
-2. **Run database migration**: `pnpm prisma db push`
-3. **Test with MCP client** (Cursor, Claude, etc.)
-4. **Monitor logs** for successful authorization flows
+2. **Run database migration**: `pnpm prisma db push` (includes new RefreshToken table)
+3. **Generate Prisma client**: `pnpm prisma generate` (required for RefreshToken model)
+4. **Test authorization flow** with MCP client (Cursor, Claude, etc.)
+5. **Test refresh token flow** to verify automatic token refresh
+6. **Monitor logs** for successful authorization and refresh flows
+
+### Verification Commands
+
+Test refresh token discovery:
+```bash
+curl https://your-domain.com/.well-known/oauth-authorization-server | jq '.grant_types_supported'
+```
+
+Test token endpoint with refresh_token grant:
+```bash
+# First get tokens via authorization flow, then test refresh
+curl -X POST https://your-domain.com/api/oauth/token \
+  -d "grant_type=refresh_token&refresh_token=your_refresh_token&client_id=your_client_id"
+```
+
+### Testing Refresh Token Flow
+
+With 5-minute access tokens, you can easily test the refresh functionality:
+
+1. **Complete OAuth flow** - Get initial access + refresh tokens
+2. **Use access token** - Make MCP requests (works for 5 minutes)
+3. **Wait 5+ minutes** - Access token expires
+4. **Test expiry** - MCP request should return 401
+5. **Use refresh token** - Get new access + refresh tokens
+6. **Resume requests** - New access token should work
+
+This short expiry makes it easy to test token refresh without waiting 30 minutes!
+
+Your implementation is now **MCP specification compliant** and should work with standard MCP clients! 🎉
+
+## Refresh Token Implementation (NEW)
+
+### ✅ Added Refresh Token Support
+
+To improve user experience and follow OAuth 2.1 best practices, refresh token support has been implemented:
+
+#### **Key Features:**
+- **Short-lived access tokens**: 5 minutes for easy testing (configurable)
+- **Long-lived refresh tokens**: 7 days lifetime
+- **Token rotation**: For public clients (no client secret), refresh tokens are rotated per OAuth 2.1 requirements
+- **Resource binding**: Refresh tokens maintain the same audience binding as the original access token
+- **Standard OAuth error codes**: Proper error responses (`invalid_grant`, `invalid_client`, etc.)
+
+#### **Authorization Server Metadata Updated:**
+```json
+{
+  "grant_types_supported": ["authorization_code", "refresh_token"],
+  "resource_parameter_supported": true
+}
+```
+
+#### **Token Response Format (Updated):**
+```json
+{
+  "access_token": "abc123...",
+  "refresh_token": "def456...",
+  "token_type": "Bearer",
+  "expires_in": 300
+}
+```
+
+#### **Refresh Token Grant Usage:**
+```http
+POST /api/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=refresh_token
+&refresh_token=def456...
+&client_id=client123
+&resource=https://mcp.example.com
+```
 
-Your implementation is now **MCP specification compliant** and should work with standard MCP clients! 🎉 
+#### **Security Enhancements:**
+1. **Token Rotation**: Public clients get new refresh tokens with each refresh
+2. **Audience Validation**: Refresh tokens maintain resource binding
+3. **Expiry Management**: Both access and refresh tokens have proper expiration
+4. **Client Authentication**: Confidential clients must provide client_secret
+
+#### **Implementation Benefits:**
+- **No Re-authentication**: Users stay logged in as long as refresh token is valid
+- **Better Security**: Shorter access token lifetime reduces risk of token theft
+- **OAuth 2.1 Compliant**: Follows latest OAuth security recommendations
+- **MCP Compatible**: Works seamlessly with MCP client discovery flow
+
+### Updated Database Schema
+
+The `RefreshToken` model includes:
+- Unique token identifier
+- Expiration timestamp (7 days)
+- Client and user relationships
+- Resource binding for audience validation
+- Cascade delete for cleanup