@recall_v3/mcp-server 0.1.0

package/src/api/client.ts

@@ -0,0 +1,295 @@
+/**
+ * Recall API Client
+ *
+ * HTTP client for communicating with the Recall backend API.
+ * Handles authentication, retries, and error handling.
+ */
+
+import type {
+  SummarizeRequest,
+  SummarizeResponse,
+  SaveSessionRequest,
+  SaveSessionResponse,
+  GetContextResponse,
+  GetHistoryResponse,
+  GetTranscriptsResponse,
+  LogDecisionRequest,
+  LogDecisionResponse,
+  TeamKeyResponse,
+  RecallStatusResponse,
+  ListTeamsResponse,
+  ApiResponse,
+} from '@recall_v3/shared';
+
+// Error types for the API client
+export class RecallApiError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode?: number,
+    public readonly retryable: boolean = false
+  ) {
+    super(message);
+    this.name = 'RecallApiError';
+  }
+}
+
+export class NetworkError extends RecallApiError {
+  constructor(message: string, public readonly cause?: Error) {
+    super(message, 'NETWORK_ERROR', undefined, true);
+    this.name = 'NetworkError';
+  }
+}
+
+export class AuthenticationError extends RecallApiError {
+  constructor(message: string = 'Authentication failed') {
+    super(message, 'AUTH_ERROR', 401, false);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class TimeoutError extends RecallApiError {
+  constructor(message: string = 'Request timed out') {
+    super(message, 'TIMEOUT', undefined, true);
+    this.name = 'TimeoutError';
+  }
+}
+
+// Client configuration
+interface RecallApiClientConfig {
+  baseUrl: string;
+  token: string;
+  timeout?: number;
+  maxRetries?: number;
+  retryBaseDelay?: number;
+}
+
+/**
+ * RecallApiClient - Thin HTTP client for Recall API
+ *
+ * Features:
+ * - Bearer token authentication
+ * - Exponential backoff retry on 5xx errors
+ * - Configurable timeout (default 30s)
+ * - Typed responses using @recall_v3/shared types
+ */
+export class RecallApiClient {
+  private readonly baseUrl: string;
+  private readonly token: string;
+  private readonly timeout: number;
+  private readonly maxRetries: number;
+  private readonly retryBaseDelay: number;
+
+  constructor(config: RecallApiClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, ''); // Remove trailing slash
+    this.token = config.token;
+    this.timeout = config.timeout ?? 30000; // 30s default
+    this.maxRetries = config.maxRetries ?? 3;
+    this.retryBaseDelay = config.retryBaseDelay ?? 1000; // 1s base delay
+  }
+
+  /**
+   * Internal fetch wrapper with timeout and retry logic
+   */
+  private async request<T>(
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        try {
+          const response = await fetch(url, {
+            method,
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${this.token}`,
+            },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+          });
+
+          clearTimeout(timeoutId);
+
+          // Handle non-OK responses
+          if (!response.ok) {
+            const errorBody = await response.json().catch(() => ({})) as { error?: { code?: string; message?: string } };
+            const errorCode = errorBody?.error?.code ?? 'UNKNOWN_ERROR';
+            const errorMessage = errorBody?.error?.message ?? `HTTP ${response.status}`;
+
+            // 401 = auth error, don't retry
+            if (response.status === 401) {
+              throw new AuthenticationError(errorMessage);
+            }
+
+            // 5xx = server error, retry with backoff
+            if (response.status >= 500) {
+              throw new RecallApiError(errorMessage, errorCode, response.status, true);
+            }
+
+            // 4xx = client error, don't retry
+            throw new RecallApiError(errorMessage, errorCode, response.status, false);
+          }
+
+          // Parse successful response
+          const data = await response.json() as ApiResponse<T>;
+
+          if (!data.success && data.error) {
+            throw new RecallApiError(data.error.message, data.error.code, response.status, false);
+          }
+
+          return data.data as T;
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      } catch (error) {
+        // Handle abort (timeout)
+        if (error instanceof Error && error.name === 'AbortError') {
+          lastError = new TimeoutError();
+          // Timeout is retryable
+          if (attempt < this.maxRetries) {
+            await this.sleep(this.calculateBackoff(attempt));
+            continue;
+          }
+          throw lastError;
+        }
+
+        // Handle network errors
+        if (error instanceof TypeError && error.message.includes('fetch')) {
+          lastError = new NetworkError('Network request failed', error);
+          // Network errors are retryable
+          if (attempt < this.maxRetries) {
+            await this.sleep(this.calculateBackoff(attempt));
+            continue;
+          }
+          throw lastError;
+        }
+
+        // Handle retryable API errors
+        if (error instanceof RecallApiError && error.retryable) {
+          lastError = error;
+          if (attempt < this.maxRetries) {
+            await this.sleep(this.calculateBackoff(attempt));
+            continue;
+          }
+          throw error;
+        }
+
+        // Non-retryable errors throw immediately
+        throw error;
+      }
+    }
+
+    // Should not reach here, but just in case
+    throw lastError ?? new RecallApiError('Unknown error', 'UNKNOWN_ERROR');
+  }
+
+  /**
+   * Calculate exponential backoff delay
+   */
+  private calculateBackoff(attempt: number): number {
+    // Exponential backoff: 1s, 2s, 4s, 8s...
+    const delay = this.retryBaseDelay * Math.pow(2, attempt);
+    // Add jitter (0-25% of delay)
+    const jitter = delay * Math.random() * 0.25;
+    return delay + jitter;
+  }
+
+  /**
+   * Sleep for a given number of milliseconds
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  // =========================================================================
+  // API Methods
+  // =========================================================================
+
+  /**
+   * Summarize a session transcript
+   * Called by saveSession tool after reading JSONL from disk
+   */
+  async summarize(request: SummarizeRequest): Promise<SummarizeResponse> {
+    return this.request<SummarizeResponse>('POST', '/api/v1/summarize', request);
+  }
+
+  /**
+   * Save a session with manual input (not from transcript)
+   * Used when user provides summary directly via MCP tool
+   */
+  async saveSession(repoId: string, data: SaveSessionRequest): Promise<SaveSessionResponse> {
+    return this.request<SaveSessionResponse>('POST', `/api/v1/repos/${repoId}/sessions`, data);
+  }
+
+  /**
+   * Get context for a repository (context.md)
+   * Returns the distilled team brain for this repo
+   */
+  async getContext(repoId: string): Promise<GetContextResponse> {
+    return this.request<GetContextResponse>('GET', `/api/v1/repos/${repoId}/context`);
+  }
+
+  /**
+   * Get history for a repository (context.md + history.md)
+   * Returns more detail than getContext
+   */
+  async getHistory(repoId: string): Promise<GetHistoryResponse> {
+    return this.request<GetHistoryResponse>('GET', `/api/v1/repos/${repoId}/history`);
+  }
+
+  /**
+   * Get full transcripts for a repository
+   * WARNING: Can be very large, uses many tokens
+   */
+  async getTranscripts(repoId: string): Promise<GetTranscriptsResponse> {
+    return this.request<GetTranscriptsResponse>('GET', `/api/v1/repos/${repoId}/transcripts`);
+  }
+
+  /**
+   * Log a decision for a repository
+   */
+  async logDecision(repoId: string, data: LogDecisionRequest): Promise<LogDecisionResponse> {
+    return this.request<LogDecisionResponse>('POST', `/api/v1/repos/${repoId}/decisions`, data);
+  }
+
+  /**
+   * Get the encryption key for a team
+   * Used to decrypt content locally
+   */
+  async getTeamKey(teamId: string): Promise<TeamKeyResponse> {
+    return this.request<TeamKeyResponse>('GET', `/api/v1/teams/${teamId}/key`);
+  }
+
+  /**
+   * List teams the user belongs to
+   */
+  async listTeams(): Promise<ListTeamsResponse> {
+    return this.request<ListTeamsResponse>('GET', '/api/v1/teams');
+  }
+
+  /**
+   * Get authentication status
+   */
+  async getStatus(): Promise<RecallStatusResponse> {
+    return this.request<RecallStatusResponse>('GET', '/api/v1/status');
+  }
+
+  /**
+   * Lookup or create repo by GitHub repo info
+   * Returns the repo ID for subsequent API calls
+   */
+  async resolveRepo(fullName: string, defaultBranch?: string): Promise<{ repoId: string; teamId: string }> {
+    return this.request<{ repoId: string; teamId: string }>('POST', '/api/v1/repos/resolve', {
+      fullName,
+      defaultBranch,
+    });
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,247 @@
+/**
+ * Recall Configuration Management
+ *
+ * Manages the local config file at ~/.recall/config.json.
+ * Handles secure storage of API tokens and team keys.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import type { RecallConfig } from '@recall_v3/shared';
+
+// Current config file version
+const CONFIG_VERSION = 1;
+
+// Default API base URL (v3)
+const DEFAULT_API_BASE_URL = 'https://api-v3.recall.team';
+
+/**
+ * Get the path to the Recall config directory
+ */
+export function getConfigDir(): string {
+  return path.join(os.homedir(), '.recall');
+}
+
+/**
+ * Get the path to the config file
+ */
+export function getConfigPath(): string {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+/**
+ * Ensure the config directory exists with secure permissions
+ */
+function ensureConfigDir(): void {
+  const configDir = getConfigDir();
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { mode: 0o700, recursive: true });
+  }
+}
+
+/**
+ * Create a default empty config
+ */
+function createDefaultConfig(): RecallConfig {
+  return {
+    token: '',
+    defaultTeamId: null,
+    activeTeamId: null,
+    teamKeys: {},
+    user: null,
+    lastSyncAt: null,
+    version: CONFIG_VERSION,
+  };
+}
+
+/**
+ * Migrate old config format to new if necessary
+ */
+function migrateConfig(config: Partial<RecallConfig>): RecallConfig {
+  const migrated = { ...createDefaultConfig(), ...config };
+
+  // Future migration logic would go here
+  // For now, just ensure version is set
+  migrated.version = CONFIG_VERSION;
+
+  return migrated;
+}
+
+/**
+ * Load configuration from disk
+ * Returns a default config if the file doesn't exist
+ */
+export function loadConfig(): RecallConfig {
+  const configPath = getConfigPath();
+
+  if (!fs.existsSync(configPath)) {
+    return createDefaultConfig();
+  }
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw) as Partial<RecallConfig>;
+
+    // Migrate if necessary
+    if (!parsed.version || parsed.version < CONFIG_VERSION) {
+      const migrated = migrateConfig(parsed);
+      saveConfig(migrated);
+      return migrated;
+    }
+
+    return migrateConfig(parsed);
+  } catch (error) {
+    // If config is corrupted, return default
+    console.error('Warning: Could not load Recall config, using defaults');
+    return createDefaultConfig();
+  }
+}
+
+/**
+ * Save configuration to disk with secure permissions (0600)
+ */
+export function saveConfig(config: Partial<RecallConfig>): void {
+  ensureConfigDir();
+
+  const current = loadConfig();
+  const merged: RecallConfig = {
+    ...current,
+    ...config,
+    version: CONFIG_VERSION,
+  };
+
+  const configPath = getConfigPath();
+  const json = JSON.stringify(merged, null, 2);
+
+  // Write with secure permissions (0600 = owner read/write only)
+  fs.writeFileSync(configPath, json, { mode: 0o600 });
+}
+
+/**
+ * Get the API base URL from config or environment
+ */
+export function getApiBaseUrl(): string {
+  // Environment variable takes precedence (for development)
+  const envUrl = process.env.RECALL_API_URL;
+  if (envUrl) {
+    return envUrl;
+  }
+
+  return DEFAULT_API_BASE_URL;
+}
+
+/**
+ * Get the API token from config or environment
+ */
+export function getApiToken(): string | null {
+  // Environment variable takes precedence
+  const envToken = process.env.RECALL_API_TOKEN;
+  if (envToken) {
+    return envToken;
+  }
+
+  const config = loadConfig();
+  return config.token || null;
+}
+
+/**
+ * Store the API token securely
+ */
+export function setApiToken(token: string): void {
+  saveConfig({ token });
+}
+
+/**
+ * Get the active team ID
+ */
+export function getActiveTeamId(): string | null {
+  const config = loadConfig();
+  return config.activeTeamId ?? config.defaultTeamId ?? null;
+}
+
+/**
+ * Set the active team ID for this session
+ */
+export function setActiveTeamId(teamId: string): void {
+  saveConfig({ activeTeamId: teamId });
+}
+
+/**
+ * Set the default team ID
+ */
+export function setDefaultTeamId(teamId: string): void {
+  saveConfig({ defaultTeamId: teamId, activeTeamId: teamId });
+}
+
+/**
+ * Get a cached team encryption key
+ */
+export function getTeamKey(teamId: string): string | null {
+  const config = loadConfig();
+  return config.teamKeys[teamId] ?? null;
+}
+
+/**
+ * Cache a team encryption key
+ */
+export function setTeamKey(teamId: string, key: string): void {
+  const config = loadConfig();
+  const teamKeys = { ...config.teamKeys, [teamId]: key };
+  saveConfig({ teamKeys });
+}
+
+/**
+ * Update cached user info
+ */
+export function setUserInfo(user: { id: string; email: string | null; githubUsername: string }): void {
+  saveConfig({ user });
+}
+
+/**
+ * Update last sync timestamp
+ */
+export function setLastSyncAt(timestamp: string): void {
+  saveConfig({ lastSyncAt: timestamp });
+}
+
+/**
+ * Check if the user is authenticated (has a token)
+ */
+export function isAuthenticated(): boolean {
+  return !!getApiToken();
+}
+
+/**
+ * Clear all authentication data (logout)
+ */
+export function clearAuth(): void {
+  saveConfig({
+    token: '',
+    activeTeamId: null,
+    teamKeys: {},
+    user: null,
+    lastSyncAt: null,
+  });
+}
+
+/**
+ * Extended config interface for the MCP client
+ * Adds computed properties and convenience methods
+ */
+export interface ExtendedConfig extends RecallConfig {
+  apiBaseUrl: string;
+  isAuthenticated: boolean;
+}
+
+/**
+ * Get the full extended config
+ */
+export function getExtendedConfig(): ExtendedConfig {
+  const config = loadConfig();
+  return {
+    ...config,
+    apiBaseUrl: getApiBaseUrl(),
+    isAuthenticated: isAuthenticated(),
+  };
+}