purmemo-mcp 1.0.0 → 2.0.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "purmemo-mcp",
-  "version": "1.0.0",
-  "description": "Official Model Context Protocol (MCP) server for Purmemo - Your AI-powered second brain with 94% memory retrieval accuracy",
-  "main": "src/index.js",
+  "version": "2.0.0",
+  "description": "Official Model Context Protocol (MCP) server for Purmemo - Seamless OAuth authentication for your AI-powered second brain",
+  "main": "src/server-oauth.js",
   "type": "module",
   "bin": {
-    "purmemo-mcp": "./bin/purmemo-mcp"
+    "purmemo-mcp": "./src/server-oauth.js",
+    "purmemo-mcp-setup": "./src/setup.js"
   },
   "files": [
     "src/",
@@ -14,35 +15,48 @@
     "LICENSE"
   ],
   "scripts": {
-    "start": "node src/index.js"
+    "start": "node src/server-oauth.js",
+    "setup": "node src/setup.js setup",
+    "status": "node src/setup.js status",
+    "logout": "node src/setup.js logout",
+    "test": "echo \"No tests yet\"",
+    "postinstall": "node -e \"console.log('\\n🧠 pūrmemo MCP v2.0.0 installed!\\n\\nNew users: Run \\'npx purmemo-mcp setup\\' to connect your account.\\nExisting users: Your API key still works (backwards compatible).\\n')\""
   },
   "keywords": [
     "mcp",
     "memory",
     "ai",
     "claude",
-    "purmemo"
+    "purmemo",
+    "oauth",
+    "authentication"
   ],
-  "author": "Christopher Coladapo <support@purmemo.ai>",
+  "author": "Purmemo Team <support@purmemo.ai>",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/coladapo/purmemo-mcp.git"
   },
   "bugs": {
-    "url": "https://github.com/coladapo/puo-memo-mcp/issues",
+    "url": "https://github.com/coladapo/purmemo-mcp/issues",
     "email": "support@purmemo.ai"
   },
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/coladapo"
   },
-  "support": "https://github.com/coladapo/puo-memo-mcp/discussions",
+  "support": "https://github.com/coladapo/purmemo-mcp/discussions",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.16.0",
-    "node-fetch": "^3.3.2"
+    "node-fetch": "^3.3.2",
+    "express": "^4.18.2",
+    "open": "^10.0.0",
+    "commander": "^11.1.0",
+    "chalk": "^5.3.0",
+    "inquirer": "^9.2.12",
+    "ora": "^7.0.1"
   },
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package/src/auth/oauth-manager.js

@@ -0,0 +1,365 @@
+/**
+ * OAuth Manager for Purmemo MCP
+ * Handles OAuth 2.1 + PKCE flow for seamless authentication
+ */
+
+import crypto from 'crypto';
+import express from 'express';
+import open from 'open';
+import TokenStore from './token-store.js';
+
+class OAuthManager {
+  constructor(config = {}) {
+    this.apiUrl = config.apiUrl || process.env.PUO_MEMO_API_URL || 'https://api.purmemo.ai';
+    this.clientId = config.clientId || 'purmemo-mcp';
+    this.redirectUri = config.redirectUri || 'http://localhost:3456/callback';
+    this.tokenStore = new TokenStore();
+    this.server = null;
+    this.pendingAuth = null;
+  }
+
+  /**
+   * Get current authentication token
+   * @returns {Promise<string|null>} Access token or null if not authenticated
+   */
+  async getToken() {
+    // First check if we have a valid token
+    const storedToken = await this.tokenStore.getToken();
+    
+    if (storedToken && storedToken.access_token) {
+      // Check if token needs refresh (expired or close to expiry)
+      if (this.isTokenExpired(storedToken)) {
+        try {
+          return await this.refreshToken(storedToken.refresh_token);
+        } catch (error) {
+          console.error('Token refresh failed:', error.message);
+          // If refresh fails, start new OAuth flow
+          return null;
+        }
+      }
+      return storedToken.access_token;
+    }
+
+    // Fallback to environment variable for backwards compatibility
+    const envApiKey = process.env.PUO_MEMO_API_KEY;
+    if (envApiKey) {
+      console.log('📔 Using API key from environment variable');
+      return envApiKey;
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if token is expired or about to expire
+   */
+  isTokenExpired(token) {
+    if (!token.expires_at) return false;
+    
+    const now = Date.now();
+    const expiresAt = new Date(token.expires_at).getTime();
+    const bufferTime = 5 * 60 * 1000; // 5 minutes buffer
+    
+    return now >= (expiresAt - bufferTime);
+  }
+
+  /**
+   * Start OAuth flow
+   * @returns {Promise<string>} Access token
+   */
+  async authenticate() {
+    if (this.pendingAuth) {
+      return this.pendingAuth;
+    }
+
+    this.pendingAuth = this.performOAuthFlow();
+    
+    try {
+      const token = await this.pendingAuth;
+      return token;
+    } finally {
+      this.pendingAuth = null;
+    }
+  }
+
+  /**
+   * Perform the actual OAuth flow
+   */
+  async performOAuthFlow() {
+    console.log('\n🔐 Starting Purmemo authentication...\n');
+    
+    // Generate PKCE challenge
+    const codeVerifier = this.generateCodeVerifier();
+    const codeChallenge = this.generateCodeChallenge(codeVerifier);
+    const state = crypto.randomBytes(16).toString('hex');
+
+    // Build OAuth URL
+    const authUrl = new URL(`${this.apiUrl}/api/oauth/initiate`);
+    authUrl.searchParams.append('client_id', this.clientId);
+    authUrl.searchParams.append('redirect_uri', this.redirectUri);
+    authUrl.searchParams.append('response_type', 'code');
+    authUrl.searchParams.append('scope', 'memories.read memories.write entities.read');
+    authUrl.searchParams.append('state', state);
+    authUrl.searchParams.append('code_challenge', codeChallenge);
+    authUrl.searchParams.append('code_challenge_method', 'S256');
+
+    // Start local server for callback
+    const authCode = await this.startCallbackServer(state);
+    
+    // Open browser for authentication
+    console.log('📱 Opening browser for authentication...');
+    console.log('   If browser doesn\'t open, visit:');
+    console.log(`   ${authUrl.toString()}\n`);
+    
+    await open(authUrl.toString());
+
+    // Wait for callback with auth code
+    const code = await authCode;
+
+    // Exchange code for token
+    const tokenResponse = await this.exchangeCodeForToken(code, codeVerifier);
+    
+    // Store token securely
+    await this.tokenStore.saveToken(tokenResponse);
+    
+    console.log('✅ Authentication successful!\n');
+    
+    return tokenResponse.access_token;
+  }
+
+  /**
+   * Start local server to handle OAuth callback
+   */
+  startCallbackServer(expectedState) {
+    return new Promise((resolve, reject) => {
+      const app = express();
+      let resolved = false;
+
+      app.get('/callback', async (req, res) => {
+        const { code, state, error, error_description } = req.query;
+
+        if (error) {
+          res.send(`
+            <html>
+              <head>
+                <title>Authentication Failed</title>
+                <style>
+                  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; 
+                         display: flex; justify-content: center; align-items: center; 
+                         height: 100vh; margin: 0; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); }
+                  .container { background: white; padding: 40px; border-radius: 10px; 
+                              box-shadow: 0 20px 60px rgba(0,0,0,0.3); text-align: center; max-width: 400px; }
+                  h1 { color: #e53e3e; margin: 0 0 10px 0; }
+                  p { color: #718096; margin: 10px 0; }
+                  .error { background: #fed7d7; padding: 10px; border-radius: 5px; 
+                          color: #c53030; margin-top: 20px; }
+                </style>
+              </head>
+              <body>
+                <div class="container">
+                  <h1>❌ Authentication Failed</h1>
+                  <p>Unable to complete authentication</p>
+                  <div class="error">${error}: ${error_description || 'Unknown error'}</div>
+                  <p style="margin-top: 20px; font-size: 14px;">You can close this window</p>
+                </div>
+              </body>
+            </html>
+          `);
+          
+          if (!resolved) {
+            resolved = true;
+            this.stopCallbackServer();
+            reject(new Error(`OAuth error: ${error} - ${error_description}`));
+          }
+          return;
+        }
+
+        if (state !== expectedState) {
+          res.send(`
+            <html>
+              <head><title>Security Error</title></head>
+              <body style="font-family: sans-serif; text-align: center; padding: 50px;">
+                <h1 style="color: red;">Security Error</h1>
+                <p>State mismatch - possible CSRF attack</p>
+              </body>
+            </html>
+          `);
+          
+          if (!resolved) {
+            resolved = true;
+            this.stopCallbackServer();
+            reject(new Error('OAuth state mismatch'));
+          }
+          return;
+        }
+
+        // Success response
+        res.send(`
+          <html>
+            <head>
+              <title>Authentication Successful</title>
+              <style>
+                body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; 
+                       display: flex; justify-content: center; align-items: center; 
+                       height: 100vh; margin: 0; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); }
+                .container { background: white; padding: 40px; border-radius: 10px; 
+                            box-shadow: 0 20px 60px rgba(0,0,0,0.3); text-align: center; max-width: 400px; }
+                h1 { color: #48bb78; margin: 0 0 10px 0; }
+                p { color: #718096; margin: 10px 0; }
+                .success { background: #c6f6d5; padding: 15px; border-radius: 5px; 
+                          color: #22543d; margin-top: 20px; }
+                .logo { font-size: 48px; margin-bottom: 20px; }
+              </style>
+            </head>
+            <body>
+              <div class="container">
+                <div class="logo">🧠</div>
+                <h1>✅ Authentication Successful!</h1>
+                <p>You're now connected to Purmemo</p>
+                <div class="success">
+                  You can now close this window and return to Claude Desktop
+                </div>
+                <script>setTimeout(() => window.close(), 3000);</script>
+              </div>
+            </body>
+          </html>
+        `);
+
+        if (!resolved) {
+          resolved = true;
+          this.stopCallbackServer();
+          resolve(code);
+        }
+      });
+
+      // Start server
+      this.server = app.listen(3456, () => {
+        console.log('🌐 Waiting for authentication callback...\n');
+      });
+
+      // Timeout after 5 minutes
+      setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          this.stopCallbackServer();
+          reject(new Error('Authentication timeout'));
+        }
+      }, 5 * 60 * 1000);
+    });
+  }
+
+  /**
+   * Stop the callback server
+   */
+  stopCallbackServer() {
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+  }
+
+  /**
+   * Exchange authorization code for access token
+   */
+  async exchangeCodeForToken(code, codeVerifier) {
+    const response = await fetch(`${this.apiUrl}/api/oauth/token`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'purmemo-mcp/2.0.0'
+      },
+      body: JSON.stringify({
+        grant_type: 'authorization_code',
+        code,
+        client_id: this.clientId,
+        redirect_uri: this.redirectUri,
+        code_verifier: codeVerifier
+      })
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    const tokenData = await response.json();
+    
+    // Add expiry time
+    if (tokenData.expires_in) {
+      tokenData.expires_at = new Date(Date.now() + tokenData.expires_in * 1000).toISOString();
+    }
+
+    // Store user tier info
+    if (tokenData.user) {
+      tokenData.user_tier = tokenData.user.tier || 'free';
+      tokenData.memory_limit = tokenData.user.tier === 'pro' ? null : 100;
+    }
+
+    return tokenData;
+  }
+
+  /**
+   * Refresh access token
+   */
+  async refreshToken(refreshToken) {
+    if (!refreshToken) {
+      throw new Error('No refresh token available');
+    }
+
+    console.log('🔄 Refreshing authentication token...');
+
+    const response = await fetch(`${this.apiUrl}/api/auth/refresh`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'purmemo-mcp/2.0.0'
+      },
+      body: JSON.stringify({
+        refresh_token: refreshToken
+      })
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token refresh failed: ${error}`);
+    }
+
+    const tokenData = await response.json();
+    
+    // Add expiry time
+    if (tokenData.expires_in) {
+      tokenData.expires_at = new Date(Date.now() + tokenData.expires_in * 1000).toISOString();
+    }
+
+    // Store refreshed token
+    await this.tokenStore.saveToken(tokenData);
+    
+    console.log('✅ Token refreshed successfully');
+    
+    return tokenData.access_token;
+  }
+
+  /**
+   * Clear stored authentication
+   */
+  async logout() {
+    await this.tokenStore.clearToken();
+    console.log('👋 Logged out successfully');
+  }
+
+  /**
+   * Generate PKCE code verifier
+   */
+  generateCodeVerifier() {
+    return crypto.randomBytes(32).toString('base64url');
+  }
+
+  /**
+   * Generate PKCE code challenge from verifier
+   */
+  generateCodeChallenge(verifier) {
+    return crypto.createHash('sha256').update(verifier).digest('base64url');
+  }
+}
+
+export default OAuthManager;

package/src/auth/token-store.js

@@ -0,0 +1,155 @@
+/**
+ * Secure Token Storage for Purmemo MCP
+ * Stores OAuth tokens securely in user's home directory
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+import os from 'os';
+
+class TokenStore {
+  constructor() {
+    // Store tokens in user's home directory
+    this.configDir = path.join(os.homedir(), '.purmemo');
+    this.tokenFile = path.join(this.configDir, 'auth.json');
+    this.encryptionKey = this.getEncryptionKey();
+  }
+
+  /**
+   * Get or generate encryption key for token storage
+   */
+  getEncryptionKey() {
+    // Use machine ID + user info for key generation
+    const machineId = os.hostname() + os.userInfo().username;
+    return crypto.createHash('sha256').update(machineId).digest();
+  }
+
+  /**
+   * Ensure config directory exists
+   */
+  async ensureConfigDir() {
+    try {
+      await fs.mkdir(this.configDir, { recursive: true });
+      // Set restrictive permissions (owner read/write only)
+      if (process.platform !== 'win32') {
+        await fs.chmod(this.configDir, 0o700);
+      }
+    } catch (error) {
+      console.error('Failed to create config directory:', error);
+    }
+  }
+
+  /**
+   * Encrypt data
+   */
+  encrypt(data) {
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv('aes-256-cbc', this.encryptionKey, iv);
+    
+    let encrypted = cipher.update(JSON.stringify(data), 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    
+    return {
+      iv: iv.toString('hex'),
+      data: encrypted
+    };
+  }
+
+  /**
+   * Decrypt data
+   */
+  decrypt(encryptedData) {
+    const iv = Buffer.from(encryptedData.iv, 'hex');
+    const decipher = crypto.createDecipheriv('aes-256-cbc', this.encryptionKey, iv);
+    
+    let decrypted = decipher.update(encryptedData.data, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    
+    return JSON.parse(decrypted);
+  }
+
+  /**
+   * Save token to disk
+   */
+  async saveToken(tokenData) {
+    await this.ensureConfigDir();
+    
+    // Encrypt token data
+    const encrypted = this.encrypt(tokenData);
+    
+    // Write to file
+    await fs.writeFile(
+      this.tokenFile, 
+      JSON.stringify(encrypted, null, 2),
+      'utf8'
+    );
+    
+    // Set restrictive permissions
+    if (process.platform !== 'win32') {
+      await fs.chmod(this.tokenFile, 0o600);
+    }
+  }
+
+  /**
+   * Get stored token
+   */
+  async getToken() {
+    try {
+      const data = await fs.readFile(this.tokenFile, 'utf8');
+      const encrypted = JSON.parse(data);
+      return this.decrypt(encrypted);
+    } catch (error) {
+      // File doesn't exist or is corrupted
+      if (error.code === 'ENOENT') {
+        return null;
+      }
+      console.error('Failed to read token:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Clear stored token
+   */
+  async clearToken() {
+    try {
+      await fs.unlink(this.tokenFile);
+    } catch (error) {
+      // Ignore if file doesn't exist
+      if (error.code !== 'ENOENT') {
+        console.error('Failed to clear token:', error);
+      }
+    }
+  }
+
+  /**
+   * Check if token exists
+   */
+  async hasToken() {
+    try {
+      await fs.access(this.tokenFile);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get user info from stored token
+   */
+  async getUserInfo() {
+    const token = await this.getToken();
+    if (!token) return null;
+    
+    return {
+      user_id: token.user?.id,
+      email: token.user?.email,
+      tier: token.user_tier || 'free',
+      memory_limit: token.memory_limit,
+      expires_at: token.expires_at
+    };
+  }
+}
+
+export default TokenStore;

package/src/server-oauth.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * pūrmemo MCP Server v2.0.0 - With OAuth Support
+ * Seamless authentication without manual API key configuration
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import fetch from 'node-fetch';
+import OAuthManager from './auth/oauth-manager.js';
+
+// Initialize OAuth manager
+const authManager = new OAuthManager({
+  apiUrl: process.env.PUO_MEMO_API_URL || 'https://api.purmemo.ai'
+});
+
+// API URL configuration
+const API_URL = process.env.PUO_MEMO_API_URL || 'https://api.purmemo.ai';
+
+// User state
+let userInfo = null;
+let memoryCount = 0;
+
+// Tool definitions
+const TOOLS = [
+  {
+    name: 'memory',
+    description: '💾 Save anything to memory',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: 'What to remember' },
+        title: { type: 'string', description: 'Optional: Title for the memory' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Optional: Tags' },
+        attachments: { type: 'array', items: { type: 'string' }, description: 'Optional: File paths or URLs' }
+      },
+      required: ['content']
+    }
+  },
+  {
+    name: 'recall',
+    description: '🔍 Search your memories',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'What to search for' },
+        limit: { type: 'integer', description: 'How many results (default: 10)', default: 10 },
+        search_type: { type: 'string', enum: ['keyword', 'semantic', 'hybrid'], default: 'hybrid' }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'entities',
+    description: '🏷️ Extract entities from memories (people, places, concepts)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entity_name: { type: 'string', description: 'Optional: Specific entity to look up' },
+        entity_type: { 
+          type: 'string', 
+          enum: ['person', 'organization', 'location', 'concept', 'technology', 'project', 'document', 'event'],
+          description: 'Optional: Filter by entity type' 
+        }
+      }
+    }
+  },
+  {
+    name: 'attach',
+    description: '📎 Attach files to an existing memory',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        memory_id: { type: 'string', description: 'Memory ID to attach files to' },
+        file_paths: { type: 'array', items: { type: 'string' }, description: 'File paths or URLs' }
+      },
+      required: ['memory_id', 'file_paths']
+    }
+  },
+  {
+    name: 'correction',
+    description: '✏️ Add a correction to an existing memory',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        memory_id: { type: 'string', description: 'ID of the memory to correct' },
+        correction: { type: 'string', description: 'The corrected content' },
+        reason: { type: 'string', description: 'Optional: Reason for the correction' }
+      },
+      required: ['memory_id', 'correction']
+    }
+  }
+];
+
+// Create server
+const server = new Server(
+  {
+    name: 'purmemo-mcp',
+    version: '2.0.0'
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+
+/**
+ * Get authentication token, prompting for OAuth if needed
+ */
+async function getAuthToken() {
+  let token = await authManager.getToken();
+  
+  if (!token) {
+    console.log('\n⚠️  Authentication required for Purmemo MCP');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+    console.log('This is a one-time setup. You\'ll be redirected to sign in.');
+    console.log('After authentication, all tools will work automatically.\n');
+    
+    token = await authManager.authenticate();
+    
+    // Get user info after authentication
+    userInfo = await authManager.tokenStore.getUserInfo();
+    if (userInfo) {
+      console.log(`👤 Authenticated as: ${userInfo.email}`);
+      console.log(`📊 Account tier: ${userInfo.tier}`);
+      if (userInfo.memory_limit) {
+        console.log(`📝 Memory limit: ${userInfo.memory_limit} (upgrade to Pro for unlimited)`);
+      }
+      console.log('');
+    }
+  }
+  
+  return token;
+}
+
+/**
+ * Check if user has reached memory limit (for free tier)
+ */
+async function checkMemoryLimit(token) {
+  if (!userInfo) {
+    userInfo = await authManager.tokenStore.getUserInfo();
+  }
+  
+  if (userInfo && userInfo.tier === 'free' && userInfo.memory_limit) {
+    // Get current memory count
+    try {
+      const response = await fetch(`${API_URL}/api/v5/memories?limit=1`, {
+        headers: {
+          'Authorization': `Bearer ${token}`,
+          'User-Agent': 'purmemo-mcp/2.0.0'
+        }
+      });
+      
+      if (response.ok) {
+        const data = await response.json();
+        memoryCount = data.total_count || 0;
+        
+        if (memoryCount >= userInfo.memory_limit) {
+          return {
+            exceeded: true,
+            message: `You've reached your free tier limit of ${userInfo.memory_limit} memories. Upgrade to Pro at https://app.purmemo.ai for unlimited memories.`,
+            current: memoryCount,
+            limit: userInfo.memory_limit
+          };
+        }
+      }
+    } catch (error) {
+      console.error('Failed to check memory limit:', error);
+    }
+  }
+  
+  return { exceeded: false };
+}
+
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS
+}));
+
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  try {
+    // Get auth token (will prompt for OAuth if needed)
+    const token = await getAuthToken();
+    
+    if (!token) {
+      throw new Error('Authentication required. Please run the setup command to authenticate.');
+    }
+    
+    // Check memory limit for memory creation
+    if (name === 'memory') {
+      const limitCheck = await checkMemoryLimit(token);
+      if (limitCheck.exceeded) {
+        return {
+          error: 'Memory limit exceeded',
+          message: limitCheck.message,
+          current_count: limitCheck.current,
+          limit: limitCheck.limit,
+          upgrade_url: 'https://app.purmemo.ai/upgrade'
+        };
+      }
+    }
+    
+    let response;
+    
+    switch (name) {
+      case 'memory':
+        // POST request for creating memory
+        response = await fetch(`${API_URL}/api/v5/memories`, {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'User-Agent': 'purmemo-mcp/2.0.0'
+          },
+          body: JSON.stringify(args)
+        });
+        
+        // Increment memory count for free tier tracking
+        if (response.ok && userInfo?.tier === 'free') {
+          memoryCount++;
+          if (userInfo.memory_limit) {
+            const remaining = userInfo.memory_limit - memoryCount;
+            if (remaining > 0 && remaining <= 10) {
+              console.log(`ℹ️  ${remaining} memories remaining in free tier`);
+            }
+          }
+        }
+        break;
+        
+      case 'recall':
+        // GET request for search
+        const searchParams = new URLSearchParams({
+          q: args.query || '',
+          limit: args.limit || 10,
+          search_type: args.search_type || 'hybrid'
+        });
+        response = await fetch(`${API_URL}/api/v5/memories/search?${searchParams}`, {
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'User-Agent': 'purmemo-mcp/2.0.0'
+          }
+        });
+        break;
+        
+      case 'entities':
+        // GET request for entities
+        const entityParams = new URLSearchParams();
+        if (args.entity_name) entityParams.append('name', args.entity_name);
+        if (args.entity_type) entityParams.append('type', args.entity_type);
+        
+        response = await fetch(`${API_URL}/api/v5/entities?${entityParams}`, {
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'User-Agent': 'purmemo-mcp/2.0.0'
+          }
+        });
+        break;
+        
+      case 'attach':
+        // POST request for attachments
+        response = await fetch(`${API_URL}/api/v5/memories/${args.memory_id}/attachments`, {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'User-Agent': 'purmemo-mcp/2.0.0'
+          },
+          body: JSON.stringify({ file_paths: args.file_paths })
+        });
+        break;
+        
+      case 'correction':
+        // POST request for corrections
+        response = await fetch(`${API_URL}/api/v5/memories/${args.memory_id}/corrections`, {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'User-Agent': 'purmemo-mcp/2.0.0'
+          },
+          body: JSON.stringify({
+            correction: args.correction,
+            reason: args.reason
+          })
+        });
+        break;
+        
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    
+    if (!response.ok) {
+      const error = await response.text();
+      
+      // Handle specific error cases
+      if (response.status === 401) {
+        // Token might be expired, try to refresh
+        console.log('🔄 Authentication expired, refreshing...');
+        await authManager.tokenStore.clearToken();
+        const newToken = await authManager.authenticate();
+        
+        // Suggest retrying the operation
+        throw new Error('Authentication refreshed. Please try your request again.');
+      }
+      
+      throw new Error(`API error: ${error}`);
+    }
+    
+    return await response.json();
+    
+  } catch (error) {
+    console.error(`❌ Error executing ${name}:`, error.message);
+    
+    // Provide helpful error messages
+    if (error.message.includes('ECONNREFUSED')) {
+      throw new Error('Unable to connect to Purmemo API. Please check your internet connection.');
+    }
+    
+    if (error.message.includes('Authentication')) {
+      throw new Error(`Authentication issue: ${error.message}. You may need to reconnect your account.`);
+    }
+    
+    throw error;
+  }
+});
+
+// Initialize on startup
+async function initialize() {
+  console.log('🧠 pūrmemo MCP v2.0.0 starting...\n');
+  
+  // Check if we have stored authentication
+  const hasAuth = await authManager.tokenStore.hasToken();
+  
+  if (hasAuth) {
+    userInfo = await authManager.tokenStore.getUserInfo();
+    if (userInfo) {
+      console.log(`✅ Authenticated as: ${userInfo.email}`);
+      console.log(`📊 Account tier: ${userInfo.tier}`);
+      if (userInfo.memory_limit) {
+        console.log(`📝 Memory limit: ${userInfo.memory_limit}`);
+      }
+    }
+  } else {
+    // Check for legacy API key
+    if (process.env.PUO_MEMO_API_KEY) {
+      console.log('📔 Using API key from environment (legacy mode)');
+      console.log('💡 Tip: Remove PUO_MEMO_API_KEY to use OAuth authentication');
+    } else {
+      console.log('🔐 No authentication found');
+      console.log('📱 You\'ll be prompted to sign in when you use your first tool');
+      console.log('   This is a one-time setup for seamless access');
+    }
+  }
+  
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('Ready to serve MCP requests\n');
+}
+
+// Start server
+initialize().then(() => {
+  const transport = new StdioServerTransport();
+  server.connect(transport);
+}).catch(error => {
+  console.error('Failed to initialize:', error);
+  process.exit(1);
+});

package/src/setup.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * pūrmemo MCP Setup Command
+ * Allows users to manually authenticate or manage their connection
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import OAuthManager from './auth/oauth-manager.js';
+import TokenStore from './auth/token-store.js';
+import ora from 'ora';
+
+const program = new Command();
+const authManager = new OAuthManager();
+const tokenStore = new TokenStore();
+
+// ASCII Art Banner
+const banner = `
+╔═══════════════════════════════════════════╗
+║                                           ║
+║            🧠 pūrmemo MCP                 ║
+║         Memory Management Tool            ║
+║                                           ║
+╚═══════════════════════════════════════════╝
+`;
+
+program
+  .name('purmemo-mcp')
+  .description('Setup and manage your pūrmemo MCP connection')
+  .version('2.0.0');
+
+program
+  .command('setup')
+  .description('Connect your pūrmemo account')
+  .action(async () => {
+    console.log(chalk.cyan(banner));
+    
+    // Check if already authenticated
+    const hasAuth = await tokenStore.hasToken();
+    
+    if (hasAuth) {
+      const userInfo = await tokenStore.getUserInfo();
+      console.log(chalk.green('✅ You are already authenticated!'));
+      console.log(chalk.gray(`   Email: ${userInfo?.email}`));
+      console.log(chalk.gray(`   Tier: ${userInfo?.tier}`));
+      console.log('');
+      
+      const { action } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'action',
+          message: 'What would you like to do?',
+          choices: [
+            { name: 'Keep current connection', value: 'keep' },
+            { name: 'Sign in with a different account', value: 'reconnect' },
+            { name: 'Sign out', value: 'logout' }
+          ]
+        }
+      ]);
+      
+      if (action === 'keep') {
+        console.log(chalk.green('\n✨ Your connection is active and ready to use!'));
+        process.exit(0);
+      } else if (action === 'logout') {
+        await authManager.logout();
+        console.log(chalk.yellow('\n👋 You have been signed out.'));
+        process.exit(0);
+      }
+      // Fall through to reconnect
+    }
+    
+    console.log(chalk.yellow('\n📱 Starting authentication process...\n'));
+    console.log(chalk.gray('You will be redirected to your browser to sign in.'));
+    console.log(chalk.gray('Choose your preferred method: Google, GitHub, or Email.\n'));
+    
+    const spinner = ora('Preparing authentication...').start();
+    
+    try {
+      await new Promise(resolve => setTimeout(resolve, 1000)); // Brief pause
+      spinner.stop();
+      
+      const token = await authManager.authenticate();
+      
+      if (token) {
+        const userInfo = await tokenStore.getUserInfo();
+        
+        console.log('');
+        console.log(chalk.green.bold('🎉 Success! You are now connected to pūrmemo'));
+        console.log('');
+        console.log(chalk.white('Account Information:'));
+        console.log(chalk.gray('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log(chalk.cyan(`  Email: ${userInfo?.email}`));
+        console.log(chalk.cyan(`  Tier: ${userInfo?.tier === 'pro' ? '⭐ Pro' : '🆓 Free'}`));
+        
+        if (userInfo?.memory_limit) {
+          console.log(chalk.yellow(`  Memory Limit: ${userInfo.memory_limit} memories`));
+          console.log(chalk.gray(`  (Upgrade to Pro for unlimited memories)`));
+        } else {
+          console.log(chalk.green(`  Memory Limit: Unlimited`));
+        }
+        
+        console.log('');
+        console.log(chalk.white('Available Tools:'));
+        console.log(chalk.gray('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log(chalk.green('  ✓ memory   ') + chalk.gray('- Save anything to memory'));
+        console.log(chalk.green('  ✓ recall   ') + chalk.gray('- Search your memories'));
+        console.log(chalk.green('  ✓ entities ') + chalk.gray('- Extract people, places, concepts'));
+        console.log(chalk.green('  ✓ attach   ') + chalk.gray('- Attach files to memories'));
+        console.log(chalk.green('  ✓ correction') + chalk.gray('- Correct existing memories'));
+        
+        console.log('');
+        console.log(chalk.cyan.bold('🚀 You can now use all pūrmemo tools in Claude Desktop!'));
+        console.log('');
+      }
+    } catch (error) {
+      spinner.fail('Authentication failed');
+      console.error(chalk.red(`\n❌ Error: ${error.message}`));
+      console.log(chalk.gray('\nPlease try again or visit https://app.purmemo.ai for help.'));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('status')
+  .description('Check your connection status')
+  .action(async () => {
+    console.log(chalk.cyan(banner));
+    
+    const hasAuth = await tokenStore.hasToken();
+    
+    if (!hasAuth) {
+      console.log(chalk.yellow('⚠️  Not authenticated'));
+      console.log(chalk.gray('\nRun "npx purmemo-mcp setup" to connect your account.'));
+      return;
+    }
+    
+    const userInfo = await tokenStore.getUserInfo();
+    const spinner = ora('Checking connection...').start();
+    
+    try {
+      // Test API connection
+      const token = await authManager.getToken();
+      const response = await fetch('https://api.purmemo.ai/api/v5/memories?limit=1', {
+        headers: {
+          'Authorization': `Bearer ${token}`,
+          'User-Agent': 'purmemo-mcp/2.0.0'
+        }
+      });
+      
+      spinner.stop();
+      
+      if (response.ok) {
+        const data = await response.json();
+        const memoryCount = data.total_count || 0;
+        
+        console.log(chalk.green.bold('✅ Connection Active'));
+        console.log('');
+        console.log(chalk.white('Account Details:'));
+        console.log(chalk.gray('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log(`  Email: ${userInfo?.email}`);
+        console.log(`  Tier: ${userInfo?.tier === 'pro' ? '⭐ Pro' : '🆓 Free'}`);
+        console.log(`  Memories: ${memoryCount}`);
+        
+        if (userInfo?.memory_limit) {
+          const remaining = userInfo.memory_limit - memoryCount;
+          console.log(`  Remaining: ${remaining} of ${userInfo.memory_limit}`);
+          
+          if (remaining <= 10) {
+            console.log('');
+            console.log(chalk.yellow('⚠️  You are approaching your free tier limit.'));
+            console.log(chalk.gray('   Upgrade to Pro at https://app.purmemo.ai'));
+          }
+        }
+        
+        // Check token expiry
+        if (userInfo?.expires_at) {
+          const expiresAt = new Date(userInfo.expires_at);
+          const now = new Date();
+          const hoursUntilExpiry = Math.floor((expiresAt - now) / (1000 * 60 * 60));
+          
+          if (hoursUntilExpiry < 24) {
+            console.log('');
+            console.log(chalk.yellow(`⚠️  Token expires in ${hoursUntilExpiry} hours`));
+            console.log(chalk.gray('   It will auto-refresh when needed.'));
+          }
+        }
+      } else {
+        spinner.fail('Connection test failed');
+        console.log(chalk.red(`\n❌ API returned status: ${response.status}`));
+        console.log(chalk.gray('\nTry running "npx purmemo-mcp setup" to reconnect.'));
+      }
+    } catch (error) {
+      spinner.fail('Connection test failed');
+      console.error(chalk.red(`\n❌ Error: ${error.message}`));
+      console.log(chalk.gray('\nCheck your internet connection and try again.'));
+    }
+  });
+
+program
+  .command('logout')
+  .description('Sign out from your pūrmemo account')
+  .action(async () => {
+    console.log(chalk.cyan(banner));
+    
+    const hasAuth = await tokenStore.hasToken();
+    
+    if (!hasAuth) {
+      console.log(chalk.yellow('⚠️  You are not signed in.'));
+      return;
+    }
+    
+    const userInfo = await tokenStore.getUserInfo();
+    
+    const { confirm } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: `Are you sure you want to sign out from ${userInfo?.email}?`,
+        default: false
+      }
+    ]);
+    
+    if (confirm) {
+      await authManager.logout();
+      console.log(chalk.green('\n✅ Successfully signed out.'));
+      console.log(chalk.gray('Run "npx purmemo-mcp setup" to sign in again.'));
+    } else {
+      console.log(chalk.gray('\nSign out cancelled.'));
+    }
+  });
+
+program
+  .command('upgrade')
+  .description('Open upgrade page to get Pro features')
+  .action(async () => {
+    console.log(chalk.cyan(banner));
+    console.log(chalk.yellow('🚀 Opening upgrade page...'));
+    console.log(chalk.gray('\nPro features include:'));
+    console.log(chalk.green('  • Unlimited memories'));
+    console.log(chalk.green('  • Advanced AI models'));
+    console.log(chalk.green('  • Priority support'));
+    console.log(chalk.green('  • API access'));
+    
+    const open = (await import('open')).default;
+    await open('https://app.purmemo.ai/upgrade');
+  });
+
+// Handle unknown commands
+program.on('command:*', () => {
+  console.error(chalk.red('\nInvalid command: %s'), program.args.join(' '));
+  console.log(chalk.gray('Run "npx purmemo-mcp --help" for available commands.'));
+  process.exit(1);
+});
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  console.log(chalk.cyan(banner));
+  console.log(chalk.white('Welcome to pūrmemo MCP!\n'));
+  console.log(chalk.gray('Get started by connecting your account:\n'));
+  console.log(chalk.cyan('  npx purmemo-mcp setup\n'));
+  console.log(chalk.gray('For more commands, run: npx purmemo-mcp --help'));
+}
+
+program.parse();