@recall_v3/mcp-server 0.1.0

package/src/tools/getTranscripts.ts

@@ -0,0 +1,150 @@
+/**
+ * getTranscripts Tool Implementation
+ *
+ * Fetches full session transcripts (context.md + history.md + transcripts.md).
+ * WARNING: This can be very large and use many tokens.
+ * Only use when you need complete historical details.
+ */
+
+import { RecallApiClient, AuthenticationError, RecallApiError } from '../api/client.js';
+import { getApiBaseUrl, getApiToken, getTeamKey, setTeamKey } from '../config/index.js';
+import { decryptContent } from '../crypto/index.js';
+import { successResponse, errorResponse, formattedResponse, type ToolResponse } from './types.js';
+import { resolveProjectPath, getRepoInfo } from './utils.js';
+
+export interface GetTranscriptsArgs {
+  projectPath: string;
+}
+
+/**
+ * Execute the getTranscripts tool
+ *
+ * @param args - Tool arguments (projectPath is required)
+ * @returns MCP tool response with full transcripts content
+ */
+export async function getTranscripts(args: GetTranscriptsArgs): Promise<ToolResponse> {
+  try {
+    // Get API token
+    const token = getApiToken();
+    if (!token) {
+      return errorResponse(
+        'Not authenticated. Run `recall auth` to connect your account, or set RECALL_API_TOKEN environment variable.'
+      );
+    }
+
+    // Resolve project path
+    const projectPath = resolveProjectPath(args.projectPath);
+
+    // Get repo info from git
+    const repoInfo = await getRepoInfo(projectPath);
+    if (!repoInfo) {
+      return errorResponse(
+        `Could not determine repository info for: ${projectPath}\n` +
+        'Make sure this is a git repository with a remote origin.'
+      );
+    }
+
+    // Create API client
+    const client = new RecallApiClient({
+      baseUrl: getApiBaseUrl(),
+      token,
+    });
+
+    // Resolve repo to get repoId and teamId
+    const { repoId, teamId } = await client.resolveRepo(repoInfo.fullName, repoInfo.defaultBranch);
+
+    // Get team key (fetch from API if not cached)
+    let teamKey = getTeamKey(teamId);
+    if (!teamKey) {
+      const keyResponse = await client.getTeamKey(teamId);
+      teamKey = keyResponse.encryptionKey;
+      setTeamKey(teamId, teamKey);
+    }
+
+    // Fetch transcripts from API
+    const response = await client.getTranscripts(repoId);
+
+    // Decrypt all content
+    let contextMd: string;
+    let historyMd: string;
+    let transcriptsMd: string;
+
+    try {
+      // Decrypt context
+      if (response.contextMd.startsWith('{') || response.contextMd.includes(':')) {
+        contextMd = decryptContent(response.contextMd, teamKey);
+      } else {
+        contextMd = response.contextMd;
+      }
+
+      // Decrypt history
+      if (response.historyMd.startsWith('{') || response.historyMd.includes(':')) {
+        historyMd = decryptContent(response.historyMd, teamKey);
+      } else {
+        historyMd = response.historyMd;
+      }
+
+      // Decrypt transcripts
+      if (response.transcriptsMd.startsWith('{') || response.transcriptsMd.includes(':')) {
+        transcriptsMd = decryptContent(response.transcriptsMd, teamKey);
+      } else {
+        transcriptsMd = response.transcriptsMd;
+      }
+    } catch (decryptError) {
+      // If decryption fails, use as-is
+      contextMd = response.contextMd;
+      historyMd = response.historyMd;
+      transcriptsMd = response.transcriptsMd;
+    }
+
+    // Combine all content with warning
+    const combinedContent = [
+      `# TOKEN WARNING`,
+      ``,
+      response.tokenWarning,
+      ``,
+      `---`,
+      ``,
+      `# Recall Context`,
+      ``,
+      contextMd,
+      ``,
+      `---`,
+      ``,
+      `# Session History`,
+      ``,
+      historyMd,
+      ``,
+      `---`,
+      ``,
+      `# Full Transcripts`,
+      ``,
+      transcriptsMd,
+    ].join('\n');
+
+    // Format output
+    const header = `Reading full transcripts from: ${projectPath}/.recall`;
+    return formattedResponse(header, combinedContent);
+
+  } catch (error) {
+    if (error instanceof AuthenticationError) {
+      return errorResponse(
+        'Authentication failed. Your token may have expired.\n' +
+        'Run `recall auth` to reconnect your account.'
+      );
+    }
+
+    if (error instanceof RecallApiError) {
+      if (error.code === 'REPO_NOT_FOUND') {
+        return errorResponse(
+          'This repository is not connected to Recall.\n' +
+          'Run `recall init` to set up team memory for this repo.'
+        );
+      }
+      return errorResponse(`API Error: ${error.message}`);
+    }
+
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    return errorResponse(message);
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Tool Implementations
+ *
+ * Exports all MCP tool implementations.
+ */
+
+export { getContext, type GetContextArgs } from './getContext.js';
+export { getHistory, type GetHistoryArgs } from './getHistory.js';
+export { getTranscripts, type GetTranscriptsArgs } from './getTranscripts.js';
+export { saveSession, type SaveSessionArgs } from './saveSession.js';
+export { logDecision, type LogDecisionArgs } from './logDecision.js';
+export { type ToolResponse, successResponse, errorResponse, formattedResponse } from './types.js';
+export * from './utils.js';

package/src/tools/logDecision.ts

@@ -0,0 +1,118 @@
+/**
+ * logDecision Tool Implementation
+ *
+ * Logs an important decision made during coding.
+ * Quick way to capture why something was done.
+ */
+
+import { RecallApiClient, AuthenticationError, RecallApiError } from '../api/client.js';
+import { getApiBaseUrl, getApiToken, getTeamKey, setTeamKey } from '../config/index.js';
+import { successResponse, errorResponse, type ToolResponse } from './types.js';
+import { resolveProjectPath, getRepoInfo } from './utils.js';
+import type { LogDecisionRequest } from '@recall_v3/shared';
+
+export interface LogDecisionArgs {
+  decision: string;
+  reasoning: string;
+}
+
+/**
+ * Execute the logDecision tool
+ *
+ * @param args - Tool arguments with decision and reasoning
+ * @returns MCP tool response with confirmation
+ */
+export async function logDecision(args: LogDecisionArgs): Promise<ToolResponse> {
+  try {
+    // Validate required fields
+    if (!args.decision || args.decision.trim().length === 0) {
+      return errorResponse('Decision is required. Please describe what was decided.');
+    }
+
+    if (!args.reasoning || args.reasoning.trim().length === 0) {
+      return errorResponse('Reasoning is required. Please explain why this decision was made.');
+    }
+
+    // Get API token
+    const token = getApiToken();
+    if (!token) {
+      return errorResponse(
+        'Not authenticated. Run `recall auth` to connect your account, or set RECALL_API_TOKEN environment variable.'
+      );
+    }
+
+    // Resolve project path (use cwd)
+    const projectPath = resolveProjectPath(undefined);
+
+    // Get repo info from git
+    const repoInfo = await getRepoInfo(projectPath);
+    if (!repoInfo) {
+      return errorResponse(
+        `Could not determine repository info for: ${projectPath}\n` +
+        'Make sure this is a git repository with a remote origin.'
+      );
+    }
+
+    // Create API client
+    const client = new RecallApiClient({
+      baseUrl: getApiBaseUrl(),
+      token,
+    });
+
+    // Resolve repo to get repoId and teamId
+    const { repoId, teamId } = await client.resolveRepo(repoInfo.fullName, repoInfo.defaultBranch);
+
+    // Get team key (fetch from API if not cached)
+    let teamKey = getTeamKey(teamId);
+    if (!teamKey) {
+      const keyResponse = await client.getTeamKey(teamId);
+      teamKey = keyResponse.encryptionKey;
+      setTeamKey(teamId, teamKey);
+    }
+
+    // Build the decision request
+    const decisionRequest: LogDecisionRequest = {
+      decision: args.decision.trim(),
+      reasoning: args.reasoning.trim(),
+    };
+
+    // Log decision via API
+    const response = await client.logDecision(repoId, decisionRequest);
+
+    // Build success message
+    const successMessage = [
+      `Decision logged successfully.`,
+      ``,
+      `Decision ID: ${response.decisionId}`,
+      `Repository: ${repoInfo.fullName}`,
+      ``,
+      `What: ${args.decision.trim()}`,
+      `Why: ${args.reasoning.trim()}`,
+      ``,
+      `This decision has been added to the team memory.`,
+    ].join('\n');
+
+    return successResponse(successMessage);
+
+  } catch (error) {
+    if (error instanceof AuthenticationError) {
+      return errorResponse(
+        'Authentication failed. Your token may have expired.\n' +
+        'Run `recall auth` to reconnect your account.'
+      );
+    }
+
+    if (error instanceof RecallApiError) {
+      if (error.code === 'REPO_NOT_FOUND') {
+        return errorResponse(
+          'This repository is not connected to Recall.\n' +
+          'Run `recall init` to set up team memory for this repo.'
+        );
+      }
+      return errorResponse(`API Error: ${error.message}`);
+    }
+
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    return errorResponse(message);
+  }
+}

package/src/tools/saveSession.ts

@@ -0,0 +1,159 @@
+/**
+ * saveSession Tool Implementation
+ *
+ * Saves a summary of what was accomplished in this coding session.
+ * Updates the team memory files via the Recall API.
+ */
+
+import { RecallApiClient, AuthenticationError, RecallApiError } from '../api/client.js';
+import { getApiBaseUrl, getApiToken, getTeamKey, setTeamKey } from '../config/index.js';
+import { encryptContent } from '../crypto/index.js';
+import { successResponse, errorResponse, type ToolResponse } from './types.js';
+import { resolveProjectPath, getRepoInfo } from './utils.js';
+import type { SaveSessionRequest } from '@recall_v3/shared';
+
+export interface SaveSessionArgs {
+  summary: string;
+  decisions?: Array<{
+    what: string;
+    why: string;
+  }>;
+  mistakes?: string[];
+  filesChanged?: string[];
+  nextSteps?: string;
+  blockers?: string;
+}
+
+/**
+ * Execute the saveSession tool
+ *
+ * @param args - Tool arguments with session summary and metadata
+ * @returns MCP tool response with save confirmation
+ */
+export async function saveSession(args: SaveSessionArgs): Promise<ToolResponse> {
+  try {
+    // Validate required fields
+    if (!args.summary || args.summary.trim().length === 0) {
+      return errorResponse('Summary is required. Please provide a description of what was accomplished.');
+    }
+
+    // Get API token
+    const token = getApiToken();
+    if (!token) {
+      return errorResponse(
+        'Not authenticated. Run `recall auth` to connect your account, or set RECALL_API_TOKEN environment variable.'
+      );
+    }
+
+    // Resolve project path (use cwd since projectPath is not in args)
+    const projectPath = resolveProjectPath(undefined);
+
+    // Get repo info from git
+    const repoInfo = await getRepoInfo(projectPath);
+    if (!repoInfo) {
+      return errorResponse(
+        `Could not determine repository info for: ${projectPath}\n` +
+        'Make sure this is a git repository with a remote origin.'
+      );
+    }
+
+    // Create API client
+    const client = new RecallApiClient({
+      baseUrl: getApiBaseUrl(),
+      token,
+    });
+
+    // Resolve repo to get repoId and teamId
+    const { repoId, teamId } = await client.resolveRepo(repoInfo.fullName, repoInfo.defaultBranch);
+
+    // Get team key (fetch from API if not cached)
+    let teamKey = getTeamKey(teamId);
+    if (!teamKey) {
+      const keyResponse = await client.getTeamKey(teamId);
+      teamKey = keyResponse.encryptionKey;
+      setTeamKey(teamId, teamKey);
+    }
+
+    // Build the session request
+    const sessionRequest: SaveSessionRequest = {
+      summary: args.summary.trim(),
+    };
+
+    if (args.decisions && args.decisions.length > 0) {
+      sessionRequest.decisions = args.decisions;
+    }
+
+    if (args.mistakes && args.mistakes.length > 0) {
+      sessionRequest.mistakes = args.mistakes;
+    }
+
+    if (args.filesChanged && args.filesChanged.length > 0) {
+      sessionRequest.filesChanged = args.filesChanged;
+    }
+
+    if (args.nextSteps && args.nextSteps.trim().length > 0) {
+      sessionRequest.nextSteps = args.nextSteps.trim();
+    }
+
+    if (args.blockers && args.blockers.trim().length > 0) {
+      sessionRequest.blockers = args.blockers.trim();
+    }
+
+    // Save session via API
+    const response = await client.saveSession(repoId, sessionRequest);
+
+    // Build success message
+    const parts: string[] = [
+      `Session saved successfully.`,
+      ``,
+      `Session ID: ${response.sessionId}`,
+      `Repository: ${repoInfo.fullName}`,
+    ];
+
+    if (args.decisions && args.decisions.length > 0) {
+      parts.push(`Decisions logged: ${args.decisions.length}`);
+    }
+
+    if (args.mistakes && args.mistakes.length > 0) {
+      parts.push(`Mistakes documented: ${args.mistakes.length}`);
+    }
+
+    if (args.filesChanged && args.filesChanged.length > 0) {
+      parts.push(`Files tracked: ${args.filesChanged.length}`);
+    }
+
+    if (args.nextSteps) {
+      parts.push(`Next steps: ${args.nextSteps}`);
+    }
+
+    if (args.blockers) {
+      parts.push(`Blockers: ${args.blockers}`);
+    }
+
+    parts.push(``);
+    parts.push(`Team memory has been updated.`);
+
+    return successResponse(parts.join('\n'));
+
+  } catch (error) {
+    if (error instanceof AuthenticationError) {
+      return errorResponse(
+        'Authentication failed. Your token may have expired.\n' +
+        'Run `recall auth` to reconnect your account.'
+      );
+    }
+
+    if (error instanceof RecallApiError) {
+      if (error.code === 'REPO_NOT_FOUND') {
+        return errorResponse(
+          'This repository is not connected to Recall.\n' +
+          'Run `recall init` to set up team memory for this repo.'
+        );
+      }
+      return errorResponse(`API Error: ${error.message}`);
+    }
+
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    return errorResponse(message);
+  }
+}

package/src/tools/types.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP Tool Response Types
+ *
+ * Shared types for tool implementations.
+ */
+
+/**
+ * Content item in MCP response
+ */
+export interface TextContent {
+  type: 'text';
+  text: string;
+}
+
+/**
+ * Standard MCP tool response format
+ */
+export interface ToolResponse {
+  content: TextContent[];
+  isError?: boolean;
+}
+
+/**
+ * Create a success response
+ */
+export function successResponse(text: string): ToolResponse {
+  return {
+    content: [{ type: 'text', text }],
+  };
+}
+
+/**
+ * Create an error response
+ */
+export function errorResponse(message: string): ToolResponse {
+  return {
+    content: [{ type: 'text', text: `Error: ${message}` }],
+    isError: true,
+  };
+}
+
+/**
+ * Create a formatted response with header and content
+ */
+export function formattedResponse(header: string, content: string): ToolResponse {
+  return successResponse(`[${header}]\n\n${content}`);
+}

package/src/tools/utils.ts

@@ -0,0 +1,226 @@
+/**
+ * Tool Utilities
+ *
+ * Shared utilities for tool implementations.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+
+/**
+ * Repository information extracted from git
+ */
+export interface RepoInfo {
+  /** Full name like "owner/repo" */
+  fullName: string;
+  /** Remote URL */
+  remoteUrl: string;
+  /** Default branch name */
+  defaultBranch: string;
+  /** Local repo root path */
+  localPath: string;
+}
+
+/**
+ * Resolve project path from argument or cwd
+ */
+export function resolveProjectPath(projectPath?: string): string {
+  if (projectPath) {
+    // Resolve to absolute path
+    return path.resolve(projectPath);
+  }
+
+  // Use current working directory
+  return process.cwd();
+}
+
+/**
+ * Find the git root directory for a given path
+ */
+export function findGitRoot(startPath: string): string | null {
+  let currentPath = path.resolve(startPath);
+
+  while (currentPath !== path.dirname(currentPath)) {
+    if (fs.existsSync(path.join(currentPath, '.git'))) {
+      return currentPath;
+    }
+    currentPath = path.dirname(currentPath);
+  }
+
+  return null;
+}
+
+/**
+ * Execute a git command in the given directory
+ */
+function execGit(args: string[], cwd: string): string | null {
+  try {
+    const result = execSync(`git ${args.join(' ')}`, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return result.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse GitHub/GitLab remote URL to get owner/repo
+ */
+function parseRemoteUrl(url: string): string | null {
+  // SSH format: git@github.com:owner/repo.git
+  const sshMatch = url.match(/git@[\w.-]+:([\w.-]+\/[\w.-]+?)(?:\.git)?$/);
+  if (sshMatch) {
+    return sshMatch[1];
+  }
+
+  // HTTPS format: https://github.com/owner/repo.git
+  const httpsMatch = url.match(/https?:\/\/[\w.-]+\/([\w.-]+\/[\w.-]+?)(?:\.git)?$/);
+  if (httpsMatch) {
+    return httpsMatch[1];
+  }
+
+  return null;
+}
+
+/**
+ * Get repository information from git
+ */
+export async function getRepoInfo(projectPath: string): Promise<RepoInfo | null> {
+  // Find git root
+  const gitRoot = findGitRoot(projectPath);
+  if (!gitRoot) {
+    return null;
+  }
+
+  // Get remote URL
+  const remoteUrl = execGit(['config', '--get', 'remote.origin.url'], gitRoot);
+  if (!remoteUrl) {
+    return null;
+  }
+
+  // Parse full name from URL
+  const fullName = parseRemoteUrl(remoteUrl);
+  if (!fullName) {
+    return null;
+  }
+
+  // Get default branch
+  // Try to get from remote HEAD first
+  let defaultBranch = execGit(['symbolic-ref', 'refs/remotes/origin/HEAD', '--short'], gitRoot);
+  if (defaultBranch) {
+    // Remove "origin/" prefix
+    defaultBranch = defaultBranch.replace(/^origin\//, '');
+  } else {
+    // Fallback to common defaults
+    defaultBranch = 'main';
+  }
+
+  return {
+    fullName,
+    remoteUrl,
+    defaultBranch,
+    localPath: gitRoot,
+  };
+}
+
+/**
+ * Read a file if it exists
+ */
+export function readFileIfExists(filePath: string): string | null {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the Claude session directory for a project
+ * Claude stores sessions in ~/.claude/projects/<hash>/
+ */
+export function getClaudeSessionDir(projectPath: string): string | null {
+  const claudeDir = path.join(process.env.HOME || '', '.claude', 'projects');
+
+  if (!fs.existsSync(claudeDir)) {
+    return null;
+  }
+
+  // Claude uses a hash of the project path
+  // We need to find the matching directory
+  try {
+    const dirs = fs.readdirSync(claudeDir);
+
+    for (const dir of dirs) {
+      const sessionPath = path.join(claudeDir, dir);
+      const stat = fs.statSync(sessionPath);
+
+      if (!stat.isDirectory()) continue;
+
+      // Check if this directory's config points to our project
+      const configPath = path.join(sessionPath, 'config.json');
+      if (fs.existsSync(configPath)) {
+        try {
+          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8')) as { projectPath?: string };
+          if (config.projectPath === projectPath) {
+            return sessionPath;
+          }
+        } catch {
+          // Skip invalid config files
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Find the most recent Claude session JSONL file
+ */
+export function findLatestSessionFile(projectPath: string): string | null {
+  const sessionDir = getClaudeSessionDir(projectPath);
+  if (!sessionDir) {
+    return null;
+  }
+
+  try {
+    const files = fs.readdirSync(sessionDir)
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => ({
+        name: f,
+        path: path.join(sessionDir, f),
+        mtime: fs.statSync(path.join(sessionDir, f)).mtime,
+      }))
+      .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+
+    return files.length > 0 ? files[0].path : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format bytes to human-readable size
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Format duration in seconds to human-readable
+ */
+export function formatDuration(seconds: number): string {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  const hours = Math.floor(seconds / 3600);
+  const mins = Math.floor((seconds % 3600) / 60);
+  return `${hours}h ${mins}m`;
+}