@recall_v3/mcp-server 0.1.0 → 3.0.0

package/src/cli.ts

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+
+/**
+ * Recall v3 CLI
+ *
+ * Command-line interface for Recall MCP operations.
+ * Used by Claude Code hooks and for manual operations.
+ *
+ * Commands:
+ *   recall-mcp context     Load and display team context
+ *   recall-mcp save        Save current session
+ *   recall-mcp status      Check authentication status
+ */
+
+import { getContext } from './tools/getContext.js';
+import { saveSession } from './tools/saveSession.js';
+import { getApiBaseUrl, getApiToken, getConfigPath } from './config/index.js';
+import { RecallApiClient } from './api/client.js';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+const flags = args.slice(1);
+
+// Check for --quiet flag
+const quiet = flags.includes('--quiet') || flags.includes('-q');
+
+// Helper to log only if not quiet
+function log(message: string): void {
+  if (!quiet) {
+    console.log(message);
+  }
+}
+
+// Helper to log errors (always shown)
+function logError(message: string): void {
+  console.error(message);
+}
+
+/**
+ * Parse --project-path flag from args
+ */
+function getProjectPathFromFlags(flagList: string[]): string | undefined {
+  const projectPathIndex = flagList.findIndex(f => f === '--project-path' || f === '-p');
+  if (projectPathIndex !== -1 && flagList[projectPathIndex + 1]) {
+    return flagList[projectPathIndex + 1];
+  }
+  return undefined;
+}
+
+// Parse --project-path flag
+const projectPath = getProjectPathFromFlags(flags);
+
+/**
+ * Display usage information
+ */
+function showHelp(): void {
+  console.log(`
+Recall v3 CLI - Team memory for AI coding assistants
+
+Usage:
+  recall-mcp <command> [options]
+
+Commands:
+  context         Load team context for current repository
+  save            Save current session (with AI summarization)
+  status          Check authentication and connection status
+  help            Show this help message
+
+Options:
+  --quiet, -q              Suppress non-essential output
+  --summary, -s            Provide a manual summary (skips AI summarization)
+  --project-path, -p PATH  Specify the git repository path (defaults to cwd)
+
+Save Command:
+  The save command supports three modes:
+
+  1. AI Summarization (recommended):
+     echo "<conversation transcript>" | recall-mcp save
+     - Pipes conversation to API for AI-powered summarization
+     - Extracts decisions, mistakes, files changed automatically
+
+  2. Manual Summary:
+     recall-mcp save --summary "Fixed authentication bug"
+     - Use when you want to write your own summary
+
+  3. Placeholder (fallback):
+     recall-mcp save --quiet
+     - Saves minimal placeholder when no transcript available
+     - Used by Claude Code stop hooks as a backup
+
+Examples:
+  recall-mcp context                              # Load context at session start
+  recall-mcp save --quiet                         # Save session quietly (for hooks)
+  recall-mcp save --summary "Fixed X"             # Save with manual summary
+  cat transcript.txt | recall-mcp save            # Save with AI summarization
+  recall-mcp save -p /path/to/repo --quiet        # Save for specific repo (Claude Code hooks)
+  recall-mcp context --project-path /path/to/repo # Load context for specific repo
+  recall-mcp status                               # Check if properly configured
+
+Environment Variables:
+  RECALL_API_URL      API base URL (default: https://api-v3.recall.team)
+  RECALL_API_TOKEN    Authentication token (required)
+`);
+}
+
+/**
+ * Load and display team context
+ */
+async function runContext(): Promise<void> {
+  try {
+    const result = await getContext({ projectPath });
+
+    if (result.isError) {
+      logError(`Error: ${result.content[0]?.text || 'Unknown error'}`);
+      process.exit(1);
+    }
+
+    // Output the context (always, even in quiet mode - it's the primary output)
+    console.log(result.content[0]?.text || '');
+
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    logError(`Failed to load context: ${message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Read from stdin if available (non-blocking)
+ * Handles large transcripts (Claude Code sessions can be 1MB+)
+ */
+async function readStdin(): Promise<string | null> {
+  return new Promise((resolve) => {
+    // Check if stdin has data (is a pipe, not TTY)
+    if (process.stdin.isTTY) {
+      resolve(null);
+      return;
+    }
+
+    const chunks: string[] = [];
+    let resolved = false;
+
+    // Initial timeout - wait up to 500ms for first data
+    let timeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        resolve(chunks.length > 0 ? chunks.join('') : null);
+      }
+    }, 500);
+
+    process.stdin.setEncoding('utf8');
+
+    process.stdin.on('data', (chunk: string) => {
+      // Clear and reset timeout on each chunk (allows large files)
+      clearTimeout(timeout);
+      chunks.push(chunk);
+
+      // Set a shorter timeout between chunks (100ms idle = end of data)
+      timeout = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          resolve(chunks.join(''));
+        }
+      }, 100);
+    });
+
+    process.stdin.on('end', () => {
+      clearTimeout(timeout);
+      if (!resolved) {
+        resolved = true;
+        resolve(chunks.length > 0 ? chunks.join('') : null);
+      }
+    });
+
+    process.stdin.on('error', () => {
+      clearTimeout(timeout);
+      if (!resolved) {
+        resolved = true;
+        resolve(null);
+      }
+    });
+
+    // Start reading
+    process.stdin.resume();
+  });
+}
+
+/**
+ * Save current session
+ *
+ * Supports two modes:
+ * 1. With transcript via stdin: `echo "conversation..." | recall-mcp save`
+ *    - Sends transcript to API for AI summarization
+ * 2. Without transcript: `recall-mcp save`
+ *    - Saves a minimal placeholder (fallback)
+ *
+ * Usage with --summary flag: `recall-mcp save --summary "What we did"`
+ */
+async function runSave(): Promise<void> {
+  try {
+    // Check for --summary flag
+    const summaryIndex = flags.findIndex(f => f === '--summary' || f === '-s');
+    let providedSummary: string | undefined;
+    if (summaryIndex !== -1 && flags[summaryIndex + 1]) {
+      providedSummary = flags[summaryIndex + 1];
+    }
+
+    // Try to read transcript from stdin
+    const transcript = await readStdin();
+
+    // Build saveSession args
+    const saveArgs: { summary?: string; transcript?: string; projectPath?: string } = {};
+
+    // Add project path if specified
+    if (projectPath) {
+      saveArgs.projectPath = projectPath;
+    }
+
+    if (transcript && transcript.trim().length >= 50) {
+      // We have a transcript - send it for AI summarization
+      saveArgs.transcript = transcript;
+      log('Summarizing session with AI...');
+    } else if (providedSummary) {
+      // Use provided summary
+      saveArgs.summary = providedSummary;
+    } else {
+      // Fallback to placeholder - this is the minimal save case
+      saveArgs.summary = 'Session auto-saved by Recall hook';
+    }
+
+    const result = await saveSession(saveArgs);
+
+    if (result.isError) {
+      logError(`Error: ${result.content[0]?.text || 'Unknown error'}`);
+      process.exit(1);
+    }
+
+    log(result.content[0]?.text || 'Session saved');
+
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    logError(`Failed to save session: ${message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Check authentication and connection status
+ */
+async function runStatus(): Promise<void> {
+  try {
+    const token = getApiToken();
+    const baseUrl = getApiBaseUrl();
+
+    console.log('Recall v3 Status');
+    console.log('================');
+    console.log(`Config: ${getConfigPath()}`);
+    console.log(`API URL: ${baseUrl}`);
+    console.log(`Token: ${token ? `${token.substring(0, 10)}...` : 'Not set'}`);
+
+    if (!token) {
+      logError('\nError: RECALL_API_TOKEN not set');
+      logError(`Set the environment variable or configure ${getConfigPath()}`);
+      process.exit(1);
+    }
+
+    // Test API connection
+    const client = new RecallApiClient({
+      baseUrl,
+      token,
+    });
+
+    console.log('\nTesting API connection...');
+
+    try {
+      const teams = await client.listTeams();
+      console.log(`✓ Connected successfully`);
+      console.log(`✓ Teams: ${teams.teams?.length || 0}`);
+
+      if (teams.teams && teams.teams.length > 0) {
+        for (const team of teams.teams) {
+          console.log(`  - ${team.name} (${team.role})`);
+        }
+      }
+    } catch (apiError) {
+      const message = apiError instanceof Error ? apiError.message : 'Unknown error';
+      logError(`✗ API connection failed: ${message}`);
+      process.exit(1);
+    }
+
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    logError(`Status check failed: ${message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Main entry point
+ */
+async function main(): Promise<void> {
+  switch (command) {
+    case 'context':
+      await runContext();
+      break;
+
+    case 'save':
+      await runSave();
+      break;
+
+    case 'status':
+      await runStatus();
+      break;
+
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      showHelp();
+      break;
+
+    default:
+      logError(`Unknown command: ${command}`);
+      logError('Run "recall-mcp help" for usage information');
+      process.exit(1);
+  }
+}
+
+// Run CLI
+main().catch((error) => {
+  logError(`Fatal error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+  process.exit(1);
+});

package/src/config/index.ts

@@ -1,7 +1,8 @@
 /**
- * Recall Configuration Management
+ * Recall v3 Configuration Management
  *
- * Manages the local config file at ~/.recall/config.json.
+ * Manages the local config file at ~/.config/recall/config.json.
+ * This is intentionally SEPARATE from v2's ~/.recall/ directory.
  * Handles secure storage of API tokens and team keys.
  */
 
@@ -16,11 +17,26 @@ const CONFIG_VERSION = 1;
 // Default API base URL (v3)
 const DEFAULT_API_BASE_URL = 'https://api-v3.recall.team';
 
+// v3 uses ~/.config/recall/ (XDG-compliant, separate from v2's ~/.recall/)
+const V3_CONFIG_DIR = path.join(os.homedir(), '.config', 'recall');
+
+// v2 used ~/.recall/ - we check this for migration
+const V2_CONFIG_DIR = path.join(os.homedir(), '.recall');
+
 /**
- * Get the path to the Recall config directory
+ * Get the path to the Recall v3 config directory
+ * Uses ~/.config/recall/ (XDG-compliant, separate from v2)
  */
 export function getConfigDir(): string {
-  return path.join(os.homedir(), '.recall');
+  return V3_CONFIG_DIR;
+}
+
+/**
+ * Get the path to the legacy v2 config directory
+ * (used only for migration checking)
+ */
+export function getLegacyConfigDir(): string {
+  return V2_CONFIG_DIR;
 }
 
 /**
@@ -68,11 +84,75 @@ function migrateConfig(config: Partial<RecallConfig>): RecallConfig {
   return migrated;
 }
 
+/**
+ * Check if a config file at a given path is a v3 config
+ * v3 configs have teamKeys and a version field (v2 didn't)
+ */
+function isV3Config(config: Record<string, unknown>): boolean {
+  // v3 configs always have version field
+  return typeof config.version === 'number' && config.version >= 1;
+}
+
+/**
+ * Migrate v3 config from old v2 location (~/.recall/) to new v3 location (~/.config/recall/)
+ * This only migrates if:
+ * 1. No config exists at new v3 location
+ * 2. A v3 config exists at old v2 location (has version field)
+ *
+ * v2 configs (without version field) are left alone - they belong to v2
+ */
+function migrateFromV2Location(): void {
+  const v3ConfigPath = getConfigPath();
+  const v2ConfigPath = path.join(getLegacyConfigDir(), 'config.json');
+
+  // If v3 config already exists at new location, nothing to migrate
+  if (fs.existsSync(v3ConfigPath)) {
+    return;
+  }
+
+  // If no config exists at old v2 location, nothing to migrate
+  if (!fs.existsSync(v2ConfigPath)) {
+    return;
+  }
+
+  try {
+    const raw = fs.readFileSync(v2ConfigPath, 'utf-8');
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+
+    // Only migrate if it's a v3 config (has version field)
+    // v2 configs don't have version field and belong to v2
+    if (!isV3Config(parsed)) {
+      return;
+    }
+
+    // This is a v3 config in the old location - migrate it
+    console.log(`[Recall v3] Migrating config from ~/.recall/ to ~/.config/recall/`);
+
+    // Ensure new directory exists
+    ensureConfigDir();
+
+    // Copy config to new location
+    fs.writeFileSync(v3ConfigPath, JSON.stringify(parsed, null, 2), { mode: 0o600 });
+
+    // Remove config from old location (but leave other v2 artifacts)
+    // Note: We only remove config.json, not the whole directory
+    fs.unlinkSync(v2ConfigPath);
+
+    console.log(`[Recall v3] Migration complete. v3 config is now at ~/.config/recall/config.json`);
+  } catch (error) {
+    // Migration failed - not critical, user can manually migrate
+    console.warn(`[Recall v3] Could not migrate config from ~/.recall/ (non-critical)`);
+  }
+}
+
 /**
  * Load configuration from disk
  * Returns a default config if the file doesn't exist
  */
 export function loadConfig(): RecallConfig {
+  // First, try to migrate from old v2 location if needed
+  migrateFromV2Location();
+
   const configPath = getConfigPath();
 
   if (!fs.existsSync(configPath)) {

package/src/crypto/index.ts

@@ -205,3 +205,36 @@ export function encryptContent(plaintext: string, keyBase64: string): string {
   const payload = encrypt(plaintext, keyBase64);
   return JSON.stringify(payload);
 }
+
+/**
+ * Encrypt content and return in Recall format: RECALL_ENCRYPTED:v1:iv:tag:ciphertext
+ * This is the format expected by the v3 API.
+ */
+export function encryptForApi(plaintext: string, keyBase64: string): string {
+  const payload = encrypt(plaintext, keyBase64);
+  return `RECALL_ENCRYPTED:v1:${payload.iv}:${payload.tag}:${payload.ciphertext}`;
+}
+
+/**
+ * Decrypt content in Recall format: RECALL_ENCRYPTED:v1:iv:tag:ciphertext
+ * This is the format returned by the v3 API.
+ */
+export function decryptFromApi(encrypted: string, keyBase64: string): string {
+  if (!encrypted.startsWith('RECALL_ENCRYPTED:')) {
+    throw new Error('Invalid encrypted format: must start with RECALL_ENCRYPTED:');
+  }
+
+  const parts = encrypted.split(':');
+  if (parts.length !== 5) {
+    throw new Error('Invalid encrypted format: expected RECALL_ENCRYPTED:v1:iv:tag:ciphertext');
+  }
+
+  const [, version, iv, tag, ciphertext] = parts;
+
+  if (version !== 'v1') {
+    throw new Error(`Unsupported encryption version: ${version}`);
+  }
+
+  const payload: EncryptedPayload = { iv, tag, ciphertext };
+  return decrypt(payload, keyBase64);
+}

package/src/index.ts

@@ -33,9 +33,9 @@ import {
 // Tool definitions
 const TOOLS = [
   {
-    name: 'recall_get_context',
+    name: 'recall3_get_context',
     description:
-      "Get team brain (context.md) for the current repository. This is the distilled current state - loads automatically at every session start. Use recall_get_history for the full encyclopedia.",
+      "Get team brain (context.md) for the current repository. This is the distilled current state - loads automatically at every session start. Use recall3_get_history for the full encyclopedia.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -48,9 +48,9 @@ const TOOLS = [
     },
   },
   {
-    name: 'recall_get_history',
+    name: 'recall3_get_history',
     description:
-      "Get detailed session history (context.md + recent sessions). This includes more context than recall_get_context but uses more tokens.",
+      "Get detailed session history (context.md + recent sessions). This includes more context than recall3_get_context but uses more tokens.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -64,7 +64,7 @@ const TOOLS = [
     },
   },
   {
-    name: 'recall_get_transcripts',
+    name: 'recall3_get_transcripts',
     description:
       "Get full session transcripts (context.md + history.md). WARNING: This can be very large and use many tokens. Only use when you need complete historical details.",
     inputSchema: {
@@ -80,7 +80,7 @@ const TOOLS = [
     },
   },
   {
-    name: 'recall_save_session',
+    name: 'recall3_save_session',
     description:
       "Save a summary of what was accomplished in this coding session. This updates the team memory files.",
     inputSchema: {
@@ -127,7 +127,7 @@ const TOOLS = [
     },
   },
   {
-    name: 'recall_log_decision',
+    name: 'recall3_log_decision',
     description:
       "Log an important decision made during coding. Quick way to capture why something was done.",
     inputSchema: {
@@ -179,23 +179,23 @@ class RecallMCPServer {
       try {
         let result;
         switch (name) {
-          case 'recall_get_context':
+          case 'recall3_get_context':
             result = await getContext(args as unknown as GetContextArgs);
             break;
 
-          case 'recall_get_history':
+          case 'recall3_get_history':
             result = await getHistory(args as unknown as GetHistoryArgs);
             break;
 
-          case 'recall_get_transcripts':
+          case 'recall3_get_transcripts':
             result = await getTranscripts(args as unknown as GetTranscriptsArgs);
             break;
 
-          case 'recall_save_session':
+          case 'recall3_save_session':
             result = await saveSession(args as unknown as SaveSessionArgs);
             break;
 
-          case 'recall_log_decision':
+          case 'recall3_log_decision':
             result = await logDecision(args as unknown as LogDecisionArgs);
             break;