find_file_context

Search Claude conversation history to find all discussions and modifications related to a specific file, helping users track changes and reference previous work.

Instructions

Find all conversations and changes related to a specific file

Input Schema

TableJSON Schema

Name	Required	Description	Default
`filepath`	Yes	File path to search for in conversation history
`operation_type`	No	Filter by operation: read, edit, create, or all	all
`limit`	No	Maximum number of results (default: 15)
`detail_level`	No	Response detail: summary (default), detailed, raw	summary

Implementation Reference

src/index.ts:284-302 (handler)

MCP server dispatch handler for 'find_file_context' tool: extracts args, calls UniversalHistorySearchEngine.findFileContext, formats result with BeautifulFormatter

case 'find_file_context': {
  const universalResult = await this.universalEngine.findFileContext(
    args?.filepath as string,
    (args?.limit as number) || 15
  );

  const detailLevel = (args?.detail_level as string) || 'summary';
  const operationType = (args?.operation_type as string) || 'all';
  const formattedResult = this.formatter.formatFileContext(
    universalResult.results,
    args?.filepath as string,
    detailLevel,
    operationType
  );

  return {
    content: [{ type: 'text', text: formattedResult }],
  };
}

src/universal-engine.ts:1117-1144 (handler)

UniversalHistorySearchEngine.findFileContext: proxies to HistorySearchEngine.findFileContext (primary impl), adds desktop support (currently disabled)

async findFileContext(
  filepath: string,
  limit?: number
): Promise<{ source: string; results: FileContext[]; enhanced: boolean }> {
  await this.initialize();

  const claudeCodeResults = await this.claudeCodeEngine.findFileContext(filepath, limit);

  if (!this.claudeDesktopAvailable) {
    return {
      source: 'claude-code',
      results: claudeCodeResults,
      enhanced: false,
    };
  }

  const desktopMessages = await this.searchClaudeDesktopConversations(filepath, undefined, limit);

  const combinedResults = this.combineFileContextResults(claudeCodeResults, desktopMessages);

  const hasDesktopData = desktopMessages.length > 0;

  return {
    source: hasDesktopData ? 'claude-desktop' : 'claude-code',
    results: combinedResults,
    enhanced: hasDesktopData,
  };
}

src/search.ts:735-851 (handler)

Core HistorySearchEngine.findFileContext implementation: parallel search across projects' jsonl conversation files for messages referencing the filepath, extracts related contexts grouped by operation

async findFileContext(filePath: string, limit: number = 25): Promise<FileContext[]> {
  const fileContexts: FileContext[] = [];

  try {
    const projectDirs = await findProjectDirectories();

    // COMPREHENSIVE: Process more projects to match GLOBAL's reach
    const limitedDirs = projectDirs.slice(0, 15); // Increased significantly to match GLOBAL scope

    // PARALLEL PROCESSING: Process all projects concurrently
    const projectResults = await Promise.allSettled(
      limitedDirs.map(async (projectDir) => {
        const jsonlFiles = await findJsonlFiles(projectDir);

        // COMPREHENSIVE: Process more files to match GLOBAL's reach
        const limitedFiles = jsonlFiles.slice(0, 10); // Increased to match GLOBAL scope

        const fileResults = await Promise.allSettled(
          limitedFiles.map(async (file) => {
            const messages = await this.parser.parseJsonlFile(projectDir, file);

            const fileMessages = messages.filter((msg) => {
              // ENHANCED file matching logic like GLOBAL with more patterns
              const hasFileRef = msg.context?.filesReferenced?.some((ref) => {
                const refLower = ref.toLowerCase();
                const pathLower = filePath.toLowerCase();
                // More comprehensive matching patterns
                return (
                  refLower.includes(pathLower) ||
                  pathLower.includes(refLower) ||
                  refLower.endsWith('/' + pathLower) ||
                  pathLower.endsWith('/' + refLower) ||
                  refLower.split('/').pop() === pathLower ||
                  pathLower.split('/').pop() === refLower ||
                  refLower === pathLower ||
                  refLower.includes(pathLower.replace(/\\/g, '/')) ||
                  refLower.includes(pathLower.replace(/\//g, '\\'))
                );
              });

              // Enhanced content matching with case variations and path separators
              const contentLower = msg.content.toLowerCase();
              const pathVariations = [
                filePath.toLowerCase(),
                filePath.toLowerCase().replace(/\\/g, '/'),
                filePath.toLowerCase().replace(/\//g, '\\'),
                filePath.toLowerCase().split('/').pop() || '',
                filePath.toLowerCase().split('\\').pop() || '',
              ];

              const hasContentRef = pathVariations.some(
                (variation) => variation.length > 0 && contentLower.includes(variation)
              );

              // Enhanced git pattern matching
              const hasGitRef =
                /(?:modified|added|deleted|new file|renamed|M\s+|A\s+|D\s+)[\s:]*[^\n]*/.test(
                  msg.content
                ) &&
                pathVariations.some(
                  (variation) => variation.length > 0 && contentLower.includes(variation)
                );

              return hasFileRef || hasContentRef || hasGitRef;
            });

            if (fileMessages.length > 0) {
              // Claude-optimized filtering - preserve valuable context
              const cleanFileMessages = fileMessages.filter((msg) => {
                return msg.content.length > 15 && !this.isLowValueContent(msg.content);
              });

              const dedupedMessages = SearchHelpers.deduplicateByContent(cleanFileMessages);

              if (dedupedMessages.length > 0) {
                // Group by operation type (heuristic)
                const operationType = SearchHelpers.inferOperationType(dedupedMessages);

                return {
                  filePath,
                  lastModified: dedupedMessages[0]?.timestamp || '',
                  relatedMessages: dedupedMessages.slice(0, Math.min(limit, 10)), // More context for Claude
                  operationType,
                };
              }
            }
            return null;
          })
        );

        // Collect successful file results
        const validContexts: FileContext[] = [];
        for (const result of fileResults) {
          if (result.status === 'fulfilled' && result.value) {
            validContexts.push(result.value);
          }
        }

        return validContexts;
      })
    );

    // Aggregate all results from parallel processing
    for (const result of projectResults) {
      if (result.status === 'fulfilled') {
        fileContexts.push(...result.value);
      }
    }

    return fileContexts.sort(
      (a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime()
    );
  } catch (error) {
    console.error('File context search error:', error);
    return [];
  }
}

src/index.ts:77-107 (schema)

Input schema and metadata definition for find_file_context tool in MCP ListTools response

{
  name: 'find_file_context',
  description: 'Find all conversations and changes related to a specific file',
  inputSchema: {
    type: 'object',
    properties: {
      filepath: {
        type: 'string',
        description: 'File path to search for in conversation history',
      },
      operation_type: {
        type: 'string',
        description: 'Filter by operation: read, edit, create, or all',
        enum: ['read', 'edit', 'create', 'all'],
        default: 'all',
      },
      limit: {
        type: 'number',
        description: 'Maximum number of results (default: 15)',
        default: 15,
      },
      detail_level: {
        type: 'string',
        description: 'Response detail: summary (default), detailed, raw',
        enum: ['summary', 'detailed', 'raw'],
        default: 'summary',
      },
    },
    required: ['filepath'],
  },
},

src/index.ts:41-256 (registration)

Registration of all tools including find_file_context in MCP ListToolsRequestSchema handler

this.server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'search_conversations',
        description: 'Search through Claude Code conversation history with smart insights',
        inputSchema: {
          type: 'object',
          properties: {
            query: {
              type: 'string',
              description: 'Search query to find relevant conversations',
            },
            project: {
              type: 'string',
              description: 'Optional project name to filter results',
            },
            timeframe: {
              type: 'string',
              description: 'Time range filter (today, week, month)',
            },
            limit: {
              type: 'number',
              description: 'Maximum number of results (default: 10)',
              default: 10,
            },
            detail_level: {
              type: 'string',
              description: 'Response detail: summary (default), detailed, raw',
              enum: ['summary', 'detailed', 'raw'],
              default: 'summary',
            },
          },
          required: ['query'],
        },
      },
      {
        name: 'find_file_context',
        description: 'Find all conversations and changes related to a specific file',
        inputSchema: {
          type: 'object',
          properties: {
            filepath: {
              type: 'string',
              description: 'File path to search for in conversation history',
            },
            operation_type: {
              type: 'string',
              description: 'Filter by operation: read, edit, create, or all',
              enum: ['read', 'edit', 'create', 'all'],
              default: 'all',
            },
            limit: {
              type: 'number',
              description: 'Maximum number of results (default: 15)',
              default: 15,
            },
            detail_level: {
              type: 'string',
              description: 'Response detail: summary (default), detailed, raw',
              enum: ['summary', 'detailed', 'raw'],
              default: 'summary',
            },
          },
          required: ['filepath'],
        },
      },
      {
        name: 'find_similar_queries',
        description: 'Find previous similar questions or queries with enhanced matching',
        inputSchema: {
          type: 'object',
          properties: {
            query: {
              type: 'string',
              description: 'Query to find similar previous questions',
            },
            limit: {
              type: 'number',
              description: 'Maximum number of results (default: 8)',
              default: 8,
            },
            detail_level: {
              type: 'string',
              description: 'Response detail: summary (default), detailed, raw',
              enum: ['summary', 'detailed', 'raw'],
              default: 'summary',
            },
          },
          required: ['query'],
        },
      },
      {
        name: 'get_error_solutions',
        description: 'Find solutions for specific errors with enhanced matching',
        inputSchema: {
          type: 'object',
          properties: {
            error_pattern: {
              type: 'string',
              description: 'Error message or pattern to search for solutions',
            },
            limit: {
              type: 'number',
              description: 'Maximum number of results (default: 8)',
              default: 8,
            },
            detail_level: {
              type: 'string',
              description: 'Response detail: summary (default), detailed, raw',
              enum: ['summary', 'detailed', 'raw'],
              default: 'summary',
            },
          },
          required: ['error_pattern'],
        },
      },
      {
        name: 'list_recent_sessions',
        description: 'Browse recent sessions with smart activity detection and summaries',
        inputSchema: {
          type: 'object',
          properties: {
            limit: {
              type: 'number',
              description: 'Maximum number of sessions (default: 10)',
              default: 10,
            },
            project: {
              type: 'string',
              description: 'Optional project name to filter sessions',
            },
            include_summary: {
              type: 'boolean',
              description: 'Include intelligent session summaries (default: true)',
              default: true,
            },
          },
        },
      },
      {
        name: 'extract_compact_summary',
        description: 'Get intelligent summary of a conversation session with key insights',
        inputSchema: {
          type: 'object',
          properties: {
            session_id: {
              type: 'string',
              description: 'Session ID to summarize',
            },
            max_messages: {
              type: 'number',
              description: 'Maximum messages to analyze (default: 10)',
              default: 10,
            },
            focus: {
              type: 'string',
              description: 'Focus area: solutions, tools, files, or all',
              enum: ['solutions', 'tools', 'files', 'all'],
              default: 'all',
            },
          },
          required: ['session_id'],
        },
      },
      {
        name: 'find_tool_patterns',
        description: 'Analyze tool usage patterns, workflows, and successful practices',
        inputSchema: {
          type: 'object',
          properties: {
            tool_name: {
              type: 'string',
              description: 'Optional specific tool name to analyze',
            },
            pattern_type: {
              type: 'string',
              description: 'Type of patterns: tools, workflows, or solutions',
              enum: ['tools', 'workflows', 'solutions'],
              default: 'tools',
            },
            limit: {
              type: 'number',
              description: 'Maximum number of patterns (default: 12)',
              default: 12,
            },
          },
        },
      },
      {
        name: 'search_plans',
        description:
          'Search Claude Code plan files for past implementation approaches, decisions, and patterns',
        inputSchema: {
          type: 'object',
          properties: {
            query: {
              type: 'string',
              description: 'Search query for plan content',
            },
            limit: {
              type: 'number',
              description: 'Maximum number of results (default: 10)',
              default: 10,
            },
            detail_level: {
              type: 'string',
              description: 'Response detail level',
              enum: ['summary', 'detailed', 'raw'],
              default: 'summary',
            },
          },
          required: ['query'],
        },
      },
    ],

Claude Historian