Local History MCP Server

Instructions

Implementation Reference

• src/index.ts:302-336 (handler)

  Main handler function that executes the tool logic: finds the file history using VSCodeHistoryParser, formats summaries of all entries, and returns a formatted text response.

  private async getFileHistory(filePath: string) {
  	const history = this.historyParser.findHistoryByFilePath(filePath);
  
  	if (!history) {
  		return {
  			content: [
  				{
  					type: 'text',
  					text: `No local history found for: ${filePath}`,
  				},
  			],
  		};
  	}
  
  	const entriesText = history.entries
  		.map(
  			(entry, index) =>
  				`[${index}] ${new Date(entry.timestamp).toLocaleString()}\n` +
  				`     File: ${entry.relativePath}\n` +
  				`     Size: ${entry.content.length} characters`,
  		)
  		.join('\n\n');
  
  	return {
  		content: [
  			{
  				type: 'text',
  				text:
  					`History for: ${history.originalFilePath}\n` +
  					`Total entries: ${history.entries.length}\n\n` +
  					`History entries (most recent first):\n\n${entriesText}`,
  			},
  		],
  	};
  }

• src/index.ts:62-77 (registration)

  Tool registration in the ListTools response, including name, description, and input schema.

  {
  	name: 'get_file_history',
  	description: 'Get the complete history for a specific file',
  	inputSchema: {
  		type: 'object',
  		properties: {
  			filePath: {
  				type: 'string',
  				description:
  					'The path to the file. Please provide an absolute path (e.g., "/Users/user/project/biome.json") for reliable matching.',
  			},
  		},
  		required: ['filePath'],
  		additionalProperties: false,
  	},
  },

• src/index.ts:170-185 (handler)

  Dispatch handler in CallToolRequest switch statement: validates input parameters and delegates to private getFileHistory method.

  case 'get_file_history': {
  	if (!args || typeof args !== 'object' || !('filePath' in args)) {
  		throw new McpError(
  			ErrorCode.InvalidParams,
  			'Missing required parameter: filePath',
  		);
  	}
  	const filePathHistory = args.filePath as string;
  	if (!path.isAbsolute(filePathHistory)) {
  		throw new McpError(
  			ErrorCode.InvalidParams,
  			'filePath must be an absolute path',
  		);
  	}
  	return await this.getFileHistory(filePathHistory);
  }

• src/history-parser.ts:231-254 (helper)

  Key helper method called by the handler to locate the FileHistory object for the given file path by searching all histories.

  public findHistoryByFilePath(targetFilePath: string): FileHistory | null {
  	const histories = this.getAllFileHistories();
  
  	// Convert URI to path if needed
  	const cleanTargetPath = uriToPath(targetFilePath);
  	const normalizedTarget = path.resolve(cleanTargetPath);
  
  	for (const history of histories) {
  		const cleanHistoryPath = uriToPath(history.originalFilePath);
  		const normalizedHistory = path.resolve(cleanHistoryPath);
  
  		// Exact match
  		if (normalizedTarget === normalizedHistory) {
  			return history;
  		}
  
  		// Case-insensitive match (for case-insensitive filesystems)
  		if (normalizedTarget.toLowerCase() === normalizedHistory.toLowerCase()) {
  			return history;
  		}
  	}
  
  	return null;
  }

• src/index.ts:65-76 (schema)

  Input schema definition for the get_file_history tool, specifying the required filePath parameter.

  inputSchema: {
  	type: 'object',
  	properties: {
  		filePath: {
  			type: 'string',
  			description:
  				'The path to the file. Please provide an absolute path (e.g., "/Users/user/project/biome.json") for reliable matching.',
  		},
  	},
  	required: ['filePath'],
  	additionalProperties: false,
  },