Local History MCP Server

Instructions

Implementation Reference

• src/index.ts:470-487 (handler)

  The primary handler function for the 'get_history_stats' tool. It delegates to the history parser for stats computation and formats the response as MCP-compliant content with statistics display.

  private async getHistoryStats() {
  	const stats = this.historyParser.getHistoryStats();
  
  	return {
  		content: [
  			{
  				type: 'text',
  				text:
  					'📊 Local History Statistics\n\n' +
  					`History directory: ${stats.historyDirPath}\n` +
  					`Directory exists: ${stats.historyDirExists ? '✅' : '❌'}\n` +
  					`Total files with history: ${stats.totalFiles}\n` +
  					`Total history entries: ${stats.totalEntries}\n` +
  					`Average entries per file: ${stats.totalFiles > 0 ? (stats.totalEntries / stats.totalFiles).toFixed(1) : 'N/A'}`,
  			},
  		],
  	};
  }

• src/history-parser.ts:259-277 (helper)

  Core helper method in VSCodeHistoryParser class that calculates the actual history statistics by aggregating all file histories.

  public getHistoryStats(): {
  	totalFiles: number;
  	totalEntries: number;
  	historyDirExists: boolean;
  	historyDirPath: string;
  } {
  	const histories = this.getAllFileHistories();
  	const totalEntries = histories.reduce(
  		(sum, history) => sum + history.entries.length,
  		0,
  	);
  
  	return {
  		totalFiles: histories.length,
  		totalEntries,
  		historyDirExists: this.historyDirectoryExists(),
  		historyDirPath: this.historyDir,
  	};
  }

• src/index.ts:127-136 (schema)

  Input schema and metadata (name, description) for the 'get_history_stats' tool, defined in the ListTools response. No input parameters required.

  {
  	name: 'get_history_stats',
  	description:
  		'Get statistics about the local history (total files, entries, etc.)',
  	inputSchema: {
  		type: 'object',
  		properties: {},
  		additionalProperties: false,
  	},
  },

• src/index.ts:162-272 (registration)

  Registration of the CallTool request handler, including the switch case that dispatches 'get_history_stats' calls to the handler method.

  	this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
  		try {
  			const { name, arguments: args } = request.params;
  
  			switch (name) {
  				case 'list_history_files':
  					return await this.listHistoryFiles();
  
  				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);
  				}
  
  				case 'get_history_entry': {
  					if (
  						!args ||
  						typeof args !== 'object' ||
  						!('filePath' in args) ||
  						!('entryIndex' in args)
  					) {
  						throw new McpError(
  							ErrorCode.InvalidParams,
  							'Missing required parameters: filePath, entryIndex',
  						);
  					}
  					const filePathEntry = args.filePath as string;
  					if (!path.isAbsolute(filePathEntry)) {
  						throw new McpError(
  							ErrorCode.InvalidParams,
  							'filePath must be an absolute path',
  						);
  					}
  					return await this.getHistoryEntry(
  						filePathEntry,
  						args.entryIndex as number,
  					);
  				}
  
  				case 'restore_from_history': {
  					if (
  						!args ||
  						typeof args !== 'object' ||
  						!('filePath' in args) ||
  						!('entryIndex' in args)
  					) {
  						throw new McpError(
  							ErrorCode.InvalidParams,
  							'Missing required parameters: filePath, entryIndex',
  						);
  					}
  					const filePathRestore = args.filePath as string;
  					if (!path.isAbsolute(filePathRestore)) {
  						throw new McpError(
  							ErrorCode.InvalidParams,
  							'filePath must be an absolute path',
  						);
  					}
  					return await this.restoreFromHistory(
  						filePathRestore,
  						args.entryIndex as number,
  						((args as Record<string, unknown>).createBackup as boolean) ??
  							true,
  					);
  				}
  
  				case 'get_history_stats':
  					return await this.getHistoryStats();
  
  				case 'search_history_content':
  					if (!args || typeof args !== 'object' || !('searchTerm' in args)) {
  						throw new McpError(
  							ErrorCode.InvalidParams,
  							'Missing required parameter: searchTerm',
  						);
  					}
  					return await this.searchHistoryContent(
  						args.searchTerm as string,
  						((args as Record<string, unknown>).caseSensitive as boolean) ??
  							false,
  					);
  
  				default:
  					throw new McpError(
  						ErrorCode.MethodNotFound,
  						`Unknown tool: ${name}`,
  					);
  			}
  		} catch (error) {
  			if (error instanceof McpError) {
  				throw error;
  			}
  
  			throw new McpError(
  				ErrorCode.InternalError,
  				`Tool execution failed: ${error instanceof Error ? error.message : String(error)}`,
  			);
  		}
  	});
  }