@recall_v3/mcp-server 0.1.0

package/src/crypto/index.ts

@@ -0,0 +1,207 @@
+/**
+ * Recall Encryption Utilities
+ *
+ * AES-256-GCM encryption/decryption compatible with Web Crypto API.
+ * Uses Node.js crypto module for server-side operations.
+ */
+
+import * as crypto from 'node:crypto';
+import type { EncryptedPayload } from '@recall_v3/shared';
+
+// AES-256-GCM constants
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12; // 96 bits for GCM
+const TAG_LENGTH = 16; // 128 bits for GCM auth tag
+
+/**
+ * Generate a cryptographically secure random IV
+ */
+export function generateIV(): Uint8Array {
+  return crypto.randomBytes(IV_LENGTH);
+}
+
+/**
+ * Generate a new AES-256 encryption key
+ * Returns base64-encoded key
+ */
+export function generateKey(): string {
+  const key = crypto.randomBytes(32); // 256 bits
+  return key.toString('base64');
+}
+
+/**
+ * Encrypt plaintext using AES-256-GCM
+ *
+ * @param plaintext - The string to encrypt
+ * @param keyBase64 - Base64-encoded 256-bit key
+ * @returns EncryptedPayload with base64-encoded ciphertext, iv, and tag
+ */
+export function encrypt(plaintext: string, keyBase64: string): EncryptedPayload {
+  // Decode the key
+  const key = Buffer.from(keyBase64, 'base64');
+
+  if (key.length !== 32) {
+    throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+  }
+
+  // Generate a random IV
+  const iv = generateIV();
+
+  // Create cipher
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv, {
+    authTagLength: TAG_LENGTH,
+  });
+
+  // Encrypt
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, 'utf8'),
+    cipher.final(),
+  ]);
+
+  // Get auth tag
+  const tag = cipher.getAuthTag();
+
+  // Return base64-encoded values
+  return {
+    ciphertext: encrypted.toString('base64'),
+    iv: Buffer.from(iv).toString('base64'),
+    tag: tag.toString('base64'),
+  };
+}
+
+/**
+ * Decrypt an encrypted payload using AES-256-GCM
+ *
+ * @param payload - EncryptedPayload with base64-encoded values
+ * @param keyBase64 - Base64-encoded 256-bit key
+ * @returns Decrypted plaintext string
+ */
+export function decrypt(payload: EncryptedPayload, keyBase64: string): string {
+  // Decode all components
+  const key = Buffer.from(keyBase64, 'base64');
+  const iv = Buffer.from(payload.iv, 'base64');
+  const ciphertext = Buffer.from(payload.ciphertext, 'base64');
+  const tag = Buffer.from(payload.tag, 'base64');
+
+  if (key.length !== 32) {
+    throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+  }
+
+  if (iv.length !== IV_LENGTH) {
+    throw new Error(`Invalid IV length: expected ${IV_LENGTH} bytes, got ${iv.length}`);
+  }
+
+  if (tag.length !== TAG_LENGTH) {
+    throw new Error(`Invalid tag length: expected ${TAG_LENGTH} bytes, got ${tag.length}`);
+  }
+
+  // Create decipher
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv, {
+    authTagLength: TAG_LENGTH,
+  });
+
+  // Set auth tag
+  decipher.setAuthTag(tag);
+
+  // Decrypt
+  try {
+    const decrypted = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final(),
+    ]);
+
+    return decrypted.toString('utf8');
+  } catch (error) {
+    // GCM authentication failure
+    if (error instanceof Error && error.message.includes('Unsupported state')) {
+      throw new Error('Decryption failed: authentication tag mismatch');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Parse an encrypted string into an EncryptedPayload
+ * The format is: base64(iv):base64(tag):base64(ciphertext)
+ * This is an alternative compact format for storage
+ */
+export function parseEncryptedString(encrypted: string): EncryptedPayload {
+  const parts = encrypted.split(':');
+  if (parts.length !== 3) {
+    throw new Error('Invalid encrypted string format');
+  }
+
+  return {
+    iv: parts[0],
+    tag: parts[1],
+    ciphertext: parts[2],
+  };
+}
+
+/**
+ * Serialize an EncryptedPayload to a compact string
+ * Format: base64(iv):base64(tag):base64(ciphertext)
+ */
+export function serializeEncrypted(payload: EncryptedPayload): string {
+  return `${payload.iv}:${payload.tag}:${payload.ciphertext}`;
+}
+
+/**
+ * Check if a string looks like an encrypted payload
+ */
+export function isEncryptedString(str: string): boolean {
+  // Check for compact format (iv:tag:ciphertext)
+  if (str.includes(':')) {
+    const parts = str.split(':');
+    if (parts.length === 3) {
+      // Each part should be valid base64
+      return parts.every(part => {
+        try {
+          Buffer.from(part, 'base64');
+          return true;
+        } catch {
+          return false;
+        }
+      });
+    }
+  }
+
+  // Check for JSON format
+  try {
+    const parsed = JSON.parse(str) as unknown;
+    return (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      'ciphertext' in parsed &&
+      'iv' in parsed &&
+      'tag' in parsed
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decrypt content that might be in either format (JSON or compact string)
+ */
+export function decryptContent(encrypted: string, keyBase64: string): string {
+  let payload: EncryptedPayload;
+
+  // Try JSON format first
+  try {
+    payload = JSON.parse(encrypted) as EncryptedPayload;
+  } catch {
+    // Try compact string format
+    payload = parseEncryptedString(encrypted);
+  }
+
+  return decrypt(payload, keyBase64);
+}
+
+/**
+ * Encrypt content and return as JSON string
+ */
+export function encryptContent(plaintext: string, keyBase64: string): string {
+  const payload = encrypt(plaintext, keyBase64);
+  return JSON.stringify(payload);
+}

package/src/index.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+/**
+ * Recall MCP Server v3
+ * Local MCP server for AI coding assistants
+ *
+ * This package provides the local MCP server that connects
+ * to the Recall API for team memory synchronization.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// Tool implementations
+import {
+  getContext,
+  getHistory,
+  getTranscripts,
+  saveSession,
+  logDecision,
+  type GetContextArgs,
+  type GetHistoryArgs,
+  type GetTranscriptsArgs,
+  type SaveSessionArgs,
+  type LogDecisionArgs,
+} from './tools/index.js';
+
+// Tool definitions
+const TOOLS = [
+  {
+    name: 'recall_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.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: {
+          type: 'string',
+          description:
+            'Optional: explicit path to the project root. If not provided, uses current working directory.',
+        },
+      },
+    },
+  },
+  {
+    name: 'recall_get_history',
+    description:
+      "Get detailed session history (context.md + recent sessions). This includes more context than recall_get_context but uses more tokens.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: {
+          type: 'string',
+          description:
+            'Path to the project root. REQUIRED to ensure correct repo context. Use the absolute path to the project you are working in.',
+        },
+      },
+      required: ['projectPath'],
+    },
+  },
+  {
+    name: 'recall_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: {
+      type: 'object',
+      properties: {
+        projectPath: {
+          type: 'string',
+          description:
+            'Path to the project root. REQUIRED to ensure correct repo context. Use the absolute path to the project you are working in.',
+        },
+      },
+      required: ['projectPath'],
+    },
+  },
+  {
+    name: 'recall_save_session',
+    description:
+      "Save a summary of what was accomplished in this coding session. This updates the team memory files.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        summary: {
+          type: 'string',
+          description:
+            'What was accomplished in this session - list all items worked on, kept short',
+        },
+        decisions: {
+          type: 'array',
+          description: 'Key decisions made',
+          items: {
+            type: 'object',
+            properties: {
+              what: { type: 'string', description: 'What was decided' },
+              why: { type: 'string', description: 'Why this decision was made' },
+            },
+            required: ['what', 'why'],
+          },
+        },
+        mistakes: {
+          type: 'array',
+          description:
+            'Mistakes or gotchas discovered - things the team should not repeat',
+          items: { type: 'string' },
+        },
+        filesChanged: {
+          type: 'array',
+          description: 'Files that were modified',
+          items: { type: 'string' },
+        },
+        nextSteps: {
+          type: 'string',
+          description: 'What should be done next',
+        },
+        blockers: {
+          type: 'string',
+          description: 'Any blockers encountered',
+        },
+      },
+      required: ['summary'],
+    },
+  },
+  {
+    name: 'recall_log_decision',
+    description:
+      "Log an important decision made during coding. Quick way to capture why something was done.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        decision: {
+          type: 'string',
+          description: 'What was decided',
+        },
+        reasoning: {
+          type: 'string',
+          description: 'Why this decision was made',
+        },
+      },
+      required: ['decision', 'reasoning'],
+    },
+  },
+];
+
+class RecallMCPServer {
+  private server: Server;
+
+  constructor() {
+    this.server = new Server(
+      {
+        name: 'recall-mcp-v3',
+        version: '0.1.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return { tools: TOOLS };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
+      const { name, arguments: args = {} } = request.params;
+
+      try {
+        let result;
+        switch (name) {
+          case 'recall_get_context':
+            result = await getContext(args as unknown as GetContextArgs);
+            break;
+
+          case 'recall_get_history':
+            result = await getHistory(args as unknown as GetHistoryArgs);
+            break;
+
+          case 'recall_get_transcripts':
+            result = await getTranscripts(args as unknown as GetTranscriptsArgs);
+            break;
+
+          case 'recall_save_session':
+            result = await saveSession(args as unknown as SaveSessionArgs);
+            break;
+
+          case 'recall_log_decision':
+            result = await logDecision(args as unknown as LogDecisionArgs);
+            break;
+
+          default:
+            return {
+              content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+              isError: true,
+            };
+        }
+
+        return {
+          content: result.content.map(c => ({ type: 'text' as const, text: c.text })),
+          isError: result.isError,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+          content: [{ type: 'text', text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  async run(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('Recall MCP v3 server running on stdio');
+  }
+}
+
+// Start server
+const server = new RecallMCPServer();
+server.run().catch(console.error);

package/src/tools/getContext.ts

@@ -0,0 +1,106 @@
+/**
+ * getContext Tool Implementation
+ *
+ * Fetches the team brain (context.md) for the current repository.
+ * This is the distilled current state - loaded at every session start.
+ */
+
+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 GetContextArgs {
+  projectPath?: string;
+}
+
+/**
+ * Execute the getContext tool
+ *
+ * @param args - Tool arguments (projectPath is optional)
+ * @returns MCP tool response with context.md content
+ */
+export async function getContext(args: GetContextArgs): 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 context from API
+    const response = await client.getContext(repoId);
+
+    // The contextMd comes encrypted from the API, decrypt it
+    let contextMd: string;
+    try {
+      // Check if content is encrypted
+      if (response.contextMd.startsWith('{') || response.contextMd.includes(':')) {
+        contextMd = decryptContent(response.contextMd, teamKey);
+      } else {
+        // Already plaintext (shouldn't happen, but handle gracefully)
+        contextMd = response.contextMd;
+      }
+    } catch (decryptError) {
+      // If decryption fails, it might already be plaintext
+      contextMd = response.contextMd;
+    }
+
+    // Format output with metadata
+    const header = `Reading from: ${projectPath}/.recall`;
+    return formattedResponse(header, contextMd);
+
+  } 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/getHistory.ts

@@ -0,0 +1,118 @@
+/**
+ * getHistory Tool Implementation
+ *
+ * Fetches context.md + recent session history for the repository.
+ * This provides more detail than getContext but uses more tokens.
+ */
+
+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 GetHistoryArgs {
+  projectPath: string;
+}
+
+/**
+ * Execute the getHistory tool
+ *
+ * @param args - Tool arguments (projectPath is required)
+ * @returns MCP tool response with context.md + history.md content
+ */
+export async function getHistory(args: GetHistoryArgs): 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 history from API
+    const response = await client.getHistory(repoId);
+
+    // Decrypt content
+    let contextMd: string;
+    let historyMd: 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;
+      }
+    } catch (decryptError) {
+      // If decryption fails, use as-is
+      contextMd = response.contextMd;
+      historyMd = response.historyMd;
+    }
+
+    // Combine context and history
+    const combinedContent = `# Recall Context\n\n${contextMd}\n\n---\n\n# Session History\n\n${historyMd}`;
+
+    // Format output with metadata
+    const header = `Reading history from: ${projectPath}/.recall (${response.sessionCount} sessions)`;
+    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);
+  }
+}